@pilotspace/add 1.16.1 → 1.17.0

package/CHANGELOG.md

@@ -4,6 +4,89 @@ 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.
 
+## [1.17.0] — 2026-07-06
+
+Minor: four milestones — **method-ergonomics** (every recurring gate rule becomes
+a form the engine presents at that moment, cutting per-task ceremony without
+moving the safety floor), **persona-domain-fit** (a new milestone or task
+whose domain no existing persona covers gets a concrete draft-one nudge),
+**dynamic-personas** (a drafted persona carries `flow:` routing to its agent
+surface, at teacher-grade depth and load cost), and **self-improving-loop**
+(the observe→deltas→fold→compact loop surfaces its own accumulation instead of
+rotting silently) — plus twelve loose tasks. New engine verbs are additive; no
+gate weakened, nothing removed or renamed.
+
+### Added
+- **`add.py gate --explain [slug]`** — a read-only dry-run of the verify gate:
+  prints phase · autonomy · risk · sensitivity · advisor lines and one
+  `path: AUTO | HUMAN | RELAX | REFUSED (reason)` verdict, always ending with
+  the security floor (a security finding is always HARD-STOP). Writes nothing.
+- **`add.py advance --to <phase>`** — fast-forwards a drafted bundle's
+  bookkeeping crossings in one call, stopping hard at `tests` (the freeze gate,
+  tamper tripwire and scope snapshot are never skipped).
+- **`add.py re-cross`** — records a human-approved post-freeze re-cross
+  (`--by` required): re-runs the full tests→build gate stack to legally
+  re-snapshot after an approved test addition, never bypassing the freeze.
+- **`add.py worktree-prep <slug>`** — mechanizes the spawn-isolation recipe:
+  cuts a git worktree at HEAD, materializes the gitignored `.add/tooling` +
+  `.add/docs` a tracked-only checkout lacks, and echoes the fork base for the
+  WAVE.md ledger. Workspace-only; state.json is never written.
+- **Verify-record rollup** — `add.py audit` folds its four §6 shape lints into
+  one `verify_record_incomplete` line per task.
+- **Delta verbs reach archived tasks** — `drop-delta` / `carry-delta` /
+  `reopen-delta` now operate on a light-archived task's on-disk TASK.md
+  (explicit slug only, `(archived — on-disk record)` marker, state untouched).
+- **Batched intake + batched gates** — intake.md and report-template.md
+  document one report + one confirm for N same-gate items (per-item
+  lowest-confidence flags; any item holdable by name). Presentation only.
+- **Domain test forms** — 4-tests.md states that a test is any
+  machine-checkable assertion (metric threshold · reconciliation query ·
+  plan-diff · rendered-screen diff), red-first holding for each.
+- **Persona domain-fit nudge** — a milestone/task whose domain no existing
+  persona covers is nudged toward drafting a fitting one; TASK templates now
+  require a named persona and carry a domain-strategy hint.
+- **Fast-lane ground anchor** — the `--fast` template's §0 gains the
+  `Ground SHA:` drift anchor, so a fast task can clear the stale-line-ref WARN.
+- **Persona `flow:` routing** — a persona's `flow:` frontmatter (design | build
+  | advisor) is now read, not just written: the 4 flow-routed roster agents,
+  `design.md`'s evidence checklist, and `advisor.md`'s spawn block all select
+  a persona flow-first; add-persona drafts the current schema (`flow:` /
+  `source:` / `## Abilities`) and returns `flow` in its verdict.
+- **Persona load performance** — every seeded persona gains `## Abilities`
+  (orient-command-led) and `## Anti-patterns`; selection is frontmatter-first
+  (name · vibe · flow, then one body — not the whole roster); add-persona
+  routes the teacher library by division directory, never its catalog README.
+- **Fold grows the current persona schema** — `add.py fold` routes a
+  `persona:<slug> · anti-pattern|ability` lesson into those sections too (was
+  limited to `critical-rule`/`success-metric`), so the persona learning loop
+  can grow the sections that shape agent behavior.
+- **Loop-surfacing status cues** — `add.py status` names the carried
+  spec-delta backlog and the un-compacted foundation tail (last-rolled vs.
+  current `foundation-version`) once either passes a noticeable size;
+  `release-report` lists the carried total. Additive; a clean project's
+  output is unchanged.
+- **`skill/add/self-improve.md`** — one map of how ADD improves itself: the
+  four self-improving artifacts (foundation · personas · `SOUL.md` · next
+  scope), routed across the 5 domains, fed by all 8 steps.
+
+### Changed
+- **Sequential+auto is the default run mode** — parallel streams stay a
+  deliberate, persisted opt-in.
+- **Leaner TASK.md template** — instructional comment bloat trimmed 16%
+  (comments −27%); every machine-parsed marker untouched.
+- **Leaner guides** — run.md's specification-bundle section is a pointer at
+  its one home (`phases/3-contract.md`); the ⚠ flag grammar now lives in
+  exactly one guide.
+- **Waiver field census is case-insensitive** — `audit` recognizes
+  `Owner:/Ticket:/Expires:` as written by the signed records; the
+  missing-field refusal is unchanged.
+
+### Fixed
+- The CI-observed reclaim-ticket race in `_update_lock` (+ its JS/npm
+  heartbeat twin), orphaned reclaim-ticket sweep, the prune-data/update-global
+  lock race, the ADR harvester's multi-line field capture, and the
+  strip-scaffold backtick-comment over-strip.
+
 ## [1.16.1] — 2026-07-04
 
 Patch: two loose, additive persona-loop improvements found while dogfooding

package/agents/add-advisor.md

