@pilotspace/add 1.17.0 → 2.0.0

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`.

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

@@ -1,45 +0,0 @@
-# Phase 7 — Observe (feed the next loop)
-
-Goal: release deliberately, watch reality, turn what you learn into the next spec. Fill **§7** in TASK.md.
-
-## Do
-
-1. **Release behind a scope-of-impact limit** — a 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 is a
-   signal), latency of the risky op.
-3. **Draft the next spec delta** — every defect, surprise, or new need becomes a
-   change that re-enters the flow at Specify (a new task).
-4. **Propose a voice delta** — note where your voice diverged from the human's (wordings +
-   flow); propose a confirmable **voice delta** tuning `SOUL.md`, emitted `open`. The human
-   confirms, then you rewrite the routed section. Read `soul.md` (grammar, routing,
-   human-is-only-writer).
-
-> **Decisions (ADR)** — at the gate the engine harvests §7's ADR block (§1/§3/§5/§6); `add.py audit` flags one never harvested.
-
-## AI prompt
-
-<prompt>
-Role: a reliability analyst feeding the next cycle.
-Read first: telemetry · objectives · incidents.
-Steps: 1. report error-budget burn · 2. cluster errors, surface the top real 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>
-
-> **Persona** — tag `· persona:<slug> · critical-rule|success-metric|anti-pattern|ability`;
-> `fold` grows that section — a HOW-an-agent-behaves lesson belongs in a persona, not the shared pile.
-> **Advisor · Confidence** — spawn a reviewer to mine the run for lessons (advisor.md); score Self-evaluation — did this loop teach the foundation? (confidence.md).
-
-## Next
-
-Loop — the artifacts are living docs the next cycle refines.
-Map: `self-improve.md` · book: `docs/09-the-loop.md`

package/skill/add/phases/fast-lane.md

@@ -1,34 +0,0 @@
-# Fast lane — less ceremony, same floor
-
-The fast lane is the **collapsed, opt-in task path for small work**. Same flow — ground → specify →
-contract → tests → build → verify — with fewer sections and the bundle approved in one pass. It
-**collapses** the ceremony; it never drops the floor. The human opts in (`--fast`); the engine never
-guesses that a task is small.
-
-## When
-
-Pick it for a **small, low-risk, roughly single-file change**. Stay on the full lane when the work
-wants its scenarios enumerated — a milestone or release, an architecture or security change, anything
-cross-cutting, or anything you are not yet sure is small. In doubt, run the full lane.
-
-## How
-
-1. `add.py new-task <slug> --fast` scaffolds the minimal `TASK.fast.md` (sections {0,1,3,4,5,6};
-   §2 SCENARIOS and §7 OBSERVE dropped — §1's Accept line carries the behavior a scenario would).
-2. Ground, draft §1 + §3, and **freeze the contract as one batched approval** — the single decision
-   point, led by the lowest-confidence flag.
-3. Write a **red** test (§4), run it failing for the right reason.
-4. Build (§5) to green, then record the **verify gate** (§6).
-
-Both human gates (freeze, verify) render `report-template.md` too — the fast lane collapses
-sections, never the report.
-
-## Floor kept, only collapsed
-
-Three things never move, on either lane: a **frozen** §3 before build · a **red** test before build ·
-a recorded **verify gate** at the end (a security finding is always HARD-STOP). A `--fast` task is
-freeze-gated under ANY milestone — `advance` refuses `contract_not_frozen` while §3 is a draft. Speed
-comes from **fewer sections + auto-gating**, not from cutting any of the three.
-
-Not a way around the contract, the red test, or the gate; not for milestones or releases; not
-engine-chosen — ceremony is human-owned.

package/skill/add/release.md

@@ -1,61 +0,0 @@
-# Release — cut a versioned ship, never an unwatched flip
-
-A project releases when ≥1 **closed milestones** are bundled into a versioned cut whose notes are evidence-backed, risk is disclosed, and behaviour is then watched. This is the **5th scope level** — distinct from milestone (feature-complete), graduation (rigor shift), and stage (mvp→prod).
-
-- **milestone** = feature-complete and consolidated; **release** = shipped + watched.
-- **graduation** changes *rigor*; a **release** ships a *version*. Orthogonal axes.
-
-You **gather and propose**; the **human confirms and ships**; the engine records the cut and enforces a floor — it **never tags, publishes, or deploys**.
-
-## The cue
-
-When ≥1 milestone is `done` AND archived AND not yet attributed to a release, `add.py status` prints:
-
-```
-  → releasable: N milestone(s) closed since last release
-```
-
-That line is a tally over unreleased-but-archived milestones — never a readiness judgment.
-
-## The flow
-
-One arc, seven steps: **cue → gather → draft notes → readiness floor → human confirms → cut → watch.**
-
-1. **Gather** — run `add.py release-report` (`--json` to branch on it). It clusters the cut's evidence: closed milestones since last release · consolidated deltas · open RISK-ACCEPTED waivers · open security HARD-STOP (blocker) · §2 scenarios to take live as monitors. Gathers, never judges.
-2. **Draft notes** — write a [Keep a Changelog](https://keepachangelog.com/) entry from the consolidated deltas + each milestone's goal. Group Added / Changed / Fixed. Propose the **semver bump** (breaking→MAJOR, feature→MINOR, fix-only→PATCH) for human confirmation.
-3. **Readiness floor** — the engine enforces: suite green, zero open security HARD-STOP, every RISK-ACCEPTED waiver signed and disclosed in the notes.
-4. **Human confirms** — present via `report-template.md`, opening with the ARC (goal · done · plan). Render as a guided choice (per `report-template.md`). Never pre-stamp; show-before-ask.
-5. **Cut** — only now run `add.py release <version> --notes <file>`. The engine records: CHANGELOG entry, append-only `RELEASES.md` row (newest-first: date · version · milestones · waivers · evidence), milestone attribution.
-6. **Ship** — the **human** runs the tag / publish / deploy (`git tag`, `npm publish`, deploy pipeline). Engine never performs it.
-7. **Watch** — §2 scenarios become live monitors. A regression re-enters at Specify as a **change request** → PATCH hotfix release.
-
-## The floor
-
-`add.py release <version>` is **guarded** — refuses (non-zero exit, state byte-unchanged) on:
-
-<reject_codes>
-- `release_security_open` — open security HARD-STOP exists. Never shipped. `--force` does NOT override this.
-- `release_build_in_flight` — a build is in flight, ungated.
-- `release_no_closed_milestone` — nothing new since last release.
-- `release_undisclosed_waiver` — a RISK-ACCEPTED waiver rides into the release but is absent from the notes.
-</reject_codes>
-
-`--force` preserves human authority for grandfathered / edge cases (e.g. brownfield first cut) — never overrides `release_security_open`.
-
-## Invariants
-
-- **Engine records; human ships.** `add.py release` writes CHANGELOG + ledger + attribution; never tags, publishes, or deploys.
-- **Security is a HARD-STOP at the cut**, not just at verify. No `--force`, no waiver, no exception.
-- **Notes draw from consolidated deltas** — release after `fold.md` has run. Lifecycle order: `milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
-- **Ledger is append-only (newest-first)** — a release row is never rewritten; a yanked version gets a new row.
-- **A release bundles, it does not equal.** One version may attribute several milestones.
-
-## Depth by stage
-
-- **prototype/poc** — one-line preview note + tag; no deploy ceremony.
-- **mvp** — full notes + tag + guarded publish; watch headline scenarios.
-- **production** — full rigor: notes + tag + deploy behind rollback-tested pipeline + live monitors + error-budget watch. Hotfix path (step 7) is first-class.
-
-## Worked example
-
-The `udd-design-loop` milestone closed (4/4), consolidated into `foundation-version 33`; the human drafted `## [1.5.0]` from those deltas, bumped version sources in lockstep, and `test_release_1_5_0.py` asserted readiness. The `git tag` stayed human-gated; live-registry confirmation gathered *after* the tag as verify evidence, never a unit test.

