@pilotspace/add 1.17.0 → 2.0.0

package/docs/03-step-1-specify.md

@@ -1,123 +0,0 @@
-# 03 · Step 1 — Specify
-
-[← 02 The flow](./02-the-flow.md) · [Contents](./README.md) · Next: [04 Step 2 Scenarios →](./04-step-2-scenarios.md)
-
-> **Purpose:** state, in plain language, what the feature must do and what it must reject, with no ambiguity left for the AI to resolve by guessing.
-> **Produces:** the **§1 SPECIFY** block of the task's `TASK.md` (one file per task — what this chapter is the *why* behind; historically a separate `SPEC.md`).
-> **How it works — co-specification:** AI and human **brainstorm the shape together**; the AI drafts; the **human validates, with the AI's advice.** The decisive advice is a *lowest-confidence flag* — the AI names the one or two things most likely to be wrong, so the human's attention lands where it matters. The human owns the decision; the AI owns surfacing what it does not yet know.
-
----
-
-## Why this step is first
-
-The specification is the description the AI will build from. Every other artifact descends from it. Anything vague here does not stay vague — it becomes a concrete wrong guess in the code, discovered late. The cheapest moment to remove an ambiguity is now, in a sentence, before anything depends on it.
-
-There is also a diagnostic value: **if you cannot write the spec, you do not yet understand the feature well enough to build it.** The inability to specify is information, not an obstacle to push past.
-
-## Co-specification — how the spec gets made
-
-A specification is not dictated by one side. It is made in three moves:
-
-1. **Diverge — brainstorm by both.** Before drafting, the AI surfaces the *decision space*: the two or three genuine ways to frame the feature, and the open questions it would otherwise resolve by guessing. You react — add, kill, redirect. This is the brainstorm, and it lives in the conversation, not in a new document.
-2. **Converge — the AI drafts, and ranks its own uncertainty.** The AI writes the spec below, then ranks where its confidence is lowest. It does not hand you a flat list of equal-looking assumptions to nod through; it tells you *where it is most likely wrong, and what that would cost.*
-3. **Validate — you decide, with the AI's advice.** You read the ranked uncertainty first, then confirm, correct, or send it back. Your approval is real because your attention was aimed.
-
-The brainstorm leaves a *light trace, not a document.* What you chose becomes a rule; what you weighed and dropped becomes a one-line **`Framings weighed:`** note; what stayed genuinely uncertain becomes a **lowest-confidence flag**. Nothing new to maintain — the residue lands in the spec you were writing anyway.
-
-## What a good specification contains
-
-Four parts, kept short:
-
-1. **Must** — the behaviors the feature is required to perform.
-2. **Reject** — the inputs or situations it must refuse, each paired with a named error.
-3. **After** — the state that is true once it succeeds (what changed).
-4. **Assumptions — lowest-confidence first** — the things you are taking for granted, **ranked so the most-likely-wrong come first.** The top one or two carry a `⚠` flag with *why it is uncertain* and *what it costs if wrong*; the rest are the low-stakes tail. A spec with genuinely nothing uncertain still names its single biggest risk, however small — the AI never claims a blank mind.
-
-Naming the errors matters. "Reject bad amounts" is an instruction to guess; `amount <= 0 -> "amount_invalid"` is a rule that produces a testable scenario and a defined contract response.
-
-### Rule IDs (optional — opt-in by usage)
-
-Give each Must a stable `M<n>:` ID; a Reject's own error code already IS its ID (referenced later as `R:<error_code>`). Once a task uses a tag anywhere in §2 SCENARIOS or §4 TESTS, `add.py check` starts asking that every Must/Reject be covered by a scenario tag or a test's `covers:` line — a task that never tags anything is never retro-flagged. See the template's own inline example for the exact grammar.
-
-## Template
-
-```
-# SPEC.md
-Feature: <name>
-Framings weighed: <chosen> (chosen) · <alternative> · <alternative>
-Must:
-  - <required behavior>
-Reject:
-  - <bad input / situation> -> "<error_code>"
-After:
-  - <what is true once it succeeds>
-Assumptions — lowest-confidence first:
-  ⚠ <most-likely-wrong assumption> — lowest confidence because <why>; if wrong: <cost>
-  - [x] <confirmed / low-stakes assumption> — <one line>
-```
-
-## ▶ Example
-
-```
-Feature: Transfer money between my own accounts
-Framings weighed: synchronous single-currency transfer (chosen) · queued transfer · multi-currency with FX
-Must:
-  - move an amount from one of my accounts to another of mine
-  - amount > 0
-  - source and destination are different accounts
-  - source has enough balance
-After:
-  - source balance -= amount, destination balance += amount
-Reject:
-  - amount <= 0           -> "amount_invalid"
-  - source == destination -> "same_account"
-  - balance < amount      -> "insufficient_funds"
-  - account not mine      -> "forbidden"
-Assumptions — lowest-confidence first:
-  ⚠ same currency only (no FX) in v1 — lowest confidence because the ticket never said; if wrong: the whole amount/rounding model changes and this contract is wrong
-  - [x] no daily limit in v1 — confirmed: out of scope for v1
-```
-
-The `Framings weighed:` line shows what was considered and dropped, so the chosen shape is a *decision*, not a default. The `⚠` line is the one the stakeholder reads first: the assumption most likely to be wrong and most expensive to get wrong. The flat `[x]` line is real but low-stakes. A reviewer can now spend their attention where it pays.
-
-## The AI's role here
-
-Use the AI to **open the space and then narrow it honestly.** First it brainstorms the genuine framings with you (diverge). Then it drafts the spec from whatever raw material you have — a ticket, an interview, a contract document — listing every assumption it had to make, **ranked lowest-confidence first**, and flagging the one or two it is least confident in with *why* and *what it costs if wrong*. Its instinct is to fill gaps silently and present a confident wall; the method forces those gaps into the open, and forces the confident wall to declare its own soft spots. See `playbook/1_specify.md` in [Appendix B](./appendix-b-prompts.md).
-
-The defining instruction: *if a requirement is unclear, ask — do not resolve it by guessing — and of the things you must assume, say plainly where your confidence is lowest.*
-
-## Common mistakes
-
-- **Stating only the happy path.** The "Reject" list is where most real complexity lives; an empty one usually means it has not been thought through.
-- **Free-text errors.** Errors must be named codes, not sentences, so they can become scenarios and contract responses.
-- **Hidden assumptions.** If an assumption is not written down, it is not confirmed — it is a future bug with a delay timer.
-- **A flat list of "confirmed" assumptions.** Eight equal-looking ticks invite a reflex approval. Rank them; flag the one or two that are load-bearing. An unranked list hides the risk inside the noise.
-- **"Existing behavior" claims without a citation.** An assumption row that asserts "this is how X works today" is describing intent, not code. Any wiring claim or assumption that depends on the current state of an existing path must carry a grep/line citation (e.g. `file.rs:203`) — otherwise it is a future bug in disguise.
-- **Wiring claims that name a symbol, not a caller chain.** Verifying that a function exists is not the same as verifying it is reachable. A wiring claim is only valid when it names the production caller chain from an actual entry point — not just the symbol's location in a file. A function that nothing calls is dead, not wired.
-
-## Exit check
-
-A spec is done when:
-
-- [ ] Every required behavior is stated explicitly.
-- [ ] Every rejection has a named error code.
-- [ ] The success state-change is described.
-- [ ] The assumptions are ordered lowest-confidence first, and the one or two `⚠` flags carry *why* + *cost* — or, for genuinely trivial scope, an honest "none material" that still names the single biggest risk.
-
-The shift from older practice: you no longer pre-confirm every assumption to advance. You confirm that the AI has *ranked* its uncertainty and that you have *engaged the top of the rank.* Stated honestly: the flag makes a genuine review cheap and a lazy one visibly negligent — it cannot force the read. That is the most a lightweight check can buy.
-
-## If the check fails
-
-If you cannot state a rule clearly, the feature is not ready to build. Stop, take the question to whoever owns the requirement, and resolve it. Do not let the AI proceed on an unresolved point — that is the exact failure the whole method exists to prevent.
-
----
-
-## The one approval, and where the flag really lands
-
-In the one-approval flow, you do not approve the spec alone — you approve the whole frozen bundle (spec, scenarios, contract, tests) once, at the contract freeze. So the lowest-confidence flag is **bundle-wide**: at that single decision point the AI leads with *"of everything I'm asking you to freeze, these one or two points are most likely wrong"* — and a flag may point at an uncovered scenario or the contract shape, not only a spec assumption. The ranking you do here in Specify is the first input into that one gate. See [05 Contract](./05-step-3-contract.md) and the `add` skill's `run.md`.
-
----
-
-## When the feature has a user interface
-
-For anything with a UI, extend this step with a quick design: the **user flows** (the happy path and the main alternatives) and **every screen state** — loading, empty, error, and success. Correct logic behind a confusing or incomplete interface is still a poor product, and undesigned states are exactly where an AI will improvise something ugly. In the early **Prototype** stage, this design work is the main event and the code is throwaway (see [10 Stages](./10-setup-and-stages.md)).

