@pilotspace/add 1.1.0 → 1.2.0

package/skill/add/phases/1-specify.md

@@ -11,42 +11,52 @@ understand the feature — that is information, not an obstacle. Stop and ask.
 
 1. **Diverge** — before drafting, surface the decision space: the 2–3 genuine framings of the
    feature + the open questions you would otherwise guess. Invite the user to add, kill,
-   redirect. (Conversational — no new file. At prototype/poc this collapses to one sentence.)
-2. **Converge** — draft §1, then RANK what you are least sure about (below).
+   redirect. (Conversational — no new file. At prototype/poc this shortens to one sentence.)
+2. **Converge** — draft §1, then RANK where your confidence is lowest (below).
 3. **Validate** — present the ranked uncertainty first; the user confirms, corrects, or sends back.
 
 ## Produce (in TASK.md §1)
 
+<output_format>
 - **Framings weighed** — a one-line trace of what you considered: `X (chosen) · Y · Z`.
 - **Must** — each required behavior.
 - **Reject** — each refused input/situation, paired with a **named error code**
   (`amount <= 0 -> "amount_invalid"`, never "handle bad input").
 - **After** — the state that is true once it succeeds.
-- **Assumptions — least-sure first** — ranked most-likely-wrong → least. The top 1–2 carry a
-  `⚠` flag: `⚠ <assumption> — least sure because <why>; if wrong: <cost>`. The rest are the
-  low-stakes `[x]` tail. Never a flat wall of equal `[x]` ticks — that is what gets rubber-stamped.
+- **Assumptions — lowest-confidence first** — ranked most-likely-wrong → least. The top 1–2 carry a
+  `⚠` flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. The rest are the
+  low-stakes `[x]` tail. Keep the ranking visible — a flat list of equal `[x]` ticks gets approved without reading.
+</output_format>
 
-## The least-sure flag is bundle-wide
+## The lowest-confidence flag is bundle-wide
 
 The single human approval happens once, at the contract freeze, over the whole bundle. So your
-§1 ranking is the FIRST FEEDER into a bundle-level flag the user reads at the seam (`run.md`):
+§1 ranking is the first input into a bundle-level flag the user reads at the decision point (`run.md`):
 *"of everything I'm asking you to freeze, these 1–2 are most likely wrong."* A flag may point at
 a §1 assumption, an uncovered scenario, or the contract shape.
 
 ## AI prompt
 
-> Role: a domain analyst who brainstorms, then asks rather than assumes. Read CONVENTIONS,
-> GLOSSARY, and the user's raw input. First surface 2–3 framings + open questions and let me
-> react. Then produce §1: Framings weighed, every Must, every Reject with a named error code,
-> the After state, and the Assumptions RANKED least-sure first — flag the 1–2 you are least
-> sure about with why + cost. Never resolve an ambiguity by guessing.
+<prompt>
+Role: a domain analyst who brainstorms, then asks rather than assumes.
+Read first: CONVENTIONS · GLOSSARY · the user's raw input.
+Objective: fill §1 SPECIFY with zero ambiguity left for the AI to resolve by guessing.
+Steps:
+  1. Surface 2–3 framings + the open questions; let the user react before you draft.
+  2. Produce §1 — Framings weighed, every Must, every Reject with a named error code, the
+     After state, and the Assumptions RANKED lowest-confidence first.
+  3. Flag the 1–2 where your confidence is lowest, each with why + cost.
+Never: resolve an ambiguity by guessing.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Framings weighed noted; every required behavior stated.
 - [ ] Every rejection has a named error code; success state-change described.
-- [ ] Assumptions ordered least-sure first; the 1–2 `⚠` flags carry why + cost — or an honest
+- [ ] Assumptions ordered lowest-confidence first; the 1–2 `⚠` flags carry why + cost — or an honest
       "none material" that still names the single biggest risk (never a blank "none").
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/2-scenarios.md

@@ -6,6 +6,7 @@ generated from it. Fill **§2 SCENARIOS** in TASK.md.
 
 ## Produce (in TASK.md §2)
 
+<output_format>
 ```gherkin
 Scenario: <short name>
   Given <starting situation>
@@ -15,20 +16,29 @@ Scenario: <short name>
 ```
 
 The `And ... unchanged` clause catches corrupting partial failures (e.g. a balance
-deducted before a check fails). Never omit it on a rejection.
+deducted before a check fails). Include it on every rejection.
+</output_format>
 
 ## AI prompt
 
