@pilotspace/add 1.17.0 → 2.0.0

package/docs/15-foundations-and-lineage.md

@@ -1,106 +0,0 @@
-# 15 · Foundations & Lineage
-
-[← 14 The foundation](./14-foundation.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
-
----
-
-ADD did not appear from nowhere. It sits where four currents meet: the **recursive
-self-improvement** thesis (AI that helps build the next AI), a decade of **autonomous and
-agentic** research, the **spec-driven development** movement (the specification, not the
-code, is the source of truth), and the **tests-first** discipline that constrains a
-generate→check→refine loop with executable tests — turning fluent model output into
-trustworthy software. This chapter tells that story; [Appendix G](./appendix-g-references.md)
-is the verified source list it cites into. Every `[Author Year]` here resolves to an entry
-there.
-
-## The frame — "closing the loop"
-
-Anthropic's recursive-self-improvement picture runs from autonomous agents delegating to
-workers *today* toward a future where Claude improves Claude — *closing the loop* on the
-work of building AI itself [Favaro & Clark 2026]. That is the backdrop ADD is built for, and
-its position inside that picture is deliberately narrow: ADD is a **human-gated,
-evidence-trusted** instance of recursive self-improvement. The AI drives the whole inner
-cycle — specify → build → verify → observe — but a human owns the frozen contract and the
-verify gate, and trust comes from passing tests and re-resolved evidence, never from a
-diff that merely reads plausibly. The argument is not that the loop should stay open
-forever; it is that the loop should be *bounded by human direction* rather than left to run
-unattended [Amodei 2024]. ADD is one concrete shape for that bound.
-
-## The four currents
-
-**Recursive self-improvement.** The mathematical anchor is the Gödel machine — a
-self-modifying agent that rewrites itself *only when it can prove the rewrite helps*
-[Schmidhuber 2003]. ADD enforces the same discipline socially rather than formally: the
-never-weaken-a-test rule is "only change on proof" expressed as a gate. The algorithmic kin
-arrived later — a scaffolding program that improves the code that improves code
-[Zelikman et al. 2023], a generate→critique→refine micro-loop [Madaan et al. 2023], agents
-that keep verbal reflections and retry [Shinn et al. 2023], an agent that grows a reusable
-skill library over time [Wang et al. 2023], and an evolutionary coder that beat a
-long-standing matrix-multiplication record under continuous checking
-[Novikov et al. 2025]. And where a self-rewarding loop has the model judge its own reward
-[Yuan et al. 2024], ADD diverges by design — it makes the tests and a human the reward
-signal, not the model's own opinion.
-
-**Autonomous and agentic workflows.** The architecture vocabulary comes from the canonical
-taxonomy of prompt-chaining, routing, orchestrator-workers, and the evaluator-optimizer loop
-[Schluntz & Zhang 2024] — where evaluator-optimizer *is* build→verify→refine and
-orchestrator-workers is ADD's wave parallelism. Underneath it sit the base agent loop of
-interleaved think→act→observe [Yao et al. 2022], the self-supervised tool use that lets an
-agent run its own tests and builds [Schick et al. 2023], and the designed agent–computer
-interface that materially lifts autonomous issue resolution [Yang et al. 2024] — the role
-ADD's `add.py` engine plays for the method. The production reports close the gap from theory
-to practice: checkpoints, subagents, and rollback for autonomous work [Anthropic 2025a], and
-a lead orchestrating subagents under an LLM judge [Anthropic 2025b].
-
-**Spec-driven development.** ADD's closest siblings are explicit specification systems.
-GitHub's **spec-kit** runs `constitution` → `specify` → `plan` → `tasks` → `implement` with
-the spec as the executable source of truth [GitHub 2025]; its launch framed task
-decomposition as "TDD for your AI agent" [Delimarsky 2025], and its rationale named the
-failure spec-driven work exists to solve — context degrading over a long session
-[Vesely 2025]. The academic vocabulary followed, with a taxonomy of Spec-First,
-Spec-Anchored, and Spec-as-Source rigor [Piskala 2026], and the pattern is converging across
-vendors [InfoQ 2025]. Nearest of all is **GSD** — a spec-driven, context-engineering system
-for the same Claude-Code niche [GSD 2025].
-
-**Tests-first and verification.** The empirical backbone is direct: supplying tests
-alongside the prompt measurably lifts pass rates [Mathews & Nagappan 2024], and the field's
-yardstick judges a fix solely by whether the project's own tests pass [Jimenez et al. 2023].
-"Done" means the tests pass — which is exactly how ADD gates a feature. The safety framing
-completes the current: human control and transparency made concrete [Anthropic 2025c], under
-a governance ceiling that grows *more* binding, not less, as the loop gets more capable
-[Anthropic 2026b].
-
-## Where ADD diverges
-
-The shared lineage is real, but ADD is not a re-skin of its siblings. spec-kit stops at
-`implement`; GSD ends at verify. ADD closes the loop past both by adding three things
-neither spec-kit [GitHub 2025] nor GSD [GSD 2025] carries as a first-class gate:
-
-- a **failing-tests-first gate** — no build starts until the tests are red for the right
-  reason, so the contract is proven executable before any code exists;
-- an **observe → `fold`** step — confirmed lessons learned consolidate back into a versioned
-  foundation, so the method improves itself across loops (retrospective consolidation is the
-  recursive-self-improvement current turned inward on ADD);
-- a **dynamic goal-loop** — the engine holds a milestone open and reopens tasks until its
-  exit criteria are met, rather than declaring done when a checklist empties.
-
-ADD also deliberately targets **less doc-time than GSD** — a lean foundation and one human
-approval per task instead of a document per phase. The tests-first gate, the `fold`, and the
-goal-loop are ADD's contribution; everything beneath them is inherited.
-
-## The evidence chain — the loop already runs
-
-The case that this is not speculative rests on three measured facts. First, the task
-time-horizon: the length of work models complete unaided keeps doubling [Favaro & Clark 2026].
-Second, the authorship share: by 2026 more than 80% of the code merged at Anthropic was
-Claude-authored [Favaro & Clark 2026]. Third, the **Automated Alignment Researchers** result:
-nine parallel Claude agents recovered roughly 97% of the human-expert gap on an alignment task
-in five days against the human team's seven [Anthropic 2026a] — parallel agents working under
-review, which is precisely ADD's wave-plus-verify shape. The loop already runs.
-
-What it does *not* yet supply is the discipline to trust the output. That is ADD's
-contribution: the frozen contract, the never-weaken-a-test rule, the evidence-over-inspection
-gate, and the security HARD-STOP that no autonomy level may auto-pass [Anthropic 2025c],
-held beneath the responsible-scaling governance ceiling [Anthropic 2026b]. As the loop grows
-more capable, those gates and the human-owned verify matter more, not less. ADD is the human-gated, evidence-trusted way to stand inside the
-closing loop and still own the result.

package/docs/16-releasing.md

@@ -1,182 +0,0 @@
-# 16 · Releasing
-
-[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [17 Components →](./17-components.md)
-
----
-
-The flow chapters ([03](./03-step-1-specify.md)–[08](./08-step-6-verify.md)) take one feature from
-spec to verified. The loop chapter ([09](./09-the-loop.md)) keeps a milestone going until its goal
-is met. The stages chapter ([10](./10-setup-and-stages.md)) graduates the project's rigor. None of
-them *ship*. This chapter names the act every project eventually performs and that the method, until
-now, never formalized: bundling closed milestones into a versioned, user-facing release whose notes
-are evidence-backed, whose risk is disclosed, and whose behaviour is then watched.
-
-Releasing is the **fifth scope level** — after setup, intake, the milestone loop, and stage graduation.
-Like every scope level it runs the same shape: **gather → propose → the human
-confirms → the engine records and enforces a floor.** And like graduation, it ends with an outward
-act the human owns. The operational recipe lives in the `release.md` skill guide; this chapter is the
-*why* behind it.
-
-## 16.1 · Why release is its own scope level
-
-A number bump is not a release. A release is the moment one or more **closed milestones** become a
-versioned cut that real users can run. Three distinctions make it its own scope level:
-
-- **Milestone ≠ release.** A milestone is *feature-complete and consolidated* — its goal is met and
-  its lessons are gathered into the foundation (see [14 · The foundation](./14-foundation.md) and the
-  `fold.md` retrospective consolidation). A release is *shipped and watched*. The first is an internal
-  state; the second faces outward.
-- **Graduation ≠ release.** Stage graduation moves the project's *rigor* (mvp → production); a release
-  ships a *version*. The two axes are orthogonal: you cut a prototype preview, an mvp beta, and a
-  production GA, each at its own stage. You release at every stage, not only at the end.
-- **A release bundles; it does not equal.** One version may attribute several milestones — "we shipped
-  after a couple of milestones closed" is the normal case, not the exception. Forcing one release per
-  milestone is the anti-pattern; the decoupling is the whole point.
-
-So release sits beside the other scope levels rather than inside any of them. The granularity ladder
-is now complete: intake → milestone → task, with stage graduation and release as the two cross-cutting
-levels that change *rigor* and ship *versions* respectively (see the **Scope level** entry in
-[Appendix C](./appendix-c-glossary.md)).
-
-## 16.2 · The cue and the inventory — gather, never judge
-
-The trigger is a status line. When at least one milestone is `done`, archived, and not yet attributed
-to any release, `add.py status` prints:
-
-```
-  → releasable: N milestone(s) closed since last release
-```
-
-That line is a **tally**, never a verdict. It counts archived-but-unreleased milestones; it is silent
-for a project that has never released or has already shipped everything (grandfathered — zero change).
-It says *there is something to consider*, not *you are ready*.
-
-To gather the cut's evidence, run `add.py release-report`. It clusters five labeled record-sets: the
-closed milestones since the last release · their **consolidated deltas** (the "what changed" record) ·
-the open `RISK-ACCEPTED` waivers riding into the release · any open security `HARD-STOP` (a blocker) ·
-the §2 scenarios to take live as monitors. The report **gathers; it does not judge** — there is no
-readiness score to read off, because a tally that pretended to be a verdict would invite reading the
-number instead of the evidence.
-
-The reuse claim, stated plainly: **the consolidated deltas are the changelog source.** You do not write
-release notes from memory. The foundation already recorded what changed when each milestone was
-consolidated (`fold.md`); the release surfaces it. This is why release runs *after* consolidation, not
-before. The lifecycle order is one line:
-`milestone-done → fold → compact → archive → (repeat ≥1×) → release → watch`.
-
-## 16.3 · Drafting the notes and the version — the proposal
-
-From those record-sets you draft a [Keep a Changelog](https://keepachangelog.com/) entry: group the
-changes under Added / Changed / Fixed and name the headline capabilities concretely, in the user's
-language, not the commit's. Each bundled milestone's goal anchors one or more entries.
-
-Then propose the version. Semver is a decision the evidence informs but does not make for you: a
-breaking change is a MAJOR, a new capability a MINOR, a fix-only cut a PATCH. You propose the bump; the
-**human confirms it** — the version is a judgement, not a default the tool fills in.
-
-Both the notes and the version are *shown before they are asked about*. Present the drafted entry, the
-proposed version, and the waivers shipping in this cut via the report template — opening with the ARC
-(goal · done · plan) — and let the human approve once. The question is a summary to decide on; the
-artifact itself is rendered first, never pre-stamped.
-
-## 16.4 · The floor — what the engine enforces
-
-`add.py release <version>` is **guarded**. Before it records anything it enforces a readiness floor,
-refusing with a non-zero exit and leaving every file byte-unchanged on any of four conditions:
-
-- `release_security_open` — an open security `HARD-STOP` exists. This is the non-negotiable one: a
-  security finding is never shipped. Resolve it first, as a change request back to Specify.
-- `release_build_in_flight` — a build is in flight: a task sits in build/verify with no recorded green gate. A release ships on evidence, not on a plausible diff.
-- `release_no_closed_milestone` — nothing new since the last release. The cut would be a no-op; do not
-  bump a version to mark time.
-- `release_undisclosed_waiver` — a `RISK-ACCEPTED` waiver rides into the release but is missing from the
-  notes. Disclosure *is* the floor: a shipped risk the user cannot read about is a hidden risk.
-
-The security stop is **un-forceable.** `--force` exists for grandfathered and brownfield first-cuts —
-the same authority valve as `stage --force` ([10 · Setup and stages](./10-setup-and-stages.md)) — and
-it can override the other three rejects, but it can never override `release_security_open`. This mirrors
-the verify gate exactly ([08 · Verify](./08-step-6-verify.md)) and the governance ceiling that no
-autonomy level may lift ([11 · Governance](./11-governance.md)): a security `HARD-STOP` is the one
-outcome the method refuses to auto-pass, at verify and again at the cut.
-
-## 16.5 · The cut versus the ship — the engine records, the human ships
-
-Only after the human confirms do you run the cut. And here is the line that keeps releasing honest:
-**the engine records; the human ships.**
-
-`add.py release <version>` **records** the marker. It prepends the entry to `CHANGELOG.md`, stamps one
-append-only row (newest-first, like the §Key Decisions log) into `RELEASES.md` — date · version ·
-milestones · waivers shipped · evidence — and attributes the bundled milestones to this version, so the
-cue stops firing for them. The ledger is the attribution source: a milestone is "released" because a
-`RELEASES.md` row says so, never because a file was edited to claim it.
-
-What the engine does **not** do is act outward. It **never tags, publishes, or deploys.** The outward
-act — `git tag`, `npm publish`, the deploy pipeline — is the human's, tool-agnostic, exactly as the
-method tool "never renders" in design and "never spawns" a subagent. Design-for-failure — timeouts,
-retries, rollback, a tested revert path — belongs in the pipeline the human owns, not in a method tool
-that has no business holding deploy credentials. The tag is the human-gated trigger; the record is the
-engine's receipt that the floor was met.
-
-> **A caveat worth one paragraph.** `add.py release` writes `CHANGELOG.md` at the **project root**. That
-> is the right default for most repositories. But a repo with a different changelog convention — for
-> instance a **nested-package** layout whose root `CHANGELOG.md` is a deliberate pointer to a package's
-> own changelog — will get release blocks *prepended above* its existing content rather than replacing
-> it (the writer preserves what is there; it does not clobber). Reconcile per repo: either let the root
-> file carry the canonical log, or point the human's publish step at the package changelog the team
-> treats as the source of truth.
-
-## 16.6 · Watch and the hotfix path — re-entering observe
-
-A release is not the finish line; it is where the most reliable information finally appears. The §2
-scenarios that were pass/fail cases at build time become **live monitors** for the released version, and
-error-budget burn feeds the next loop. Live-registry and deploy confirmation are post-cut *evidence*,
-gathered after the tag — not unit tests pretending to be one.
-
-The unhappy path is first-class. A regression found in the wild re-enters at Specify as a **change
-request**, which narrows to a **hotfix release** — the same seven-step flow, scoped to the fix, cut as a
-PATCH. Releasing does not have a separate emergency mode; it has the ordinary flow at a tighter scope.
-
-Depth follows the stage, as everywhere in the method:
-
-- **prototype / poc** — a one-line preview note and a tag; no deploy ceremony. The point is feedback.
-- **mvp** — full notes, a tag, a guarded publish; watch the headline scenarios.
-- **production** — every step at full rigor: notes, tag, a deploy behind a rollback-tested pipeline,
-  live scenario monitors, and error-budget watch. The hotfix path is a routine capability here, not a
-  fire drill.
-
-## 16.7 · The flow, in one arc
-
-One arc, seven steps:
-
-**cue → gather → draft notes → readiness floor → human confirms → cut → watch**
-
-1. **cue** — `add.py status` prints `→ releasable: N` when an archived milestone is unreleased.
-2. **gather** — `add.py release-report` clusters the five record-sets (gather, never judge).
-3. **draft notes** — a Keep-a-Changelog entry drawn from the consolidated deltas; propose the version.
-4. **readiness floor** — the four guarded rejects; the security stop is un-forceable.
-5. **human confirms** — the notes, version, and waivers are shown, then approved once.
-6. **cut** — `add.py release <version>` records the CHANGELOG block + the `RELEASES.md` row + attribution.
-7. **watch** — the scenarios become monitors; a wild regression becomes a PATCH hotfix release.
-
-The recipe for each step — flags, the report's `--json` shape, the exact ledger row — lives in the
-`release.md` skill guide. This chapter is the reasoning; the guide is the procedure.
-
-## 16.8 · Worked example — this method's own 1.5.0
-
-The repository already runs this by hand, which is the best evidence the flow is real. The
-`udd-design-loop` milestone closed (4/4) and consolidated into `foundation-version 33`. From those
-deltas the human drafted the `## [1.5.0]` changelog entry, bumped the three version sources in
-lockstep, and a forward-pinned `test_release_1_5_0.py` asserted in-repo readiness: the versions agree,
-the changelog lineage survives, the feature anchors are named, and the engine is untouched by the
-release. The cut itself — the `git tag` that triggers the npm and PyPI publish — stayed human-gated,
-and the live-registry confirmation was gathered *after* the tag as verify evidence, never as a unit
-test.
-
-That ritual is what this chapter formalizes. `release-report` gathers the inventory, the floor enforces
-the security stop and the disclosures, `add.py release` records the cut, and the human still owns the
-tag. The method releases itself the way it asks every project to release: gather the evidence, disclose
-the risk, record the marker, and let a person make the outward call.
-
----
-
-[← 15 Foundations & Lineage](./15-foundations-and-lineage.md) · [Contents](./README.md) · Next: [17 Components →](./17-components.md)

package/docs/17-components.md

@@ -1,143 +0,0 @@
-# 17 · Components — monorepo and multi-repo
-
-[← 16 Releasing](./16-releasing.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
-
----
-
-Most of this book treats a project as one codebase with one green bar. Real
-systems are rarely that tidy: a backend and a frontend, a shared library and two
-apps, or three services across three repos. ADD models all of these the same
-way — as a **graph of components**. A component owns a source root, its own
-green bar, and the contracts it produces or consumes. With that, **one milestone
-can ship a vertical slice across components** — a backend endpoint and the
-frontend that calls it — instead of splitting the slice across milestones.
-
-This pillar is **opt-in and additive**: a project that declares no components
-behaves exactly as the rest of the book describes. You reach for it only when a
-milestone genuinely spans more than one green bar.
-
-## Declare the components
-
-Components are **declared, never inferred** — ADD does not scan `apps/*` and
-guess. You name them in `.add/components.toml`:
-
-```toml
-[component.gateway]
-root      = "apps/gateway"
-green_bar = "pytest + pyright"
-
-[component.dashboard]
-root      = "apps/web"
-green_bar = "vitest + a11y"
-```
-
-Each component owns a **root** (the source subtree it governs) and a
-**green-bar** (the suite + checks that prove *that* component healthy). A task
-binds to a component with a `component:` header line; the component's root is
-then added to the task's §5 Scope automatically. A project with no
-`components.toml`, or a task with no `component:` line, is byte-identical to a
-single-component project.
-
-## Verify each task against its own green bar
-
-In a mixed milestone, a backend task and a frontend task pass on **different
-toolchains**. The verify gate enforces this per component: a task bound to
-`gateway` must cite its component's green-bar (`pytest + pyright`) in the §6
-Build-expectations evidence, or the gate refuses `component_green_bar_uncited`.
-The engine never *runs* the suite — that invariant holds here too. The AI runs
-the right suite for the bound component; the gate checks the **right bar was
-cited** in the evidence. Two tasks, one milestone, two green bars — each held to
-its own.
-
-At the gate the engine also **surfaces** the bound component's `verify` command —
-the literal suite to run (e.g. `pytest -q`) — beside the expected green-bar, and
-records it in the §6 gate record so the ledger shows which suite backed the gate.
-It prints *what* to run; it never runs it (NO-EXEC). In the fast lane the same
-`component:` affordance is available, so a small task in a monorepo can bind a
-component and get its bar and `verify` surfaced too.
-
-## Freeze a contract between components
-
-When one component produces an interface another consumes, that boundary needs a
-**frozen, machine-checkable contract**. Declare it, name its producer and
-consumers:
-
-```toml
-[contract.gateway-api]
-producer  = "gateway"
-consumers = ["dashboard"]
-```
-
-A task declares its role with a header line — `produces: gateway-api` or
-`consumes: gateway-api`. When the **producer** task freezes its §3 and crosses
-contract→tests, the engine writes an immutable snapshot at
-`.add/contracts/gateway-api.json` (id, producer, version, frozen date, and a
-hash over the frozen §3 shape). When a **consumer** task crosses contract→tests,
-it **pins** that live hash. If the producer later re-freezes a *changed* shape,
-`add.py check` flags every consumer `contract_consumer_stale` — a §7 delta to
-re-pin against the new shape. A missing or malformed snapshot is a HARD-STOP, not
-a guess: the consumer never builds against a shape that was never frozen.
-
-## One milestone, a full-stack slice
-
-The reason to put a producer and a consumer in the *same* milestone is to ship a
-vertical slice — but the frontend must not commit to an endpoint the backend has
-not frozen yet. ADD enforces that ordering with a **hold**: a `consumes:` task
-cannot advance scenarios→contract (it cannot write its §3) while its producer's
-snapshot does not yet exist. The engine refuses `producer_contract_unfrozen` and
-the task stays at `scenarios`. Once the backend freezes its contract, the
-frontend proceeds and pins it. The slice is **ordered by the frozen contract**,
-all inside one milestone — the FE stays downstream of the BE endpoint, not split
-into a later milestone.
-
-The hold checks more than existence. Even once a snapshot exists, if a live
-producer task has *re-opened or drifted* its §3 — the snapshot no longer matches
-a frozen producer — the consumer is held `producer_contract_stale` rather than
-pinning a shape that is mid-change (the freeze-recency guard). Outside the hold,
-`add.py check` surfaces the softer `contract_producer_stale` (a live producer
-drifted past a pinned consumer) and `contract_snapshot_hashless` (a snapshot
-carrying no hash to verify against) as **never-red warnings** — measured and
-reported, never blocking.
-
-## Across repositories: federation
-
-Components in separate repositories work the same way; only the
-**snapshot transport** differs. A consumer repo declares where a producer repo
-publishes its frozen contract:
-
-```toml
-[federation.gateway-api]
-source = "../gateway/.add/contracts/gateway-api.json"
-pin    = "v1"        # optional — the version this repo expects
-```
-
-`add.py federate pull gateway-api` reads that source, validates it (valid JSON,
-matching id, a hash, and — if `pin` is set — a matching version), and lands a
-**byte-for-byte copy** at the local `.add/contracts/gateway-api.json`. From
-there, the consuming repo's task holds and pins exactly as in a monorepo. The
-pull is **fail-loud by design**: an unknown id, an unreadable source, a `source`
-that **escapes the consumer repo's allowlist** (`federation_source_escapes` — the
-path is confined to a sibling of the repo root, so a `../../etc`-style traversal
-lands nothing), an invalid snapshot, or a version mismatch each HARD-STOPS — federation
-never builds an FE against a guessed, out-of-tree, or stale endpoint. The producer's snapshot
-is the published artifact; "publishing" is committing that file in the producer
-repo. Each repo keeps its own git-native `state.json`; federation transports only
-the immutable frozen shape, never shared mutable state.
-
-## What this pillar is not
-
-- **Not auto-discovery.** Components are declared in `components.toml`, not
-  inferred from the directory tree.
-- **Not a central server.** Federation copies an immutable snapshot between
-  repos; there is no shared service and no shared mutable state.
-- **Not a new approval.** The component machinery rides the existing six-step
-  flow and its single contract-freeze approval — it adds gates the engine
-  enforces, not human checkpoints.
-
-The whole pillar is structure, not policy: who *owns* a component and how
-autonomy is set per component is the identity/governance story (chapters 11–12),
-layered on top of this graph.
-
----
-
-[← 16 Releasing](./16-releasing.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)

package/docs/18-personas.md

@@ -1,80 +0,0 @@
-# 18 · Personas — the project-fit learning loop
-
-[← 17 Components](./17-components.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)
-
----
-
-A **persona** is a project-fit requirements lens the agent adopts so its work matches *this*
-codebase's standards instead of a generic default. It is not a chat costume: a persona is a small,
-versioned file under `.add/personas/<slug>.md` with three machine-readable parts —
-
-- **Identity** — the stance the worker takes (e.g. *a payments engineer who treats money as exact*).
-- **Critical Rules** — the constraints that must hold (the non-negotiables for this domain).
-- **Success Metrics** — the measurable done-bar (what "good" looks like, in numbers where it can).
-
-The **persona loop** is how those files come to exist, improve, and get used: **seed → grow →
-apply**. The loop is opt-in and additive — a project with no personas behaves exactly as before.
-
-## Where personas come from — the teacher
-
-ADD does not invent personas from nothing. It learns them from a **teacher**: a corpus of worked
-agent definitions that ADD ships as a vendored local library at `.add/personas-teacher/`.
-The teacher is read **off-build**, by the AI, while drafting a persona — it is a *source of ideas*,
-**never a runtime dependency**: nothing in the engine imports it, fetches it, or needs it present to
-run. You distil a teacher entry down to the three-part shape above and commit the result; from then
-on the project owns that persona outright.
-
-## Seed — at setup
-
-The first personas are **seeded** during project setup, from the foundation (`PROJECT.md`'s domain
-and standards). Setup proposes a starter persona or two that fit the project's domain; the human
-confirms. Seeding writes `.add/personas/<slug>.md` and nothing else — no behaviour changes until a
-task actually applies one.
-
-## Grow — observe → delta → consolidate
-
-Personas are **living documents**: they improve through the same loop the foundation uses. In a
-task's **observe** phase the AI emits a **persona delta** — a one-line, tagged proposal to add or
-sharpen a critical-rule, success-metric, anti-pattern, or ability, written `open` with evidence (just like a lesson learned).
-At a retrospective the human **consolidates** confirmed deltas into the persona file (the same
-`fold` step the foundation uses), bumping it forward. The consolidation is judgment-free
-transcription: the engine routes a confirmed delta into the named
-persona's `## Critical Rules`, `## Success Metrics`, `## Anti-patterns`, or `## Abilities` section and **never clobbers** existing content.
-So a persona gets *more* accurate every milestone instead of drifting.
-
-## Apply — three surfaces
-
-A seeded, grown persona earns its keep when work adopts it. Three surfaces apply a persona, and all
-three treat it the same way — as **advice**, never authority:
-
-- **UDD (design).** At the design-definition loop a persona frames the requirements lens: which
-  rules and metrics a UI/UX slice must satisfy for this project's users.
-- **advisor / streams (delegation).** When you delegate a piece of your plan to a subagent, its
-  `<persona>` block **selects** the best-fit `.add/personas/<slug>.md` and the returned verdict
-  **records** which persona did the work. The independent earned-green refute-read selects a
-  **Code-Reviewer** persona whose findings carry severity markers — 🔴 blocker · 🟡 concern · 💭 note.
-  The same canonical persona body rides every runner (Claude, Cursor, Copilot, Codex), so a
-  **cross-runner subagent** behaves identically wherever it is spawned.
-- **build (overlay).** While building, the orchestrating agent may load the active persona as a
-  domain identity **overlay** layered on `SOUL.md`: SOUL is the voice and trust rules; the persona is
-  the domain stance. The overlay **never rewrites** SOUL.md (it is human-owned) and never overrides a
-  trust rule.
-
-## The non-negotiable — a persona never lowers a gate
-
-A persona changes *how carefully* the work is done; it never changes *what passes*. This is the one
-hard rule across every surface:
-
-- A **security** finding is always a **HARD-STOP**, whatever persona was adopted.
-- High-risk scope still escalates to the human; a stronger persona never buys back a gate.
-- The engine stays **NO-EXEC** throughout: it never spawns a subagent, never runs a persona, never
-  reads one on the build path. Selecting, loading, and applying a persona is the orchestrating
-  agent's judgment — the engine only records what was used (for the audit trail) and measures that
-  the record is present; it never auto-passes on a persona's say-so.
-
-In short: a persona makes the agent *fit the project*. Direction, freezing, evidence, and the gate
-are exactly as strict as they were before — the loop adds expertise, not permission.
-
----
-
-[← 17 Components](./17-components.md) · [Contents](./README.md) · Next: [Appendix A Templates →](./appendix-a-templates.md)

package/docs/README.md

@@ -1,77 +0,0 @@
-# AI-Driven Development
-
-### A complete, practical book on building software when AI writes the code
-
-**Edition:** 1.0 · **Type:** Methodology + operating manual
-
----
-
-## What this book is
-
-This is a complete guide to **AIDD (AI-Driven Development)** — a way of building software in which an AI agent writes most of the code and people do the two things AI cannot reliably do alone: decide *what* to build, and *verify* that what was built is correct.
-
-It is written to be read once front to back, then kept open beside you as a working manual. The early chapters explain *why* the method has the shape it does; the middle chapters explain each step in detail; the later chapters explain how to operate it across a real team and product; the appendices are copy-paste reference material.
-
-A single worked example — *transferring money between a user's own accounts* — runs through the entire book so that every abstract step has a concrete form you can see.
-
-## Who it is for
-
-Anyone who builds software with AI in the loop: engineers, architects, testers, designers, product owners, and the managers who lead them. No part assumes you have read the others; cross-references point you to what you need.
-
-## The method in one paragraph
-
-For every feature, before AI writes any code, you write four short artifacts in order — the rules it must obey, those rules as pass/fail scenarios, the data and interface contract, and the failing tests — and then you direct the AI to make the tests pass without changing them, and finally you verify the result through evidence rather than inspection. That ordered set of artifacts *is* the method. The code is disposable; the artifacts are the durable asset. Direction comes before speed, and trust comes from passing tests rather than from reading code and finding it plausible.
-
-## The flow
-
-> **Specify → Scenarios → Contract → Tests → Build → Verify → observe, then repeat.**
-
----
-
-## Table of contents
-
-**Part I — Foundations**
-- [00 · The shift: why AIDD exists](./00-introduction.md)
-- [01 · Core principles](./01-principles.md)
-- [02 · The flow, and what is disposable](./02-the-flow.md)
-
-**Part II — The method, step by step**
-- [03 · Step 1 — Specify](./03-step-1-specify.md)
-- [04 · Step 2 — Scenarios](./04-step-2-scenarios.md)
-- [05 · Step 3 — Contract](./05-step-3-contract.md)
-- [06 · Step 4 — Tests](./06-step-4-tests.md)
-- [07 · Step 5 — Build](./07-step-5-build.md)
-- [08 · Step 6 — Verify](./08-step-6-verify.md)
-- [09 · The loop — observe and learn](./09-the-loop.md)
-
-**Part III — Operating the method**
-- [10 · Project setup and stages](./10-setup-and-stages.md)
-- [11 · Governance](./11-governance.md)
-- [12 · Roles and responsibilities](./12-roles.md)
-- [13 · Adoption and onboarding](./13-adoption.md)
-- [14 · The foundation: project context across milestones](./14-foundation.md)
-
-**Lineage**
-- [15 · Foundations & Lineage](./15-foundations-and-lineage.md)
-
-**Releasing**
-- [16 · Releasing](./16-releasing.md)
-
-**Part IV — Reference**
-- [Appendix A · Templates](./appendix-a-templates.md)
-- [Appendix B · Prompt library](./appendix-b-prompts.md)
-- [Appendix C · Glossary](./appendix-c-glossary.md)
-- [Appendix D · The worked example, end to end](./appendix-d-worked-example.md)
-- [Appendix E · Checklists](./appendix-e-checklists.md)
-- [Appendix F · Document requirements matrix (Project → Milestone → Task)](./appendix-f-requirements-matrix.md)
-- [Appendix G · References & lineage](./appendix-g-references.md)
-
----
-
-## Conventions used in this book
-
-- **▶ Example** marks the running worked example.
-- **Do / Don't** boxes give the rule in its shortest form.
-- A **gate** is a checkpoint with an explicit pass/fail exit. Its outcome is always one of `PASS`, `RISK-ACCEPTED` (a signed waiver), or `HARD-STOP`.
-- File names like `SPEC.md`, `features/*.feature`, `contracts/*` refer to the artifacts you create per feature; see [Appendix A](./appendix-a-templates.md).
-- Where this book uses a plain step name, the formal phase name (for teams mapping to a larger standard) appears once in [Appendix C](./appendix-c-glossary.md).