@pilotspace/add 1.17.0 → 2.1.0

package/skill/add/fold.md

@@ -1,63 +0,0 @@
-# Consolidating lessons — how the foundation self-improves
-
-This **closes the loop**. `deltas.md` lets a task EMIT `open` lessons in OBSERVE; consolidation gathers the confirmed ones into a **versioned foundation**, so `DDD · SDD · UDD · TDD · ADD` sharpen across milestones.
-
-`add.py fold` is **judgment-free**: it only TRANSCRIBES each lesson's captured text into its routed home and bumps the version — it never composes prose and **never self-approves** (running the command records the human's confirmation). Choosing which lessons to keep, and polishing raw bullets into lean prose (the **compaction door**, `compact-foundation.md`), stay the human's work.
-
-## When to consolidate
-
-At **milestone close**, or on demand when opens pile up. One `add.py fold` = ONE session: one `foundation-version` bump, every resolved lesson stamped with it.
-
-## The ritual
-
-1. **Gather** — `add.py deltas` reads every task's OBSERVE block for lessons still `open`.
-2. **Confirm** — mark any lesson you do NOT want `rejected` (left in place); running `add.py fold` over the rest IS your confirmation.
-3. **Write** — `add.py fold [--task <slug>] [--comp <TAG>]` performs the mechanical write atomically:
-   - flips each selected `open` lesson to `folded` and stamps it `[folded foundation-version N]`;
-   - transcribes each VERBATIM as one bullet at the TOP (newest-first) of its routed section;
-   - prepends one §Key Decisions row (date · what · why · outcome);
-   - bumps `foundation-version` by one.
-   Validate-all-then-write: if any precondition fails the command writes NOTHING.
-4. **Propose & polish** — raw bullets later merge into lean prose (append-only, newest-first) via the compaction door.
-
-## Consolidation routing
-
-| competency | consolidates into | how |
-|------------|-----------|-----|
-| `DDD` | `PROJECT.md` §Domain | transcribed bullet at the top (newest-first) |
-| `SDD` | `PROJECT.md` §Spec | same |
-| `UDD` | `PROJECT.md` §Users | same |
-| `TDD` | `CONVENTIONS.md` §Method learnings | same |
-| `ADD` | `CONVENTIONS.md` §Method learnings | same |
-| `persona:<slug>` | `.add/personas/<slug>.md` §Critical Rules / §Success Metrics / §Anti-patterns / §Abilities | dated bullet at top; schema stays conformant |
-
-A `persona:<slug> · <hint>` lesson routes into that persona doc, not a foundation file; it is still flipped `folded` and still bumps the version once (`deltas.md`).
-
-## Status transitions & version
-
-- **confirm** `open` → `folded`; **decline** `open` → `rejected` (left in place — auditable trail).
-- Consolidation is **append-only (newest-first)** — PREPENDS, never silently rewrites, EXCEPT via the recorded compaction door.
-
-## Reject codes
-
-<reject_codes>
-- `no_open_deltas` — nothing is `open` in the selected scope. Version is NOT bumped.
-- `missing_route_section` — a lesson routes to a foundation section that does not exist. Add the section header, then re-run. Nothing is written.
-- `no_foundation_version` — `PROJECT.md` carries no parseable `foundation-version:` marker to bump.
-- `missing_persona_target` — a `persona:<slug>` lesson with no `.add/personas/<slug>.md`. Fail-closed: nothing written, no bump. Seed the persona first.
-- `persona_section_unroutable` — the section hint is not one of `critical-rule | success-metric | anti-pattern | ability`. Nothing is written.
-- `persona_clobber_forbidden` — INVARIANT: a persona consolidation prepends only; it never drops existing content or breaks the schema.
-</reject_codes>
-
-Retired: `unconfirmed_fold` · `unroutable_delta` — running `add.py fold` IS the confirmation; a missing destination is `missing_route_section`.
-
-## Worked example
-
-The `competency-deltas` task closed its OBSERVE with two lessons:
-
-```
-- [ADD · open] dogfood .add/tooling can silently diverge from canonical (evidence: md5 mismatch)
-- [TDD · open] structural tests guard canonical artifacts but not their dogfood twins (evidence: this build)
-```
-
-The human runs `add.py fold`: both transcribe into `CONVENTIONS.md` §Method learnings, a §Key Decisions row is prepended, both flip to `folded`, and `foundation-version` bumps 1 → 2 — one atomic write.