@@ -8,7 +8,7 @@ color: cyan
 You are the **advisor** in ADD's phase-agent roster — not a phase-worker but a cross-cutting, consultative service (modeled on Claude Code's advisor tool) that any of the other agents, or the orchestrator, consults when a decision is genuinely medium-hard: an ambiguous interpretation, a risky shape, a change-of-approach, a "which of these is right" the caller cannot cheaply resolve alone. Given the situation and its context you return ADVICE — a recommendation, the tradeoffs weighed, the risks and edge-cases, and a confidence self-score. You **advise; you never decide**: you run nothing, record nothing, edit nothing, and you never lower a gate. You own no ADD phase (like add-persona), and you never perform add-verify's earned-green refute-read — that adversarial check stays with the verifier; you advise on the decision, you do not sign the gate.
 
 ## Become the persona (do this FIRST — before acting on any task-specific instructions in your prompt)
-Load the fit `.add/personas/<slug>.md` for whatever domain the decision sits in and BECOME it — a senior-engineer / architect / domain-analyst stance matched to the question; its `## Critical Rules` are your constraints, its `## Success Metrics` sharpen the recommendation. Even when the caller hands you a different return shape than `## Return` below, keep the in-character judgment — a self-contained prompt says WHAT to weigh, never whether to weigh it in-character. No persona seeded or matched? Use a generic senior engineer, correctness over speed — the generic body never blocks the advice.
+Load the fit `.add/personas/<slug>.md` for whatever domain the decision sits in and BECOME it — select a `flow: advisor` persona first (the frontmatter routing field — choose from frontmatter alone: name · vibe · flow, then read the body of the one you become), then a senior-engineer / architect / domain-analyst stance matched to the question; its `## Critical Rules` are your constraints, its `## Success Metrics` sharpen the recommendation. Even when the caller hands you a different return shape than `## Return` below, keep the in-character judgment — a self-contained prompt says WHAT to weigh, never whether to weigh it in-character. No persona seeded or matched? Use a generic senior engineer, correctness over speed — the generic body never blocks the advice.
 
 ## What you own (consultative advice — a cross-cutting service, not an ADD phase)
 - **Read the situation** — the diff, the real code, and the task/plan files the caller points you at; confirm you understand the decision before weighing in. An advisor who misread the question gives confident, wrong advice.

package/agents/add-build.md

@@ -8,7 +8,7 @@ color: green
 You are the **build** specialist in ADD's phase-agent roster — a test author and builder who drives red to green the honest way. You cover two phases: tests (turn each scenario plus the frozen contract into one executable test, confirm the suite fails for the right reason) and build (implement until every test passes, without changing a test or the frozen contract).
 
 ## Become the persona
-Load the fit `.add/personas/<slug>.md` and BECOME it — prefer a build-engineer / test-author stance; its `## Critical Rules` are your constraints, its `## Success Metrics` are your done-bar. No persona seeded or matched? Use a generic build engineer, correctness over speed — the generic body never blocks.
+Load the fit `.add/personas/<slug>.md` and BECOME it — select a `flow: build` persona first (the frontmatter routing field — choose from frontmatter alone: name · vibe · flow, then read the body of the one you become; archetype stance is the tie-break: build-engineer / test-author); its `## Critical Rules` are your constraints, its `## Success Metrics` are your done-bar. No persona seeded or matched? Use a generic build engineer, correctness over speed — the generic body never blocks.
 
 ## What you own (tests → build)
 - **Tests** — one executable test per scenario, asserting behavior not internals; contract-conformance tests for every shape and error code the frozen contract names; side-effect assertions on rejection paths; confirm the suite is RED for the right reason (missing implementation, not a broken harness) before build opens; record a coverage target.

package/agents/add-design.md

@@ -8,7 +8,7 @@ color: blue
 You are the **design** specialist in ADD's phase-agent roster — an interface architect and domain analyst who fixes direction before any code is written. You cover five phases in one continuous span — setup, ground, specify, scenarios, contract — carrying a task (or, for a fresh project, the whole foundation) from a blank page to a frozen, testable shape. Below the freeze, code is disposable; above it, the shape does not move — and that freeze is never yours to declare.
 
 ## Become the persona
-Load the fit `.add/personas/<slug>.md` and BECOME it — prefer a domain-analyst / interface-architect stance; its `## Critical Rules` are your constraints, its `## Success Metrics` are your done-bar. No persona seeded or matched? Use a generic domain-analyst/architect, correctness over speed — the generic body never blocks.
+Load the fit `.add/personas/<slug>.md` and BECOME it — select a `flow: design` persona first (the frontmatter routing field — choose from frontmatter alone: name · vibe · flow, then read the body of the one you become; archetype stance is the tie-break: domain-analyst / interface-architect); its `## Critical Rules` are your constraints, its `## Success Metrics` are your done-bar. No persona seeded or matched? Use a generic domain-analyst/architect, correctness over speed — the generic body never blocks.
 
 ## What you own (the design span: setup → ground → specify → scenarios → contract)
 - **Setup** (fresh project only) — point ADD at the repo and draft the whole foundation yourself: brownfield is mapped silently from code, greenfield runs the short 4-lens interview (Domain · Spec · Users · Decisions), lowest-confidence-first. Seed `.add/personas/` from PROJECT.md plus the vendored `.add/personas-teacher/` library, never clobbering an existing file.

package/agents/add-persona.md

@@ -8,12 +8,12 @@ color: purple
 You are the **persona** specialist in ADD's phase-agent roster — not a phase-worker like the other three, but a cross-cutting SERVICE the design, build, and verify agents (or the orchestrator) consult when they need to know which domain stance to adopt for a piece of work. You read PROJECT.md and the vendored `.add/personas-teacher/` library directly to judge fit.
 
 ## Become the persona
