@pilotspace/add 1.17.0 → 2.0.0

package/docs/09-the-loop.md

@@ -1,75 +0,0 @@
-# 09 · The loop — observe and learn
-
-[← 08 Step 6 Verify](./08-step-6-verify.md) · [Contents](./README.md) · Next: [10 Setup and stages →](./10-setup-and-stages.md)
-
-> **Purpose:** release the verified change, watch how it behaves in reality, and turn what you learn into the next specification.
-> **Produces:** a running feature, observations, and the next `SPEC.md` delta.
-
----
-
-## The flow is a loop, not a line
-
-Older mental models end at "ship." That framing is the source of a common pathology: teams treat release as a finish line, and so they hide defects to protect the line rather than manage them in the open. In AIDD, release is not the end of the flow — it is the point where the most reliable information about the feature finally becomes available: how it behaves with real users, real data, and real load.
-
-That information is the input to the next cycle. What you learn in production becomes the next specification, and the flow returns to [Step 1](./03-step-1-specify.md). The cycle is continuous.
-
-## Release deliberately
-
-Release behind a mechanism that limits the scope of impact of a mistake — a feature flag, a gradual rollout, or both. The verification step established that the feature is correct against everything you anticipated; a controlled release is your protection against what you did not anticipate. If something is wrong, you want to affect a few users and roll back, not affect everyone and scramble.
-
-## Reuse the scenarios as monitors
-
-The scenarios from [Step 2](./04-step-2-scenarios.md) have a second life here. They described the behavior you expected; in production they become the behavior you monitor. The same definition of "correct" that drove the tests now drives the alerts.
-
-**What to watch (▶ example):**
-
-- the overall transfer error rate;
-- the rate of each individual rejection (`amount_invalid`, `same_account`, `insufficient_funds`, `forbidden`) — a sudden spike in one is a signal, not noise;
-- latency, especially of the atomic balance update under load.
-
-## Turn observation into the next spec
-
-Every defect, surprise, or new need is written up as a change to the specification — a delta that re-enters the flow at [Step 1](./03-step-1-specify.md). An error rate that is too high, a rejection that fires more than expected, a user behavior nobody designed for: each becomes a concrete, specified next step rather than a vague intention.
-
-This is also where the AI returns to a useful role: summarizing telemetry, clustering errors into themes, and drafting the proposed spec delta for a person to review. But the production decisions — what to roll back, what to prioritize — remain human.
-
-## The decision record (ADR)
-
-Observe is also where the loop's **decisions** become durable. At the gate the engine harvests §7's **Decisions (ADR)** block from the stamps the task already carries — the §1 framing it chose (and the alternatives it rejected), the §3 contract a person froze, the §5 strategy it actually used, and the §6 gate outcome — tagging each line `[human]` or `[AI]`. It is *harvested, not authored*: the engine writes no decision of its own, only what the task already recorded, so the trail can never drift from what actually happened. The result is one consolidated, auditable record of who decided what — and `add.py audit` flags a done task whose block never harvested (`adr_record_missing`), so the record cannot silently go missing.
-
-## Lessons learned and the retrospective consolidation
-
-A spec delta feeds the *next feature*. But a loop also teaches the **method itself** — that the domain model missed a boundary, that a whole class of scenario was never tested, that a build convention helped or hurt. AIDD captures those as **lessons learned**: a single tagged learning, written in the Observe step, marking which of the five competencies it sharpens.
-
-| tag | competency | a delta here means you learned something about… |
-|-----|------------|--------------------------------------------------|
-| `DDD` | Domain | the domain model — an entity, rule, or boundary the spec assumed wrong |
-| `SDD` | Spec | what the feature must do or reject — a missing or wrong requirement |
-| `UDD` | UI/UX | the user-facing shape — a flow, affordance, or wording that misled |
-| `TDD` | Test | how we prove correctness — a missing scenario, a flaky or hollow test |
-| `ADD` | AI/build | how the AI builds — a harness, prompt, or convention that helped or hurt |
-
-Each delta is one tagged entry — `- [COMPETENCY · status] the learning (evidence: a pointer)` — and the evidence is **required**: a failing scenario, a production signal, a review note. No evidence means it is an opinion, not a delta. The AI **emits** deltas as `open`; it never consolidates its own. Consolidation is judgment, and judgment is the human's — the same verify/observe decision point that keeps the AI from grading its own work.
-
-**The ship review.** Before the consolidation, once a milestone's goal is met, the AI fills the milestone's `## Close — ship review` — the whole-milestone, cross-task evidence a person reads *before* checking the exit-criteria boxes (it is evidence, **not a new gate**). It has three parts: **ship by domain** — what changed in each bounded context (`tooling` · `skill` · `book`); **cross-task evidence** — one row per task (its gate, its tests, any residue); and a **goal-met map** — each exit criterion tied to the evidence that satisfies it. The AI then defines the milestone's **release steps**: the ordered, tool-agnostic hints to ship the milestone, of which `merge` is one small step (a pull request, an exported hand-off document, a tag or a publish are others). Those steps **feed** the release scope, not a second flow. The ritual itself lives in the `add` skill's `loop.md`; this chapter only names it.
-
-**The consolidation.** At milestone close (or on demand, when open deltas pile up), a person runs the retrospective consolidation: **gather** every `open` delta across the milestone's tasks, **group** them by competency, **propose** the exact foundation edit for each, **confirm** with the human one by one, then **write** — append-only, newest-first (the newest record prepended at the top) — flipping each delta to `folded` (merged) or `rejected` (considered and deliberately not merged, left in place so the trail survives), and bumping the `foundation-version:` marker. `DDD`/`SDD`/`UDD` deltas consolidate into the matching section of `PROJECT.md`; `TDD`/`ADD` consolidate into `CONVENTIONS.md` (they sharpen the engine, not the product); and **every** consolidation also prepends one row at the top of `PROJECT.md` §Key Decisions — the universal, auditable record of what the foundation learned.
-
-**Tooling.** `add.py deltas` lists every open delta across the project (so nothing waiting to be consolidated is invisible); `add.py check` lints each delta's well-formedness — known competency tag, valid status, non-empty evidence. `add.py fold [--task <slug>] [--comp <TAG>]` mechanizes the consolidation — flip + transcribe + route + bump, validate-all-then-write so a reject leaves the tree byte-unchanged; running it **is** the human's confirmation, and the engine never self-approves *which* lessons to keep.
-
-**Foundation compaction.** The consolidation *prepends* new learnings; **foundation compaction** is the separate, later step that *shrinks* the result. At milestone close (or on demand, once a foundation spec grows past one screen), the AI proposes collapsing the stable, shipped, zero-residue tail of each foundation spec into ONE per-spec **rolled-up settled line** at the bottom — and the human confirms, one line at a time, exactly as with the consolidation. It never deletes: a settled line summarizes the prose and keeps a `see git` pointer, so the record is lossy on wording but lossless on traceability, and any OPEN residue always stays live. Each spec collapses in its own **per-spec shape** — `PROJECT.md` §Spec version bullets, §Key-Decisions rows, `CONVENTIONS.md` learnings, the `GLOSSARY.md` definition, the `MODEL_REGISTRY.md` rows — under one shared eligibility rule. Because every append-only sequence is **newest-first** (newest record on top), compaction collapses *upward from the bottom*: the settled line anchors at the tail (the oldest end). Like the consolidation it is convention-guided — there is deliberately no `add.py` command for it (read `compact-foundation.md`) — and it is distinct from the engine's `add.py compact <slug>`, which archives a finished milestone's files rather than shrinking a living spec.
-
-## Re-entrancy: the loop is the whole point
-
-Two principles converge here. *The flow is re-entrant* — any step can send you back to an earlier one — and *the flow is a loop* — production feeds the next specification. Together they mean the artifacts you built are never "finished"; they are living documents that the next cycle refines.
-
-A team operating this way does not experience requirements changing as a failure of planning. It experiences it as the system working: reality is teaching the specification, and the specification is teaching the next build.
-
-## The milestone holds until its goal is met
-
-A single feature loops through Observe back to Specify; a **milestone** has the same shape at a larger scale, and a gate to match. A milestone is not finished when its tasks are done — it is finished when its **goal** is met, expressed as the exit criteria in `MILESTONE.md`. So `add.py milestone-done` is **goal-gated**: it refuses to close a milestone while any exit criterion is still unchecked, and **holds until** every box is checked. Those checkboxes are the human's affirmation that the goal is genuinely met — the engine reads the tally, it never judges the goal itself. (A milestone with no exit criteria closes as before; `milestone-done` is the only path to `done`, and archiving refuses anything not yet done — so the one gate cannot be slipped.)
-
-While the milestone is held open, the work each task leaves behind — open lessons, and items discovered but out of scope — becomes its next tasks: the AI proposes them, the human confirms, and the loop continues until the goal is reached. The milestone is the loop made concrete; the exit criteria are its finish line.
-
-> **Do:** release small, watch the scenarios, and feed every learning back into the spec.
-> **Don't:** treat shipping as the end. The most valuable information about a feature arrives *after* it ships.