package/docs/04-step-2-scenarios.md

@@ -1,90 +0,0 @@
-# 04 · Step 2 — Scenarios
-
-[← 03 Step 1 Specify](./03-step-1-specify.md) · [Contents](./README.md) · Next: [05 Step 3 Contract →](./05-step-3-contract.md)
-
-> **Purpose:** rewrite each rule from the spec as a concrete, pass-or-fail scenario.
-> **Produces:** the **§2 SCENARIOS** block of the task's `TASK.md` (one file per task — what this chapter is the *why* behind; historically a separate `features/<name>.feature`).
-> **Person's job:** decide what "correct" looks like in concrete situations. **AI's job:** draft the scenarios.
-
-> **Part of the specification bundle (v7).** In the default flow these scenarios are drafted by the AI alongside the spec, contract, and failing tests as **one bundle**, approved by a person **once** (the one approval), at the contract freeze — not signed off step by step. This chapter is how to get the scenarios *right*; [05 Contract](./05-step-3-contract.md) is where the bundle is frozen. See [11 Governance](./11-governance.md).
-
----
-
-## Why turn rules into scenarios
-
-A plain rule is still open to interpretation. "Source must have enough balance" leaves open: enough for what, exactly? What happens to the balances when it is *not* enough? A scenario removes the interpretation by pinning a specific situation to a specific expected result.
-
-Scenarios occupy a unique position: they are **readable by people and checkable by machines at the same time.** A product owner can confirm a scenario is what they meant; a test can be generated directly from it. This makes them the bridge between the human-led half of the flow and the machine-led back. They are the single most leverage-bearing artifact in the method, because everything downstream — the tests, and through them the build's definition of success — is generated from them.
-
-## The form
-
-Each scenario has three parts:
-
-- **Given** — the starting situation.
-- **When** — the action taken.
-- **Then** — the result that must follow.
-
-Where a rule also constrains what must *not* change, add an **And** clause to state it. Unwanted side effects are caught by what you assert stays the same, not only by what you assert changes.
-
-## Template
-
-```
-Scenario: <short name>
-  Given <starting situation>
-  When <action>
-  Then <expected result>
-  And <what must remain unchanged>   # when relevant
-```
-
-## ▶ Example
-
-```
-Scenario: successful transfer
-  Given A has 100 and B has 0, both mine
-  When I transfer 30 from A to B
-  Then A has 70 and B has 30
-
-Scenario: insufficient funds
-  Given A has 20, mine
-  When I transfer 50 from A to B
-  Then it is rejected "insufficient_funds"
-  And no balance changes
-
-Scenario: not my account
-  Given account C is not mine
-  When I transfer 10 from C to B
-  Then it is rejected "forbidden"
-```
-
-The `And no balance changes` line is doing real work: it specifies that a rejected transfer must leave the world untouched — a property the AI could easily violate by deducting before checking.
-
-### Tagging back to a rule ID (optional — opt-in by usage)
-
-If §1's Musts and Rejects carry stable IDs (`M1:`, and a Reject's own error code as `R:<error_code>`), tag each `Scenario:` line with the ID(s) it covers, e.g. `# M1, R:amount_invalid`. Once a task tags even one scenario this way, `add.py check` starts confirming every §1 ID is covered by a tag here or a `covers:` line in §4 TESTS — a task that never tags anything is left alone. See the template's own inline example for the exact grammar.
-
-## Cover the edge cases
-
-The transfer above is one domain; the same gaps recur in every domain — an HR leave request, a marketing campaign send, a checkout. Beyond the spec's "Reject" rules, sweep the recurring gaps and add a scenario for each that applies (or rule it out on purpose): boundary, duplicate/idempotent, ownership, stale/out-of-order, partial failure, concurrency, malformed input, limits/volume.
-
-## The AI's role here
-
-Hand the AI the spec and have it draft a scenario for each rule, including the rejection rules. Then read them as the person who owns the requirement: do they describe what you actually meant? Correct any that drift. See `playbook/2_scenarios.md` in [Appendix B](./appendix-b-prompts.md).
-
-## Common mistakes
-
-- **Only happy-path scenarios.** Every "Reject" rule in the spec needs its own scenario, or that rule will never be verified.
-- **Edge cases left to the build.** A boundary, a duplicate, or a partial failure with no scenario becomes whatever the AI happens to code. Sweep the categories above against the task's domain.
-- **Vague results.** "Then it works" is not checkable. The result must be a specific, observable fact ("A has 70").
-- **Forgetting the unchanged state.** For any rejection, assert that nothing changed; otherwise a partial, corrupting failure can pass.
-
-## Exit check
-
-- [ ] Every "Must" rule has at least one scenario.
-- [ ] Every "Reject" rule has at least one scenario.
-- [ ] The edge-case categories that apply to this task's domain have a scenario (or are ruled out on purpose).
-- [ ] Each scenario's result is a specific, observable fact.
-- [ ] Rejections assert what must stay unchanged.
-
-## If the check fails
-
-A rule with no scenario will never be tested, and therefore will never be verified — it is a rule in name only. Either write the missing scenario or remove the rule from the spec. Do not carry an unscenarioed rule into the contract.