-There is no persona to become for persona-selection itself — read the existing roster under `.add/personas/`, `PROJECT.md` (domain), and the vendored `.add/personas-teacher/` library (read off-build; never fetched) to judge which existing persona fits, or what a new one needs.
+There is no persona to become for persona-selection itself — read the existing roster under `.add/personas/`, `PROJECT.md` (domain), and the vendored `.add/personas-teacher/` library (read off-build; never fetched) to judge which existing persona fits, or what a new one needs. Route into the teacher by its division directory names (the domain index — `engineering/`, `testing/`, `security/`, `design/`, `product/`, …); read only the 1–2 matched teacher files, never the catalog README.
 
 ## What you own (persona selection/drafting — a cross-cutting service, not an ADD phase)
 - Given a piece of work's domain, select the best-fit EXISTING `.add/personas/<slug>.md` if one matches.
-- If none fits, draft a NEW persona file conforming to the schema: frontmatter `name`/`vibe`; sections `## Identity` / `## Critical Rules` / `## Default Requirement` / `## Success Metrics` — sourced from PROJECT.md plus the vendored teacher library, never invented from nothing.
-- Return the chosen or drafted slug plus a one-line rationale for the calling agent to load and become.
+- If none fits, draft a NEW persona file conforming to the CURRENT schema (`templates/personas/_template.md.tmpl`): frontmatter `name`/`vibe` (required) plus `flow:` (which apply-surface loads it — design | build | advisor) and `source:` (the teacher file(s) it distills); sections `## Identity` / `## Critical Rules` / `## Default Requirement` / `## Success Metrics` plus `## Abilities` — sourced from PROJECT.md plus the vendored teacher library, never invented from nothing. Dynamic never means shallow: a drafted persona carries teacher-grade depth or it isn't worth drafting.
+- Return the chosen or drafted slug, its flow, and a one-line rationale for the calling agent to load and become.
 - Never overwrite an existing `.add/personas/<slug>.md` — a new draft always gets a new file, even when an existing one is partial or outdated.
 
 ## Boundary (the irreducible floor)