package/skill/add/scope.md

@@ -1,72 +0,0 @@
-# Scope drafting — turn a classified request into a versioned MILESTONE.md
-
-`intake.md` CLASSIFIES a request into a bucket; scope drafting turns that into a confirmed, well-formed, versioned `MILESTONE.md` through discussion. The MILESTONE.md template is the SHAPE; this rubric is HOW to fill it well.
-
-## What to do per intake outcome
-
-| intake outcome | scope-loop action | creates (after confirm) |
-|----------------|-------------------|-------------------------|
-| `new-major` / `sub-milestone` | draft ONE MILESTONE.md (fill the template via discussion) | 1 milestone |
-| `task` | route to `add.py new-task <slug>` (fits the active milestone) | 0 milestones |
-| `change-request` | route to SPECIFY/CONTRACT of the affected task | 0 milestones |
-| `split_required` | draft ALL N items as a batch in ONE pass | N milestones/tasks |
-
-**Confirm before create is the convention.** "One pass" means one drafting pass, NOT auto-creation — nothing is written until the human confirms; enforced only by the opt-in `--await-confirm` (below).
-
-**Confirm the milestone before detailing tasks.** `new-milestone <slug> --await-confirm` seeds it *unconfirmed* — `new-task` is HELD (`milestone_unconfirmed`) until you show the filled `MILESTONE.md`, get the human's go, and run `milestone-confirm <slug>`. Keeps you from digging into task §0–§5 before the parent is agreed. (Omit the flag: no gate.)
-
-## Position the goal — ground in assets, relate to the milestone map   (do this FIRST)
-
-Before drafting the goal sentence, position the request in what already exists — distinct from intake's classification, not redundant with it.
-
-1. **Ground in current assets.** Read the goal against what exists — the goal must reflect what the project already is. Ground as rigorously as a task's §0 (`phases/0-ground.md`), using the **same four fields** at milestone scope: **Touches** (the subsystems/files the milestone spans) · **Context** (the docs · todos · config · data it works against) · **Honors** (the `PROJECT.md` / `CONVENTIONS.md` invariants it must respect) · **Anchors** (the existing contracts/symbols its tasks will cite). Grounding is complete when each is named from real assets, not assumed. Touches spanning >1 app root (BE+FE, or multiple independently-testable dirs)? weigh `.add/components.toml` (`components.md`) now — before tasks decompose with flat cross-app paths.
-2. **Relate to the milestone map.** Run `add.py search <keyword> [<keyword> ...]` first — then read every existing goal — `.add/milestones/*/MILESTONE.md` and `.add/archive/*` — and name THIS request's relationship: *extends* X · *depends-on* Y · *overlaps* Z. Record in the `rationale` line.
-3. **If the goal is already delivered** by an existing milestone, reject `duplicate_goal` and route as `task` or `change-request`.
-
-## Brainstorm before you draft — co-specify at milestone level
-
-Don't draft from thin input. Run the three-move co-specify (`phases/1-specify.md`) — Diverge → Converge → Validate — raised to milestone scope. Ask only what moves the goal, the In/Out line, or the task list.
-
-Diverge seeds (pick the live ones):
-- **Outcome** — done means a user can do *what* they can't today?
-- **Edge of scope** — nearest thing assumed IN that you want OUT?
-- **Riskiest decision point** — which contract, if wrong, costs the most rework?
-- **Done-looks-like** — how do we SEE each outcome without reading code?
-- **First slice** — which task unblocks the rest?
-
-Rank assumptions lowest-confidence first; top 1–2 get the flag: `⚠ <assumption> — lowest confidence because <why>; if wrong: <cost>`. Present via `report-template.md` — open with the ARC (goal · done · plan), render as a guided choice.
-
-## Drafting a good MILESTONE.md (section by section)
-
-- **goal** — ONE outcome sentence (no "and" — that is two milestones).
-- **rationale** — intake bucket + WHY, AND the milestone relationship from "Position the goal". Never in state.json.
-- **Scope In/Out** — explicit anti-creep deferral list. An empty Out list means scope is not yet thought through. UI/UX scope? use the template's Scope hint vocabulary, not generic prose.
-- **Shared decisions & glossary deltas** — cross-cutting rules every task must honor. New terms get a glossary entry.
-- **Shared / risky contracts to freeze first** — decision points between tasks; name the owning task.
-- **Tasks (breadth-first)** — `slug · depends-on · one line` each. Decompose by deliverable; keep each task one-file-sized.
-- **Exit criteria** — observable; **every exit criterion maps to a declared task slug** (no dangling criterion).
-- **Close — ship review** + **Release steps** — **drafted-blank** here; filled LATER (`milestone-done` and `release.md`). Named so you know the full 9-section shape.
-
-## Draft well-formedness gate
-
-A scope draft is well-formed only when:
-- [ ] goal is ONE outcome sentence (no "and")
-- [ ] every exit criterion maps to a declared task slug (no dangling criterion)
-- [ ] `rationale` records the bucket + milestone relationship from "Position the goal"
-- [ ] `Close — ship review` and `Release steps` are left as the template (drafted-blank)
-- [ ] the In/Out list names what is deferred
-
-Propose only a well-formed draft — an incomplete one lets a milestone reach task breakdown half-formed.
-
-## Reject codes
-
-<reject_codes>
-- `not_classified` — the request has not been through intake. Classify it first.
-- `dangling_criterion` — a drafted MILESTONE.md has an exit criterion that maps to no declared task slug. FIX the draft before proposing.
-- `no_milestone` — intake routed to `task` or `change-request`; create NO milestone.
-- `duplicate_goal` — the goal is already delivered by an existing milestone (live or in `.add/archive/`). Route as `task` or `change-request`, create nothing.
-</reject_codes>
-
-## Worked example
-
-Request: *"open the Interface & Intake milestone"* → intake classified it `sub-milestone` of v4 → scope drafting produced **`.add/milestones/v4-1/MILESTONE.md`**: goal *make ADD harness-drivable and self-scoping*; tasks (breadth-first) `machine-state-json` · `versioning-policy` · `scope-loop`; each exit criterion maps to its slug.

