Discovery, decisions and goal check

Part of the Cobalt Cockpit documentation. This text was moved here from the root README when the README was restructured for v0.6.0; the wording is unchanged unless a sentence says otherwise. Overview: Verification Readiness.

The read-only view of what stands before DONE, /cockpit ready, is described in the README; the six gates and the goal check it reports on are the ones on this page.

Added in v0.5.1. It is Cockpit's own heuristic, not an Anthropic workflow or endorsement, and it adds no model call: the level comes from deterministic rules over the prompt, the files the host saw edited and the consultation grounds Cockpit already reads. A router (NobodyWho or JEV) may still advise on routing; it cannot lower a level, skip a gate or waive a consultation.

A level only goes up during a task, and each level's guidance is given once. The progress tool gained three actions: discover (objective, acceptance criteria, material unknowns, relevant risks), decide (one decision) and align (the goal check). /cockpit discovery shows the state:

COBALT / DISCOVERY
LEVEL / STANDARD
GOAL / Implement booking cancellation
UNKNOWNS / 2 unresolved
DECISIONS / 1 recorded
ALIGNMENT / PENDING

Decisions. A record holds a problem, the chosen approach, alternatives with the reason each was rejected, trade-offs, evidence and a status (provisional, verified, revised). Cockpit stores what the model reported and nothing else: an alternative without its reason, or a verified decision without evidence, is refused rather than filled in. Records are redacted for credential shapes before they enter task state or the Run Ledger, bounded (12 per task, 64 per ledger, detail dropped before records when the 384,000-byte budget is tight) and not required for LIGHT work. The ledger also keeps one entry per task saying which level was chosen and why, in short codes, with no prompt text. Cockpit never creates DECISIONS.md or CLAUDE.md; /ledger export decisions prints Markdown for you to paste.