package/skill/add/graduate.md

@@ -1,39 +0,0 @@
-# Stage graduation — propose the move to production as a roadmap, never a flip
-
-A project graduates when the MVP is genuinely covered AND a human-confirmed roadmap of production work exists. This is the **4th scope level** — after setup, intake/scope, and the milestone loop. It turns the bare `add.py stage` flip into the **final step** of an analytics-driven, interview-led orchestration.
-
-You **gather and propose**; the **human confirms and judges**; the engine only counts tallies and enforces the floor. The engine never decides "ready" — that is judgment, and it belongs to the interview.
-
-## The cue
-
-When every milestone is `done` AND the human's stage-goal-criteria in `PROJECT.md` are all `[x]`, `add.py status` prints:
-
-```
-  → MVP covered → propose graduation
-```
-
-Before both tallies complete, status is silent. A project with no stage-goal-criteria block is grandfathered — zero change.
-
-## The flow
-
-1. **Gather** — run `add.py graduation-report` (`--json` to branch on it). Clusters the MVP loop's evidence: open deltas by competency · open RISK-ACCEPTED waivers · RETRO records · verify residue · observe-loop coverage gaps. Gathers, never judges.
-2. **Co-specify interview** — synthesize *"what production means HERE"* WITH the human, using the gathered records as the agenda. Interview to real confidence — do not guess what "production-ready" means for this project.
-3. **Draft the roadmap** — for each production outcome the interview surfaces, draft a production milestone: `add.py new-milestone <slug> --stage production --goal "…"`, then write its exit criteria. The roadmap is **≥1** milestone containing the hardening work (SLOs, rollback tests, incident runbooks).
-4. **Human confirms** — present the roadmap via `report-template.md`, opening with the ARC (goal · done · plan). Render as a guided choice (per `report-template.md`). Nothing advances on an unconfirmed draft.
-5. **Flip — the final step** — only now run `add.py stage production`. Because ≥1 production milestone now exists, the guard passes and the transition is recorded.
-
-## The floor
-
-`add.py stage production` is **guarded**: refuses with `stage_no_roadmap` when zero milestones have `stage: production`. The check is a tally, never a readiness judgment. `--force` overrides for grandfathered/edge cases.
-
-Guard is on the `→production` transition only. Flips to prototype/poc/mvp are unchanged. `add.py init --stage production` is an explicit at-creation declaration — out of scope of the guard.
-
-## Invariants
-
-- **The flip is the final step**, never called outside this confirmed-roadmap path.
-- **No auto-flip.** Every step is human-confirmed; the engine gathers, counts, and enforces the floor — it does not advance the stage on its own.
-- **The flow is continuous, not cue-reentrant.** Once you draft the first production milestone, `status` stops printing the cue. Do NOT re-await the cue; carry straight through to confirm and flip.
-
-## Depth and reuse
-
-The same orchestration serves prototype→poc and poc→mvp; **mvp→production** is the rigorous proof case. At lower stages, run it light — same shape, less depth.

package/skill/add/phases/0-ground.md