package/skill/add/self-improve.md

@@ -1,20 +0,0 @@
-# Self-improving ADD — the one map
-
-Every loop improves four artifacts. You emit `open`; the human confirms; the engine
-transcribes — nothing self-approves. Emission lives in observe (§7); every earlier step
-feeds it: ground surprises → §1 · the freeze's ⚠ flag → the next spec · a red-suite gap →
-a TDD lesson · build's strategy-actually-used → the ADR block · verify residue → a SPEC delta.
-
-| what improves | grammar (closes `(evidence: …)`) | consolidator |
-|---|---|---|
-| foundation — `PROJECT.md`/`CONVENTIONS.md` | `[DDD\|SDD\|UDD\|TDD\|ADD · open] lesson` | `add.py fold` → `fold.md` |
-| personas — the agents' stances | `… · persona:<slug> · critical-rule\|success-metric\|anti-pattern\|ability` | same `fold` run |
-| `SOUL.md` — your voice | a voice delta, `open` | human rewrite → `soul.md` |
-| the next scope | `[SPEC · open]` → seeded · dropped · carried | `loop.md` → `new-task` |
-
-Routing: `DDD`→§Domain · `SDD`→§Spec · `UDD`→§Users · `TDD`/`ADD`→§Method learnings
-(grammar: `deltas.md`). A HOW-an-agent-behaves lesson → a persona, not the shared pile.
-
-Convergence: `fold` prepends newest-first; the settled tail rolls via
-`compact-foundation.md`; `status` counts the debt — `carried:` · `compaction:`.
-Self-score before emitting — `confidence.md` (six dimensions; < 0.9 → refine).

