@pilotspace/add 1.16.1 → 2.0.0

package/skill/add/advisor.md

@@ -1,80 +0,0 @@
-# Advisor — spawning one subagent to follow your plan
-
-The **advisor** strategy: spawn a *single* subagent to execute one piece of your plan, then merge
-its verdict back. It is the single-subagent companion to `streams.md` (which pipelines *many* tasks
-in parallel worktrees) — you delegate *one* well-scoped piece and stay in the loop. The engine never
-spawns; this is your call per step.
-
-## When to spawn — and when not
-
-Spawn when the piece is **separable and worth the round-trip**: a broad sweep; an independent adversarial review (the `6-verify` refute-read — fresh context, not graded by the author); a well-scoped batch; or context-offload to a small verdict.
-
-Do **not** spawn for narrow, cheap work — pay the round-trip only when the piece is big or independent enough. When in doubt, do it in-context.
-
-**Prefer the named roster.** Check first whether the piece fits one of ADD's five phase specialists — `add-design` (setup–contract) · `add-build` (tests·build) · `add-verify` (verify·observe) · `add-persona` (fit-persona selection) · `add-advisor` (a consultative second opinion) — before an ad-hoc spawn; each already carries the worker contract below.
-
-## The 3-lens sequential checklist at verify
-
-At Verify, sweep security → concurrency → architecture in order. **Security HARD-STOP ends the checklist** (leave the rest blank). Each lens returns: **CLEAR** · **HARD-STOP** (security only) · **RESIDUE** (concurrency/architecture).
-
-Record it in §6 `### Advisor 3-lens verdict`: **Verdict** (PASS/HARD-STOP) · **Residue** (none or brief) · **Binding** (`yes` for `sensitivity: mechanical` — the engine reads it for `advisor-gate-relax`; `advisory` otherwise).
-
-**Persona for the refute-read.** When the piece is the earned-green refute-read, select a **Code-Reviewer** persona; its findings carry severity markers — 🔴 blocker · 🟡 concern · 💭 note. A persona is advisory: it never lowers a gate (a security finding still HARD-STOPs).
-
-## The plan-following prompt template
-
-Give the subagent the *piece it owns* and a fixed return shape. This reuses `streams.md`'s
-worker-contract tags — identical on any runner; only the spawn adapter (see `streams.md`) changes.
-The `<strategy>` block mirrors the task's §5 as the subagent's PREFERRED path — it self-improves on that plan and reports the strategy it actually used.
-
-```xml
-<objective>
-Execute THIS piece of the orchestrator's plan: {{PIECE}}. You own only this piece — not the
-surrounding decisions. Return a verdict; do not record state.
-</objective>
-
-<persona>
-SELECT the best-fit project persona for this piece and load `.add/personas/{{PERSONA_SLUG}}.md` —
-Identity→your stance · Critical Rules→constraints · Success Metrics→done-bar (streams.md's worker
-contract). No match → a {{DOMAIN}} engineer, correctness over speed; never blocks.
-Work step by step, following the plan:
-1. Load the context files + the persona; confirm you understand the piece you own.
-2. Do the work in small steps, honoring the orchestrator's plan and constraints.
-3. Self-score your result with confidence.md; if any dimension < 0.9, refine before returning.
-</persona>
-
-<strategy>
-The task's §5 plan — the Strategy (ordered batches) order and the Known-problem fixes — is
-your PREFERRED starting path, not a hard rule. Improve on it when a better strategy emerges
-as you build; on done, report the strategy you ACTUALLY used so the orchestrator can update
-§5 for the audit trail.
-</strategy>
-
-<context_files>
-the plan / task files the piece needs (read-only unless the piece says otherwise)
-</context_files>
-
-<return>
-End with a structured verdict the orchestrator parses and RECORDS:
-{ piece, persona, result, evidence, confidence: {per-dimension 0–1}, open_questions }.
-`persona` names the slug you adopted (or `generic`) — the orchestrator records which persona did the work.
-Do NOT run add.py or write any shared state — you propose, the orchestrator records.
-</return>
-```
-
-## Choosing the model — vendor-neutral tiers
-
-Pick the tier from `streams.md`: **mid** for an ordinary piece; **top** for a complex/ambiguous/
-cross-cutting one. The tier→model-id mapping + spawn adapter live there. A stronger model never buys
-back a gate: high-risk scope still escalates.
-
-## The hard rule — delegate, don't abdicate
-
-<constraints>
-The engine never spawns — it's the orchestrating agent's choice. And:
-- the subagent PROPOSES; the orchestrator RECORDS — a worker never runs add.py or writes shared state;
-- delegation never lowers a gate — a SECURITY finding still HARD-STOPs and high-risk scope still escalates, whoever did the work;
-- the subagent returns its confidence.md self-score; a low score means refine or re-spawn, never a pass.
-</constraints>
-
-> Used per step: each phase guide's Advisor hook points here (the per-step hooks).