package/docs/05-step-3-contract.md

@@ -1,80 +0,0 @@
-# 05 · Step 3 — Contract
-
-[← 04 Step 2 Scenarios](./04-step-2-scenarios.md) · [Contents](./README.md) · Next: [06 Step 4 Tests →](./06-step-4-tests.md)
-
-> **Purpose:** fix the external shape of the feature — interfaces, data structures, names, and error cases — and freeze it.
-> **Produces:** `contracts/<name>.md` (plus a mock and contract tests).
-> **Person's job:** approve and freeze the shape. **AI's job:** generate the first draft, the mock, and the contract tests.
-
-> **The one approval lands here (v7).** In the default flow the AI drafts spec, scenarios, this contract, and the failing tests as **one specification bundle**, and a person gives a **single approval at this freeze**. Freezing the contract is the one human gate of the bundle, not the third of three sign-offs; reject any part and the whole bundle returns to draft (backward correction, not failure). See [11 Governance](./11-governance.md).
-
----
-
-## The decision point of the whole method
-
-This step is the decision point between the human-led and machine-led halves of the flow, and it is what makes everything after it safe.
-
-The reasoning is simple. The AI is allowed to write and rewrite code quickly. That is only safe if there is a stable surface that the rest of the system depends on and that the AI is not allowed to disturb. The frozen contract is that surface. Below it, the code is disposable and can be regenerated freely; above it, nothing breaks, because the shape it depends on does not move.
-
-Freezing the contract is therefore not bureaucracy — it is the precondition for granting the AI real autonomy in the build step. Without it, every regeneration risks silently changing an interface that another part of the system relies on.
-
-## What the contract contains
-
-- **Interfaces** — the endpoints, functions, or messages, with their inputs and outputs.
-- **Data structures** — the request and response shapes, and the persistent schema.
-- **Names** — drawn from the project glossary, so the same concept has the same name everywhere.
-- **Error cases** — the defined failures, using the error codes from the spec.
-
-## Template
-
-```
-# contracts/<name>.md
-<METHOD> <path>   body: { <fields> }
-  200 -> { <success fields> }
-  4xx -> { error: "<code>" | "<code>" }
-Schema: <tables/fields touched, and access pattern>
-Status: FROZEN @ v<n>
-```
-
-## ▶ Example
-
-```
-POST /transfers   body: { fromAccountId, toAccountId, amount }
-  200 -> { transferId, fromBalance, toBalance }
-  400 -> { error: "amount_invalid" | "same_account" | "insufficient_funds" }
-  403 -> { error: "forbidden" }
-Schema: accounts.balance (read + write, must be transactional)
-Status: FROZEN @ v1
-```
-
-Every error code traces back to a rejection rule in the spec, and the schema note (`must be transactional`) flags the one place where correctness depends on more than shape — a hint the verification step will follow up.
-
-## The AI's role here
-
-The AI generates the contract from the spec and design, and additionally produces two things that make the contract enforceable: a **mock server** that returns the contracted shapes, and **contract tests** that pin those shapes. With the mock in place, work that depends on this feature can proceed before the real code exists. See `playbook/3_contract.md` in [Appendix B](./appendix-b-prompts.md).
-
-## The change-request rule
-
-Once frozen, a contract does not change casually. A needed change is a **change request**: you return to [Step 1](./03-step-1-specify.md), adjust the spec, re-freeze at a new version, and come forward again. The AI never alters a frozen contract on its own initiative.
-
-This rule is what keeps the contract trustworthy as a foundation. If it could drift, nothing built on it would be safe.
-
-> **Do:** version and freeze the contract before any implementation.
-> **Don't:** let the build step quietly change an interface to make code easier — that breaks everything depending on it.
-
-## Common mistakes
-
-- **Inconsistent names.** If the contract calls it `fromAccountId` and the schema calls it `src_acct`, the AI will produce subtle mismatches. Use the glossary everywhere.
-- **Undefined errors.** Every failure the spec rejects must have a contracted response, or callers cannot handle it.
-- **Freezing too early or too late.** Freeze once the spec and design are stable — not before they are agreed, and not after code has already been written against an unfrozen shape.
-
-## Exit check
-
-- [ ] Contract is versioned and marked `FROZEN`.
-- [ ] Contract tests pass against the mock.
-- [ ] Every name matches the project glossary.
-- [ ] Every spec rejection has a contracted error response.
-
-## If the check fails
-
-If the contract is not yet stable enough to freeze, the upstream artifacts are not settled — return to the spec or scenarios and resolve what is still open. If a frozen contract later needs to change, treat it as a change request rather than an edit; the discipline is the point.

