@pilotspace/add 1.14.0 → 1.15.0

package/CHANGELOG.md

@@ -4,7 +4,155 @@ All notable changes to the ADD method (`@pilotspace/add` on npm,
 `pilotspace-add` on PyPI) are documented here. The format follows
 [Keep a Changelog](https://keepachangelog.com/); versions follow semver.
 
-## [Unreleased]
+## [1.15.0] — 2026-07-02
+
+Ten milestones — the largest bundle yet — round out ADD's self-knowledge
+(**context-search**, **seams**, **artifact-graph**, **traceability-ids**,
+**ground-trust**, **drift-guard**), extend it past static rules
+(**persona-teacher-bundle**, **persona-learning-loop**, **advisor-gated-autonomy**),
+and past Claude Code itself (**portable-roster**). All additive; nothing removed
+or renamed on the CLI surface.
+
+### Added (context-search — find prior work before you drift into it)
+- **`add.py search <keyword...>`** — case-insensitive substring search over the
+  milestone/task corpus (active + archived), title/goal/rationale lines only, never
+  the full body. Surfaced at new-scope drafting and inside the specify/scenarios
+  phase guides, so related prior work is found before drafting — not after a
+  conflicting design ships.
+
+### Added (seams — one home for a shared contract)
+- **`SEAMS.md`.** Symbols that ≥2 tasks touch get promoted into a milestone-level
+  doc that §0 references, so a shared contract has one home instead of being
+  re-derived — and drifting — per task.
+
+### Added (artifact-graph — a traversable cross-artifact graph)
+- **Bidirectional backlinks.** Every ADD artifact now carries minimal backlink
+  metadata (task↔milestone↔release↔deps↔delta) so the cross-artifact graph is
+  traversable without re-deriving it by hand.
+
+### Added (traceability-ids — every rule earns a stable ID)
+- **`M#` / `R#` rule IDs.** Every §1 Must/Reject rule gets a stable ID that §2
+  scenarios and §4 tests reference via a `covers:` line, plus lint coverage so no
+  rule ships unscenarioed or untested.
+
+### Added (persona-teacher-bundle — a vendored, pinned teacher corpus)
+- **agency-agents, vendored.** The agency-agents teacher corpus ships as a pinned,
+  MIT-attributed local library (`.add/personas-teacher/`), bundled into both the
+  npm and PyPI distributions, de-branded from method prose, and refreshed on a
+  schedule. The engine stays NO-EXEC; the release build is zero-network.
+
+### Added (persona-learning-loop — personas that learn your project)
+- **Project-fit personas.** The AI seeds requirements personas at setup (a living
+  doc the project uses live), grows them through the observe→fold self-improve
+  loop, applies them at UDD/advisor/build, and exposes a cross-runner
+  (Claude Code · Codex · …) persona-aware subagent prompt.
+
+### Added (advisor-gated-autonomy — earn autonomy through instrumentation, not by removing the gate)
+- **A persisted, advisor-guarded `auto + parallel` run mode** so high-speed builds stay safe
+  without a human on every step. The whole milestone was dogfooded — every task built
+  `conservative` / human-gated, because you cannot auto-gate the feature that relaxes auto-gating.
+- **`sensitivity:` taxonomy.** A human-declared TASK-header risk-CLASS (base
+  `security · data · architecture · mechanical`, project-extensible via `GLOSSARY.md`) — ADD now
+  reasons about *what kind* of risk, not just *how much* (`risk:`). Validated at freeze; the engine
+  never classifies.
+- **Persisted run mode + setup choice.** The `auto + parallel` posture is persisted and chosen at
+  setup; `add.py status` shows `run mode: parallel + auto`. The non-interactive default stays
+  byte-identical.
+- **Persisted DAG-plan snapshot.** An auditable snapshot of the computed plan (waves · critical path ·
+  tiers) with a freshness check vs the live `depends_on` edges (edges stay the source of truth).
+- **Advisor 3-lens verdict.** The refute-read becomes a tier-aware single advisor running a sequential
+  security → concurrency → architecture sweep recorded in §6 (Verdict · Residue · Binding) — the
+  non-functional review is now structured and auditable; `advisor_verdict_unrecorded` measure-not-block lint.
+- **Advisor coverage audits (measure, never block).** `add.py audit` flags a missing advisor verdict,
+  a self-reviewed verdict (reviewer = author), and a mechanical task with advisor-found residue (mis-tier).
+- **`advisor-gate-relax` — the narrowest safe relaxation.** A `risk: high` + `sensitivity: mechanical`
+  task with a recorded `Verdict: PASS` + `Residue: none` auto-completes via `gate PASS` without a lowered
+  autonomy level. **Security and every non-mechanical class are never relaxed** — the human-in-the-loop
+  floor is untouched.
+- **Per-phase spawn hint.** `status`/`guide` print an advisory subagent-spawn hint (idiom + tier) for the
+  active phase; advisory only — the engine still never spawns.
+- Documentation, glossary (4 new terms), and headers aligned with the feature.
+
+### Added (portable-roster — the phase-roster for every coding tool, not just Claude)
+- **`AGENTS.md` / `.clinerules` carry the roster.** Non-Claude coding tools (Cursor,
+  Copilot, Codex, Cline, …) now receive the ADD phase-roster's 5 roles and
+  boundaries through the `AGENTS.md` the installer already drops, not just
+  Claude Code's native subagents.
+- **`add-advisor` — the 5th roster agent.** A consultative, frontier-model agent
+  (`model: opus`) any phase can spawn on a medium-hard decision — an ambiguous
+  read, a risky shape, a change of approach. It recommends and weighs tradeoffs;
+  it never decides.
+
+### Changed (ground-trust — GROUND surfaces problems, not just structure)
+- **GROUND now surfaces the issues/risks** it finds in the real code (feeding
+  SPECIFY) and links each task's related intent back to the foundation
+  (`PROJECT.md` · `GLOSSARY.md` · conversation) — specs build on problems found,
+  not assumed.
+
+### Changed (drift-guard — kill §0 reference rot)
+- **§0 cites symbols, not line numbers**, stamps `ground_sha`, refreshes at close,
+  and strips dead live-phase scaffolding at done — a closed TASK.md stays true to
+  the code instead of rotting the moment a line shifts.
+
+### Changed (loop-readability — human-scannable output across every phase)
+- **Report shape, audited and tightened.** `report-template.md`'s ARC + 6-block
+  shape was checked against its own stated rules (summary-first, one decision,
+  guided-choice) across all 8 phase guides' gate-reporting cues; 2 guides
+  (`0-setup.md`'s baseline-lock sentence, `3-contract.md`'s freeze-gate
+  sentence) had drifted and were tightened to name SHAPE ahead of the APPROVE
+  guided choice.
+- **SKILL.md's compact pipeline sentence now names the decision banner**
+  ("rendered first, above everything") ahead of the ARC, matching
+  `report-template.md`'s actual render order — closing a gap the shape audit
+  surfaced.
+- **`MILESTONE.md.tmpl` gains a UI/UX Scope hint** — the axes to name
+  precisely for a UI feature (information architecture, interaction pattern,
+  visual hierarchy, design tokens, component states, accessibility floor,
+  responsive breakpoints, user journey), pointing at `design.md` — with
+  adoption pointers wired into `1-specify.md` and `scope.md` so drafters
+  actually reach it. The seed this milestone was created to dogfood.
+
+### Added / Changed (loose tasks since 1.14.0)
+- **Report template PLAN/SHAPE + APPROVE banner** (`report-plan-approve`) — the
+  chat-report decision point renders a clearer guided-choice banner.
+- **`status` pagination** (`status-pagination`) — milestones/tasks sort by
+  updated-descending and cap to the top 10, with a `--all` escape hatch, so a
+  long-lived project's `status` stays scannable.
+- **Lean 3-agent phase roster + adaptive persona agent** (`phase-agents-lean`).
+- **Skill-tree compaction** (`skill-tree-compaction-audit`) — audited and
+  compacted the ADD skill tree for genuine prose redundancy under the pinned
+  lean-fence budget.
+- **Vendor-tree `.gitignore` fixes** — nested `.add/.gitignore` vendor-tree
+  patterns now resolve relative to `.add/`, not repo root
+  (`gitignore-vendor-path-fix`); the installer's own `.gitignore` seed covers all
+  3 managed vendor trees (`installer-gitignore-mirrors`); `update --global`
+  re-seeds `.gitignore` for every registered project, not just fresh installs
+  (`update-global-gitignore-seed`).
+- **CI tooling-mirror gap closed** (`ci-tooling-mirror-gap`) — the `.add/tooling`
+  dogfood mirror is materialized in CI's test + publish-guard jobs, not just
+  locally.
+- **Fresh-checkout skip-count tolerance widened**
+  (`nested-suite-skip-count-tolerance`) — the nested-suite OK-regex now tolerates
+  every known environment-conditional skip, not just the recursion guard.
+- **Scope-walk hygiene** — `.claude` pruned from the scope walk
+  (`scope-exclude-claude`); stale mirror trees re-synced to canonical
+  (`mirror-resync`); `.add/tooling` untracked as a regenerable dogfood mirror
+  (`untrack-add-tooling`).
+
+### Changed
+- Five version sources bump in lockstep to **1.15.0** (`package.json`,
+  `package-lock.json` ×2, `pyproject.toml`, `.claude-plugin/plugin.json`,
+  `add_method.__version__`).
+
+This release bundles **11 closed milestones** (`seams`, `context-search`,
+`drift-guard`, `artifact-graph`, `ground-trust`, `traceability-ids`,
+`persona-teacher-bundle`, `persona-learning-loop`, `advisor-gated-autonomy`,
+`portable-roster`, `loop-readability`) and 13 loose tasks since 1.14.0. Every
+milestone was built end-to-end through ADD's own spec→tests→build→verify flow.
+25 open SPEC deltas (non-security backlog spanning the newly-grounded
+install-update-hardening tasks, report-shape-scan-audit/skill-banner-cue
+follow-ups, and pre-existing items — full list: `add.py deltas`) ride forward
+unresolved into the next cycle.
 
 ## [1.14.0] — 2026-06-29
 

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,41 @@
+# Third-party notices
+
+This project bundles third-party material. Each component below is redistributed under its own
+license, retained in full alongside the vendored files. These notices satisfy the attribution
+requirement of the licenses; they are not affected by any product/marketing naming choices.
+
+---
+
+## Vendored teacher corpus — `add-method/personas-teacher/`
+
+A pinned snapshot of an external library of agent definitions, vendored as a local teacher corpus
+that the persona phase reads off-build. The pinned upstream commit and trim rules are recorded in
+`add-method/personas-teacher/VENDOR.md`; the upstream license is retained verbatim at
+`add-method/personas-teacher/LICENSE`.
+
+- License: **MIT**
+- Copyright (c) 2025 AgentLand Contributors
+
+```
+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.
+```

package/bin/cli.js

@@ -585,11 +585,21 @@ function seedSoulMd(target) {
   }
 }
 