package/skill/add/compact-foundation.md

@@ -1,40 +0,0 @@
-# Foundation compaction — collapse the stable tail
-
-`fold.md` PREPENDS new learnings (newest-first); foundation compaction COLLAPSES the stable tail of each foundation spec into a rolled-up settled line — keeping PROJECT.md, CONVENTIONS.md, GLOSSARY.md, and MODEL_REGISTRY.md to one screen as the project grows.
-
-You **gather and propose**; the **human confirms**; you then write the settled line. This is a **convention**, not a command — there is no `add.py compact-foundation`. It is DISTINCT from engine `add.py compact <slug>` (the archive recovery-bundle move).
-
-## When
-
-At **milestone close** (after `fold.md`) or **on demand** when a spec has grown past one screen. Always a SEPARATE step from `fold.md`.
-
-## Eligibility
-
-An entry is compaction-eligible **IFF** its milestone is **shipped** (done/archived) **AND** it carries **zero open residues**/deltas. Unshipped or open-residue entries are NOT eligible (`open-residue-version`).
-
-## The ritual
-
-1. **Gather** — collect the stable, shipped, zero-residue tail of the target spec.
-2. **Propose** — draft the per-spec rolled-up settled line and show the human.
-3. **Confirm** — no write happens without confirmation.
-4. **Write** — replace the collapsed tail with ONE settled line at the BOTTOM (newest-first: live records stay on top, settled line anchors at the tail), carrying a git/archive pointer.
-
-## Per-spec rolled-line shapes
-
-- **PROJECT.md §Spec** — `[folded fv N..M]` bullets → `settled fvN–fvM — <theme> (see git)`.
-- **PROJECT.md §Key-Decisions** — shipped rows → `| settled <dateA>–<dateB> | <N> decisions rolled | … | see git |` at the tail.
-- **CONVENTIONS.md** — `(TAG)` learnings → `- settled conventions <range> — <N> rules (see git)`.
-- **GLOSSARY.md** — verbose stable definition → terse canonical line + `(rationale: see git)`.
-- **MODEL_REGISTRY.md** — superseded model rows → `Prior models: <list> (see git)`.
-
-## Preservation
-
-- **Never delete** — summarize and point; a settled line is lossy on prose, lossless on traceability.
-- A git/archive pointer is mandatory (`trail-loss` if dropped).
-- OPEN residues stay live.
-
-## Reject codes
-
-- `open-residue-version` — entry is unshipped or has ≥1 open delta/residue; leave it live.
-- `trail-loss` — the collapse would drop the git/archive pointer or audit summary.
-- `wrong-order` — a record is not newest-first, or the settled line is not at the tail.

package/skill/add/components.md