package/docs/06-step-4-tests.md

@@ -1,85 +0,0 @@
-# 06 · Step 4 — Tests
-
-[← 05 Step 3 Contract](./05-step-3-contract.md) · [Contents](./README.md) · Next: [07 Step 5 Build →](./07-step-5-build.md)
-
-> **Purpose:** turn the scenarios and contract into automated tests, and confirm they fail before any code exists.
-> **Produces:** a failing (red) automated test suite.
-> **Person's job:** set the targets and coverage. **AI's job:** generate the tests.
-
-> **Part of the specification bundle (v7).** In the default flow these tests are drafted by the AI as part of the specification **bundle** (spec · scenarios · contract · tests) and approved by a person **once**, at the contract freeze — the tests are part of what that one approval covers. They still must be **red before the build**. See [11 Governance](./11-governance.md).
-
----
-
-## Why tests come before code
-
-This is the step that operationalizes the second principle — *trust through evidence, not inspection.* The tests written here are how you will judge the AI's code in [Step 5](./07-step-5-build.md). For that judgment to be honest, the tests must exist *before* the code.
-
-The reason is mechanical. If code is written first and tests after, the tests are unconsciously shaped to match whatever the code happens to do — including its mistakes. Tests written first, from the scenarios, are shaped only by the agreed definition of correct. They are an independent standard the code must rise to meet, not a description of what the code already does.
-
-## The must-fail principle
-
-After generating the tests, you run them — and they must **fail**, because no implementation exists yet. This sounds trivial and is not. A test that passes before any code is written is testing nothing; it is a false reassurance that will later wave bad code through. Confirming the suite is "red for the right reason" (a missing implementation, not a broken test) is what makes it genuinely protective.
-
-## What to test
-
-- **One test per scenario** — every scenario from [Step 2](./04-step-2-scenarios.md) becomes an executable test.
-- **Contract conformance** — tests that pin the shapes and error responses from [Step 3](./05-step-3-contract.md).
-- **Edge cases from the spec** — the boundary values implied by the "Reject" rules.
-- **Behavior, not internals** — tests assert what the feature does (the observable result), never how it is implemented, so the code can be regenerated freely beneath them.
-
-## ▶ Example
-
-```python
-def test_successful_transfer():
-    a = account(balance=100, owner=me); b = account(balance=0, owner=me)
-    r = transfer(a.id, b.id, 30)
-    assert r.status == 200
-    assert a.balance == 70 and b.balance == 30
-
-def test_insufficient_funds():
-    a = account(balance=20, owner=me); b = account(balance=0, owner=me)
-    r = transfer(a.id, b.id, 50)
-    assert r.status == 400 and r.error == "insufficient_funds"
-    assert a.balance == 20    # unchanged — the side-effect assertion
-
-def test_not_my_account():
-    c = account(balance=100, owner=someone_else); b = account(balance=0, owner=me)
-    r = transfer(c.id, b.id, 10)
-    assert r.status == 403 and r.error == "forbidden"
-```
-
-Run this now, with no implementation: all three fail. That is the correct, honest starting point for the build.
-
-### Declaring which rule a test covers (optional — opt-in by usage)
-
-If §1's Musts and Rejects carry stable IDs, add a trailing `covers: M1, R:amount_invalid` to a test-plan line to declare which ID(s) that test satisfies. Once any test in a task declares a `covers:` line (or any §2 scenario carries a tag), `add.py check` confirms every §1 ID is covered by a tag or a `covers:` line somewhere — a task that never uses either is left alone. See the template's own inline example for the exact grammar.
-
-## The AI's role here
-
-The AI generates the test suite from the scenarios and contract. Your job is to confirm two things it cannot judge for itself: that each test asserts *behavior* rather than internal detail, and that none of them pass by accident before code exists. See `playbook/4_tests.md` in [Appendix B](./appendix-b-prompts.md).
-
-## Common mistakes
-
-- **Tests that test the implementation.** Asserting on private internals couples the test to one version of the code and defeats disposability.
-- **A green suite before the build.** Means the tests are not actually exercising the missing feature — fix them now.
-- **Skipping the side-effect assertions.** Without `assert a.balance == 20` on the rejection path, a corrupting partial failure passes silently.
-- **No coverage target.** Without a recorded target, coverage can quietly erode during the build.
-- **`should_panic` as a red test.** Marking a test `#[should_panic(expected = "implement in green wave")]` (or the equivalent in any language) passes immediately and stays green while red — it is a lying red. Declare unimplemented paths with `todo!()` (or `unimplemented!()`) so the test actually fails. If a test is intentionally designed to flip from red to green during the build, say so with a comment: `// flip authorized at green wave`.
-- **Collateral tests named by category, not by exact name.** When a spec adds a slash command, a new CLI subcommand, or any other globally-enumerated thing, there is a fixed collateral set of tests that count or enumerate it (e.g. a command-registry count test, a help-text snapshot, an autocomplete positional assert). Pre-list these tests by their **exact test names** in §4 — not categories — so the build agent's edits to those "pre-existing" tests are expected and the count is right. Naming only the category means the agent finds the wrong test or misses one.
-- **Arithmetic not checked against frozen constants.** Before freezing, check that the red suite can reach green: a fixture with N bytes fails a hard-coded M-byte budget if N > M — the suite can never pass. Run the numbers before freeze, and add an additive override (e.g. `set_budget`) when the scenario implies a limit the production constant cannot satisfy in test.
-- **Non-hermetic tests that read real user state.** Tests that call a loader with `None` (defaulting to `~/.helios/settings.json` or the real home dir) become torn-read flakes under a parallel suite and assert nothing useful. Red tests that create or read production paths must redirect them to a temp dir; grep new tests for `home_dir`, `~/.config`, real-path defaults before freeze.
-- **Tests that share a per-machine singleton without isolation.** Background services (embedded servers, filesystem watchers) bind to fixed ports or paths. Tests that start such a service must tear it down, or they collide with a parallel run or an already-running dev instance. If the singleton cannot be isolated, gate those tests as serial (one thread, no parallel execution) and document it.
-
-## Exit check
-
-- [ ] One test exists per scenario.
-- [ ] The suite runs in the pipeline and is **red for the right reason**.
-- [ ] Tests assert observable behavior, not internals.
-- [ ] A coverage target is recorded.
-- [ ] No `should_panic` lying reds — unimplemented paths use `todo!()` or equivalent so they actually fail.
-- [ ] Collateral tests for globally-enumerated things (command counts, help snapshots) are listed by exact name.
-- [ ] Arithmetic checked: the red fixtures can reach green against the frozen constants.
-
-## If the check fails
-
-If a test passes before any implementation, it is a fake test — repair it before continuing, because it is your only independent check on the AI. If the suite is red for the wrong reason (a syntax or harness error), fix the harness first; a build cannot be judged against a broken net.