-// Ensure .add/.gitignore lists the engine's transient artifacts. Seed it from the bundled
-// tooling/templates/gitignore.tmpl if absent; else APPEND-IF-ABSENT each pattern line the
-// template carries that the file lacks — additive only, never reorders/removes user lines,
-// idempotent; comment/blank lines are not appended to an existing file. Fail-soft. Twin of
-// _installer.py:_seed_gitignore.
+// kept OUTSIDE add_engine/constants.py / gitignore.tmpl deliberately: the engine's own
+// _GITIGNORE_BODY constant must never contain "personas-teacher" (test_engine_unchanged_
+// and_handsoff — the engine stays hands-off of the teacher vendor tree). The INSTALLER
+// already names that tree explicitly (MANAGED/OPTIONAL), so it is free to seed this one
+// extra ignore line itself. BARE (not repo-root style): .add/.gitignore lives INSIDE
+// .add/, so git resolves its patterns relative to .add/ itself. Twin of
+// _installer.py:_INSTALLER_MANAGED_IGNORE_EXTRA.
+const INSTALLER_MANAGED_IGNORE_EXTRA = ["personas-teacher/"];
+
+// Ensure .add/.gitignore lists the engine's transient artifacts + managed vendor trees.
+// Seed it from the bundled tooling/templates/gitignore.tmpl (plus
+// INSTALLER_MANAGED_IGNORE_EXTRA) if absent; else APPEND-IF-ABSENT each pattern line that
+// combined body carries that the file lacks — additive only, never reorders/removes user
+// lines, idempotent; comment/blank lines are not appended to an existing file. Fail-soft.
+// Twin of _installer.py:_seed_gitignore.
 function seedGitignore(target) {
   const source = path.join(PKG_ROOT, "tooling", "templates", "gitignore.tmpl");
   if (!fs.existsSync(source)) {
@@ -598,7 +608,9 @@ function seedGitignore(target) {
   }
   const dest = path.join(target, ".add", ".gitignore");
   try {
-    const body = fs.readFileSync(source, "utf8");
+    let body = fs.readFileSync(source, "utf8");
+    if (!body.endsWith("\n")) body += "\n";
+    body += INSTALLER_MANAGED_IGNORE_EXTRA.join("\n") + "\n";
     if (!fs.existsSync(dest)) {
       fs.mkdirSync(path.dirname(dest), { recursive: true });
       fs.writeFileSync(dest, body);                       // seed-if-missing
@@ -725,7 +737,13 @@ const MANAGED = [
   ["skill/add", [".claude", "skills", "add"], false],
   ["tooling", [".add", "tooling"], true],
   ["docs", [".add", "docs"], false],
+  ["personas-teacher", [".add", "personas-teacher"], false],
 ];
+// Optional managed trees: an ENHANCEMENT the persona phase reads, not core runtime. The real
+// package always ships these (guarded by test_packaging); a malformed/older package missing one
+// must NOT abort the install — the core lands and the optional tree is soft-skipped. Twin of
+// _installer.py:OPTIONAL. Design-for-failure.
+const OPTIONAL = new Set(["personas-teacher"]);
 const STAMP_FILE = ".add-version";
 const LOCK_FILE = ".update.lock";   // the `update --global` home lock (never user-data)
 
@@ -786,7 +804,7 @@ function cleanReplaceTree(src, dest, stripTests) {
   return { restored: restored, refreshed: refreshed };
 }
 
-const TREE_LABEL = { "skill/add": "skill", "tooling": "tooling", "docs": "docs" };
+const TREE_LABEL = { "skill/add": "skill", "tooling": "tooling", "docs": "docs", "personas-teacher": "personas" };
 
 // Per managed tree: "missing" (dest absent OR empty) or "present".
 function managedStatus(target) {
@@ -805,7 +823,9 @@ function managedStatus(target) {
 // a corrupt package leaves the target untouched).
 function reconcile(args, target, srcRoot) {
   srcRoot = srcRoot || PKG_ROOT;   // default: the package; the global home feeds propagation
-  const trees = MANAGED.filter(([sub]) => !(sub === "skill/add" && args.noSkill));
+  const trees = MANAGED
+    .filter(([sub]) => !(sub === "skill/add" && args.noSkill))
+    .filter(([sub]) => !(OPTIONAL.has(sub) && !fs.existsSync(path.join(srcRoot, sub))));  // soft-skip absent optional
   for (const [sub] of trees) {
     if (!fs.existsSync(path.join(srcRoot, sub))) {
       fail("missing packaged source: " + path.join(srcRoot, sub));
@@ -876,18 +896,20 @@ const GLOBAL_TREES = [
   ["skill/add", ["skill", "add"], false],
   ["tooling", ["tooling"], true],
   ["docs", ["docs"], false],
+  ["personas-teacher", ["personas-teacher"], false],
 ];
 
 // Clean-replace the bundled managed layer INTO <home> (canonical mirror), then DEPLOY the
 // skill to ~/.claude/skills/add. Throws if a dir can't be written (caller -> home_unwritable).
 // Prechecks ALL sources first (design-for-failure: a corrupt package leaves the home as-is).
 function reconcileGlobal(home, claudeDir, noSkill) {
-  for (const [sub] of GLOBAL_TREES) {
+  const trees = GLOBAL_TREES.filter(([sub]) => !(OPTIONAL.has(sub) && !fs.existsSync(path.join(PKG_ROOT, sub))));
+  for (const [sub] of trees) {
     if (!fs.existsSync(path.join(PKG_ROOT, sub))) {
       fail("missing packaged source: " + path.join(PKG_ROOT, sub));
     }
   }
-  for (const [sub, destParts, stripTests] of GLOBAL_TREES) {
+  for (const [sub, destParts, stripTests] of trees) {
     cleanReplaceTree(path.join(PKG_ROOT, sub), path.join(home, ...destParts), stripTests);
   }
   if (!noSkill) cleanReplaceTree(path.join(home, "skill", "add"), claudeDir, false);
@@ -1123,6 +1145,7 @@ function cmdUpdateGlobal(args) {
       log("  ⚠ registered path " + np + " is not an ADD project (no .add/) — dropping"); dropped++; continue;
     }
     reconcile(args, np, home);      // standard MANAGED map, sourced from the home mirror
+    seedGitignore(np);               // keep .add/.gitignore current too (parity: _installer.py)
     // re-persist an opted-in project (one that already has a snapshot); a vanished
     // project's snapshot is KEPT above (the backup outlives the dir).
     if (fs.existsSync(path.join(home, "data", dataKey(np)))) persistData(home, np);
@@ -1156,7 +1179,10 @@ function cmdUpdate(args) {
   // same-version no-op ONLY when nothing is missing — a missing managed tree HEALS
   // even at the current version (heal-reconcile).
   const status = managedStatus(target);
-  const missing = MANAGED.some(([sub]) => status[sub] === "missing");
+  // An optional tree absent from BOTH the package and the project can't be healed, so it
+  // never counts as "missing" — otherwise a same-version update would never reach the no-op.
+  const missing = MANAGED.some(([sub]) => status[sub] === "missing"
+    && !(OPTIONAL.has(sub) && !fs.existsSync(path.join(PKG_ROOT, sub))));
   if (cur === version && !args.force && !missing) {
     log("ADD already at " + version + " — nothing to update (use --force to re-materialize).");
     return;

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/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.15.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"
@@ -24,6 +24,8 @@
     "!**/*.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.