@pilotspace/add 1.14.0 → 1.16.0

package/docs/02-the-flow.md

@@ -93,7 +93,7 @@ The flow runs in two directions under two rules that never conflict. **Backward
 | 6 Verify | own the residue (security · concurrency · architecture); approve when `conservative` | gather evidence; **auto-PASS on complete evidence** under `autonomy: auto` |
 | 7 Observe | read the signal; consolidate confirmed deltas into PROJECT.md | run behind a flag; emit lessons learned |
 
-**What the human sees when it is their turn — the decision arc.** Whenever the flow stops for the human — the baseline approval that ends setup, the contract-freeze decision point and an escalated verify gate within each task, and the wider decision points of the loop (intake · scope · milestone close · stage graduation) — the AI opens its report with the **decision arc**: three engine-sourced lines — `goal:` the milestone goal the work serves · `done:` the proven progress toward it · `plan:` what comes next. The arc renders first, above the report's summary, so the human confirms with sight of the whole trajectory rather than a local snapshot. Within that report the AI also presents the **DECISION** itself as a **guided choice** — one highlighted **recommended pick** (`▶ … (recommended)`) plus its real, described alternatives — so the human chooses with the recommendation and each option's consequence in view rather than a bare next-step line. Both are presentation only — they never add a gate or change an outcome, and the guided choice fires at human gates only. See [Appendix C](./appendix-c-glossary.md) and the `add` skill's `report-template.md` for the convention itself.
+**What the human sees when it is their turn — the decision banner and arc.** Whenever the flow stops for the human — the baseline approval that ends setup, the contract-freeze decision point and an escalated verify gate within each task, and the wider decision points of the loop (intake · scope · milestone close · stage graduation) — the AI opens its report with a **banner** (`PLAN · <title> · <gate> → APPROVE?` plus a file-path line) and the **decision arc**: three engine-sourced lines — `goal:` the milestone goal the work serves · `done:` the proven progress toward it · `plan:` what comes next. The arc renders above the report's summary, so the human confirms with sight of the whole trajectory rather than a local snapshot. Within that report the AI also presents **APPROVE** itself as a **guided choice** — one highlighted **recommended pick** (`▶ … (recommended)`) plus its real, described alternatives — so the human chooses with the recommendation and each option's consequence in view rather than a bare next-step line. Both are presentation only — they never add a gate or change an outcome, and the guided choice fires at human gates only. See [Appendix C](./appendix-c-glossary.md) and the `add` skill's `report-template.md` for the convention itself.
 
 ## What survives, and what is disposable
 

package/docs/03-step-1-specify.md

@@ -35,6 +35,10 @@ Four parts, kept short:
 
 Naming the errors matters. "Reject bad amounts" is an instruction to guess; `amount <= 0 -> "amount_invalid"` is a rule that produces a testable scenario and a defined contract response.
 
+### Rule IDs (optional — opt-in by usage)
+
+Give each Must a stable `M<n>:` ID; a Reject's own error code already IS its ID (referenced later as `R:<error_code>`). Once a task uses a tag anywhere in §2 SCENARIOS or §4 TESTS, `add.py check` starts asking that every Must/Reject be covered by a scenario tag or a test's `covers:` line — a task that never tags anything is never retro-flagged. See the template's own inline example for the exact grammar.
+
 ## Template
 
 ```

package/docs/04-step-2-scenarios.md

@@ -58,6 +58,10 @@ Scenario: not my account
 
 The `And no balance changes` line is doing real work: it specifies that a rejected transfer must leave the world untouched — a property the AI could easily violate by deducting before checking.
 
+### Tagging back to a rule ID (optional — opt-in by usage)
+
+If §1's Musts and Rejects carry stable IDs (`M1:`, and a Reject's own error code as `R:<error_code>`), tag each `Scenario:` line with the ID(s) it covers, e.g. `# M1, R:amount_invalid`. Once a task tags even one scenario this way, `add.py check` starts confirming every §1 ID is covered by a tag here or a `covers:` line in §4 TESTS — a task that never tags anything is left alone. See the template's own inline example for the exact grammar.
+
 ## Cover the edge cases
 
 The transfer above is one domain; the same gaps recur in every domain — an HR leave request, a marketing campaign send, a checkout. Beyond the spec's "Reject" rules, sweep the recurring gaps and add a scenario for each that applies (or rule it out on purpose): boundary, duplicate/idempotent, ownership, stale/out-of-order, partial failure, concurrency, malformed input, limits/volume.

package/docs/06-step-4-tests.md

@@ -50,6 +50,10 @@ def test_not_my_account():
 
 Run this now, with no implementation: all three fail. That is the correct, honest starting point for the build.
 