package/docs/07-step-5-build.md

@@ -1,82 +0,0 @@
-# 07 · Step 5 — Build
-
-[← 06 Step 4 Tests](./06-step-4-tests.md) · [Contents](./README.md) · Next: [08 Step 6 Verify →](./08-step-6-verify.md)
-
-> **Purpose:** have the AI implement the feature so that every failing test passes.
-> **Produces:** working code, plus the evidence that the tests now pass.
-> **Person's job:** direct, in small batches. **AI's job:** implement.
-
----
-
-## The only step the AI leads
-
-This is the step the AI is genuinely good at, and the only one where it should be doing the heavy lifting. It works precisely because the previous four steps removed all the ambiguity: the AI is no longer guessing what to build: it has a spec, a set of scenarios, a frozen contract, and a suite of failing tests that define "done" exactly. Its task is narrow and checkable — turn the suite green.
-
-This is the difference between AIDD and vague-prompt coding. The same agent that produces confident nonsense from "build me a transfer feature" produces correct, bounded code from "make these specific failing tests pass without changing them." The agent did not change; the direction did.
-
-## The build prompt
-
-The instruction is explicit about constraints, because the constraints are what keep the speed safe.
-
-```
-Read SPEC.md, contracts/<name>.md, and tests/<name>_test.py.
-Implement the feature so that EVERY test passes.
-Constraints:
-  - Do NOT change any test.
-  - Do NOT change the contract.
-  - <feature-specific safety rule>.
-  - Stop and ask if any requirement is unclear — do not guess.
-  - Use only packages listed in dependencies.allowlist.
-Report which tests pass and exactly what you changed.
-```
-
-For the running example, the feature-specific safety rule is *"make the balance update atomic — debit and credit occur in a single transaction."* This is the one correctness property the tests alone may not force, so it is named directly to the builder.
-
-See `playbook/5_build.md` in [Appendix B](./appendix-b-prompts.md).
-
-## Work in small batches
-
-Direct the AI one task at a time, and keep each task small enough that its result can be reviewed in full. This is a direct application of the principle *you cannot move faster than you can verify.* A single enormous change that turns the whole suite green at once is not a triumph — it is an unreviewable blob. Small batches keep the verification step (next chapter) tractable and keep a human genuinely in the loop.
-
-## The iteration loop
-
-```
-AI writes code → pipeline runs the tests → some still fail
-   → AI iterates → ... → all green → hand to Verify
-```
-
-The loop is tight and largely autonomous within a task: the AI runs the tests, sees what fails, and adjusts. Your attention is needed at the boundaries — defining the task going in, and reviewing the result coming out — not on each internal iteration.
-
-## The cardinal rule: never change the test to pass
-
-An AI under pressure to make a suite green has an available shortcut: weaken or delete the failing test. This must be forbidden explicitly and caught reliably. A test changed to fit the code inverts the entire method — the code is now judging itself. If you find a test was altered during the build, reject the change outright and re-prompt with the constraint restated.
-
-The same applies to the contract: the build implements *against* the frozen contract and may not edit it. A genuine need to change either is a change request that returns to an earlier step.
-
-## How much autonomy
-
-The autonomy granted in this step should match the evidence and your review capacity (see [11 Governance](./11-governance.md)):
-
-- Where the area is new or risky, the AI proposes and a person reviews every change.
-- Where the contract and tests are solid, the AI generates freely and a person reviews each batch.
-- Only in narrow, well-tested areas, with a full evidence bundle attached, may the AI integrate its own work.
-
-## Common mistakes
-
-- **Batches too large to review.** Shrinks verification to approving without reading.
-- **Letting the AI add unknown dependencies.** The allow-list check in the pipeline should block this automatically; if it does not, the supply-chain risk is real (an AI may invent a plausible package name that an attacker has registered).
-- **Accepting "all tests pass" without reading the change.** Passing tests are necessary, not sufficient — the next step exists for exactly this reason.
-
-## Exit check
-
-- [ ] All tests pass.
-- [ ] Test coverage did not decrease.
-- [ ] No test and no contract was modified by the AI.
-- [ ] No dependency outside the allow-list was added.
-- [ ] The change is small enough to review in full.
-
-## If the check fails
-
-If the AI weakened a test, reject and re-prompt. If it added an out-of-allow-list package, the pipeline blocks it; have the AI find an approved alternative or raise the package for human approval. If the batch is too large to review, ask the AI to split the work and resubmit. Only once the exit check passes does the change proceed to verification.
-
-And in the other direction: if the *verify* gate later finds a confirmed cheat — a tamper, or a build that gamed the green (overfit to the fixtures, vacuous asserts, stubbed-away logic) — the task returns *here* for an honest redo. That return is the **bounded self-heal loop** (see the run chapter): revert the tampered file or de-overfit the code, then advance again. It is capped — after the cap a confirmed cheat HARD-STOPs to the human rather than looping forever, and a gamed green is never auto-passed.