@@ -1,64 +0,0 @@
-# Phase 0 — Ground (the real codebase)
-
-Goal: before you specify, gather the REAL working folder the task touches — files, symbols,
-signatures, docs, config, data, conventions — so the contract/tests/build are grounded in what
-exists, not assumed. Fill **§0 GROUND** in TASK.md: a per-task preamble to the seven steps,
-**AI-owned** — no human gate (the one approval stays at the §3 freeze).
-
-If you cannot name the files and symbols the task touches, you do not yet understand it —
-gathering them IS the job.
-
-## Gather (in TASK.md §0)
-
-- **Touches** — the real files · symbols · signatures the task reads or changes, named from the
-  actual code (code-navigation tools — grep / symbol search, never memory). Each as `path:symbol — what it is / how keyed`; cite the **symbol**, not a bare line number (`l.NNN` rots at build; symbols survive).
-- **Context (working folder)** — NON-code artifacts touched: docs/textbase (`*.md`) · TODOs (`TODO`/`FIXME`) · config/manifests (`pyproject`/`package`/CI) · data/fixtures. Task-delta only.
-- **Honors** — patterns/conventions the work must respect, cited from `PROJECT.md`/`CONVENTIONS.md`. Task-delta only — never re-derive the architecture.
-- **Anchors the contract cites** — the specific symbols §3 CONTRACT will name. The contract may cite only anchors that appear here.
-- **Issues/Risks (→ feed §1)** — concrete problems · traps · untestable risks you find in the real code while grounding; §1 SPECIFY builds on these, not on assumptions. Task-delta only.
-- **Related intent** — the WHY: `PROJECT.md §` · `GLOSSARY` term(s) · the originating request/milestone rationale (intent, not Honors' conventions). Task-delta.
-- **Ground SHA** — the commit you grounded against (`git rev-parse --short HEAD`); any line ref is "as of" it. `check` warns on a §0 that cites line numbers with no SHA.
-
-**How:** sweep BROAD cheaply (small-model subagent / fast index / skim → compact map), then DEEPEN on what THIS task needs — don't lock a shallow pass.
-
-## Greenfield / first task
-
-The first task runs ground too. With little/no code (greenfield) or mid-setup, your grounding IS
-the foundation docs / brownfield scan you produced — point at them, don't re-scan. An honest
-"new module, no code; honors CONVENTIONS.md §X" is complete.
-
-## AI prompt
-
-<prompt>
-Role: an engineer who reads the real code before designing against it.
-Read first: PROJECT.md · CONVENTIONS.md · the files the task touches.
-Objective: fill §0 GROUND from the codebase — files/symbols/signatures + conventions + the
-anchors §3 cites + issues/risks found; never assumed.
-Steps:
-  0. Sweep broad cheaply (small-model subagent / fast index / skim), then deepen task-specifically.
-  1. Locate the files/symbols the task reads or changes (code tools, not memory).
-  2. Record signatures/keying; cite conventions (task-delta); note risks for §1; name §3's anchors.
-Never: invent a file, symbol, or signature you have not opened.
-</prompt>
-
-## Exit gate
-
-<exit_gate>
-- [ ] **Touches** — the real files/symbols the task touches are named (from the code, not assumed).
-- [ ] **Context** (working folder) — the non-code artifacts touched (docs · config · data) are named, task-delta only.
-- [ ] **Honors** — the patterns/conventions to honor are cited (task-delta; no architecture re-scan).
-- [ ] **Anchors** — the anchors §3 will cite are listed (§3 names only anchors here).
-- [ ] **Issues/Risks** — the problems/risks found are recorded for §1 (or an honest none).
-- [ ] **Related intent** — the PROJECT/GLOSSARY/origin intent is linked (or an honest none).
-- [ ] **Ground SHA** — the commit grounded against is recorded (line refs read "as of" it).
-</exit_gate>
-
-**Grounding is complete when** every field is filled from real assets (a `<…>` placeholder = weak;
-all non-optional). Skipping **Context** (beyond code) is the usual silent gap. §3 cites only anchors here.
-
-> **Advisor · Confidence** — a broad sweep is the canonical spawn (advisor.md); self-score before you specify (confidence.md).
-
-## Next
-
-`python3 .add/tooling/add.py advance` → read `phases/1-specify.md`.
-Book: `docs/02-the-flow.md` (the flow; ground is the §0 preamble to the seven steps).

package/skill/add/phases/0-setup.md

@@ -1,103 +0,0 @@
-# Phase 0 — Setup (autonomous draft → one human baseline approval)
-
-Goal: point ADD at a repo and **you** draft the whole foundation — domain, first-milestone scope, first task's contract — then hand the human one decision: the **baseline approval**. Brownfield silent; greenfield keeps a short interview; either way the only gate is `add.py lock`.
-
-## 1 · Zero-touch entry — you run init yourself
-
-No `.add/state.json`? Don't tell the human to initialise — run it yourself. Infer name + stage
-from the repo and **arm the baseline-approval gate** with `--await-lock`:
-
-```bash
-python3 .add/tooling/add.py init --name "<inferred from repo/dir>" --stage <prototype|poc|mvp|production> --await-lock
-```
-
-- `--await-lock` seeds an *unlocked* setup — the engine refuses build or `gate` until you `lock`. A plain `init` is grandfathered-locked (`already_locked` on a later `lock`).
-- name + stage are **your judgment**: throwaway → `prototype`, risky slice → `poc`, narrow → `mvp`, full rigor → `production`.
-
-`init` prints one of two things — **that is your branch**:
-- `brownfield:` → existing code (go to **2a**);
-- no `brownfield:` → empty repo (go to **2b**).
-
-## 2a · Brownfield — map it silently
-
-The code answers what a greenfield interview would ask — **read it instead of asking**. Open `adopt.md`: fill each living-doc from code, never clobber, tag every decision `evidence-grounded` or `guessed`. Ask the human **nothing** here.
-
-## 2b · Greenfield — the 4-lens interview (kept): co-specify at foundation level
-
-An empty repo has no code, so run the short interview — the **co-specify at foundation level** move
-(diverge → converge → validate, as §1 does in `phases/1-specify.md`), lifted to the foundation. Ask one load-bearing question per lens, draft, rank lowest-confidence-first, show the top flag:
-
-| Lens | The one question that unblocks the section |
-|------|--------------------------------------------|
-| Domain (DDD) | The 3–5 core nouns, and the one invariant that must NEVER break? |
-| Spec (SDD) | The first milestone's outcome — and what's explicitly NOT in v1? |
-| Users (UDD) | The primary user and the one job they hire this for? (or "no UI — surface is X") |
-| Decisions | What's already decided that you'd regret re-litigating? (first Key Decision row) |
-
-Ask only the live ones. Rank: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>` — tag thin answers `guessed`.
-
-## 2c · Domain deep-dive — per-drive, across multiple turns (deepens §2b)
-
-| Drive | Deepen |
-|-------|--------|
-| **DDD** (domain) | core nouns → model: entities, invariants, bounded edges |
-| **SDD** (spec) | milestone outcome → behaviors and explicit non-goals |
-| **UDD** (users) | primary user → jobs, surface, the one flow that must feel right |
-| **TDD** (trust) | what "done & trusted" means: risks to prove, evidence that closes them |
-
-Capture each surfaced decision as an **ADR** in `PROJECT.md` **Key Decisions** as it lands.
-
-**Under `autonomy: auto`, auto-complete all four drives in one pass** — lowest-confidence-first. This deepens **drafting**, never the gate — `lock` stays the one decision.
-
-## 3 · Draft to the lock (both paths)
-
-1. **Fill the living documentation**: `.add/PROJECT.md` (Domain · Spec · UI/UX · Key Decisions), `CONVENTIONS.md`, `GLOSSARY.md`, `MODEL_REGISTRY.md`, `dependencies.allowlist`, and — for a UI project — `DESIGN.md` (delete if no UI; `design.md`). Brownfield: from code. Greenfield: from interview, gaps flagged `guessed`.
-   - **Seed personas** (`.add/personas/`): `init` scaffolds `_template.md` (the schema). **Author one per role** from PROJECT.md + the vendored teacher library `.add/personas-teacher/` (read off-build; engine never fetches) — citing the teacher in `source:` and carrying its top `## Playbook` are the two optional parts, not the authoring. Covered by the **baseline approval**; `add.py check` validates; never clobber. Still unseeded later? `status`/`check`/`new-milestone`'s hint means: return here, draft every missing project persona — not just one.
-2. **Propose, then size it.** Float a **kickoff suggestion** for the first milestone: a **goal** (one sentence), a **flow** (task order), **scenarios** (examples of what ships). Not the frozen `MILESTONE.md`. On their reaction, draft `MILESTONE.md` (read `scope.md`).
-3. **Create the first task and draft its candidate specification bundle.** `new-task` is allowed pre-lock:
-   ```bash
-   python3 .add/tooling/add.py new-task <slug> --title "<first feature>"
-   ```
-   Draft the full bundle **§1–§4** incl. the **§4 red suite** (`phases/4-tests.md`); the lock approves it whole. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` pre-lock, but the engine **refuses build** until you `lock` (`setup_unlocked`). Sequence: **bundle (§1–§4, tests RED) → lock → build** — the red suite must FAIL before build.
-4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every drafted decision, **lowest-confidence-first**, tagged `guessed` | `evidence-grounded`.
-
-## Run mode — how the build will be driven (propose sequential + auto; confirm to keep)
-
-Before the lock, surface the **run mode** — autonomy + streams (`run.md` · `streams.md`):
-
-| Run mode | Human gates | Concurrency |
-|----------|-------------|-------------|
-| **sequential · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence | one task at a time |
-| **sequential · manual/conservative** | contract freeze **and** every Verify | one task; safest |
-
-**Propose `sequential + auto`; confirm-to-keep** (raise the gate: `add.py autonomy set conservative --project`; opt into parallel streaming for a milestone with independent tasks — `add.py streams set parallel --project`, then `add.py waves` schedules the fan-out). Record in **`PROJECT.md` Key Decisions**.
-
-Floor: **one human approval per contract**.
-
-## 4 · The one human gate — the baseline approval
-
-Open the report with the ARC per `report-template.md`, render SHAPE then APPROVE as a guided choice, then present `SETUP-REVIEW.md` lowest-confidence-first. They confirm **once** — an explicit yes; ambient agreement is not a confirmation. **Never self-stamp a timeout — hold, or re-ask.** On that recorded confirmation, you run the lock:
-
-```bash
-python3 .add/tooling/add.py lock --by "<name>"
-```
-
-Typing it themselves stays the **escape hatch** — the decision is the human's; you execute. `lock` writes the lock layers atomically and opens the build.
-
-## 5 · After the lock
-
-- The lock **is** the first task's contract approval — no separate contract-freeze sign-off.
-- Stamp the first task's §3 `Status: FROZEN @ v1`, then read `phases/5-build.md`.
-
-## Exit gate
-
-<exit_gate>
-- [ ] `.add/state.json` exists; setup was seeded unlocked (`--await-lock`) then locked.
-- [ ] Living docs filled (brownfield: from code, tagged evidence-grounded; greenfield: from the interview).
-- [ ] First task created; **§1–§4 drafted — the red suite (per `phases/4-tests.md`) runs RED before build opens**; `.add/SETUP-REVIEW.md` written lowest-confidence-first.
-- [ ] Human confirmed the baseline approval and `add.py lock --by` ran with their name; first task §3 `FROZEN @ v1`; build open.
-</exit_gate>
-
-## Next
-
-After the lock, read `phases/5-build.md` (build is open). Book: `docs/10-setup-and-stages.md`.

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

@@ -1,61 +0,0 @@
-# Phase 1 — Specify (the rules)
-
-Goal: state what the feature MUST do and what it must REJECT, with zero ambiguity
-for the AI to resolve by guessing. Fill **§1 SPECIFY** in TASK.md.
-
-Specify is **co-specification**: brainstorm the shape WITH the user, draft, then validate. If you cannot write the spec, you don't yet understand the feature — stop and ask.
-
-## Co-specify in three moves
-
-1. **Diverge** — surface the decision space: the 2–3 genuine framings + the open questions you'd otherwise guess. Invite the user to add, kill, redirect. (Conversational — no new file; at prototype/poc, one sentence.)
-2. **Converge** — draft §1 answering the §0 GROUND **Issues/Risks**, then RANK where your confidence is lowest (below).
-3. **Validate** — present the ranked uncertainty first; the user confirms, corrects, or sends back.
-
-**Identity is direction, not default (UDD).** Brand color, palette, typeface are human-owned — surface them during Diverge, never assume. For a UI feature with a screen, run the design-definition loop in `design.md`.
-
-## Produce (in TASK.md §1)
-
-<output_format>
-- **Framings weighed** — one-line trace: `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 — lowest-confidence first** — ranked most-likely-wrong → least. The top 1–2 carry a `⚠` flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. Keep the ranking visible — a flat list of equal `[x]` ticks gets approved without reading.
-</output_format>
-
-## The lowest-confidence flag is bundle-wide
-
-The single approval is at the contract freeze, over the whole bundle — so your §1 ranking feeds the bundle-level flag the user reads there (`run.md`): *"of all I'm asking you to freeze, these 1–2 are most likely wrong."*
-
-## AI prompt
-
-<prompt>
-Role: a domain analyst who brainstorms, then asks rather than assumes.
-Read first: CONVENTIONS · GLOSSARY · §0 GROUND Issues/Risks · 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 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>
-
-> **Persona** — load the fit `.add/personas/<slug>.md`; its `## Critical Rules` shape §1 (advisory; never lowers a gate).
-> **Advisor · Confidence** — for an unfamiliar domain, spawn a researcher (advisor.md); self-score the spec and let the lowest dimension aim your ⚠ flag (confidence.md).
-
-## Next
-
-`python3 .add/tooling/add.py advance` → read `phases/2-scenarios.md`.
-Book: `docs/03-step-1-specify.md`. (UI feature? also sketch flows + every screen
-state: loading/empty/error/success; name it in the parent MILESTONE.md's Scope-hint
-vocabulary, not generic prose.)

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

@@ -1,48 +0,0 @@
-# Phase 2 — Scenarios (pass/fail cases)
-
-Goal: rewrite each rule as a concrete Given/When/Then that is readable by people and checkable by machines. Fill **§2 SCENARIOS** in TASK.md.
-
-## Produce (in TASK.md §2)
-
-<output_format>
-```gherkin
-Scenario: <short name>
-  Given <starting situation>
-  When <action>
-  Then <observable result>
-  And <what must remain unchanged>   # REQUIRED for every rejection
-```
-
-The `And ... unchanged` clause catches corrupting partial failures (e.g. a balance
-deducted before a check fails). Include it on every rejection.
-</output_format>
-
-## AI prompt
-
-<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.
-  3. Sweep for the edge cases the spec omits — boundary, duplicate, partial failure, concurrency, malformed input — add one per case that applies, or rule it out on purpose.
-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.
-- [ ] Edge cases the spec omits are covered (boundary · duplicate · partial failure · …) or ruled out on purpose.
-- [ ] Each result is a specific, observable fact.
-- [ ] Every rejection asserts what stays unchanged.
-</exit_gate>
-
-> **Advisor · Confidence** — delegate a wide scenario sweep when the surface is large (advisor.md); score Edge cases honestly — a missing case surfaces there first (confidence.md).
-
-## Next
-
-`python3 .add/tooling/add.py advance` → read `phases/3-contract.md`.
-Book: `docs/04-step-2-scenarios.md`.

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

@@ -1,60 +0,0 @@
-# Phase 3 — Contract (freeze the shape)
-
-Goal: fix the external shape — interfaces, data, names, error cases — and FREEZE it. The decision point that makes the AI-led build safe: below it code is disposable; above it 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).
-- A response for **every** Reject error code from §1.
-
-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.** Present the bundle **lowest-confidence first**: the 1–2 points most likely wrong (`⚠ [spec|scenario|contract|test] … — because …; if wrong: …`). Open with the ARC per `report-template.md`, rendering SHAPE then the freeze APPROVE as a guided choice (recommended pick + alternatives) — **render before `FROZEN`, then record `Reported: yes` in §3; never on a timeout.** See `run.md`. The approval also freezes §5 **Scope (may touch)** + Strategy.
-
-## The freeze review checklist
-
-The human's one minute, aimed. Walk these seven before saying yes:
-
-- **⚠ flags first** — read the lowest-confidence flags; accept each knowing its cost if wrong. The engine refuses an unflagged freeze before build (`unflagged_freeze`); `audit` re-checks it on every record that crossed.
-- **Intent** — does §1 say what you actually want built?
-- **Cases** — does every Must and Reject have an observable §2 scenario?
-- **Shape** — glossary names, error codes, additive vs breaking: is THIS the shape to freeze?
-- **Grounded** — does §3 cite anchors that exist in the §0 GROUND map? `status`/`check` surface this.
-- **Risk** — high-risk or method-defining? Require `risk: high · autonomy: conservative` in the TASK.md header.
-- **Tests** — will §4 go red for the right reason, asserting behavior rather than internals?
-
-Reject any line and the bundle goes back to draft; the freeze stays the only gate.
-
-## AI prompt
-
-<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>
-
-> **Advisor · Confidence** — a second opinion on a risky shape is worth a spawn (advisor.md); a low self-score is your cue to lower autonomy before you freeze (confidence.md).
-
-## Next
-
-`python3 .add/tooling/add.py advance` → read `phases/4-tests.md`.
-Book: `docs/05-step-3-contract.md`.

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