-> Role: a specification tester. Read §1 and GLOSSARY. Write one scenario per Must
-> and per Reject rule. For every rejection add an And-clause asserting what must NOT
-> change. Results must be specific and observable — never "then it works".
+<prompt>
+Role: a specification tester.
+Read first: §1 · GLOSSARY.
+Objective: one scenario per Must and per Reject rule, each result specific and observable.
+Steps:
+  1. Write one scenario per Must rule and one per Reject rule.
+  2. For every rejection add an And-clause asserting what must NOT change.
+Never: settle for a vague result ("then it works") — results must be specific and observable.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] One scenario per Must rule.
 - [ ] One scenario per Reject rule.
 - [ ] Each result is a specific, observable fact.
 - [ ] Every rejection asserts what stays unchanged.
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/3-contract.md

@@ -1,12 +1,13 @@
 # Phase 3 — Contract (freeze the shape)
 
 Goal: fix the external shape — interfaces, data, names, error cases — and FREEZE
-it. This is the seam that makes the AI-led build safe: below it code is
+it. This is the decision point that makes the AI-led build safe: below it code is
 disposable; above it nothing breaks because the shape does not move. Fill
 **§3 CONTRACT** in TASK.md.
 
 ## Produce (in TASK.md §3)
 
+<output_format>
 - Interfaces (endpoints/functions/messages) with inputs/outputs.
 - Request/response shapes + persistent schema (note transactional needs).
 - Names drawn from `GLOSSARY.md` (same concept = same name everywhere).
@@ -14,17 +15,22 @@ disposable; above it nothing breaks because the shape does not move. Fill
 
 Then mark `Status: FROZEN @ v1`. Generate a mock + contract tests so dependent
 work can start before the real code exists.
+</output_format>
 