+### Declaring which rule a test covers (optional — opt-in by usage)
+
+If §1's Musts and Rejects carry stable IDs, add a trailing `covers: M1, R:amount_invalid` to a test-plan line to declare which ID(s) that test satisfies. Once any test in a task declares a `covers:` line (or any §2 scenario carries a tag), `add.py check` confirms every §1 ID is covered by a tag or a `covers:` line somewhere — a task that never uses either is left alone. See the template's own inline example for the exact grammar.
+
 ## The AI's role here
 
 The AI generates the test suite from the scenarios and contract. Your job is to confirm two things it cannot judge for itself: that each test asserts *behavior* rather than internal detail, and that none of them pass by accident before code exists. See `playbook/4_tests.md` in [Appendix B](./appendix-b-prompts.md).

package/docs/08-step-6-verify.md

@@ -31,9 +31,15 @@ Before the build, the task pre-declares its **build expectations** — the obser
 - [ ] Coverage did not decrease.
 - [ ] No test or contract was altered during the build.
 - [ ] Every pre-declared build expectation is confirmed by real evidence (not merely a green test).
+- [ ] Every §1 Must/Reject rule still traces to a §2 scenario tag or a §4 `covers:` line.
+- [ ] Every symbol §3's contract cites still resolves in the *current* tree, not just at Ground SHA.
 
 If any of these is false, stop here and return to the build; there is nothing to verify yet.
 
+A green suite proves the tests you wrote pass — it says nothing about a rule you never wired a scenario or test to at all. That is a different failure than the ones Part four covers: not a cheated pass, but a rule with no trace of ever being checked. `add.py check` scans every task project-wide for exactly this — a §1 Must or Reject with no §2 scenario tag and no §4 `covers:` line — but that sweep is easy to forget to run. `add.py audit`'s `rule_coverage_gap` notice surfaces the SAME check for the task actually at this gate, the moment it reaches Verify (a task that never adopted the tag convention at all is silently grandfathered, never retro-flagged). Neither blocks the gate; both make an already-real gap impossible to miss.
+
+The second check guards against a quieter kind of drift. §0's Ground SHA anchors the symbols §3's contract cites to the commit they were read at — but code moves *during* the build that follows. Before this gate, re-resolve every one of those symbols against the tree as it stands now, not the Ground SHA snapshot, and record it in §6's **Live-verify evidence** block. A moved or renamed anchor caught here is a one-line note; the same drift left silent is a future reader chasing a line number that no longer means what it did at Ground.
+
 ## Part two — check what tests miss
 
 Automated tests are excellent at behavior on defined inputs and poor at a few specific things. Check those by hand, every time:
@@ -77,6 +83,7 @@ A security finding is always a `HARD-STOP`; it is never waved through with a wai
 
 - [ ] All tests pass (the evidence).
 - [ ] Every pre-declared build expectation is confirmed by observable evidence.
+- [ ] Every §1 rule traces to §2/§4; every §3-cited symbol still resolves in the current tree.
 - [ ] Concurrency/timing of the risky operation is safe.
 - [ ] No exposed secrets, injection openings, or unexpected dependencies.
 - [ ] Layering and dependencies follow `CONVENTIONS.md`.

package/docs/18-personas.md

@@ -0,0 +1,80 @@
+# 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 or success-metric, 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` or `## Success Metrics` 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/appendix-c-glossary.md

@@ -18,6 +18,10 @@
 
 **Component** — a declared part of a multi-part codebase that owns a source `root` and its own `green-bar` (suite + checks), named in `.add/components.toml` under `[component.<name>]`. A task binds to one with a `component:` header line, which adds that root to its §5 Scope and holds it to that component's green bar at verify. At the gate the engine also **surfaces** the component's `verify` command (the literal suite to run, e.g. `pytest -q`) and records it — NO-EXEC, the operator runs it; the fast lane carries the same `component:` affordance. Declared, never inferred; a project with no components is byte-identical to a single-codebase project. See [17 Components](./17-components.md).
 
