ericyoung-183/anchor/anchor

Anchor

Anchor keeps live discussion agendas from drifting. Use it when the conversation has a concrete list to process sequentially, especially when “next” must mean the next item in the current deepest layer.

When To Start

Start Anchor only when both signals exist:

• A concrete list exists: review findings, diagnosis issues, audit items, TODO discussion items, or child questions under the current item.
• The conversation shows item-by-item intent: “one by one”, “next”, “continue”, “you host”, “逐条讨论”, “一个一个过”, or equivalent.

Do not start Anchor for ordinary explanatory lists, brainstorm options, or long-term backlog scans without item-by-item intent.

Required Behavior

1. Freeze the source list before discussing items. init, push-child, and interrupt require a source reference plus an exact numbered/bulleted snapshot; unstructured legacy input needs an explicit unverified-source reason.
2. Use the helper script for state changes; do not rely on memory.
3. Interpret “next” from the deepest active agenda layer.
4. Complete, defer, or block the current item before advancing.
5. complete, finish, and revise-conclusion require a real non-empty conclusion; whitespace never counts as completed evidence.
6. Every agenda mutation must pass the current --expected-cursor-token from helper context or the immediately preceding result, including the result of ack-presented. The token binds tracker cycle, revision, deepest agenda, and item so delayed commands cannot overwrite newer state in the same item or hit another layer or cycle.
7. Finish a child layer before returning to its parent. The return stops on the parent item in awaiting_advance; display and acknowledge the Whole Picture, review the returned child outcomes, record the parent synthesis with revise-conclusion, and only then run next. The helper rejects next until that synthesis is explicitly confirmed. pause suspends the whole tracker; it does not pop only the child layer.
8. A readable legacy tracker must run present, display and acknowledge that Whole Picture, and only then perform its first progress mutation.
9. If no active state exists, rebuild from a clear source or ask the user.
10. At closure, export unresolved actions only if they need long-term project memory, TODO, or docs.

Anchor Capture Protocol

Use this trigger matrix before responding to list-processing turns:

When init, push-child, interrupt, resume, or present succeeds, or finish/next automatically returns from a closed child or interrupt frame, display the returned whole_picture as the user-visible Whole Picture before substantive discussion. The picture includes every item in the active root-to-current tree and its current status. Then acknowledge the exact returned presentation_id with ack-presented, but only after the text is user-visible. Until acknowledgement, progress mutations fail closed; token-guarded pause and abandon remain recovery exits. Use same-turn acknowledgement only when the platform records visible text before the helper call; otherwise acknowledge at the first helper call on the next turn. Never acknowledge tool output alone.

Storage Rule

When init creates a new tracker in a safe Git project, the helper auto-enables project-local state by creating .anchor/config.json, .anchor/state/, and .git/info/exclude entries. Existing global-fallback trackers stay global for the same thread. Use global fallback for broad roots, non-Git or unwritable directories, ANCHOR_STATE_MODE=global, or ANCHOR_AUTO_ENABLE_PROJECT=0. Forced global mode fails if that thread already has project-local state; a custom global root also checks the default root so an existing tracker cannot be hidden.

Project TODO Bridge

When the user asks about remaining TODOs, continuing project TODOs, recording a TODO, or processing TODOs one by one, use the helper's TODO commands. todo-status is read-only and reports unsupported_format, ambiguous_format, or parse_error instead of pretending an unknown ledger is empty. Run todo-configure --format before todo-start on a uniquely inferred existing ledger; pass --path when multiple candidates exist. Detection alone is read-only evidence, not write authorization. todo-start binds each item by ID and semantic fingerprint. A closed, paused, or abandoned TODO agenda with newly completed records returns todo_sync_required; run todo-sync --expected-tracker-id <tracker-id> before claiming closure or starting a new same-thread cycle. After sync, todo-start may open the next cycle in the same thread only when every unresolved record is a root-level item with the same ID and semantic fingerprint in the same canonical TODO. The new item shows the previous blocked/deferred status and reason. Nested unresolved work, a reused ID with changed meaning, or a changed binding fails closed and must be exported or explicitly discarded. This exception never applies to an ordinary agenda. Sync preserves externally reopened old items, tolerates unrelated edits, re-reads the final file before clearing the obligation, and fails closed on target changes or unsupported writes. Do not switch the canonical TODO while a bound tracker is live or unsynced, hand-edit .anchor/config.json, or treat multiple TODO files as one active source.

Helper

Use scripts/anchor.py for deterministic state handling. Use scripts/anchor_pressure_check.py for transcript pressure checks. Use validate for one tracker and doctor --cwd <project> for a read-only runtime health report before cleanup or migration decisions. validate returns exact state_hash and event_log_hash values. After an intentional old-version write causes an event-chain error, inspect state first and use explicit repair-event-chain --expected-state-hash <state-hash> --expected-event-log-hash <event-hash> --reason <reason>; repair refuses healthy chains, stale hashes, changed event streams, and invalid agenda topology. Never repair automatically.

References:

• references/schema.md: state shape, commands, invariants.
• references/examples.md: realistic pressure examples.
• references/phrase-map.md: user phrase to state action mapping.
• references/failure-taxonomy.md: drift categories for review and debugging.
• references/closure-template.md: concise closure handoff format.