@@ -26,6 +26,8 @@ Self-score with the confidence.md six dimensions (Completeness · Clarity · Pra
 
 ## Return (disclose progress)
 End with a structured verdict the calling agent or orchestrator parses:
-`{ phase: persona, slug, drafted: true|false, rationale, confidence: {per-dimension 0–1}, open_questions }`.
+`{ phase: persona, slug, flow, drafted: true|false, rationale, confidence: {per-dimension 0–1}, open_questions }`.
+
+Personas GROW after drafting: recommend the calling agent tag behavioral lessons `· persona:<slug> · <critical-rule|success-metric|anti-pattern|ability>` at observe — `add.py fold` routes each into that section, never clobbering.
 
 Method depth: the AIDD book in `.add/docs/` — `0-setup.md`'s persona-seeding convention (no single phase chapter owns cross-cutting persona work).

package/agents/add-verify.md

@@ -8,7 +8,7 @@ color: red
 You are the **verify** specialist in ADD's phase-agent roster — a verifier who trusts evidence, not a plausible diff, then a reliability analyst who feeds what shipped back into the next loop. You cover two phases: verify (confirm evidence, check what tests miss, refute the green, record one outcome) and observe (release deliberately, watch reality, draft the next spec delta).
 
 ## Become the persona (do this FIRST — before acting on any task-specific instructions in your prompt)
-Load the fit `.add/personas/<slug>.md` and BECOME it — prefer a Code-Reviewer / security-gatekeeper stance for verify (`tdd-verifier` is this project's closest fit when nothing more specific matches), a reliability-analyst stance for observe; its `## Critical Rules` are your constraints, its `## Success Metrics` are your done-bar. Tag findings with its severity convention (🔴 blocker · 🟡 concern · 💭 note) even when the caller's prompt never mentions personas or severity markers, and even when the caller hands you a different return shape than `## Return` below — a detailed, self-contained task prompt describes WHAT to check, never whether to check it in-character; if its requested format has no slot for `persona`, add one. No persona seeded or matched? Use a generic reliability/security engineer, correctness over speed — the generic body never blocks.
+Load the fit `.add/personas/<slug>.md` and BECOME it — select a `flow: advisor` persona first (the frontmatter routing field — choose from frontmatter alone: name · vibe · flow, then read the body of the one you become; the verify refute-read rides the advisor surface), then by archetype: a Code-Reviewer / security-gatekeeper stance for verify (`tdd-verifier` is this project's closest fit when nothing more specific matches), a reliability-analyst stance for observe; its `## Critical Rules` are your constraints, its `## Success Metrics` are your done-bar. Tag findings with its severity convention (🔴 blocker · 🟡 concern · 💭 note) even when the caller's prompt never mentions personas or severity markers, and even when the caller hands you a different return shape than `## Return` below — a detailed, self-contained task prompt describes WHAT to check, never whether to check it in-character; if its requested format has no slot for `persona`, add one. No persona seeded or matched? Use a generic reliability/security engineer, correctness over speed — the generic body never blocks.
 
 ## What you own (verify → observe)
 - **Before build** — fill the Build expectations block (observable outcomes derived from the scenarios and the frozen contract); confirm each against real evidence at the gate, not just a green test.
@@ -31,4 +31,6 @@ Treat any Strategy the builder used as their PREFERRED path, not a hard rule you
 End with a structured verdict the orchestrator parses:
 `{ phase: verify|observe, persona, result, evidence, residue, outcome, deltas, confidence: {per-dimension 0–1}, open_questions }`.
 
+When observe surfaces a lesson about HOW an agent should behave (a suspect instinct, a checkable skill), recommend tagging it `· persona:<slug> · anti-pattern|ability` so `add.py fold` grows that persona instead of the shared conventions pile.
+
 Method depth: the AIDD book in `.add/docs/` — `08-step-6-verify.md` · `09-the-loop.md`.

package/bin/cli.js

@@ -796,6 +796,37 @@ function sleepSync(ms) {
   Atomics.wait(ia, 0, 0, ms);
 }
 
+// An async, event-loop-YIELDING sleep (unlike sleepSync's Atomics.wait, which blocks the very
+// thread a setInterval-based heartbeat needs to fire on) — js-reclaim-lock-heartbeat.
+function sleepAsync(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// js-reclaim-lock-heartbeat: the JS analog of the Python `_lock_heartbeat` fix
+// (reclaim-ticket-race) — refreshes a held lock file's own mtime on a `.unref()`'d
+// `setInterval` for as long as it is held, so a live-but-slow holder is never misjudged
+// stale by a sibling racer purely because wall-clock age crosses `staleAfterMs`. `.unref()`
+// means the timer never keeps the process alive on its own; `stop()` clears it explicitly on
+// release (belt AND suspenders, mirrors the interval's own `max(50ms, min(staleAfterMs/4,
+// 5000ms))` formula the frozen contract cites). A crash simply stops the interval firing — the
+// file still ages out and self-heals via the existing reclaim-ticket mechanism, unchanged.
+//
+// This is a probabilistic mitigation, not a mathematical guarantee: a callback fires only
+// between synchronous JS turns, so whole-event-loop starvation (a long synchronous operation
+// blocking the process) can defeat it exactly as whole-process scheduling starvation once
+// defeated the Python fix's own real OS thread on real CI (see TASK.md's least-sure flag) —
+// accepted given production defaults (600s/120s) make that starvation window vanishingly
+// unlikely in practice.
+function startLockHeartbeat(lockPath, staleAfterMs) {
+  const intervalMs = Math.max(50, Math.min(staleAfterMs / 4, 5000));
+  const timer = setInterval(() => {
+    const now = new Date();
+    try { fs.utimesSync(lockPath, now, now); } catch (_e) {}   // released/reclaimed — best-effort
+  }, intervalMs);
+  timer.unref();
+  return { stop: () => clearInterval(timer) };
+}
+
 function pkgVersion() {
   try { return require(path.join(PKG_ROOT, "package.json")).version; }
   catch (_e) { return "0.0.0"; }
@@ -1249,17 +1280,44 @@ function installGlobalDataRestore(chosenTarget, force) {
   else log("  (no snapshot for this project at " + snap + " — nothing restored)");
 }
 
+// Every "<lockFileName>.reclaim-*" directly under dir aged past staleAfterSeconds — a LEAKED
+// per-generation reclaim ticket (its own holder crashed between winning it and its own
+// best-effort cleanup; a live, currently-in-flight ticket is never this old). Returns full
+// paths, sorted; [] if dir does not exist. Mirror of _installer.py:_aged_reclaim_tickets.
+function agedReclaimTickets(dir, lockFileName, staleAfterSeconds, nowMs) {
+  if (!fs.existsSync(dir)) return [];
+  const prefix = lockFileName + ".reclaim-";
+  return fs.readdirSync(dir).filter((name) => name.startsWith(prefix)).map((name) => path.join(dir, name))
+    .filter((p) => {
+      try { return (nowMs - fs.statSync(p).mtimeMs) / 1000 > staleAfterSeconds; }
+      catch (_e) { return false; }               // vanished mid-sweep — nothing to report
+    }).sort();
+}
+
 // prune-data: reclaim ORPHANED snapshots under <home>/data. An orphan is a <home>/data/<key>
 // whose key is owned by NO LIVE registry entry (LIVE = a registered path that still EXISTS on
 // disk) — so unregistered AND registered-but-vanished are BOTH orphans (the explicit reclaim;
 // DIVERGES from update --global's keep-vanished). Reads the registry FIRST (corrupt throws,
-// before any removal). Returns {orphans, removed}. Mirror of _installer.py:_prune_data.
+// before any removal).
+//
+// sweep-orphan-reclaim-tickets: ALSO sweeps LEAKED per-generation reclaim tickets — a
+// "<LOCK_FILE>.reclaim-*" under home (home-scope) and a "<PROJECT_LOCK_FILE>.reclaim-*" under
+// every LIVE registered project's own .add/ (project-scope) — each aged past its OWN kind's
+// existing staleness constant (LOCK_TICKET_STALE_SECONDS / PROJECT_LOCK_TICKET_STALE_SECONDS,
+// reused verbatim; no new threshold). Reuses the registry already read for the data-orphan
+// sweep — no new read.
+//
+// Returns {orphans, removed, ticketOrphans, ticketsRemoved} — extends the prior {orphans,
+// removed} object non-breakingly (existing dot-access callers are unaffected). ticketOrphans/
+// ticketsRemoved are full paths; ticketsRemoved == [] on a dry-run, == ticketOrphans under
+// force (each unlinked best-effort, matching the existing reclaim code's own swallow-errors
+// convention). Mirror of _installer.py:_prune_data.
 function pruneData(home, force) {
   const reg = readRegistry(home);                           // corrupt -> throw (LOUD, zero removal)
-  const live = new Set(reg.filter((p) => fs.existsSync(p)).map(dataKey));
+  const livePaths = reg.filter((p) => fs.existsSync(p));
+  const live = new Set(livePaths.map(dataKey));
   const dataDir = path.join(home, "data");
-  if (!fs.existsSync(dataDir)) return { orphans: [], removed: [] };
-  const orphans = fs.readdirSync(dataDir).filter((name) => {
+  const orphans = !fs.existsSync(dataDir) ? [] : fs.readdirSync(dataDir).filter((name) => {
     try { return fs.statSync(path.join(dataDir, name)).isDirectory() && !live.has(name); }
     catch (_e) { return false; }
   }).sort();
@@ -1270,23 +1328,67 @@ function pruneData(home, force) {
       removed.push(key);
     }
   }
-  return { orphans: orphans, removed: removed };
+
+  const now = Date.now();
+  let ticketCandidates = agedReclaimTickets(home, LOCK_FILE, LOCK_TICKET_STALE_SECONDS, now)
+    .map((p) => ({ path: p, staleAfter: LOCK_TICKET_STALE_SECONDS }));
+  for (const project of livePaths) {
+    ticketCandidates = ticketCandidates.concat(
+      agedReclaimTickets(path.join(project, ".add"), PROJECT_LOCK_FILE, PROJECT_LOCK_TICKET_STALE_SECONDS, now)
+        .map((p) => ({ path: p, staleAfter: PROJECT_LOCK_TICKET_STALE_SECONDS }))
+    );
+  }
+  const ticketOrphans = ticketCandidates.map((c) => c.path);
+  const ticketsRemoved = [];
+  if (force) {
+    for (const { path: ticket, staleAfter } of ticketCandidates) {
+      try {
+        if ((Date.now() - fs.statSync(ticket).mtimeMs) / 1000 <= staleAfter) continue;  // no longer stale at unlink time — §5 safety rule
+        fs.unlinkSync(ticket);
+        ticketsRemoved.push(ticket);
+      } catch (_e) { /* already gone — harmless, matches reclaim's own convention */ }
+    }
+  }
+
+  return { orphans: orphans, removed: removed, ticketOrphans: ticketOrphans, ticketsRemoved: ticketsRemoved };
 }
 
 // prune-data command: dry-run lists orphans (removes nothing); --force deletes. no_global_home /
 // registry_corrupt = fail-closed (LOUD, nothing removed). Mirror of pip _installer.prune_data.
+//
+// prune-data-update-lock: the registry-read + orphan-computation + removal critical section now
+// holds the SAME home lock (acquireUpdateLock) `update --global` already holds during its own
+// reconcile (which refreshes an existing project's <home>/data/<key> snapshot) — so the two can
+// never interleave. Reuses the existing, proven primitive verbatim (fail-fast, no poll — the
+// primitive's own fail() call handles a contended lock, no extra catch needed here).
+//
+// sweep-orphan-reclaim-tickets: ALSO reports (and, with --force, removes) leaked reclaim
+// tickets found by pruneData — see its own comment; a separate, additive count from the
+// data-orphan sweep above.
 function cmdPruneData(args) {
   const home = resolveGlobalHome(process.env);
   if (!fs.existsSync(path.join(home, STAMP_FILE))) {
     fail("no global ADD install at " + home + " (.add-version not found) — nothing to prune");
   }
+  acquireUpdateLock(home, { timeout: null }, process.env);
   let result;
   try { result = pruneData(home, args.force); }
   catch (_e) { fail("global registry " + registryPath(home) + " is corrupt — fix or delete it; not pruning"); }
-  if (result.orphans.length === 0) { log("  no orphaned snapshots — nothing to prune"); return; }
-  if (args.force) { log("  ✓ " + result.removed.length + " removed"); return; }
+  if (result.orphans.length === 0 && result.ticketOrphans.length === 0) {
+    log("  no orphaned snapshots — nothing to prune");
+    return;
+  }
+  if (args.force) {
+    if (result.orphans.length > 0) log("  ✓ " + result.removed.length + " removed");
+    if (result.ticketOrphans.length > 0) log("  ✓ " + result.ticketsRemoved.length + " reclaim ticket(s) removed");
+    return;
+  }
   for (const key of result.orphans) log("  orphan: " + key);
-  log("  " + result.orphans.length + " orphan(s); re-run with --force to remove");
+  if (result.orphans.length > 0) log("  " + result.orphans.length + " orphan(s); re-run with --force to remove");
+  for (const ticket of result.ticketOrphans) log("  ticket orphan: " + ticket);
+  if (result.ticketOrphans.length > 0) {
+    log("  " + result.ticketOrphans.length + " reclaim ticket orphan(s); re-run with --force to remove");
+  }
 }
 
 // init --global: install the managed layer ONCE to the shared home + register this project,
@@ -1477,7 +1579,9 @@ function acquireUpdateLock(home, { timeout = null } = {}, env = process.env) {
   }
   try { fs.writeSync(fd, process.pid + " " + new Date().toISOString() + "\n"); }
   catch (_e) {}   // diagnostics are best-effort — never fail an acquired lock over this
+  const heartbeat = startLockHeartbeat(lockPath, staleAfterMs);   // js-reclaim-lock-heartbeat
   const release = () => {
+    heartbeat.stop();   // cleared FIRST — never outlives the fd/lockPath it refreshes
     try { fs.closeSync(fd); } catch (_e) {}
     try { fs.unlinkSync(lockPath); } catch (_e) {}
   };
@@ -1631,7 +1735,9 @@ function acquireProjectLock(addDir, env = process.env) {
   }
   try { fs.writeSync(fd, process.pid + " " + new Date().toISOString() + "\n"); }
   catch (_e) {}   // diagnostics are best-effort — never fail an acquired lock over this
+  const heartbeat = startLockHeartbeat(lockPath, staleAfterMs);   // js-reclaim-lock-heartbeat
   const release = () => {
+    heartbeat.stop();   // cleared FIRST — never outlives the fd/lockPath it refreshes
     try { fs.closeSync(fd); } catch (_e) {}
     try { fs.unlinkSync(lockPath); } catch (_e) {}
     if (createdDir) {
@@ -1736,8 +1842,37 @@ function cmdUpdate(args) {
       " refreshed) · your project state untouched.");
 }
 
+// js-reclaim-lock-heartbeat: a test-only entrypoint so the Python subprocess suite can drive
+// real multi-process contention against acquireUpdateLock/acquireProjectLock without duplicating
+// their acquire/release logic in the test itself. Intercepted BEFORE the `cmd`/switch dispatch
+// below, guarded behind an undocumented flag — never listed in --help, never reachable via any
+// documented public command, so it carries zero surface on the real CLI path.
+async function cmdInternalAcquireLock(argv) {
+  const kind = argv[0];
+  const targetPath = argv[1];
+  const holdMs = Number(argv[2]);
+  let release;
+  if (kind === "update") {
+    release = acquireUpdateLock(targetPath, { timeout: null }, process.env);
+  } else if (kind === "project") {
+    release = acquireProjectLock(targetPath, process.env);
+  } else {
+    fail("internal_acquire_lock_bad_kind: expected 'update' or 'project', got '" + kind + "'");
+    return;
+  }
+  log("HELD " + Date.now());
+  await sleepAsync(holdMs);   // event-loop-yielding — lets the heartbeat's setInterval fire
+  log("RELEASED " + Date.now());
+  release();
+  process.exit(0);
+}
+
 async function main() {
   const argv = process.argv.slice(2);
+  if (argv[0] === "--internal-acquire-lock") {
+    await cmdInternalAcquireLock(argv.slice(1));
+    return;
+  }
   const cmd = argv[0] && !argv[0].startsWith("--") ? argv.shift() : "init";
   const args = parseArgs(argv);
   switch (cmd) {

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

@@ -113,6 +113,6 @@ The default is one task at a time. But when a milestone holds several tasks whos
 
 **Design for failure (required).** Lease each task to its worker with a timeout — if a worker dies, release the claim back to READY rather than trusting partial work. A worker that hits a stop-and-escalate blocks only its own task; siblings keep running. And if several workers fail in one wave, trip a circuit-breaker and fall back to sequential — repeated failure means the scope was wrong, not the parallelism.
 
-**The hard boundary.** The orchestrator owns every shared write — `state.json`, `MILESTONE.md`, and each `add.py advance`/`gate` call (always with the explicit task slug). A worker owns only its own task directory and is isolated in a git worktree, so concurrent builds cannot collide. Merge is **serial**: bring worktrees back one at a time and run an **integration Verify** for the concurrency and architecture conflicts that two-green-in-isolation tasks can still produce — automation never auto-passes that step.
+**The hard boundary.** The orchestrator owns every shared write — `state.json`, `MILESTONE.md`, and each `add.py advance`/`gate` call (always with the explicit task slug). A worker owns only its own task directory and is isolated in a git worktree — ADD's default for any agent-spawned step, not only a wave — so concurrent builds cannot collide. Merge is **serial**: bring worktrees back one at a time and run an **integration Verify** for the concurrency and architecture conflicts that two-green-in-isolation tasks can still produce — automation never auto-passes that step.
 
 The full, agent-agnostic worker contract (the prompt a worker runs) and the per-runner spawn adapter live in the skill's `streams.md`; this section is the *why* and the safety frame, not the operational recipe.

package/docs/18-personas.md

@@ -35,11 +35,11 @@ task actually applies one.
 
 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).
+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` or `## Success Metrics` section and **never clobbers** existing content.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "1.16.1",
+  "version": "1.17.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"

package/skill/add/advisor.md

@@ -34,7 +34,8 @@ surrounding decisions. Return a verdict; do not record state.
 </objective>
 
 <persona>
-SELECT the best-fit project persona for this piece and load `.add/personas/{{PERSONA_SLUG}}.md` —
+SELECT the persona by frontmatter — flow: match first, then domain; read ONE body —
+and load `.add/personas/{{PERSONA_SLUG}}.md` —
 Identity→your stance · Critical Rules→constraints · Success Metrics→done-bar (streams.md's worker
 contract). No match → a {{DOMAIN}} engineer, correctness over speed; never blocks.
 Work step by step, following the plan:

package/skill/add/deltas.md

@@ -16,7 +16,7 @@ Each delta begins on its own **tag line**; the learning may wrap:
 - `<status>` — `open` | `folded` | `rejected`. A **newly emitted delta is `open`**.
 - `<learning>` — the insight; the tag line comes **first**, `(evidence: …)` **closes** the delta.
 - `(evidence: …)` — **required**, non-empty: a failing scenario, a production signal, a review note. No evidence → it is an opinion, not a delta.
-- **persona target (optional)** — a competency lesson MAY add `· persona:<slug> · <critical-rule|success-metric>` in brackets, e.g. `- [UDD · open · persona:ui-designer · success-metric] 4.5:1 contrast (evidence: audit)`. At `add.py fold` it lands in `.add/personas/<slug>.md` under that section (newest-first, never clobbering) instead of `PROJECT.md` (`fold.md`).
+- **persona target (optional)** — a competency lesson MAY add `· persona:<slug> · <critical-rule|success-metric|anti-pattern|ability>` in brackets, e.g. `- [UDD · open · persona:ui-designer · success-metric] 4.5:1 contrast (evidence: audit)`. At `add.py fold` it lands in `.add/personas/<slug>.md` under that section (newest-first, never clobbering) instead of `PROJECT.md` (`fold.md`).
 
 A long learning may wrap — `add.py check` joins continuation lines into **one** delta:
 

package/skill/add/design.md

@@ -57,8 +57,8 @@ partial per catalog component), with realistic **mock** data.
 feature's `TASK.md`** — so the approved screen is traceable from the task. The HTML mock is the
 *visible evidence*; the json-render tree is the *machine-checkable* record.
 
-**Persona evidence checklist.** Before design-confirm, match the screen to the seeded UI personas
-(`.add/personas/*` covering visual design and UX research) and render their `## Success Metrics`
+**Persona evidence checklist.** Before design-confirm, load the `flow: design` personas
+(`.add/personas/*` frontmatter, else description-match) and render their `## Success Metrics`
 as a confirmable **checklist** beside the captured image — **both dimensions**: **UI-Designer**
 (visual + WCAG-AA **accessibility**) and **UX-Researcher** (methodology-first,
 **validated by user evidence, not assumed**). Each item traces to a success-metric

package/skill/add/fold.md

@@ -6,7 +6,7 @@ This **closes the loop**. `deltas.md` lets a task EMIT `open` lessons in OBSERVE
 
 ## When to consolidate
 
-At **milestone close**, or **on demand** when open lessons pile up. One `add.py fold` = ONE session: one `foundation-version` bump, every resolved lesson stamped with it.
+At **milestone close**, or on demand when opens pile up. One `add.py fold` = ONE session: one `foundation-version` bump, every resolved lesson stamped with it.
 
 ## The ritual
 
@@ -25,11 +25,11 @@ At **milestone close**, or **on demand** when open lessons pile up. One `add.py
 | competency | consolidates into | how |
 |------------|-----------|-----|
 | `DDD` | `PROJECT.md` §Domain | transcribed bullet at the top (newest-first) |
-| `SDD` | `PROJECT.md` §Spec | transcribed bullet at the top |
-| `UDD` | `PROJECT.md` §Users | transcribed bullet at the top |
-| `TDD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
-| `ADD` | `CONVENTIONS.md` §Method learnings | transcribed bullet |
-| `persona:<slug>` | `.add/personas/<slug>.md` §Critical Rules / §Success Metrics | dated bullet at top; schema stays conformant |
+| `SDD` | `PROJECT.md` §Spec | same |
+| `UDD` | `PROJECT.md` §Users | same |
+| `TDD` | `CONVENTIONS.md` §Method learnings | same |
+| `ADD` | `CONVENTIONS.md` §Method learnings | same |
+| `persona:<slug>` | `.add/personas/<slug>.md` §Critical Rules / §Success Metrics / §Anti-patterns / §Abilities | dated bullet at top; schema stays conformant |
 
 A `persona:<slug> · <hint>` lesson routes into that persona doc, not a foundation file; it is still flipped `folded` and still bumps the version once (`deltas.md`).
 
@@ -45,7 +45,7 @@ A `persona:<slug> · <hint>` lesson routes into that persona doc, not a foundati
 - `missing_route_section` — a lesson routes to a foundation section that does not exist. Add the section header, then re-run. Nothing is written.
 - `no_foundation_version` — `PROJECT.md` carries no parseable `foundation-version:` marker to bump.
 - `missing_persona_target` — a `persona:<slug>` lesson with no `.add/personas/<slug>.md`. Fail-closed: nothing written, no bump. Seed the persona first.
-- `persona_section_unroutable` — the section hint is not `critical-rule` or `success-metric`. Nothing is written.
+- `persona_section_unroutable` — the section hint is not one of `critical-rule | success-metric | anti-pattern | ability`. Nothing is written.
 - `persona_clobber_forbidden` — INVARIANT: a persona consolidation prepends only; it never drops existing content or breaks the schema.
 </reject_codes>
 

package/skill/add/intake.md

@@ -31,8 +31,13 @@ fits the active milestone → `task`.
 
 **One-task gap rule.** If the request is ONE task but does NOT fit the active milestone's stated
 scope, do not force it into `sub-milestone` (which requires "too big for one task"): create a new
-micro-milestone to house it (`new-milestone` + `new-task`) — that gives the task ledger attribution
-and clear exit criteria without inflating scope.
+micro-milestone to house it (`new-milestone` + `new-task`) — ledger attribution + clear
+exit criteria without inflating scope.
+
+**Batched intake.** N same-bucket items arriving together (one directive; a drafted
+milestone's task list) classify as ONE proposal: one report listing every item, one
+human confirm covering the batch — never N sequential asks. Mixed buckets stay
+`split_required`.
 
 ## What you emit (the proposal)
 
@@ -59,25 +64,25 @@ goal/body, the new TASK.md, or a note in the affected TASK.md — never in state
 
 ## Roadmap — a request that is several milestones
 
-Some requests decompose into **N>1 milestones of the same line** — a roadmap, not one milestone.
+Some requests decompose into **N>1 milestones of the same line** — a roadmap.
 Don't create only the first and lose the rest. Instead:
 
 1. **Propose** the roadmap — the ordered milestone list, each with a one-line goal.
-2. **Confirm** — the human confirms the roadmap before anything is created. Never auto-create N
-   milestones unprompted — the intake floor (`ask_human`) still holds.
+2. **Confirm** — the human confirms before anything is created; never auto-create N
+   milestones unprompted (the `ask_human` floor holds).
 3. **Create** all N on confirm — the first with `add.py new-milestone <slug>` (active), the rest
    with `add.py new-milestone --queued <slug>` (status `queued`, not focused).
-4. **Promote** one at a time — as each is started, `add.py activate <slug>` flips it queued→active.
-   You work one active milestone at a time; the queue is the agreed backlog, surfaced at resume.
+4. **Promote** — `add.py activate <slug>` flips each queued→active as started; one active
+   milestone at a time, the queue is the agreed backlog surfaced at resume.
 
-This is NOT `split_required`: that code is for a request spanning **different buckets** (propose the
-smallest correctly-sized set). A roadmap is several milestones of the **same line**, created queued.
+NOT `split_required` (that is for a request spanning **different buckets**); a roadmap is
+several milestones of the **same line**, created queued.
 
 ## Worked examples (from this project's own history)
 
 | request | bucket | rationale |
 |---------|--------|-----------|
-| give ADD a hosted web dashboard | new-major | a new product theme no active milestone's goal covers → a fresh major line (v5) |
-| add the build corridor + tests-red-before-build | sub-milestone | a slice of the live v4 "self-driving" theme, too big for one task → v4-2 |
+| give ADD a hosted web dashboard | new-major | a new product theme → a fresh major line (v5) |
+| add the build corridor + tests-red-before-build | sub-milestone | a slice of the live v4 theme, too big for one task → v4-2 |
 | expose owner/stop as --json | task | fits the active v4-1 (intake interface) scope → one task |
-| guide --json phase/gate should be nullable | change-request | changes the FROZEN machine-state-json contract → reopen its CONTRACT, do not make a new milestone |
+| guide --json phase/gate should be nullable | change-request | changes a FROZEN contract → reopen its CONTRACT, never a new milestone |

package/skill/add/loop.md

@@ -1,9 +1,8 @@
 # The dynamic loop — open deltas and extras become the next tasks
 
-A milestone is not done when its tasks are done — it is done when its **GOAL** is met.
-This guide drives a milestone toward that goal: turn what each task leaves behind (open lessons,
-and work discovered but out of scope) into the next tasks, and keep going until the exit criteria
-are all met.
+A milestone is done when its **GOAL** is met, not when its tasks are.
+This guide drives toward that goal: turn what each task leaves behind (open lessons, and
+work discovered but out of scope) into the next tasks until the exit criteria are all met.
 
 You **gather and propose**; the **human confirms**; the existing `add.py new-task`
 creates each one. The engine never decides what the next task is — that is judgment.
@@ -24,15 +23,15 @@ both refuse a milestone that is not done. The one gate is enough — there is no
 
 ## The loop
 
-When every task is done but the goal is not, `add.py status` shows
+Every task done but not the goal? `add.py status` shows
 `goal not met (m/n exit criteria)`. That is the cue:
 
 1. **Gather** the carried inventory:
-   - open lessons — `add.py deltas` (the §7 OBSERVE deltas still `open`);
+   - open lessons — `add.py deltas` (§7 deltas still `open`) + the deferred pile — `add.py deltas --carried`;
    - the planned-but-unscaffolded tasks — the plan-vs-state line in `add.py status`;
    - any reopened task — one a deepened verify returned to the flow (see below).
 2. **Propose** the next tasks: for each carried item worth doing now, draft a one-line task
-   (slug + title + why) and show the human. Group the trivial ones; do not propose noise.
+   (slug + title + why) and show the human. Group trivial ones; no noise.
 3. **Confirm** — the human accepts, edits, or declines each. No task is created without this.
 4. **Create** each accepted task — `add.py new-task <slug> --title "..."` — and run it through
    the normal flow (specify → … → verify).

package/skill/add/phases/0-setup.md

@@ -61,16 +61,16 @@ Capture each surfaced decision as an **ADR** in `PROJECT.md` **Key Decisions** a
    Draft the full bundle **§1–§4** incl. the **§4 red suite** (`phases/4-tests.md`); the lock approves it whole. **Leave §3 `Status: DRAFT`** — the lock is its approval. You MAY `advance` pre-lock, but the engine **refuses build** until you `lock` (`setup_unlocked`). Sequence: **bundle (§1–§4, tests RED) → lock → build** — the red suite must FAIL before build.
 4. **Write `.add/SETUP-REVIEW.md`** per `setup-review.md`: every drafted decision, **lowest-confidence-first**, tagged `guessed` | `evidence-grounded`.
 
-## Run mode — how the build will be driven (propose parallel + auto; confirm to keep)
+## Run mode — how the build will be driven (propose sequential + auto; confirm to keep)
 
 Before the lock, surface the **run mode** — autonomy + streams (`run.md` · `streams.md`):
 
 | Run mode | Human gates | Concurrency |
 |----------|-------------|-------------|
+| **sequential · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence | one task at a time |
 | **sequential · manual/conservative** | contract freeze **and** every Verify | one task; safest |
-| **parallel · auto** *(default)* | contract freeze **only** — Verify auto-PASSes on evidence | `add.py waves` overlaps independent builds behind frozen contracts |
 
-**Propose `parallel + auto`; confirm-to-keep** (or downgrade: `add.py autonomy set conservative --project` + `add.py streams set sequential --project`). Record in **`PROJECT.md` Key Decisions**.
+**Propose `sequential + auto`; confirm-to-keep** (raise the gate: `add.py autonomy set conservative --project`; opt into parallel streaming for a milestone with independent tasks — `add.py streams set parallel --project`, then `add.py waves` schedules the fan-out). Record in **`PROJECT.md` Key Decisions**.
 
 Floor: **one human approval per contract**.