@@ -1,61 +0,0 @@
-# Phase 4 — Tests (failing-first suite)
-
-Goal: tests from scenarios + contract that FAIL before any code exists. Fill **§4 TESTS**; the suite lives in `.add/tasks/<slug>/tests/`.
-
-## The must-fail principle
-
-Run the suite now, with no implementation — **red for the right reason**
-(missing implementation, not a broken harness). A test green before code
-exists is testing nothing.
-
-**A test is any machine-checkable assertion**, not only xUnit code —
-a metric threshold (ML/data), a reconciliation query (data integrity),
-a plan-diff (infra/IaC), a rendered-screen diff (UI). Red-first holds
-for each: the assertion must FAIL before the change exists.
-
-## 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.
-- §6 **Build expectations** filled now, BEFORE build — observable outcomes from §2 + §3.
-</output_format>
-
-## Declaring where tests live
-
-§4's `Tests live in:` line is machine-read: with no local `tests/`, `add.py report`
-counts test functions at the declared backticked paths (FIRST such line only).
-`./…` → this task dir · a token with `/` → the project root · a bare name → a
-sibling of the previous token's dir. A directory counts its `*.py` files
-(non-recursive); a `.py` file counts itself. Resolved files dedupe; declared counts
-marked `†`. Paths are confined: outside the project root counts 0 — `..` traversal,
-absolute paths, and symlink escapes are never read.
-
-## AI prompt
-
-<prompt>
-Role: a test author who writes tests before code.
-Read first: §2 · §3.
-Steps: turn each scenario into an executable test; add contract-conformance and
-edge cases; run the suite red 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>
-
-> **Persona** — let the fit persona's `## Success Metrics` shape the red suite (advisory).
-> **Advisor · Confidence** — spawn a test-author for a broad red suite (advisor.md); score Completeness honestly (confidence.md).
-
-## Next
-
-`python3 .add/tooling/add.py advance` → read `phases/5-build.md`.
-Book: `docs/06-step-4-tests.md`.

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