+**persona** — a project-fit requirements lens the agent adopts, distilled from a *teacher* — the vendored local library at `.add/personas-teacher/` — to three machine-readable parts: an **Identity** (the stance), **Critical Rules** (the non-negotiable constraints), and measurable **Success Metrics** (the done-bar). Stored as a versioned `.add/personas/<slug>.md`; read off-build (the teacher is never a runtime dependency); advisory only — it never lowers a gate (a security finding still `HARD-STOP`s) and the engine stays NO-EXEC. See [18 Personas](./18-personas.md).
+
+**persona loop** — how personas come to exist and improve: **seed** (proposed at setup from the foundation) → **grow** (observe emits a persona delta; the human consolidates confirmed deltas into the file) → **apply** (UDD framing, advisor/streams subagent selection, and the build overlay atop `SOUL.md`). Opt-in and additive; a project with no personas behaves exactly as before. See [18 Personas](./18-personas.md).
+
 **Cross-component contract** — the frozen, machine-checkable interface between a producer component and its consumers, declared under `[contract.<id>]` (producer + consumers). A task names its role with a `produces: <id>` or `consumes: <id>` header. On the producer's freeze the engine writes an immutable snapshot at `.add/contracts/<id>.json`; a consumer pins its hash and is flagged `contract_consumer_stale` if the producer later re-freezes a changed shape. Inside one milestone a `consumes:` task is HELD from writing its §3 until the producer's snapshot exists — the intra-milestone BE→FE ordering. Freeze-recency: the consumer is also held `producer_contract_stale` if a *live* producer task has re-opened or drifted its §3 (the snapshot no longer matches a frozen producer); `add.py check` surfaces the softer `contract_producer_stale` and `contract_snapshot_hashless` (a snapshot with no hash to verify) as never-red warnings. See [17 Components](./17-components.md).
 
 **Federation (multi-repo)** — the transport that carries a frozen cross-component contract between separate repositories. A consumer repo declares `[federation.<id>]` with a `source` (and optional `pin`); `add.py federate pull <id>` validates the producer repo's published snapshot and lands a byte-for-byte copy locally, where it behaves exactly as in a monorepo. Fail-loud: an unknown id, unreadable source, a `source` that escapes the repo's allowlist (`federation_source_escapes` — the path is confined to a sibling of the repo root), invalid snapshot, or version mismatch HARD-STOPS and lands nothing. Each repo keeps its own git-native `state.json`; only the immutable snapshot crosses. See [17 Components](./17-components.md).
@@ -52,7 +56,7 @@
 
 **The decision arc** — the three engine-sourced lines a gate report opens with at every **decision point**: `goal:` the milestone goal the work serves · `done:` the achievement, the proven progress toward it (the gate reports render this line as `done`) · `plan:` what comes next. What `done` reports adapts per gate (verify: tests + evidence · milestone close: exit-criteria met · intake: the request sized) while the three-part shape stays constant. Rendered first, above the report's summary, so the human confirms with sight of the whole trajectory, not a local snapshot. Engine-sourced like all evidence — goal · done · plan are pulled from `add.py` output, never re-typed. Presentation only: it never adds a gate or changes a `PASS` / `RISK-ACCEPTED` / `HARD-STOP` / freeze outcome. The report it opens is the chat report a person reads at a decision point — distinct from the three Test/Quality/Risk reports a verify gate produces ([11 Governance](./11-governance.md)). See the `add` skill's `report-template.md`.
 
-**Guided decision** — a **decision point** presented not as a bare next-step line but as one highlighted **recommended pick** plus its real, described alternatives (each with its one-line consequence), so the human chooses with the recommendation and what each option costs already in view. It refines the report's DECISION block — composing with **the decision arc**, never adding a gate — and fires at human gates only (never at an autonomous `[you drive]` step). The sibling of the decision arc: both are what the human sees when it is their turn. See the `add` skill's `report-template.md` for the convention itself.
+**Guided decision** — a **decision point** presented not as a bare next-step line but as one highlighted **recommended pick** plus its real, described alternatives (each with its one-line consequence), so the human chooses with the recommendation and what each option costs already in view. It refines the report's APPROVE block — composing with **the decision arc**, never adding a gate — and fires at human gates only (never at an autonomous `[you drive]` step). The sibling of the decision arc: both are what the human sees when it is their turn. See the `add` skill's `report-template.md` for the convention itself.
 
 **Recommended pick** — the one option a **guided decision** highlights with the `▶ … (recommended)` marker: exactly one, never zero and never two. The AI's confidence self-score informs the pick; the human overrides it freely. See **Guided decision**.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.14.0",
+  "version": "1.16.0",
   "description": "ADD (AI-Driven Development). One skill. Eight steps. Five disciplines. Every feature ships through the loop — a minimal, state-tracked Claude Code skill that ships the AIDD book as its trust layer.",
   "bin": {
     "add": "bin/cli.js"
@@ -18,12 +18,15 @@
   "files": [
     "bin/",
     "skill/",
+    "agents/",
     "tooling/add.py",
     "tooling/add_engine/",
     "!tooling/add_engine/__pycache__",
     "!**/*.pyc",
     "tooling/templates/",
     "docs/",
+    "personas-teacher/",
+    "THIRD_PARTY_NOTICES.md",
     "README.md",
     "GETTING-STARTED.md",
     "CHANGELOG.md",

package/personas-teacher/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 AgentLand Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.