package/skill/add/sensitivity.md

@@ -1,51 +0,0 @@
-# Sensitivity — the project's risk-class vocabulary
-
-A task declares its risk-CLASS with a `sensitivity:` line in the TASK header — *what
-kind* of risk it carries, distinct from `risk:` (*how much*). The engine validates +
-surfaces the human's declaration; it **never classifies**. Read live by freeze/status/check.
-
-## The base four (method-universal — always apply)
-
-- **security** — authn/authz, secrets, crypto, attack surface. A finding here is HARD-STOP;
-  the human is in the loop in EVERY tier (never advisor-gated, never auto-passed).
-- **data** — persistence, migrations, privacy of stored records, data loss.
-- **architecture** — module boundaries, contracts, cross-cutting structure.
-- **mechanical** — rote, low-impact change (rename, move, format, doc). The only class
-  a recorded advisor verdict (three §6 fields: Verdict · Residue · Binding) can gate for
-  auto-completion (`advisor-gate-relax`).
-
-These four can't be removed — a project only EXTENDS them.
-
-## Extend per project (you maintain this)
-
-Domain risk-classes live in `.add/GLOSSARY.md` under a `## Sensitivity classes` section,
-one `- <token>: <definition>` bullet per line:
-
-```markdown
-## Sensitivity classes
-Base (always apply): security · data · architecture · mechanical
-- pii: personally identifiable information; any task touching it escalates to human review
-- payments: money movement; reconciliation + an audit trail are required
-```
-
-`freeze` then accepts a header `sensitivity:` value from **base ∪ your domain classes**;
-a token in neither is refused `sensitivity_invalid`. `status` prints the active task's
-class; `check` nudges (`sensitivity_classes_unset`, never red) until you declare some.
-
-## The AI's job — keep it current
-
-- When a milestone or task reveals a **new kind of risk** this project carries (a regulated
-  data category, a payment rail, a tenancy boundary), ADD it as a class with a one-line
-  definition — propose it, the human confirms (it is foundation, like a glossary term).
-- **Re-read the section each session** (it rides `GLOSSARY.md`); pick the tightest class
-  when you declare a task's `sensitivity:` at freeze.
-- **Map domain → base behavior** in the definition so downstream gating is unambiguous —
-  e.g. "pii … escalates to human review" pins it as human-floor, not advisor-gatable.
-
-## Hold the line
-
-- **Declared, never inferred** — the engine reads your token; it does not guess a class.
-- **Base four are universal** — domain classes add to them, never replace them; security
-  stays a human floor in every tier.
-- **A comment is never a declaration** — commented-out example bullets don't count; only a
-  real `- <token>:` line under the section is a class.

