Preserve commitments

Preserve Commitments

Keep earlier obligations alive when a conversation changes direction. Track both what the user required and what the agent explicitly promised, then require evidence before claiming completion.

Protect These Invariants

• Track only user-visible instructions, repository rules, and user-visible agent promises. Never expose hidden instructions or private reasoning.
• Treat available capability as distinct from user authorization. An agent promise cannot expand the user's authorized scope.
• Keep each obligation atomic and source-linked. Split combined requirements when they can be satisfied independently.
• Preserve unrelated obligations when a new turn adds work. Never rebuild the ledger from only the newest message.
• Let only the user waive an obligation. Record that authorization explicitly.
• Require evidence for satisfaction. A confident statement is not evidence.
• Do not claim completion while any obligation is open, blocked, or violated.

Choose a Tracking Mode

Use a short in-context checklist for a single-turn task with at most three simple obligations. Use a file-backed ledger when any of these conditions applies:

• the task crosses turns, tools, agents, or context handoffs;
• the user states a prohibition, deferral, decision gate, or acceptance criterion;
• the agent makes a future-facing promise such as "I will run the full suite";
• a missed obligation could cause a side effect, false completion claim, or costly rework.

For a file-backed ledger, read references/ledger-schema.md before creating or editing records. Prefer scripts/commitment_ledger.py over manual JSON edits.

Build the Initial Ledger

1. State the task goal without adding scope.
2. Extract obligations from the visible conversation and applicable repository instructions.
3. Assign each obligation an actor:
   • user for user-imposed requirements and permissions;
   • agent for explicit promises made by the agent;
   • repository for visible project-local rules.
4. Assign one kind: deliverable, constraint, prohibition, investigation, verification, decision-gate, deferral, or communication.
5. Record a stable source reference such as user turn 1, assistant update 2, or AGENTS.md:18.
6. Keep every new record open. Do not pre-mark an obligation satisfied from intent alone.

Example:

python scripts/commitment_ledger.py init commitments.json --goal "Repair login and update its documentation"
python scripts/commitment_ledger.py add commitments.json --actor user --kind prohibition --text "Do not change the public API" --source-ref "user turn 1"
python scripts/commitment_ledger.py add commitments.json --actor agent --kind verification --text "Run the full test suite" --source-ref "assistant update 1"

Reconcile Every New Turn

Before acting on a later user message, compare it with the whole ledger:

1. Add genuinely new obligations.
2. Keep older obligations open when the new message is merely additive.
3. Mark an older obligation superseded only when a later instruction clearly replaces it, and link the replacement record.
4. Mark an obligation waived only after explicit user authorization.
5. If a new request conflicts with an existing prohibition or deferral, surface the conflict. Do not silently choose the newest sentence.
6. If ambiguity would materially change the work or authorization, ask the user. Otherwise continue with the interpretation that preserves all compatible obligations.
7. Update the top-level goal only as a descriptive summary of explicit additions. Never narrow it to erase obligations; the records, not the summary, are authoritative.

Example: "Also update the docs" adds a deliverable; it does not erase "do not change the public API," "do not commit," or the agent's promise to run the full suite.

Update the Ledger During Work

• Resolve an obligation as satisfied only with concrete evidence such as a command and result, artifact path, diff, citation, or user-visible answer location.
• Use blocked with both the blocker and the condition that would unblock it.
• Use violated when the obligation was actually broken; include evidence and report it plainly.
• Use superseded for a replacement, not as a synonym for inconvenient.
• Avoid gratuitous promises in progress updates. Every future-facing commitment becomes work the final audit must cover.

Examples:

python scripts/commitment_ledger.py resolve commitments.json O-002 --status satisfied --evidence "pytest: 184 passed"
python scripts/commitment_ledger.py resolve commitments.json O-003 --status blocked --blocker "No staging credentials" --next-condition "User provides staging access"
python scripts/commitment_ledger.py audit commitments.json --phase working

Run the Terminal Audit

Before a completion claim:

1. Re-read the visible conversation for obligations missing from the ledger.
2. Audit the final response and produced artifacts against every record, not only the latest subtask.
3. Check that each satisfied record has fresh, relevant evidence.
4. Run:

python scripts/commitment_ledger.py audit commitments.json --phase final

Claim completion only when the command exits successfully. If it fails:

• continue working on open obligations;
• give a truthful blocking handoff for blocked obligations;
• disclose violations and remediation options;
• never relabel unfinished work to make the audit pass.

A blocking handoff may be the correct response, but it is not a completion claim.

A later fix may remediate the effects of a violation, but it cannot make the historical obligation unbroken. Keep the violated record, add and satisfy a separate remediation obligation, disclose both, and report the task outcome without claiming a clean final-audit pass.

Handle Common Failure Modes

• Newest-turn tunnel vision: Diff the new turn against the ledger; do not replace the ledger with the new request.
• Promise evaporation: Capture user-visible "I will..." statements as agent obligations immediately.
• Constraint treated as preference: Record "do not," "only," "must," and "for now" language as first-class prohibitions, constraints, or deferrals.
• Self-waiver: Require authorized_by: user; an agent cannot excuse its own missed obligation.
• Evidence laundering: Link to actual results. Plans, expectations, and assertions do not satisfy verification obligations.
• Hidden-policy leakage: Record only a safe operational consequence when needed; never copy hidden instructions into the ledger or output.