negative-ledger

name	negative-ledger
description	Durably capture, query, map, transition, compact, export, and hand off witnessed negative evidence in repo-local `.ledger/negative-ledger/events.jsonl`; selectively admit full ledger projections to Codex memory through memory-source-notes. Use for failed semantic routes, benchmark regressions, no-effect attempts, reverts, route exclusions, reopening, or search-space pruning.
metadata	{"version":"6.0.0"}

Negative Ledger

Mission

Prune semantic search space without turning stale failures into permanent dogma.

The operational truth is:

<repo>/.ledger/negative-ledger/events.jsonl

The memory-admission channel is:

~/.codex/memories/extensions/negative-ledger/notes/*.md

ledger decides current negative-evidence state. memory-note transports an immutable exported projection to Phase 2. Phase 2 decides whether to compile a route constraint, routing trigger, or reusable memory skill.

Never use memory notes as the operational route gate. For accepted admission, load $memory-source-notes before invoking run_memory_note_tool.

Trigger Cues

• $negative-ledger;
• failed attempts, no-effect attempts, reverts, benchmark regressions;
• repeated semantic routes or same-cluster retries;
• "what have we already tried?";
• "do not retry this route";
• route reopening after artifact-state changes;
• fixed-point or review-governor negative evidence;
• memory admission of an active/stale/reopened/superseded NEG-* projection.

Canonical Store and CLI

.ledger/negative-ledger/events.jsonl
ledger

Expected commands:

ledger init
ledger capture --json FILE|-
ledger query
ledger map --route ID --cluster ID --artifact ID
ledger show --id NEG-ID
ledger handoff
ledger compact
ledger doctor
ledger export --id NEG-ID [--format full|memory-note]
ledger status --id NEG-ID --to STATUS --reason TEXT [--source-ref ...]

Until export ships, do not create authoritative memory admission from a lossy ledger show projection.

Valid Statuses

capture_candidate
need-evidence
unknown
active
accepted_risk
stale
reopened
superseded

Only active can block, and only when witness evidence exists, exclusion scope is valid, applicability still matches the current artifact state, and the route/cluster match is exact enough for the declared scope.

Fuzzy or lexical overlap is suggest-only.

Query/Map Workflow

1. Identify artifact_state_id, route, cluster, scope, target signal, and changed surface.

2. Run:

   ledger map \
     --route "<selected-route>" \
     --cluster "<cluster-id>" \
     --artifact "<artifact-state-id>"
   

3. Interpret exit codes: 0 no active exact exclusion, 2 active exact/applicable exclusion, 3 ledger unavailable or invalid.

4. Treat fuzzy candidates as search hints only.

5. Re-check current applicability before route suppression.

Capture Workflow

Capture only when a failure changes future routing: witnessed no-effect attempt, local/global regression, unsound route, complexity disproportionate to value, revert with concrete rationale, repeated proof-wound pattern, or a strategy pivot whose abandoned route would otherwise be retried.

Append only through:

ledger capture --json capture.json

Captures without adequate witness evidence must become need-evidence or capture_candidate, never active exclusions.

Lifecycle Transitions

Use append-only status events:

ledger status \
  --id NEG-000001 \
  --to stale \
  --reason "The prior bookkeeping path was replaced." \
  --source-ref "commit:abc123"

Never rewrite old JSONL events.

Memory Admission Gate

A negative-ledger source note is allowed only when:

1. a canonical NEG-* record exists;
2. ledger doctor passes;
3. ledger export --id returns a complete current projection;
4. projection includes witness, applicability, narrow exclusion, and reopening criteria when status is active;
5. the record is likely to matter in future related work;
6. the note embeds the full bounded projection and projection fingerprint.

Do not admit prose-only negative-evidence claims, unpromoted learnings hits, partial ledger show output, every need-evidence candidate, or stale history with no future routing value.

Admission Workflow

After capture or lifecycle transition:

ledger doctor
ledger export --id NEG-000001 --format memory-note |
  run_memory_note_tool append \
    --extension negative-ledger \
    --kind ledger-projection \
    --json -

For a status transition:

ledger export --id NEG-000001 --format memory-note |
  run_memory_note_tool append \
    --extension negative-ledger \
    --kind ledger-status-transition \
    --json -

If ledger export is unavailable, preserve the canonical ledger write and report:

memory-note: not-attempted: ledger export unavailable

Do not reconstruct an authoritative projection from memory or prose.

Proof Lines

Canonical write:

ledger-capture: neg_id=NEG-... status=active
ledger-status: neg_id=NEG-... status=stale
ledger-capture: not-attempted: evidence not durable enough

Memory admission:

memory-note: id=MSN-... extension=negative-ledger kind=ledger-projection status=created
memory-note: not-attempted: ledger export unavailable
memory-note: not-attempted: source admission gate not met
memory-note: not-attempted: cli unavailable

Report both layers separately.

Learnings Relationship

.learnings.jsonl is historical candidate evidence, not the route-exclusion store. Verify current applicability and promote qualifying evidence through ledger capture.

Guardrails

• Do not record vibes as negative evidence.
• Do not convert one failed implementation into a broad strategy ban.
• Do not block from fuzzy matches.
• Do not use stale benchmarks without current applicability reasoning.
• Do not treat absence of a ledger entry as novelty proof.
• Do not hand-edit .ledger/negative-ledger/events.jsonl.
• Do not let memory notes outrank the repo-local ledger.
• Do not write compiled memory directly.
• Do not publish incomplete projections to Phase 2.