@@ -1,62 +0,0 @@
-# Phase 5 — Build (AI writes the code)
-
-Goal: implement the feature so EVERY failing test passes — without changing any
-test or the contract. This is the only phase the AI leads; §1–§4 removed all
-ambiguity. Write code into `.add/tasks/<slug>/src/`.
-
-## Work in small batches
-
-Pick ONE task-sized slice, restate its tests, implement, iterate to green.
-Keep each batch small enough to review in full.
-
-## Declaring the scope of impact (Scope + Strategy)
-
-§5 opens with two declarations, drafted with the bundle and frozen by the §3 approval — never invented mid-build:
-
-- **Scope (may touch)** — the allowlist of files the build may write (backticked tokens). A file outside it is a **STOP → change request** back to Specify, never improvisation.
-- **Strategy (ordered batches)** — the planned build order; guidance, not enforced.
-
-Enforced: a completing verify gate refuses an out-of-scope build (`scope_violation` → self-heal).
-
-## Persona overlay (optional)
-
-You may load the active `.add/personas/<slug>.md` as a domain **overlay** atop `SOUL.md` (SOUL = voice/trust; persona = domain **stance**) — name it in §5. SOUL.md is **human-owned**: the overlay never rewrites it (`soul.md`). Advisory — it never lowers a gate; security still **HARD-STOPs**.
-
-## The cardinal rule
-
-**Never weaken or delete a test to make it pass, and never edit the frozen
-contract.** A genuine need to change either is a change request back to Specify. Honor the §5 safety rule (e.g. atomic balance update).
-
-## AI prompt
-
-<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, 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 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.
-- [ ] No file outside the declared §5 Scope was touched.
-- [ ] Change small enough to review in full.
-</exit_gate>
-
-> **Advisor · Confidence** — delegate a well-scoped batch (advisor.md); self-score before presenting green, refine while cheap (confidence.md).
-
-## Next
-
-`python3 .add/tooling/add.py advance` → read `phases/6-verify.md`.
-Book: `docs/07-step-5-build.md`.
-
-> Under `autonomy: auto` Build and Verify run together as one evidence-auto-gated run. See `run.md`.
->
-> **Honest redo.** A confirmed cheat returns the task HERE — revert the tampered file or de-overfit src, then advance again (the bounded self-heal loop, `run.md`; capped, then HARD-STOPs to the human). Never weaken a test or edit the frozen contract to pass.

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