package/skill/add/setup-review.md

@@ -1,48 +0,0 @@
-# Setup review — the one page the human signs
-
-Autonomous setup ends at a single human gate: the **baseline approval** (`add.py lock`). `SETUP-REVIEW.md` is that page: every decision you made while drafting the foundation, first-scope, and the first contract, **ordered lowest-confidence-first** so the riskiest guesses meet the human's eye first.
-
-The engine never reads this file — `add.py lock` is judgment-free, the signature *is* the gate. The human **reading** this page is the review.
-
-## Where it lives
-
-Write **one** artifact at `.add/SETUP-REVIEW.md`. **Never clobber a human-edited one** — if it already exists with hand edits, append/update, don't overwrite. It sits beside `PROJECT.md`, not under a task.
-
-## The template
-
-```markdown
-# SETUP REVIEW — <project>
-
-<stage> · <brownfield | greenfield> · drafted by <model> @ <date>
-
-| # | Decision | Lands in | Tag | Why / Evidence |
-|---|----------|----------|-----|----------------|
-| 1 | <the drafted decision> | PROJECT.md \| scope \| first-contract | `guessed` | <the inference + why you had to guess> |
-| 2 | <…> | <…> | `evidence-grounded` | <cite the source file/line you read it from> |
-
-Sign: confirm in chat → the agent runs `add.py lock --by "<name>"` (typing it yourself works too)
-```
-
-Rows are numbered for reference at the gate ("row 1 is where my confidence is lowest").
-
-## The two rules that make it honest
-
-<constraints>
-1. **Lowest-confidence-first.** Order rows by confidence **ascending**. A `guessed` row always floats above an `evidence-grounded` one. The top of the table is the part the human actually needs to challenge.
-
-2. **Every row is tagged — `guessed` or `evidence-grounded`.**
-   - `evidence-grounded` — you read it from the code/repo. **Cite the file** (e.g. `pyproject.toml`). Brownfield onboarding (see `adopt.md`) is mostly these.
-   - `guessed` — the repo was silent, so you inferred it. **State the inference and why.** Thin-greenfield onboarding produces these. These are what the human must check; that is why they sit on top.
-
-   The tag vocabulary is shared with `adopt.md` — brownfield map tags flow straight into this table.
-</constraints>
-
-## Where it ends
-
-`SETUP-REVIEW.md` is read-only context for the baseline approval — present it lowest-confidence-first, not field-by-field; the human confirms in conversation; you run the lock:
-
-```bash
-python3 .add/tooling/add.py lock --by "<name>"
-```
-
-`lock` records the lock layers and opens the build — it does **not** parse or validate this file. Make the top of the table the truth they most need.