-**The freeze is the one approval.** This seam is where the single human approval lands, over the
-whole bundle (§1–§4). Before asking for it, present the bundle **least-sure first**: the 1–2 points
+**The freeze is the one approval.** This decision point is where the single human approval lands, over the
+whole bundle (§1–§4). Before asking for it, present the bundle **lowest-confidence first**: the 1–2 points
 most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`) — aim the human's
-eye before they freeze. See `run.md`.
+eye before they freeze. Open that report with the ARC (goal · done · plan) per `report-template.md` so the
+human sees the goal this freeze serves and the plan beyond it, not just the bundle. See `run.md`.
 
 ## The freeze review checklist
 
 The human's one minute, aimed. Walk these six before saying yes:
 
-- **⚠ flags first** — read the least-sure flags; accept each knowing its cost if wrong.
+- **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong.
+  The engine refuses an unflagged freeze before build: a frozen §3 with no well-formed
+  lowest-confidence flag is rejected (`unflagged_freeze`), and `audit` re-checks it on every
+  record that crossed.
 - **Intent** — does §1 say what you actually want built (and is anything you expected missing)?
 - **Cases** — does every Must and Reject have an observable §2 scenario you care about?
 - **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
@@ -32,24 +38,31 @@ The human's one minute, aimed. Walk these six before saying yes:
   `risk: high · autonomy: conservative` in the TASK.md header — the engine refuses an unguarded completion.
 - **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?
 
-This checklist AIMS the one approval — never a second gate, no sign-off forms, no
+This checklist AIMS the one approval — the freeze stays the only gate: no sign-off forms, no
 extra documents. Reject any line and the bundle goes back to draft; that is
 backward-correction, not failure.
 
 ## AI prompt
 
-> Role: an interface architect; frozen contracts are immutable. Read §1, §2,
-> GLOSSARY. Produce §3: interfaces, shapes, schema named from the glossary; a
-> response for every Reject code; a mock returning the contracted shapes and
-> contract tests pinning them. Mark FROZEN. No business logic. Never change a
-> frozen contract — a change reopens Specify.
+<prompt>
+Role: an interface architect; frozen contracts are immutable.
+Read first: §1 · §2 · GLOSSARY.
+Objective: produce §3 — the frozen external shape, nothing more.
+Steps:
+  1. Define interfaces, shapes, and schema named from the glossary, with a response for every Reject code.
+  2. Generate a mock returning the contracted shapes and contract tests pinning them.
+  3. Mark FROZEN. No business logic.
+Never: change a frozen contract — a change reopens Specify.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Versioned and marked `FROZEN`.
 - [ ] Contract tests pass against the mock.
 - [ ] Every name matches the glossary.
 - [ ] Every spec rejection has a contracted response.
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/4-tests.md

@@ -1,4 +1,4 @@
-# Phase 4 — Tests (red safety net)
+# Phase 4 — Tests (failing-first suite)
 
 Goal: turn scenarios + contract into automated tests and confirm they FAIL before
 any code exists. This operationalizes red/green TDD: red now, green only after
@@ -12,10 +12,12 @@ before code exists is testing nothing and will wave bad code through later.
 
 ## Produce
 
+<output_format>
 - One executable test per scenario (§2), asserting **behavior, not internals**.
 - Contract-conformance tests (shapes + error responses from §3).
 - Side-effect assertions on rejection paths (`assert balance unchanged`).
 - A recorded coverage target in §4.
+</output_format>
 
 ## Declaring where tests live
 
@@ -33,17 +35,25 @@ symlink escapes are never read.
 
 ## AI prompt
 
-> Role: a test author who writes tests before code. Read §2 and §3. Turn each
-> scenario into an executable test; add contract-conformance and edge-case tests;
-> run the suite and confirm it fails for the right reason. Record a coverage
-> target. Do NOT implement the feature. Never assert on internals.
+<prompt>
+Role: a test author who writes tests before code.
+Read first: §2 · §3.
+Objective: a red suite that fails for the right reason — behavior, not internals.
+Steps:
+  1. Turn each scenario into an executable test.
+  2. Add contract-conformance and edge-case tests.
+  3. Run the suite and confirm it fails for the right reason; record a coverage target.
+Never: implement the feature, or assert on internals.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] One test per scenario.
 - [ ] Suite runs and is **red for the right reason**.
 - [ ] Tests assert observable behavior.
 - [ ] Coverage target recorded.
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/5-build.md

@@ -19,18 +19,25 @@ change request back to Specify. Honor the feature-specific safety rule named in
 
 ## AI prompt
 
-> Read §1, §3, §4, and CONVENTIONS. Make EVERY failing test pass, one small batch
-> at a time. Constraints: do NOT change any test; do NOT change the contract; honor
-> the §5 safety rule; use only allow-listed packages; stop and ask if unclear.
-> Report which tests pass and exactly what changed.
+<prompt>
+Role: implement the feature so EVERY failing test passes — the build phase.
+Read first: §1 · §3 · §4 · CONVENTIONS.
+Objective: every §4 test green, one small batch at a time.
+Steps:
+  1. Make EVERY failing test pass, one small batch at a time, honoring the §5 safety rule.
+  2. Report which tests pass and exactly what changed.
+Never: change a test or the contract; use a package off the allow-list; or push past something unclear instead of asking.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] All tests pass.
 - [ ] Coverage did not decrease.
 - [ ] No test and no contract modified by the AI.
 - [ ] No dependency outside the allow-list.
 - [ ] Change small enough to review in full.
+</exit_gate>
 
 ## Next
 

package/skill/add/phases/6-verify.md

@@ -1,4 +1,4 @@
-# Phase 6 — Verify (evidence + blind-spot checks)
+# Phase 6 — Verify (evidence + non-functional review)
 
 Goal: establish trust and record an outcome. Passing tests are necessary, not
 sufficient. Fill **§6** in TASK.md including the GATE RECORD.
@@ -31,8 +31,28 @@ If any is false, stop and return to Build — there is nothing to verify yet.
   note reviewed by the auto-gate is an audit finding (`unescalated_security_note`).
 - **Architecture** — does it respect layering/dependency rules in CONVENTIONS.md?
 
+## Part three — the deep check (do not skim)
+
+Green tests prove behavior on the inputs you thought of. They do not prove the change
+is *wired in*, nor that you did not leave a dead end behind — and for a non-coding change
+they prove nothing about whether you actually *read* the thing you signed off. So one more
+requirement, every gate:
+
+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.
+
+Record it in the §6 **Deep checks** block — where each new symbol is called (a reference
+search), the dead-code scan result, or the prose you read in full and what it confirmed.
+An unfilled Deep checks block is a **shallow verify**, not a PASS.
+
 ## Record exactly one outcome (no silent pass)
 
+When you present this gate to the human, open with the ARC (goal · done · plan) per
+`report-template.md`, and reconcile its FLAGS with `add.py report --decide`'s open-item count
+before the ask — per that file's reconcile rule (verify is where a flag-vs-digest mismatch bites).
+
 | Outcome | When |
 |---------|------|
 | `PASS` | all checks met |
@@ -41,8 +61,10 @@ If any is false, stop and return to Build — there is nothing to verify yet.
 
 ## Exit gate / Next
 
-- [ ] Evidence confirmed, blind-spots checked, outcome recorded — a person approved, or
+<exit_gate>
+- [ ] Evidence confirmed, non-functional risks checked, outcome recorded — a person approved, or
   (under `autonomy: auto` with no residue) the run auto-resolved as the accountable owner.
+</exit_gate>
 
 ```bash
 python3 .add/tooling/add.py gate PASS          # marks the task done

