negative-ledger

# Negative Ledger ## Mission Prune semantic search space without turning stale failures into permanent dogma. The structural boundary is the passive definition: ```text ${CODEX_HOME:-$HOME/.codex}/skills/negative-ledger/definitions/ledger/negative-evidence-protocol.json ``` The selected definition exclusively addresses the canonical store at `.ledger/negative-ledger/events.jsonl`, and every operation or projection is explicit. The memory-admission channel is: ```text ~/.codex/memories/extensions/negative-ledger/notes/*.md ``` `$negative-ledger` owns the meaning and lifecycle of current negative-evidence state. Ledger structurally replays the declared protocol and projects that state without acquiring its semantic authority. `memory-note` transports an immutable 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 or test regressions; - repeated semantic routes or same-cluster retries; - strategy pivots that abandon a concrete route future work might repeat; - "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. ## Activation Policy Activation is broad; capture is narrow. Invoke this skill implicitly when current work may change route selection because a concrete route failed, had no effect, regressed a signal, was reverted, was rejected by current proof/review evidence, or is about to be retried under the same cluster. Do not wait for the user to literally name `$negative-ledger`. Before selecting a route that resembles a prior failure, project the canonical `route-gate`. A recalled `$learnings` row may trigger this check, but it cannot block directly. After a material strategy pivot, regression-confirmed revert, or closeout that leaves a failed route likely to recur, evaluate capture. A transient red test, syntax error, first incomplete implementation, or discarded local typo is `no-op` unless it exposes a durable failed hypothesis that changes future routing. Retain exactly one internal disposition for each material activation: ```text mapped current ledger checked; no write required captured witnessed negative evidence appended transitioned existing NEG record changed lifecycle state no-op activation evaluated; evidence was not durable or route-shaping blocked ledger unavailable/invalid or active exact/applicable exclusion matched ``` A material closeout with no failed-route semantics does not activate this source. Do not query, doctor, or capture merely to manufacture a no-op receipt. ## Canonical Store and CLI Before the first Ledger command in this workflow, load `$ledger` and complete `$ledger ensure` once. Require Ledger major version 1 and `ledger-artifact-abi/v1`: Reuse the unchanged `$ledger ensure` readiness result; recheck only when the executable, execution environment, or selected definition requirements change. Set the canonical definition once: ```bash negative_ledger_definition="$(realpath "${CODEX_HOME:-$HOME/.codex}/skills/negative-ledger/definitions/ledger/negative-evidence-protocol.json")" ``` Use only: ```text ledger definition check --definition DEFINITION ledger transact --definition DEFINITION --operation capture|promote|transition|bind-existing|rebind-existing --repo REPO ledger project --definition DEFINITION --projection current-records|route-gate|memory-note --repo REPO ledger doctor --definition DEFINITION --repo REPO ``` `ledger project --projection memory-note` is the authoritative source payload for memory admission. Never reconstruct it from a summary projection. Bind a pre-cutover current-format store exactly once before ordinary reads or writes. This validates every existing row and records the selected definition digest without rewriting the event log: ```bash ledger transact \ --definition "$negative_ledger_definition" \ --operation bind-existing \ --repo "<repo-root>" \ --format json ``` When an authoritative external transport replaces an already-bound store and `ledger doctor` reports a stale binding, use the separate one-shot custody operation. It validates the complete current event log and replaces only the binding metadata: ```bash ledger transact \ --definition "$negative_ledger_definition" \ --operation rebind-existing \ --repo "<repo-root>" \ --format json ``` Do not use rebind to choose between divergent ledgers or to bless an unknown store. Establish the authoritative transport and preserve the losing lineage as an explicit reconciliation input before rebinding. ## Valid Statuses ```text 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. ## Route-Gate Workflow For review-driven repair, apply the owner boundary in [counterexample-construction-integration.md](references/counterexample-construction-integration.md). 1. Identify `repository_id`, immutable `artifact_state_id`, human-readable `artifact_state_label`, route, cluster, declared scope, target signal, and changed surface. 2. Run: ```bash ledger project \ --definition "$negative_ledger_definition" \ --projection route-gate \ --repo "<repo-root>" \ --param "artifact=<artifact-state-id>" \ --param "identity=<declared-scope-identity>" \ --format json ``` 3. Interpret exit codes: `0` no active exact exclusion, `2` active exact/applicable exclusion, `3` ledger unavailable or invalid. 4. Pass the identity selected by the record's declared exact, route, route-family, cluster, authority-model, distinction-pattern, or proof-pattern scope. 5. Treat fuzzy candidates as search hints only. 6. Re-check current applicability before route suppression. 7. Resolve symbolic Git refs before the call, pass the immutable identity as `artifact`, and retain the human-readable source as `artifact_state_label` in capture data. ## 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. Before capture or promotion, apply the [scope challenge](#exclusion-scope-challenge) to the proposed exclusion; a witnessed failure alone does not justify its breadth. Append only through: ```bash ledger transact \ --definition "$negative_ledger_definition" \ --operation capture \ --repo "<repo-root>" \ --input capture=capture.json \ --format json ``` Captures without adequate witness evidence must become `need-evidence` or `capture_candidate`, never active exclusions. `capture.json` contains one `record` object, including its requested initial `status`. An active capture requires an explicit supported scope and its identity, an immutable artifact identity, structured source references, applicability conditions, a narrow exclusion rule, and identified reopening criteria. Select `need-evidence` before transaction when those structural requirements are incomplete; never assert `active` in prose after Ledger rejects it. Every transition to `active`, including promotion, reactivation, and reopening, requires the transition proof plus the complete replacement record, whose `status` is `active`. Use the dedicated operation so the event atomically replaces the reducer's retained record: ```bash ledger transact \ --definition "$negative_ledger_definition" \ --operation promote \ --repo "<repo-root>" \ --input promotion=promotion.json \ --format json ``` ## Exclusion Scope Challenge Ask whether a materially different realization of the excluded route could meet the same requirement under the declared applicability conditions. Distinguish a failed implementation from a failed strategy; the broader the suppressed search space, the stronger the scope argument must be. Inspect existing witnesses or proofs first; use a discriminating evaluation only when necessary and authorized. No fixed number of challenges or successful samples establishes a universal ban. An inspectable success within the claimed exclusion scope is counterevidence to that breadth. A success outside the scope is not. Confirm that a case exercises the disputed route, uses an independently justified requirement as oracle, and isolates the route rather than an invalid fixture or unrelated environment error. An imagined alternative warrants scrutiny, not a claimed successful execution. A successful sample alone does not refute a failure-rate, cost, or risk claim. Evaluate counterevidence against the recorded hypothesis and its measurement conditions; contrary samples can warrant investigation without changing the gate. Do not treat a variable outcome as a deterministic impossibility proof. Use the existing hypothesis, observed outcome, evidence, exclusion rule, applicability, and reopening fields to retain the supported boundary. For example, a stale cache entry may justify excluding reuse when the key omits a semantic input, not all caching. For a new record, choose the narrowest useful supported scope; retain `need-evidence` or `capture_candidate` when support is inadequate. Do not weaken required active-record structure to make the transaction pass. For counterevidence to an existing active record, preserve the gate until the source-owned lifecycle legally changes it. When replacing an overbroad exclusion, capture any still-supported narrower exclusion before superseding the old record, and link the evidence and replacement through structured source references. Reopening still requires proved changes to identified existing criteria; evidence that the old conclusion was unjustified is not a fabricated artifact change. Use proof-bearing supersession when appropriate instead of inventing criteria. Scope review grants no retry or mutation permission. Do not bypass an active exact applicable exclusion by calling the retry a test, sandbox, or experiment. Use the supported lifecycle and enclosing authority before a previously excluded retry becomes permissible; then project the current gate again. An unchanged or inapplicable challenge requires no write. Stop when the scope is supported, narrowed, or left pending evidence. A corrected exclusion does not automatically activate Learnings or grant architecture-selection authority. ## Lifecycle Transitions Use append-only status events. Every transition requires a JSON proof packet with a reason and structured source references: ```json { "neg_id": "NEG-000001", "from": "active", "to": "accepted_risk", "reason": "The prior evidence was accepted as a bounded risk.", "criterion_ids": [], "criterion_changes": [], "source_refs": [ {"kind": "review", "ref": "PR 123 acceptance"} ] } ``` ```bash ledger transact \ --definition "$negative_ledger_definition" \ --operation transition \ --repo "<repo-root>" \ --input transition=transition.json \ --format json ``` Reopening requires a proved before/after change for an identified criterion already present on the record: ```json { "neg_id": "NEG-000001", "from": "stale", "to": "reopened", "reason": "The implementation and representative fixture changed.", "criterion_ids": ["artifact-or-fixture-changed"], "criterion_changes": [ { "criterion_id": "artifact-or-fixture-changed", "before": "commit abc123 with fixture v1", "after": "commit def456 with fixture v2" } ], "source_refs": [ {"kind": "git", "ref": "commit:def456"}, {"kind": "test", "ref": "zig build test-ledger --summary all"} ] } ``` ```bash ledger transact \ --definition "$negative_ledger_definition" \ --operation transition \ --repo "<repo-root>" \ --input transition=reopen-proof.json \ --format json ``` Ledger rejects illegal edges, promotion without a complete active record, unknown criteria, and unchanged before/after claims before append. Never rewrite old events. ## Memory Admission Gate A negative-ledger source note is allowed only when: 1. a canonical `NEG-*` record exists; 2. definition-bound `ledger doctor` passes; 3. `ledger project --projection memory-note --param id=NEG-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, stable repository identity, event-chain fingerprint, projection fingerprint, and any prior projection link. Do not admit prose-only negative-evidence claims, unpromoted `learnings` hits, partial `current-records` output, every `need-evidence` candidate, or stale history with no future routing value. ## Admission Workflow After the source owner accepts admission for a capture or lifecycle transition, load `$memory-source-notes` and resolve its installed root independently of the target repository, then use its validated adapter: ```bash memory_source_notes_root="$(realpath "${CODEX_HOME:-$HOME/.codex}/skills/memory-source-notes")" ``` ```bash uv run "$memory_source_notes_root/scripts/negative_ledger_memory_note.py" \ admit \ --repo "<repo-root>" \ --id NEG-000001 \ --kind ledger-projection ``` For a status transition: ```bash uv run "$memory_source_notes_root/scripts/negative_ledger_memory_note.py" \ admit \ --repo "<repo-root>" \ --id NEG-000001 \ --kind ledger-status-transition ``` The adapter runs the definition-bound doctor, obtains the source-owned projection, rejects incomplete projections, preserves the deterministic projection payload bytes, and invokes `memory-note` idempotently. It transports an accepted source decision; it does not decide recurrence, utility, or route applicability. If the definition projection is unavailable, preserve the canonical Ledger transaction and report: ```text memory-note: not-attempted: ledger projection unavailable ``` Do not reconstruct an authoritative projection from memory or prose. ## Proof Lines Canonical write: ```text ledger-capture: neg_id=NEG-... status=active ledger-status: neg_id=NEG-... status=stale ledger-capture: not-attempted: evidence not durable enough ``` Memory admission: ```text memory-note: id=MSN-... extension=negative-ledger kind=ledger-projection status=created memory-note: not-attempted: ledger projection unavailable memory-note: not-attempted: source admission gate not met memory-note: not-attempted: cli unavailable ``` Report both layers separately. ## Learnings Relationship The learning source is historical candidate evidence, not the route-exclusion store. Legacy `.ledger/learnings/learnings.jsonl` and `.learnings.jsonl` are read only during migration. Verify current applicability and promote qualifying evidence through the definition's `capture` transaction. ## 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 bypass Ledger or hand-edit persistent-adapter records. - Do not let memory notes outrank the repo-local ledger. - Do not write compiled memory directly. - Do not publish incomplete projections to Phase 2. - Do not capture every transient test failure merely because implicit activation occurred. - Do not bypass failed `route-gate`, `memory-note`, or doctor projections; those boundaries must fail closed. - Do not invoke a sibling source merely because Negative Ledger activated. For changes to exclusion-scope reasoning, use the Negative Ledger cases in [validation-probes.md](../learnings/validation-probes.md). This is package validation, not a runtime dependency or activation of Learnings.