Goal check. A coding task above LIGHT cannot read DONE until align reports ALIGNED. Explicit acceptance criteria are required: with none declared the task shows CRITERIA / MISSING, ALIGNMENT / BLOCKED and DONE is refused, and Cockpit never invents criteria or evidence. Each criterion (stable id, meaningful description) needs its own met entry with evidence that names an observation (a quoted output, a file, a number); generic evidence such as "works" or a restatement of the criterion is refused, and the basis is recorded as reported, never as independently verified. Evidence goes stale, and criteria return to unevaluated, on edits (main or helper), a plan or replan, a new or revised criterion, a failing gate or a reopened unknown; read-only activity does not. Besides that, nothing reported missing, no unknown still open, every earlier milestone done, no blocker and every required gate passed. Passing tests are one input, never the whole. PARTIAL, BLOCKED and UNKNOWN are recorded and do not complete the task. Editing files (by the main session or a helper), failing a required gate or milestone, a new criterion or open unknown, or a new plan afterwards takes the check back. ALIGNED is refused before a plan exists, and a read-only plan whose edits are observed (Edit, Write, a Bash edit diff, a helper's edit) and that reaches a level above LIGHT is held for the goal check, though its gates stay not applicable. A plan restart cannot lower the level a task reached. The result is a hold on the existing progress model (the task stays UNVERIFIED below 100%), not a second percentage. LIGHT, read-only and operator-pinned LIGHT tasks, and tasks stored before v0.5.1, are never held by it. A pin of light waives this check for the rest of the session, for every later task, until you set auto; it changes only this check and the guidance: mandatory Opus consultations and the six gates are unaffected.

After DONE. For work the goal check applies to (a coding task above LIGHT), a change to the implementation takes completion back, deterministically, whether or not the model remembers to reopen the task: the goal check returns to PENDING, every criterion evaluation is cleared, and each gate that had passed goes back to pending ("stale"). The stored task is settled at once, so the status stops reading DONE. Fresh gate results and a fresh align with new evidence restore DONE. Reads, searches and commands that change nothing do not, and neither does staging, committing or stashing, because the fingerprint is of file contents against the commit it was taken against. A change is seen from: an Edit or Write result (main session or a helper), a Bash edit diff, a plan or replan, and, for everything else, a fingerprint of the git working tree: taken when ALIGNED is accepted and compared after each later tool call and before each progress call, and taken again when gates are recorded, so ALIGNED is also refused when the tree changed between the checks and the goal check. NotebookEdit, MCP filesystem writers and shell commands that rewrite files are caught by what they changed, never by their name. Measured cost of one fingerprint: 14-16 ms in a 5-100 file repository, 50-57 ms in 2,000 and 30,000 file repositories with 5 modified and 150 untracked files, about 100 ms with 1,500 modified files. It runs only while a goal check stands, once per tool call. Returning to automatic classification with /cockpit discovery auto never lowers a level the task has reached.

Limits. The completion gate is a hold on the progress model, not a proof of correctness:

• The level is a heuristic over words and file names (the full prompt text and the plan's goal), so it can misjudge a terse or oddly worded prompt in either direction; pin it with /cockpit discovery. An explicit pin of light is the operator's choice and waives the check; it is shown as an operator pin.
• Only prompts typed in the composer, or sent by the bridge or the SDK, are classified (classifying grants nothing; commands that change protected state accept only the composer and the bridge). A prompt from another origin leaves the stored prompt as it was, and a task that never receives a classifiable prompt starts at LIGHT until the plan's goal, the files edited or the model's discover raise it.
• A model that never calls the progress tool has no milestones, no criteria and no gates: the task stays at 0% and is never held or shown DONE. Cockpit cannot stop a claim of "done" made only in prose; after two edited files it reminds once.
• Criteria and evidence are checked for form only: present, individually evaluated, not generic, naming a file, quote or figure, not shared between criteria. Cockpit cannot tell whether a criterion is a good one or whether the evidence is true; evidence is recorded as reported, never as independently verified.
• Mutation coverage: edits made through Edit, Write and Bash edit diffs are observed directly. Other writers are observed only through the git working tree, so a change is missed when the project is not a git repository or has no commit yet, git does not answer in time or its output is cut short, or the tree cannot be measured safely (a FIFO, device or oversized file where Git would read it). Since v0.6.4 a goal check made in a Git repository that cannot be measured is recorded as UNKNOWN with the reason, never ALIGNED; only outside every Git repository is ALIGNED accepted without a fingerprint, and it is then shown as UNPROTECTED, the file is git-ignored or outside the repository, a tool changes a file and changes it back before the next observation, or more than 2,000 files differ from the commit. A write by a person or another program between calls is treated like any other change. Output of the test command that lands in unignored files after ALIGNED also reads as a change. Tool permissions and ownership are unchanged: nothing here allows or denies a call.
• The "After DONE" protection applies to goal-checked work only. A LIGHT task, a read-only plan whose edits are not observed by Edit, Write or a Bash edit diff, and a task stored by v0.5.0 are not goal-checked: they keep their gates and DONE after later edits. Giving a coding request a read-only plan, or phrasing it as a question, can keep the level at LIGHT.
• The fingerprint hashes the raw bytes of regular files (no git filters), the text of symbolic links and the kind of FIFOs, sockets and devices, which it never opens (since v0.6.4); it ignores file-mode changes of untracked files. A submodule or a nested repository among the changed files makes it unavailable, and build or test artifacts that are not git-ignored read as changes. Checks that passed before a task became goal-checked have no fingerprint of their own.
• An accepted goal check, and the checks it rests on, are withdrawn when a tree that was measured can no longer be measured (since v0.6.4): a failed measurement is never taken for an unchanged tree. A measurement cut short only because a file changed while it was read is taken once more first. The limits and what they do not cover: SECURITY.md.
• Evidence checks are weak by design: any figure satisfies "names a figure", restating a criterion is an exact-text test, and evidence that is made distinct by appending a tag still counts as distinct.
• Decision records and discovery entries in the Run Ledger are keyed by task number, which restarts after /cockpit reset or /clear; an older task's entry can be replaced by a new task with the same number.
• A legacy v0.5.0 task that is nearly done becomes goal-checked if discover or /cockpit discovery <level> is used on it.