package/skill/add/phases/7-observe.md

@@ -6,7 +6,7 @@ about the feature finally appears. Fill **§7** in TASK.md.
 
 ## Do
 
-1. **Release behind a blast-radius limit** — feature flag and/or gradual rollout.
+1. **Release behind a scope-of-impact limit** — feature flag and/or gradual rollout.
 2. **Reuse scenarios as monitors** — the §2 scenarios that defined "correct" now
    define what you alert on: overall error rate, each rejection's rate (a spike in
    one is a signal), latency of the risky operation under load.
@@ -15,16 +15,24 @@ about the feature finally appears. Fill **§7** in TASK.md.
 
 ## AI prompt
 
-> Role: a reliability analyst feeding the next cycle. Read telemetry, objectives,
-> incidents. Report error-budget burn; cluster errors and surface the top
-> real-world failures; draft a SPEC delta with evidence links. Never auto-roll-back
-> — recommend; a human owns the production decision.
+<prompt>
+Role: a reliability analyst feeding the next cycle.
+Read first: telemetry · objectives · incidents.
+Objective: turn what production shows into the next SPEC delta.
+Steps:
+  1. Report error-budget burn.
+  2. Cluster errors and surface the top real-world failures.
+  3. Draft a SPEC delta with evidence links.
+Never: auto-roll-back — recommend; a human owns the production decision.
+</prompt>
 
 ## Exit gate
 
+<exit_gate>
 - [ ] Released behind a flag/rollout.
 - [ ] Scenario-based monitors live.
 - [ ] A reviewed spec delta captured (becomes the next `new-task`).
+</exit_gate>
 
 ## Next
 

package/skill/add/report-template.md

@@ -1,19 +1,59 @@
-# Chat reports — the seam template (for the AI, not for add.py)
+# Chat reports — the decision-point template (for the AI, not for add.py)
 
 The engine renders artifacts (`report`, `report --decide`, `status`); this file
 governs the CHAT MESSAGE you wrap around them. The digest is the artifact BEHIND
 your presentation, never a replacement for it — and your prose is never a
 replacement for the digest.
 