package/docs/10-setup-and-stages.md

@@ -1,118 +0,0 @@
-# 10 · Project setup and stages
-
-[← 09 The loop](./09-the-loop.md) · [Contents](./README.md) · Next: [11 Governance →](./11-governance.md)
-
-This chapter covers two operational matters: what you set up once per project, and how the same flow runs at different depths as a product matures.
-
----
-
-## Setup: the AI drafts, you approve the baseline
-
-Before the first feature, the project needs a foundation — but standing it up is no longer your chore. Point ADD at the repo and **the AI does the drafting**: it runs `init` itself, reads what is there, and fills the foundation the whole project depends on. Your single act is the **baseline approval** — the one human gate that freezes it.
-
-**What the AI drafts.** From an existing codebase it works **silently** — the code answers the questions a setup interview would ask. On an empty repo it runs a short **four-lens interview** (domain · spec · users · decisions), then drafts. Either way it fills the living documentation — the files that outlive all code — and drafts the first milestone's scope and the first task's candidate contract:
-
-| Item | File | Purpose |
-|------|------|---------|
-| Foundation | `PROJECT.md` | domain · active spec · UI/UX · key decisions — the context every task reads first |
-| Conventions | `CONVENTIONS.md` | naming, layout, language, formatter — living documentation |
-| Model record | `MODEL_REGISTRY.md` | which AI model and version the project uses, for reproducibility and audit |
-| Dependency allow-list | `dependencies.allowlist` | the packages the AI may use; the pipeline rejects others |
-| Prompt playbook | `playbook/` | the six prompts from [Appendix B](./appendix-b-prompts.md) |
-| Repository + pipeline | — | runs the gates on every change |
-
-Every drafted decision is tagged **evidence-grounded** (read from the code) or **guessed** (thin or inferred) and listed lowest-confidence-first in a `SETUP-REVIEW.md`, so the one signature you give is informed rather than given without reading.
-
-**The baseline approval.** The AI presents `SETUP-REVIEW.md`; you check the `guessed` rows; you **lock** — once. That single act freezes the foundation, the first scope, and the first contract together. It is the setup-level analog of the [contract freeze](./05-step-3-contract.md), and it doubles as the first task's contract approval — so there is no separate sign-off. Before the lock the engine lets the AI draft but refuses to cross into build; after it, the build opens.
-
-**Setup exit check**
-
-- [ ] Foundation + living docs drafted (brownfield: from the code, evidence-tagged; greenfield: from the interview, gaps flagged `guessed`).
-- [ ] `SETUP-REVIEW.md` lists every drafted decision lowest-confidence-first.
-- [ ] The model is pinned; the allow-list exists and the pipeline fails on any package outside it.
-- [ ] The pipeline runs and is green on the empty skeleton.
-- [ ] The human **locked down** — and only then did the first feature's build open.
-
-Do not start a feature until the pipeline is green and the foundation is locked. The baseline approval turns the AI's draft into committed direction; the pipeline enforces every later exit check without anyone having to remember to.
-
----
-
-## Stages: the same flow at increasing depth
-
-A *stage* is one pass through the flow at a chosen depth. The steps never change between stages; what changes is how deeply you run each one. The instinct to skip steps for an early prototype is right in spirit but wrong in form — you do not skip steps, you run them lightly.
-
-### The depth matrix
-
-Depth: **Deep** (full rigor) · **Core** (real but scoped) · **Light** (just enough) · **—** (skipped or stubbed).
-
-| Step | Prototype | Proof of Concept | MVP | Production-Ready |
-|------|:---------:|:----------------:|:---:|:----------------:|
-| 1 Specify | Light | Deep (risky slice) | Deep | Deep |
-| (design, if UI) | **Deep** | Light | Core | Deep |
-| 2 Scenarios | Light | Core | Deep | Deep |
-| 3 Contract | — | Core | Deep | Deep |
-| 4 Tests | — | Core | Core | Deep |
-| 5 Build | Light (throwaway) | Core | Core | Deep |
-| 6 Verify | Light | Core | Core | Deep |
-| Loop / operate | — | — | Light | Deep |
-| **Typical time\*** | ~2–5 days | ~1–3 weeks | ~4–8 weeks | ~4–8+ weeks |
-| **Code is** | disposable | disposable | kept | hardened |
-
-\* *Ranges assume a small team on a single product slice. Scale by scope and by the number of parallel streams. The pace is set by judgment and review capacity, not by how fast the AI can type — adding more AI does not compress the human-led steps.*
-
-### Stage by stage
-
-**Prototype — prove the experience.** Run the design deeply and everything else lightly; the code is throwaway. The achievement is that a stakeholder reacts to something tangible and a go/no-go on the concept becomes possible. Do not expect real data, tests, or anything that survives.
-
-**Proof of Concept — retire the biggest technical risk.** Run the contract, tests, and build *deeply but only on the single riskiest slice*. The achievement is evidence that the hardest unknown is solvable, which turns an MVP estimate from hopeful into credible. Do not expect breadth or polish.
-
-**MVP — deliver value to real users.** Run the full flow at a narrow scope — the first complete loop, including light observation. The achievement is real users getting value while you learn from them. Do not expect scale or full operational rigor.
-
-**Production-Ready — run safely at scale.** Run every step at full rigor and deepen the operate-and-learn loop: service objectives, incident response, tested rollback, gradual delivery. The achievement is a system that is tested, secure, observable, and supportable. Do not expect "zero defects"; expect managed risk with a working feedback loop.
-
-### What carries forward
-
-The durable thing is never the code:
-
-| Transition | Discard | Keep |
-|------------|---------|------|
-| Prototype → POC | the prototype code | the validated experience (design, flows) |
-| POC → MVP | the spike code | the validated approach + the risky-interface contract |
-| MVP → Production | nothing | everything; the code is real and is hardened |
-
-The living documentation thickens as you move right: a prototype leaves you a validated design; a proof of concept adds a proven approach and a contract; the MVP adds real, kept code. By production, you are hardening, not rebuilding.
-
-### Graduating between stages
-
-Moving up a stage — most consequentially MVP → Production — is its own scope level, the fourth after setup, intake, and the milestone loop. It is *not* a label someone types: a project earns production through a human-confirmed roadmap of the hardening work, never through a bare flip. The `add` skill drives this in `graduate.md`; the shape is five steps.
-
-**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`. Until both tallies complete, nothing here applies — a project with no stage-goal-criteria block behaves exactly as before.
-
-1. **Gather the analytics.** `add.py graduation-report` clusters the whole MVP loop's evidence into five labeled record-sets — open deltas by competency, open RISK-ACCEPTED waivers by expiry, RETRO records, verify residue, and observe-loop coverage gaps. It *gathers, never judges*: there is no readiness verdict, only the records you reason from.
-2. **Interview.** Synthesize *what production means here* with the human, using those records as the agenda. This synthesis is the judgment the engine refuses to make.
-3. **Draft the roadmap.** For each production outcome the interview surfaces, draft a production milestone with the existing command — `add.py new-milestone <slug> --stage production --goal "…"` — and write its exit criteria. The roadmap is **≥1** milestone; the hardening work itself is what those milestones contain.
-4. **Human confirms.** The human accepts, edits, or declines each draft. Nothing is created on an unconfirmed draft.
-5. **Flip — the final step.** Only now run `add.py stage production`.
-
-**The floor the engine enforces.** `add.py stage production` is guarded: it refuses with `stage_no_roadmap` (non-zero exit, state byte-unchanged) when no milestone has `stage: production`. The check is a *tally* — does a production-roadmap record exist? — never a readiness judgment, mirroring the milestone goal-gate. `--force` overrides it for grandfathered or edge cases; use it deliberately, not as the normal path. The guard is on the `→production` transition only; flips to prototype/poc/mvp are unchanged. The engine never advances the stage on its own — it gathers, counts, and holds the floor while the human judges and confirms.
-
----
-
-## Parallel streams (opt-in)
-
-The default is one task at a time. But when a milestone holds several tasks whose dependencies are already `PASS` and a reviewer is ready, you may run them **concurrently** — one worker per ready task, each building behind its own frozen contract.
-
-**Be honest about the gain.** With one human reviewer you cannot beat `review_time × N_tasks`; the human-led decision points are serial. So the win is **not throughput** — it is that the reviewer is *never blocked waiting on a build*. While a person reviews task A's specification bundle, the builds for B, C, and D run behind *their* frozen contracts. You hide build latency under human latency; do not promise more.
-
-**Two queues, no new state** — both read from `add.py status`:
-
-- **READY-QUEUE** — tasks in the active milestone where the phase is not `done` and every dependency already reads `gate=PASS`. These are the only tasks a worker may pick up; a task finishing `PASS` unblocks its dependents on the next `status`.
-- **REVIEW-QUEUE** — the irreducibly serial part: the **bundle approval** (contract freeze) and any **Verify escalation**. One human, one queue, presented one at a time — never a batch that invites approval without reading.
-
-**The autonomy level is the throttle** — an explicit, overridable per-task token on an ordered ladder `manual < conservative < auto`. At `manual`, the human owns every gate and nothing auto-resolves (the strict floor). At `conservative`, both gates queue on the human (pure pipelining — builds overlap, nothing auto-resolves). At `auto` (the seeded default), only the bundle-approval decision point and residue escalations queue; Verify auto-PASSes on evidence, so real concurrency follows. The floor never drops below **one human approval per task, at the contract decision point**.
-
-**Design for failure (required).** Lease each task to its worker with a timeout — if a worker dies, release the claim back to READY rather than trusting partial work. A worker that hits a stop-and-escalate blocks only its own task; siblings keep running. And if several workers fail in one wave, trip a circuit-breaker and fall back to sequential — repeated failure means the scope was wrong, not the parallelism.
-
-**The hard boundary.** The orchestrator owns every shared write — `state.json`, `MILESTONE.md`, and each `add.py advance`/`gate` call (always with the explicit task slug). A worker owns only its own task directory and is isolated in a git worktree — ADD's default for any agent-spawned step, not only a wave — so concurrent builds cannot collide. Merge is **serial**: bring worktrees back one at a time and run an **integration Verify** for the concurrency and architecture conflicts that two-green-in-isolation tasks can still produce — automation never auto-passes that step.
-
-The full, agent-agnostic worker contract (the prompt a worker runs) and the per-runner spawn adapter live in the skill's `streams.md`; this section is the *why* and the safety frame, not the operational recipe.

package/docs/11-governance.md

@@ -1,91 +0,0 @@
-# 11 · Governance
-
-[← 10 Setup and stages](./10-setup-and-stages.md) · [Contents](./README.md) · Next: [12 Roles →](./12-roles.md)
-
-Governance is what keeps the method honest when a team runs it at speed. It is the same regardless of which AI tool writes the code, because it lives in the process and the pipeline, not in the agent.
-
----
-
-## The autonomy ladder
-
-How much the AI is allowed to do is not one switch; it is a setting chosen per area, rising with evidence and with your capacity to verify.
-
-| Level | The AI… | A person… | Typical use |
-|-------|---------|-----------|-------------|
-| **Suggest** | proposes options | decides and writes | early, exploratory work |
-| **Draft-and-review** | drafts artifacts | edits and approves each one | specs, scenarios, contracts |
-| **Generate-behind-gate** | generates code | reviews the change; it merges only if the contract and tests pass | the normal build |
-| **Auto-with-evidence** | generates and merges | samples and audits; auto-merge allowed only with a full evidence bundle attached | narrow, well-tested areas |
-
-The governing rule, restated from the principles: **operate only at the level your review capacity can sustain.** If the AI produces more than the team can verify, drop a level.
-
-The **per-scope default is auto-with-evidence behind a one-approval decision point**: the AI drafts the specification bundle, a human approves the frozen contract once, and the build auto-gates on evidence. You *lower* a scope toward draft-and-review or suggest wherever risk is high or evidence is thin — and a high-risk or method-defining scope is *always* lowered (it is never auto-run). The default sets where you start; review capacity and risk set where you stay.
-
-The engine expresses this per task as an explicit three-rung level — `autonomy: manual | conservative | auto`, an ordered ladder `manual < conservative < auto` declared in the `TASK.md` header and reviewed at the freeze. `auto` is auto-with-evidence behind the one approval (the seeded default); `conservative` is the deliberate lowering that keeps a person at the verify gate; `manual` is the strict floor where the human owns the gate and nothing auto-resolves. A high-risk or method-defining scope refuses an unguarded `auto` (`unguarded_high_risk_auto`) — it must be lowered to `conservative` or `manual`. The prose here and that engine token are one rule: prose ≡ enforcement.
-
-**Autonomy is earned by goal-clarity — the auto-ready goal.** The autonomy level decides *who* resolves Verify; an **auto-ready goal** decides whether a self-verifying run is even *meaningful*. A milestone goal is *auto-ready* when **every exit criterion cites a verifier** — `(verify: <test | command | metric>)` — so the engine can check the result against the goal without human judgment. `add.py check` raises a `goal_not_auto_ready` WARN (never red, the active milestone only) while the goal has criteria not all cited, and `status` surfaces a `goal-ready:` line every session, so the goal-clarity gap stays visible. The WARN *measures citation presence*, it never blocks: it changes neither the freeze gate nor the autonomy level — clarifying the goal is the prerequisite for a meaningful self-verifying run, not a new gate (a zero-criteria goal reads not-auto-ready and is milestone-shaping's nudge, not this one's). The lint raises the floor — a citation slot per criterion — but cannot prove the citation is honest: a human can still write `(verify: it works)`, and closing that is a person's judgment, not the engine's.
-
-## The gate-fail protocol and the three reports
-
-Every checkpoint produces three short reports — **Test** (does it pass?), **Quality** (is it well-made and conformant?), and **Risk** (what could go wrong, and who owns it?) — and resolves to exactly one outcome:
-
-- **`PASS`** — criteria met; proceed.
-- **`RISK-ACCEPTED`** — proceed with a signed waiver carrying a named owner, a linked ticket, and an expiry. Allowed for non-security gaps only.
-- **`HARD-STOP`** — cannot proceed. Triggered by any failing test or any security finding. A non-security limitation may proceed only with a signed `RISK-ACCEPTED` record carrying an owner and an expiry; security is never waved through.
-
-The rule behind the protocol is *no silent skips.* A report nobody is accountable for approving is just a document; an outcome with an owner is governance.
-
-### Why each step exists (institutional memory)
-
-When someone proposes skipping a step "to go faster," this table is the answer:
-
-| Step skipped | What happens | How you notice |
-|--------------|--------------|----------------|
-| Specify | the wrong thing gets built | shipped, but users do not use it |
-| Scenarios | the feature is vague, edges missing | the AI keeps asking questions mid-build |
-| Contract | interfaces drift | front, back, and AI disagree on shapes |
-| Tests | AI code is uncontrollable | no way to know it is right but to test by hand |
-| Verify (architecture check) | entropy explodes | the codebase is a tangle within months |
-| Operate / loop | silent rot | the same incidents recur |
-
-## The continuous concerns
-
-Four concerns are not steps but threads that run through every step, starting at project setup. Pulling them forward ("shifting left") is far cheaper than bolting them on at the end.
-
-| Concern | Begins at | Enforced at the build gate by |
-|---------|-----------|-------------------------------|
-| **Security** | setup (secret scanning, dependency allow-list) | zero high-severity findings; every AI-suggested package verified to exist |
-| **Testing** | the scenarios step | coverage must not decrease; no test weakened to pass |
-| **Observability** | setup (logging/metric conventions) | instrumentation present; service objectives verified after release |
-| **Cost** | setup (an AI-usage budget per task) | a task may not exceed its budget without escalation |
-
-## AI-specific governance
-
-A method built on AI agents needs controls older methods did not:
-
-- **Pin the model.** Record the model and version; re-check the prompt library before adopting an upgrade. AI output is non-deterministic, so provenance matters.
-- **Test the prompts.** The reusable instructions in `playbook/` are themselves artifacts: give each golden input/output cases, and re-check them when edited. A prompt that fails its check does not ship.
-- **Guard the supply chain.** No package outside the allow-list without human approval; verify each suggested package actually exists, to defeat the risk of an agent inventing a plausible name an attacker has registered.
-- **Track provenance and licensing.** License-scan both generated and pulled-in code; keep a record of what the AI produced.
-
-## Metrics that matter — and the anti-metrics
-
-Measure the scarce things:
-
-- **Contract stability** — how rarely the frozen contracts change; high churn is genuinely expensive.
-- **Validated requirement coverage** — the share of rules confirmed against real behavior.
-- **Review throughput** — the team's verification capacity, which sets the safe autonomy level.
-- **Delivery and reliability** — lead time, deployment frequency, change-failure rate, time to recover.
-
-Do **not** optimize: lines of AI code generated, code-reuse percentage, prompt counts, or velocity measured in code volume. These count the cheap, disposable thing and create incentives to keep bad code to protect a number.
-
-## Profiles: one method, three intensities
-
-| | **Express** (startup) | **Standard** (most teams) | **Regulated** (audited) |
-|---|---|---|---|
-| Steps | combine Specify + Scenarios into a one-page brief; light contract | full flow | full flow, all `HARD-STOP` |
-| Scenarios | happy path only | happy + key alternatives | exhaustive, incl. compliance |
-| Autonomy ceiling | generate-behind-gate from day one | up to auto-with-evidence | generate-behind-gate max; the AI never merges its own work |
-| Gate default | `RISK-ACCEPTED` allowed | `PASS` required to advance | `HARD-STOP`; full audit trail |
-
-Choose the profile deliberately — a startup spike and a banking system are not the same risk — and run different products at different profiles as appropriate. The choice is owned by the delivery lead (see [12 Roles](./12-roles.md)).

package/docs/12-roles.md

@@ -1,99 +0,0 @@
-# 12 · Roles and responsibilities
-
-[← 11 Governance](./11-governance.md) · [Contents](./README.md) · Next: [13 Adoption →](./13-adoption.md)
-
-Everyone on an AIDD team becomes, in part, a *verifier*; most also become *authors of the artifacts*. This chapter says what each role owns and does. Find your section; each answers the same three questions — what you do, when, and what "done" means for you.
-
----
-
-## Product / Domain Owner
-
-- **Mission:** ensure the right thing gets built. You guard the problem.
-- **Leads:** Specify. **Contributes to:** Scenarios; the loop (deciding what the next cycle addresses).
-- **Owns:** the problem definition, the glossary of domain terms, the prioritized backlog.
-- **Done means:** the spec states real user value with no disputed terms and its assumptions ranked lowest-confidence first — the one or two most likely wrong flagged with *why* and *what they cost*; after release, you have decided what the next loop must address.
-- **Apply it:** run the Specify prompt against a real ticket or interview, then read the AI's lowest-confidence flag *first* and decide the one or two load-bearing assumptions before skimming the low-stakes tail. If you cannot confirm a load-bearing rule, it is not ready to build.
-
-## Architect / Engineering Lead
-
-- **Mission:** own the load-bearing surfaces and the checks that protect them.
-- **Leads:** project setup; the Contract freeze. **Accountable for:** all the durable artifacts.
-- **Owns:** `CONVENTIONS.md`, the contracts, the architecture check in verification, the model record.
-- **Done means:** contracts are frozen and versioned; the architecture check runs in the pipeline; autonomy levels match the team's real review capacity.
-- **Apply it:** treat the contract freeze as a one-way door. When a stream wants to change a frozen contract, route it as a change request that reopens Specify — never let code quietly move the surface.
-
-## Software Engineer (Senior)
-
-- **Mission:** direct the build and hold quality at the architecture check.
-- **Leads:** Build. **Contributes to:** Contract, Tests; reviews others' changes.
-- **Owns:** the implementation, the architecture conformance check, the evidence bundle on each change.
-- **Done means:** all tests pass without any test being weakened; coverage holds; architecture and security checks pass; a person has reviewed it.
-- **Apply it:** work in small batches the review can keep up with, and never let the AI edit a test to make it pass — that is the cardinal sin of the build step.
-
-## Software Engineer (Junior)
-
-- **Mission:** learn the craft by entering at the build end and growing toward judgment.
-- **Leads:** nothing yet. **Contributes to:** Build (against handed-over specs and contracts), Tests.
-- **Owns:** your tasks' code and tests; raising a flag when a spec is ambiguous — which is a contribution, not a failure.
-- **Done means:** your task's tests pass honestly, your change has a clear evidence bundle, and a senior has reviewed it.
-- **Apply it:** start with specs and contracts given to you and make red tests green without weakening them; over time move *up* toward design and specification as your judgment matures (see [13 Adoption](./13-adoption.md)).
-
-## QA / Test Engineer
-
-- **Mission:** make "done" machine-checkable; you are the guardrail for AI-written code.
-- **Leads:** Tests. **Contributes to:** Scenarios (turning rules into checkable form); the loop (production monitors).
-- **Owns:** the test suite, the scenario files, the coverage target, the test report at each gate.
-- **Done means:** every scenario has a test that was red before the build; the suite is honest (nothing passes by default); coverage never regresses.
-- **Apply it:** co-author the scenarios so the path from rule to test loses nothing, and confirm the suite fails for the *right* reason before the build begins.
-
-## Product Designer (UI/UX)
-
-- **Mission:** ensure correct logic does not ship inside a poor experience.
-- **Leads:** the design portion of Specify; the Prototype stage. **Contributes to:** Scenarios (experience-side rules).
-- **Owns:** the user flows, the specification of every screen state, the design document, the clickable prototype.
-- **Done means:** every screen has all its states designed; the prototype matches the scenarios; the self-critique for generic, low-effort output has passed.
-- **Apply it:** in the Prototype stage you lead — make the experience tangible fast, and carry the design forward while the prototype code is discarded.
-
-## DevOps / SRE / Platform
-
-- **Mission:** make the continuous concerns real and run the operate-and-learn loop.
-- **Leads:** the loop / operations. **Contributes to:** setup (pipeline, observability conventions), Build (deployment, gradual delivery).
-- **Owns:** gate enforcement in the pipeline, telemetry conventions, service-objective dashboards, rollback, the cost budget.
-- **Done means:** the gate outcomes are enforced mechanically in the pipeline; instrumentation is required to pass the build gate; rollback is tested; objectives are observed after release.
-- **Apply it:** wire the gate-fail protocol into the pipeline so a `HARD-STOP` is automatic, not a meeting, and shift security checks to setup rather than the end.
-
-## Security Engineer
-
-- **Mission:** keep AI-written code from importing AI-shaped risk.
-- **Leads:** the security thread. **Contributes to:** setup (allow-list, secret scanning), Specify (threat modeling), Build (scanning), AI governance.
-- **Owns:** the dependency allow-list, the provenance and license record, the security report at each gate, the supply-chain policy.
-- **Done means:** zero high-severity findings at the build gate; every AI-suggested dependency verified real and intended; generated and pulled-in code license-scanned.
-- **Apply it:** assume the AI will at some point hardcode a secret and invent a package name; gate against both from setup, and keep security findings as `HARD-STOP`, never waivers.
-
-## Engineering Manager / Delivery Lead
-
-- **Mission:** match intensity to risk, and protect verification capacity.
-- **Leads:** profile selection and stage planning. **Contributes to:** unblocking every step; the loop (priorities).
-- **Owns:** the chosen profile, the stage roadmap, the metrics dashboard.
-- **Done means:** the team operates at an autonomy level its review capacity can sustain; metrics track the scarce things, not code volume; each stage exits on its real achievement, not a date.
-- **Apply it:** choose the profile deliberately, and watch review throughput as the true measure of velocity — if AI output outpaces review, slow the engine rather than rushing the review.
-
----
-
-## Responsibility matrix
-
-`A` Accountable · `R` Responsible/Lead · `C` Consulted · `I` Informed
-
-| Role | Setup | Specify | Scenarios | Contract | Tests | Build | Verify | Loop |
-|------|:--:|:--:|:--:|:--:|:--:|:--:|:--:|:--:|
-| Product / Domain | C | **R** | R | I | I | I | I | R |
-| Architect / Lead | **R/A** | C | C | **R/A** | C | A | A | C |
-| Engineer (Senior) | C | I | C | R | R | **R** | R | C |
-| Engineer (Junior) | I | I | I | I | R | R | I | I |
-| QA / Test | I | C | R | C | **R** | C | C | C |
-| Designer | I | R (design) | R | C | I | I | I | I |
-| DevOps / SRE | R | I | I | C | C | R | R | **R** |
-| Security | R | C | I | C | C | R | R | C |
-| EM / Delivery | C | C | C | C | C | C | C | C |
-
-> If your role is only ever `I`, you are not yet using the method — find the step where your judgment *is* the gate.

package/docs/13-adoption.md

@@ -1,67 +0,0 @@
-# 13 · Adoption and onboarding
-
-[← 12 Roles](./12-roles.md) · [Contents](./README.md) · Next: [14 The foundation →](./14-foundation.md)
-
-How a team starts using AIDD, and how a new person becomes productive in it.
-
----
-
-## A 90-day rollout
-
-Adopt the method on one real product, not as an all-at-once mandate.
-
-1. **Days 1–15 — Lock the foundation.** On one pilot service, let the AI draft the foundation — conventions, glossary, dependency allow-list, model record — from the existing code (or the four-lens interview if greenfield), then **lock it down** with one signature. The prompt playbook is [Appendix B](./appendix-b-prompts.md).
-2. **Days 16–45 — One feature, end to end.** Run a single feature through the whole flow at the **Express** profile. Capture friction; tune the prompts' golden cases as you go.
-3. **Days 46–75 — Turn on the gates.** Wire the three reports and the gate-fail protocol into the pipeline; introduce the autonomy ladder at the generate-behind-gate level.
-4. **Days 76–90 — Promote.** Move the pilot to the **Standard** profile, draft the **Regulated** variant for any compliance-bound product, and publish the prompts as a shared, versioned playbook.
-
-## Choosing a profile
-
-| Choose… | When… |
-|---------|-------|
-| **Express** | startup, spike, or internal tool; speed of learning dominates; small scope of impact |
-| **Standard** | a normal product with real users and ordinary risk |
-| **Regulated** | finance, health, or anything audited; failure is expensive or legally consequential |
-
-The choice is deliberate and owned by the delivery lead; different products can run at different profiles.
-
-## Onboarding: enter from the build end
-
-The most common onboarding mistake is to start newcomers at the most abstract step. Specification and domain discovery require judgment a newcomer has not yet built. So bring people in from the *concrete* end and move them toward judgment:
-
-1. **Weeks 1–4 — Build and Tests.** Implement tasks against specs and contracts handed to you; write tests. Learn the architecture check and the evidence bundle.
-2. **Weeks 5–8 — Contract and design.** Start contributing to contracts and screen states; learn why the surface is frozen.
-3. **Weeks 9–12 — Scenarios and Specify.** Co-author scenarios and specs; practice removing ambiguity.
-4. **Beyond — Domain discovery.** The most abstract work comes last, once judgment is calibrated.
-
-You graduate *up* the flow, from execution toward direction. Deciding what to build is the senior skill, not the entry skill.
-
-## Tool portability
-
-The prompts are plain text that reference files in the repository, and the gates are enforced in the pipeline, not in the agent. So the method does not depend on any one AI coding tool — the agent is replaceable, the method is not. A conformant prompt is (1) tool-agnostic plain language, (2) anchored to repository files rather than chat memory, (3) self-describing about which model and exit criteria it assumes, and (4) checkable by the pipeline.
-
-| Concern | Where it lives |
-|---------|----------------|
-| Prompt discovery | a folder convention in the repo (`playbook/`) |
-| Context | repository files the prompt names explicitly |
-| Gate enforcement | the build pipeline |
-
-Switching tools changes the discovery convention and nothing structural.
-
-## First week, by role
-
-| Role | First-week task |
-|------|------------------|
-| Product / Domain | run the Specify prompt on a real input; produce a glossary you would defend |
-| Architect / Lead | review the AI's setup draft and lock it down (the first contract freezes with it); wire the architecture check into the pipeline |
-| Engineer (Senior) | run the Build prompt on one small task; produce a full evidence bundle |
-| Engineer (Junior) | take a handed-over spec; make a red test green without weakening it |
-| QA / Test | convert one rule into a scenario, then a failing test |
-| Designer | take a spec; produce flows, all screen states, and a clickable prototype |
-| DevOps / SRE | wire one gate report into the pipeline; add secret-scan and allow-list to setup |
-| Security | build the dependency allow-list; make security findings a `HARD-STOP` |
-| EM / Delivery | choose the pilot's profile; stand up the review-throughput metric |
-
----
-
-> Adoption is a loop too. The method itself is a living document: every cycle should feed improvements back into your copy of these prompts and conventions.

package/docs/14-foundation.md

@@ -1,142 +0,0 @@
-# 14 · The foundation: project context across milestones
-
-[← 13 Adoption](./13-adoption.md) · [Contents](./README.md) · Next: [15 Foundations & Lineage →](./15-foundations-and-lineage.md)
-
----
-
-## The engine needs ground
-
-The flow in [Part II](./02-the-flow.md) is the *engine*: Specify → Scenarios →
-Contract → Tests → Build → Verify, run as a tight loop. TDD and ADD turn inside
-that engine — write the failing test, let the AI generate code, repeat.
-
-But an engine needs something to stand on. Every loop quietly assumes context that
-no single task owns: *what the words mean*, *what we are building right now*, and
-*how its users experience it*. When that context lives only in someone's head, each new session —
-and each new milestone — starts cold, and the AI fills the gap with plausible
-guesses. That is the same failure the method exists to prevent ([00](./00-introduction.md)),
-one level up.
-
-The **foundation** is the layer that holds this context and *outlives every
-milestone*. It is not new ceremony; it is the [living documentation](./appendix-f-requirements-matrix.md)
-the method already names, made explicit as three concerns.
-
-## Three concerns, one foundation
-
-![The engine needs ground — the TDD ⇄ ADD engine runs on a DDD · SDD · UDD foundation: context feeds up, and any loop may send a correction back down](./add-foundation.png)
-
-- **DDD — Domain.** The shared, precise language and the boundaries it lives in:
-  the core concepts, the modules/contexts they belong to, and the invariants that
-  must always hold — the domain model and context map behind the names. One name
-  per concept — the same names the spec, the contract, and the code all use. (The
-  [GLOSSARY](./appendix-c-glossary.md) holds the full term list; the foundation
-  holds the model those terms describe.)
-
-- **SDD — Spec.** *The living document.* What is being built right now and what is
-  settled versus still open. This is not a frozen plan written once — it is the
-  layer that changes as the loop learns ([01](./01-principles.md)). In ADD it does
-  not duplicate the work; it **points** to the active milestone and the frozen
-  contracts that other tasks build against.
-
-- **UDD — UI/UX.** *Users use the interface, not the spec.* The experience designed
-  before code: the **user flows** (happy and alternative paths), the **UI states**
-  every screen must handle (loading · empty · error · success), and a design source
-  of truth — a `DESIGN.md` or clickable prototype. The AI can generate a prototype
-  from a design system; a person owns the empathy — what the user is trying to do,
-  and what "good" feels like from their side. The scenarios ([04](./04-step-2-scenarios.md))
-  test that behaviour; the foundation keeps the design intent that makes a screen
-  worth building.
-
-When a milestone has screens, UDD is not only a static `DESIGN.md` — it runs a
-**design-definition loop** that turns the domain into a screen the human has *seen
-and confirmed before build*. Its five beats are `design-intake → review-domain →
-research-components → wireframe → render-capture-confirm`: interview the human on the
-four design axes (fidelity · concept · layout · visual design) so the look is directed
-not guessed, read the domain into screens and regions, research and reuse components
-before inventing them, wireframe the structure low-fi, then render a real screen and
-**capture** it. That capture is the **design-confirm**
-evidence — a real image the person approves *before* implementation, so the build
-matches the layout instead of discovering it. The book keeps the *why*; the
-operational recipe (the wireframe format, the token-bound mock, the capture engines)
-lives in the `add` skill's `design.md` and the `udd-wireframe.md` template (`tooling/templates/`).
-
-These three foundation competencies, together with the **TDD ⇄ ADD** engine of
-[Part II](./02-the-flow.md), are ADD's five. The first four feed context to the
-fifth, where the AI executes on it:
-
-![ADD's five competencies — DDD · SDD · UDD · TDD · ADD: the first four are human-led and feed context to ADD, which is AI-led under your direction](./add-competencies.png)
-
-> The diagram's foundation (DDD · SDD · UDD) and the method's own words — living
-> documentation · the foundation document · ubiquitous language — name the same three ideas. This
-> chapter is where the diagram and the text finally meet.
-
-## One file, not three
-
-A foundation that takes a week to write is a foundation no one keeps current. So
-ADD realizes all three concerns as **one living document — `PROJECT.md`** — with
-one short section each, plus an append-only record of key decisions:
-
-```
-.add/PROJECT.md
-  ## Domain (DDD)                — concepts · contexts · invariants
-  ## Spec / Living Document (SDD)— → active milestone + frozen contracts
-  ## Users (UDD)                 — UI/UX: user flows · states · DESIGN.md / prototype
-  ## Key Decisions               — append-only: date · decision · why · outcome
-```
-
-Keep it to one screen. If a section wants to grow into a manual, that is a signal
-the detail belongs in a milestone or a contract, not the foundation. The foundation
-is the *thin, durable* context the engine reads first — not a place to relocate the
-work. And you do not hand-write it: at setup the AI **drafts** all four sections —
-silently from an existing codebase, or from a short four-lens interview on a
-greenfield repo — and a single human **baseline approval** freezes that draft as committed
-direction (the setup-level analog of a contract freeze).
-
-## How it feeds the engine — and takes feedback back
-
-The arrow runs both ways, which is the whole point of a re-entrant method:
-
-- **Down → up.** At the start of any session or milestone, read `PROJECT.md`
-  before touching a task. It is the cheapest way to point the AI in the right
-  direction. `add.py status` prints a pointer to it for exactly this reason.
-- **Up → down.** When a loop reveals that the domain model was wrong, the spec
-  stance has shifted, or a user assumption did not survive contact with reality,
-  you **stop and update the foundation** — then come forward again. A passing test
-  built on a broken foundation is still the wrong software, fast.
-
-## Where it sits in the hierarchy
-
-The foundation is the **Project tier** of the document hierarchy
-([Appendix F](./appendix-f-requirements-matrix.md)) — created once, kept for the
-life of the product, owned above any single milestone.
-
-![Three tiers of documents — Project (the foundation, .add/PROJECT.md) → Milestone → Task: scope narrows and lifespan shortens down the stack](./add-hierarchy.png)
-
-| Tier | Lives in | Lifespan | Holds |
-|------|----------|----------|-------|
-| **Project** (foundation) | `.add/PROJECT.md` + living-doc files | whole product | domain, spec stance, users, decisions |
-| **Milestone** | `.add/milestones/<slug>/MILESTONE.md` | one depth-bounded goal | scope, shared contracts, exit criteria |
-| **Task** | `.add/tasks/<slug>/TASK.md` | one feature | the seven-step artifacts |
-
-A milestone is a *version bump* to the foundation, not a fresh start: when it
-closes, consolidate what it validated into `PROJECT.md` (a decision, a settled domain
-term, a confirmed user journey) and open the next one against the same, now-richer,
-ground. The consolidation is not informal: each loop emits **lessons learned** (tagged
-`DDD · SDD · UDD · TDD · ADD`) in its Observe step, and at milestone close a person
-gathers the open ones and consolidates them — append-only, with the `foundation-version:`
-bumped — into the foundation. See [09 · The loop](./09-the-loop.md#lessons-learned-and-the-retrospective-consolidation)
-for the grammar, the ritual, and the tooling (`add.py deltas`, `add.py check`).
-
-## In the tooling
-
-- `add.py init` scaffolds `PROJECT.md` as a living-doc file; the AI then drafts its
-  content and a single human **baseline approval** (`add.py lock`) freezes it. Like every
-  living-doc file, `init` **never overwrites a hand-edited one**.
-- `add.py status` shows a one-line pointer to the foundation, so a fresh session
-  re-orients on context before code.
-- The guideline block written into `CLAUDE.md` / `AGENTS.md` tells any agent the
-  same thing: run `status`, read the foundation, then work the loop.
-
-> **The thesis, one level up.** The engine builds the thing right; the foundation
-> keeps the engine pointed at the right thing — across every milestone, not just
-> the current one.