@@ -1,69 +0,0 @@
-# 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.
-
-> **Who resolves this gate depends on the `autonomy:` header.** Under `autonomy: auto` (the default)
-> a run auto-PASSes on complete evidence with **no residue** (security · concurrency · architecture),
-> recorded *auto-resolved* with the named run as owner;
-> **security is always a HARD-STOP and is never auto-passed**. Under `conservative`, or whenever
-> residue is found, this phase is **human-led** (auto-PASS conditions: `run.md`).
-
-## Before you build — declare the build expectations
-
-Fill the §6 **Build expectations** block BEFORE Build: OBSERVABLE outcomes derived from §2 + §3. At this gate, confirm each against real evidence (the `confirmed by` column) — one with no evidence isn't yet verified.
-
-## Part one — confirm the evidence
-
-- [ ] All tests pass.
-- [ ] Coverage did not decrease.
-- [ ] No test or contract was altered during build.
-- [ ] Every §6 Build expectation is confirmed by real evidence (not just a green test).
-- [ ] §1 rules trace to §2/§4 — an untraced rule is a coverage gap (`add.py audit`'s `rule_coverage_gap`; `check` has detail).
-- [ ] every §3-cited symbol still resolves in the CURRENT tree, not just Ground SHA (§6 Live-verify evidence catches a stale/moved anchor here, not later).
-
-If any is false, stop and return to Build.
-
-## Part two — check what tests miss
-
-- **Concurrency/timing** — correct when two run at once? (Tests run serially and miss races.)
-- **Security** — exposed secrets, injection openings, unexpected dependencies. A security finding is always `HARD-STOP`, never a waiver. ANY note here escalates to the human — start it with `NOTE` or `⚠` so `add.py audit` can see it (`unescalated_security_note`). **But that check sees only what you wrote down:** it fires on a *marked* note auto-gated to PASS — a finding you never marked is **invisible**, escalated to no one. Under `auto`, a human **spot-audit** (reading the diff) is the only backstop for a *missed* security finding.
-- **Architecture** — respects layering/dependency rules in CONVENTIONS.md?
-
-Run the three lenses in order — a Security `HARD-STOP` ends the checklist (leave the rest blank). Record in §6 `### Advisor 3-lens verdict` (Verdict · Residue · Binding): `sensitivity: mechanical` → Binding `yes` (engine reads it for `advisor-gate-relax`), every other class → Binding `advisory`. `add.py audit` flags an unfilled block `advisor_verdict_unrecorded`, a companion to `refute_unrecorded`.
-
-## Part three — the 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. The resolver judges which path; the engine never classifies.
-
-Record in the §6 **Deep checks** block — an unfilled one is a **shallow verify**, not a PASS.
-
-## Part four — was the green earned?
-
-A green suite proves tests pass — not that the build EARNED them. Three judgment cheats pass the unchanged suite: src overfit to the test fixtures (special-cased to literal inputs), vacuous asserts (green against an empty implementation), and real logic stubbed away — all invisible to the mechanical tamper tripwire. Score them with an adversarial refute-read: an independent reviewer — the engine never spawns one — prompted to argue the green was NOT earned. A confirmed earned-green failure is HARD-STOP-class: never auto-passed, never RISK-ACCEPTED — a first cheat enters the bounded self-heal loop (run.md). Under `auto`, **record the verdict** in §6's `### Refute-read verdict` block — `add.py audit` flags an unrecorded `refute_unrecorded`, one of three measure-not-block shape lints it surfaces (also `shallow_deep_check` + `risk_unset`).
-
-## Record exactly one outcome (no silent pass)
-
-Present this gate via `report-template.md`'s ARC, render APPROVE, and reconcile FLAGS with `add.py report --decide`'s open-item count. **Human-led: render before `gate` and record `Reported: yes` in §6, never self-stamp.**
-
-| Outcome | When |
-|---------|------|
-| `PASS` | all checks met |
-| `RISK-ACCEPTED` | a **non-security** gap, with signed owner + ticket + expiry |
-| `HARD-STOP` | any failing test or any security finding |
-
-## Exit gate / Next
-
-<exit_gate>
-- [ ] Evidence confirmed, non-functional risks checked, outcome recorded — a person approved, or
-  (under `autonomy: auto`, no residue) the run auto-resolved as accountable owner.
-</exit_gate>
-
-> **Persona** — run the refute-read under the fit persona / Code-Reviewer lens (advisory; security still HARD-STOPs).
-> **Advisor · Confidence** — the earned-green refute-read is the canonical adversarial spawn (advisor.md); score it before recording the gate (confidence.md).
-
-```bash
-python3 .add/tooling/add.py gate PASS          # marks the task done
-# or: add.py gate RISK-ACCEPTED   |   add.py gate HARD-STOP (return to Build)
-```
-Then read `phases/7-observe.md`. Book: `docs/08-step-6-verify.md`.