-Use it every time you report at or near a decision seam: an intake proposal, a
-bundle/front approval, a verify gate, a task completion, a milestone close.
+Use it every time you report at or near a decision point: an intake proposal, a
+bundle approval, a verify gate, a task completion, a milestone close.
+
+## The decision arc — rendered first, above the five blocks
+
+Every report at a human gate opens with the **ARC** — three labelled lines that
+place the decision in the work's whole arc, so the human confirms with sight of
+where this is going, not just the step in front of them. Render it first, then a
+separator, then the unchanged five blocks below:
+
+```
+ARC  goal: <the milestone / project goal this decision serves>
+     done: <proven progress — tasks done · exit-criteria met · what this gate proves>
+     plan: <this gate → the next step → the goal>
+```
+
+- **goal** — the milestone or project goal the decision serves, read from the
+  `m-goal` line in `add.py status`; never re-typed from memory.
+- **done** — proven progress only: exit-criteria met/total and tasks done from
+  the rollup, plus what this gate proves. An honest fact, never a hope.
+- **plan** — this gate → the next step → the goal, mirroring the rollup's
+  `DECIDE NEXT` line.
+
+The arc is required at every human gate: **baseline-lock · contract-freeze ·
+verify · intake · scope · milestone-close · graduation**. The three labels stay
+constant; their content adapts to the gate. The arc is presentation only — it
+adds no gate and changes no PASS / RISK-ACCEPTED / HARD-STOP / freeze outcome.
+
+Its facts are engine-sourced, exactly like EVIDENCE below: goal = `m-goal` ·
+done = exit-criteria met/total + tasks done · plan = `DECIDE NEXT`. If your arc
+and `add.py` output disagree, the engine wins — fix the arc, not the engine.
+
+### Per-gate examples — one shape, gate-specific content
+
+- **verify** — `goal:` ship the decision arc · `done:` report-arc tests 6/6
+  green, gate ready · `plan:` PASS this gate → wire the arc into every gate → goal.
+- **contract-freeze** — `goal:` … · `done:` bundle drafted, lowest-confidence
+  flag surfaced · `plan:` freeze §3 → build → goal.
+- **milestone-close** — `goal:` … · `done:` exit-criteria 3/3 met, all tasks
+  done · `plan:` close → archive → the next milestone.
+- **intake** — `goal:` the sized request · `done:` classified new-major,
+  rationale stated · `plan:` create the milestone → first contract → goal.
 
 ## The five blocks, in order
 
 ```
 SUMMARY   one line: intent + target + where we are
 DECISION  what you need from the human (or "none — FYI")
-⚠ FLAGS   least-sure first, why + cost-if-wrong
+⚠ FLAGS   lowest-confidence first, why + cost-if-wrong
 EVIDENCE  small table: tests · gates · parity · check — engine-sourced
 NEXT      the single next action + what it unlocks
 ```
@@ -24,7 +64,7 @@ NEXT      the single next action + what it unlocks
 2. **DECISION** — the question the human must answer, stated plainly; exactly
    one decision per report, or an explicit "none — FYI". If a decision exists,
    ask it AFTER everything below has been shown (show-before-ask).
-3. **⚠ FLAGS** — least-sure first, each with *why* it is least sure and the
+3. **⚠ FLAGS** — lowest-confidence first, each with *why* confidence is lowest and the
    *cost if wrong*. Where TASK.md markers exist (`⚠` / `- [~]` / `- [ ]`),
    quote them verbatim and keep their document order — extraction ≠ judgment.
 4. **EVIDENCE** — engine-sourced facts pasted from `add.py` output, never
@@ -34,15 +74,33 @@ NEXT      the single next action + what it unlocks
    line when it is right; overrule it only with a stated reason (e.g. planned
    tasks the state file cannot see yet).
 
+**The ask itself** — when block 2's decision becomes a literal question component
+(option picker, numbered menu), compose it as a summary: the detail stays in the
+report above, the question carries intent + what "yes" means + the flag count.
+
 ## Hard rules
 
+<constraints>
 - **Summary-first.** Never bury the decision under a task list or a diff.
 - **Show before ask.** Render the artifact (digest · diff · report) before any
   approval question; the human decides on what they can see.
-- **Never pre-stamp a human seam.** Freeze / gate / lock fields stay DRAFT or
+- **Reconcile the count.** Before the ask, your ⚠ FLAGS must reconcile with
+  `add.py report --decide`'s open-item count. If your prose calls an item
+  resolved while the digest still counts it open, the engine wins — fix the data
+  (the TASK.md markers the digest reads), not the sentence. A report whose flag
+  count disagrees with the engine is the un-transparent gate the ARC exists to close.
+- **Never pre-stamp a human decision point.** Freeze / gate / lock fields stay DRAFT or
   blank until the answer returns: show → ask → stamp → advance. An artifact
   must never claim an approval that has not happened.
-- **One report per seam.** After an approval, point at the frozen artifact —
+- **One report per decision point.** After an approval, point at the frozen artifact —
   do not re-render the whole bundle.
 - **Honest scope.** "Done" means the request, not the last task: report
   "task 2/3", never "done" while approved scope remains.
+- **The question is a summary, never the artifact.** Every approval ask carries
+  two layers: a compact SUMMARY · DECISION · ⚠ FLAGS block sits in chat
+  immediately before the ask (positional), and the question text itself is a
+  summary of two lines at most — intent + what "yes" means + the flag count —
+  pointing at the report above (compositional). The full bundle, diff, or
+  artifact lives only in the chat report; a question that re-carries it buries
+  the decision.
+</constraints>