@@ -1,52 +0,0 @@
-# Components — monorepo and multi-repo slices
-
-Opt-in pillar for a milestone spanning **more than one green bar** — a BE + its
-FE, a shared lib + two apps, services across repos. No components declared =
-byte-identical to a single-codebase project. Full narrative: `17-components.md`.
-
-## Declare (never inferred)
-
-`.add/components.toml`:
-
-```toml
-[component.gateway]
-root      = "apps/gateway"
-green_bar = "pytest + pyright"
-[component.dashboard]
-root      = "apps/web"
-green_bar = "vitest + a11y"
-```
-
-A task binds with a `component: <name>` header → that root joins its §5 Scope,
-and verify holds it to that component's green-bar.
-
-## The loop
-
-1. **Per-component verify.** A bound task must CITE its green-bar in §6 evidence
-   or the gate refuses `component_green_bar_uncited`. The engine never runs the
-   suite — it **surfaces** the component's `verify` command (and records it in §6);
-   you run it (NO-EXEC). The fast lane carries the same `component:` affordance.
-2. **Freeze a cross-component contract.** Declare `[contract.<id>]`
-   (producer + consumers). A task names its role `produces: <id>` / `consumes: <id>`.
-   The producer's freeze (contract→tests) writes the immutable snapshot
-   `.add/contracts/<id>.json`; the consumer pins its hash. A changed re-freeze
-   flags consumers `contract_consumer_stale`; a missing/malformed snapshot
-   HARD-STOPS — never build against an unfrozen shape.
-3. **One milestone, full slice.** A `consumes:` task is HELD from advancing
-   scenarios→contract (`producer_contract_unfrozen`) until the producer's snapshot
-   exists — and `producer_contract_stale` if a live producer re-opened/drifted its
-   §3 (freeze-recency). The FE stays downstream of the frozen BE, in one milestone.
-4. **Across repos — federate.** A consumer repo declares `[federation.<id>]`
-   (`source` + optional `pin`); `add.py federate pull <id>` validates and lands a
-   byte-for-byte copy of the producer's snapshot locally. Fail-loud:
-   unknown id / unreadable source / a `source` escaping the repo's allowlist
-   (`federation_source_escapes`, confined to a repo-root sibling) / invalid
-   snapshot / version mismatch each HARD-STOPS and lands nothing.
-
-## Hold the line
-
-- **Declared, not inferred** — no scanning `apps/*`.
-- **No central server / no shared mutable state** — federation copies an immutable
-  snapshot; each repo keeps its own `state.json`.
-- **No new approval** — engine-enforced gates on the six-step flow, not extra human
-  checkpoints. Per-component ownership/autonomy is the identity story (`streams.md`).

package/skill/add/confidence.md

@@ -1,32 +0,0 @@
-# Confidence — the self-score that aims attention
-
-The **confidence self-score** is an *advisory* check an agent runs on its own drafted artifact — a spec, a contract, a build, or a subagent verdict — *before* presenting it. It sharpens the draft and aims the reader's eye at the soft spots; it is never a gate.
-
-## The six dimensions
-
-Score each 0–1 honestly on the artifact you are about to hand over:
-
-- **Completeness** — did it cover every rule, scenario, and rejection the task asked for?
-- **Clarity** — would the next reader understand it without you in the room?
-- **Practicality** — is it feasible and implementable as written, against the real code?
-- **Optimization** — does it balance correctness, simplicity, and cost — no gold-plating, no corner cut?
-- **Edge cases** — did it name the failure modes, the concurrency, the empty/oversized inputs?
-- **Self-evaluation** — does it carry its own refine step — a way to catch its own mistakes?
-
-If **any** dimension scores **< 0.9**, refine the artifact before presenting, then re-score.
-
-## Where it plugs in
-
-- It **feeds the lowest-confidence flag** (run.md · 1-specify.md): the lowest-scoring dimension is what you surface ⚠-first at the contract freeze.
-- A persistently low score on a risky scope is a signal to **recommend** lowering the autonomy level (auto → conservative / manual; run.md) — the level stays the human's call.
-
-## The hard rule — advisory, never a gate
-
-<constraints>
-The confidence self-score is advisory only — never a gate. It never:
-- auto-pass a verify or block a run — the verify outcome rests on evidence (passing tests, the non-functional review), not a self-assigned number;
-- substitutes for evidence or for the human decision point;
-- is recorded as a score the human "agreed to" — a self-asserted score that gated would only move an unread approval one level up (run.md).
-
-What it MAY do: aim the lowest-confidence flag, trigger a refine pass, and recommend an autonomy adjustment. The gate itself stays evidence-based and human-owned.
-</constraints>

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 open lessons 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 | transcribed bullet at the top |
-| `UDD` | `PROJECT.md` §Users | transcribed bullet at the top |
-| `TDD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
-| `ADD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
-| `persona:<slug>` | `.add/personas/<slug>.md` §Critical Rules / §Success Metrics | 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 `critical-rule` or `success-metric`. 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 parallel + auto; confirm to keep)
-
-Before the lock, surface the **run mode** — autonomy + streams (`run.md` · `streams.md`):
-
-| Run mode | Human gates | Concurrency |
-|----------|-------------|-------------|
-| **sequential · manual/conservative** | contract freeze **and** every Verify | one task; safest |
-| **parallel · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence | `add.py waves` overlaps independent builds behind frozen contracts |
-
-**Propose `parallel + auto`; confirm-to-keep** (or downgrade: `add.py autonomy set conservative --project` + `add.py streams set sequential --project`). 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`.