package/docs/08-step-6-verify.md

@@ -1,105 +0,0 @@
-# 08 · Step 6 — Verify
-
-[← 07 Step 5 Build](./07-step-5-build.md) · [Contents](./README.md) · Next: [09 The loop →](./09-the-loop.md)
-
-> **Purpose:** confirm the result is correct and safe to release.
-> **Produces:** a reviewed change with a recorded outcome, ready to release.
-> **Who resolves it:** set per task by the `autonomy:` header. Under `autonomy: auto` (the default) the run resolves the gate on evidence; under `conservative`, or for any residue, it is the human's check. **Security always escalates to a human.**
-
----
-
-## Where trust is actually established
-
-The build produced passing tests. That is necessary but not sufficient. Verification is where a person establishes trust — and the principle governing it is *trust through evidence, not inspection.*
-
-This needs care, because it is easy to misread. "Not by inspection" does not mean "do not look at the code." It means the *basis* of trust is the passing evidence plus a deliberate check of the specific things tests cannot easily catch — not a general impression that the code reads plausibly. Plausibility is exactly the trap: AI code is frequently plausible and wrong. So verification has two parts: confirm the evidence, then check the known non-functional risks.
-
-## Who resolves Verify — the automated quality gate
-
-Verify can be resolved two ways, set per task by the `autonomy:` header (see [governance](./11-governance.md) and the autonomy level):
-
-- **Auto (the default).** When `autonomy: auto`, the run resolves the gate on **evidence** rather than waiting for a person — but only when *all* of these hold — the **same canonical list run.md owns**: every test green, coverage not decreased, no test weakened and no contract edited, the convergence loops dry, the completeness-critic clean, the deep check filled, the earned-green refute-read verdict recorded (the §6 `### Refute-read verdict` field, under auto), and **no residue** (security, concurrency, or architecture). It records `PASS` as *auto-resolved*, naming the run as the accountable owner — an explicit pass, not a skip. This is principle 7: a gate may be resolved by evidence when that evidence is sufficient and the result is logged.
-- **Human.** When `autonomy: conservative`, or whenever the run finds residue it cannot judge, the gate stops for a person; the two parts below are theirs.
-
-**Security is always a `HARD-STOP` and is never auto-passed, at any autonomy level.** The two parts that follow — confirm the evidence, then check the non-functional risks — are what *either* resolver works through; the only question is whether a person or the recorded run signs the outcome.
-
-## Part one — confirm the evidence
-
-Before the build, the task pre-declares its **build expectations** — the observable outcomes a correct build must produce, read off §2's scenarios and §3's contract. Confirm each one here against evidence you can see, not a restated test name: this is what makes the gate check the build is *right*, not merely that the suite is green.
-
-- [ ] All tests pass.
-- [ ] Coverage did not decrease.
-- [ ] No test or contract was altered during the build.
-- [ ] Every pre-declared build expectation is confirmed by real evidence (not merely a green test).
-- [ ] Every §1 Must/Reject rule still traces to a §2 scenario tag or a §4 `covers:` line.
-- [ ] Every symbol §3's contract cites still resolves in the *current* tree, not just at Ground SHA.
-
-If any of these is false, stop here and return to the build; there is nothing to verify yet.
-
-A green suite proves the tests you wrote pass — it says nothing about a rule you never wired a scenario or test to at all. That is a different failure than the ones Part four covers: not a cheated pass, but a rule with no trace of ever being checked. `add.py check` scans every task project-wide for exactly this — a §1 Must or Reject with no §2 scenario tag and no §4 `covers:` line — but that sweep is easy to forget to run. `add.py audit`'s `rule_coverage_gap` notice surfaces the SAME check for the task actually at this gate, the moment it reaches Verify (a task that never adopted the tag convention at all is silently grandfathered, never retro-flagged). Neither blocks the gate; both make an already-real gap impossible to miss.
-
-The second check guards against a quieter kind of drift. §0's Ground SHA anchors the symbols §3's contract cites to the commit they were read at — but code moves *during* the build that follows. Before this gate, re-resolve every one of those symbols against the tree as it stands now, not the Ground SHA snapshot, and record it in §6's **Live-verify evidence** block. A moved or renamed anchor caught here is a one-line note; the same drift left silent is a future reader chasing a line number that no longer means what it did at Ground.
-
-## Part two — check what tests miss
-
-Automated tests are excellent at behavior on defined inputs and poor at a few specific things. Check those by hand, every time:
-
-- **Concurrency and timing.** Is the operation correct when two of them happen at once? Tests usually run serially and miss races.
-  - ▶ *Example: the balance update must be one atomic transaction. Confirm that two simultaneous transfers from the same account cannot both pass the balance check and overdraw it.* This is the single most important check for this feature, and it is the reason the build prompt named atomicity explicitly.
-- **Security.** Are there exposed secrets, injection openings, or unexpected dependencies? AI-generated code is known to hardcode secrets and to pull in packages by plausible-but-wrong names. A security finding is always a `HARD-STOP`, never a waiver — and it escalates only if it is *written down*: `add.py audit`'s `unescalated_security_note` check fires on a **marked** note that slipped through as an auto-gate PASS, but a finding you **never marked** is invisible to the engine, escalated to no one. That is the honest limit of the auto-gate: under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding — the same backstop named for an unrecorded earned-green refute-read.
-- **Architecture conformance.** Does the change respect the layering and dependency rules in `CONVENTIONS.md`? Speed with no architectural check produces a fast-growing tangle that becomes unmaintainable within months.
-
-## Part three — the deep check (do not skim)
-
-Two failures slip straight past green tests. The first is code that is never *wired in* — a new function that nothing calls, an endpoint no route reaches: the tests for it pass in isolation while the feature is, in practice, absent. The second is the opposite — code left *dead* behind a path nothing exercises, quietly rotting. And for a change that produced prose rather than code, the equivalent failure is signing off on a claim you never actually read in full. Plausibility hides all three. So verification carries one explicit requirement beyond the non-functional review:
-
-> Deep check — do not skim. If the task produced code, record that every new symbol is referenced (wiring) and that no new dead/unused code was introduced. If it produced prose or non-code, record a semantic read — what you read in full and what it confirmed. Which path applies is the resolver's judgement; the engine never classifies.
-
-This is *evidence*, not impression: a reference search showing where each new symbol is called, a scan confirming nothing new is orphaned, or — for prose — a note of exactly what was read and what it confirmed. An unfilled deep check is a **shallow verify**, not a pass. The engine cannot judge wiring, dead code, or whether prose was truly read; the resolver records the evidence, and a person (under `conservative`) or the recorded run (under `auto`) signs it.
-
-**The wiring trace is a named step, not a free-form note.** For every new hook, closure, or middleware registered in this task: trace from the process entry point to the call site and record it explicitly — symbol, file, line. A symbol that is only reachable via a test helper or `make_config` but not via the production entry point (e.g. `build_harness_with_dispatcher`, `interactive_mode`) is not wired. This is the third repeated class in production: "runtime-activation-order/silent-noop" — the code exists and the unit tests pass, but the feature is absent in the running program. The wiring trace is how you catch it before a user does.
-
-## Part four — was the green earned?
-
-Passing tests say the code satisfies the cases you wrote down. They do not say it earned that pass honestly — and the mechanical tamper tripwire (Step 6's floor) only catches an *edited* test or contract, not a build that gamed the *unchanged* suite. The same rubric the phase guide carries names what the tripwire cannot see:
-
-A green suite proves the tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite without earning it: src overfit to the test fixtures (special-cased to the literal inputs, not the general behavior §1 asked for), vacuous asserts (tautological — green even against an empty implementation), and real logic stubbed away (the function returns a constant the tests happen to accept). These cheats are invisible to the mechanical tamper tripwire, which only sees edited files. Score them with an adversarial refute-read: an independent reviewer — a subagent under `autonomy: auto` is recommended, the engine never spawns one — prompted to argue the green was NOT earned from outside the build context. This is the verify-gate, whole-suite specialization of run.md's adversarial verify (see run.md), not a new discipline. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — but a first cheat is a chance to redo: a confirmed cheat (mechanical tamper or a reported earned-green failure) enters the bounded self-heal loop — it returns to build for an honest redo, and only after the loop's cap does it HARD-STOP to the human (the loop lives in run.md).
-
-Under `autonomy: auto` there is no human at the gate to confirm the refute-read happened, so the verdict is **recorded** — a `### Refute-read verdict` field in §6 (`Verdict: EARNED | NOT-EARNED`, plus who read it and what they adversarially probed). This closes an honesty gap the auto-gate would otherwise leave open: the method *says* an auto-PASS rests on an earned-green check, but nothing made that check visible. Now `add.py audit` surfaces a verify-or-later task whose verdict block is still a placeholder as `refute_unrecorded` — a **measure, not a gate**: it never blocks the run (a hard gate on this universal completion path would break far too much to justify it, and the engine cannot read whether a self-graded `EARNED` is *true* anyway — only whether it was written). The honest backstop is the same one named for a missed security finding: a human **spot-audit** reading the diff. A `NOT-EARNED` verdict is not a dead end — it routes through `add.py heal` for an honest redo, never an auto-PASS. The discipline this records is simple: under auto, you are the accountable owner of the gate, so you leave the trace of the check you owe.
-
-## Recording the outcome
-
-Every verification ends with exactly one recorded outcome, with an accountable owner — never a silent pass:
-
-| Outcome | Meaning | Allowed when |
-|---------|---------|--------------|
-| `PASS` | all checks met | the normal path |
-| `RISK-ACCEPTED` | proceed with a signed waiver: named owner, linked ticket, expiry date | a non-security gap only |
-| `HARD-STOP` | cannot proceed | any failing test or any security finding |
-
-A security finding is always a `HARD-STOP`; it is never waved through with a waiver. A `RISK-ACCEPTED` outcome is a deliberate, documented decision to ship a known, non-security limitation — not a way to skip the check.
-
-## The verification checklist
-
-- [ ] All tests pass (the evidence).
-- [ ] Every pre-declared build expectation is confirmed by observable evidence.
-- [ ] Every §1 rule traces to §2/§4; every §3-cited symbol still resolves in the current tree.
-- [ ] Concurrency/timing of the risky operation is safe.
-- [ ] No exposed secrets, injection openings, or unexpected dependencies.
-- [ ] Layering and dependencies follow `CONVENTIONS.md`.
-- [ ] Deep check (do not skim): for code, every new symbol is referenced (wiring) and no new dead/unused code was introduced; for prose/non-code, a semantic read is recorded.
-- [ ] The change is approved — by a person, **or** (under `autonomy: auto`, no residue) auto-resolved by the run as the recorded accountable owner.
-- [ ] An outcome is recorded (`PASS` / `RISK-ACCEPTED` / `HARD-STOP`).
-
-## Common mistakes
-
-- **Shipping on plausibility.** Reading the diff, finding it reasonable, and approving — without the evidence and the non-functional review — is the precise failure the method exists to prevent.
-- **Treating a security gap as acceptable risk.** It is a `HARD-STOP`, not a waiver.
-- **Skipping the concurrency check** because the tests are green. Tests rarely exercise simultaneity; this is a manual check by design.
-- **Trusting the green agent's self-reported test count.** A build agent running a filtered suite (e.g. `-E 'test(theme)'`) only sees tests inside the filter. Collateral failures outside the filter — a stale count in `all_commands_in_registry`, an e2e snapshot the agent did not touch — are invisible. The orchestrator's **full-suite rerun is load-bearing**; never skip it on the grounds that the scoped run was green.
-- **User-observable-only failures escalate to the human before exhausting discriminating probes.** When a symptom is only observable by a person (a TCC dialog, a visual flicker, an OS-level prompt), do not respond by running the suite again. Instead, design two or three targeted probes that let the user distinguish cause A from cause B in one interaction each. Three AskUser probes resolve what three blind reruns cannot.
-- **Background-process hangs misdiagnosed as test failures.** A test that never exits is not a failure in the test logic — it is a hang. The diagnosis recipe: background the test process, run `pgrep` to find it, use the platform profiler (`sample <pid>` on macOS, `perf` on Linux) to sample the stack, then `lsof -p <pid>` to see open files. Run an isolation experiment (suspect line on/off, 3×3) before reading any code. Entry-count caps do not bound wall time — a single huge directory or a blocking syscall inside a `spawn_blocking` call can hang indefinitely even when the entry cap is satisfied.
-
-## If the check fails
-
-A failing test or a security finding returns the change to the build step ([Step 5](./07-step-5-build.md)). A non-security limitation may proceed only with a signed `RISK-ACCEPTED` record carrying an owner and an expiry — so the team can find and close it later. Nothing proceeds on an unrecorded decision.