@pilotspace/add 2.2.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,110 @@ 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.
 
+## [2.4.0] — 2026-07-24
+
+Minor: the **strategy-intake** milestone closes — a fitting **persona** becomes ADD's
+adaptive project-management brain — plus the follow-on cleanup that completes the 2.3.0
+**scenarios fold** and adds a CI sweep of every shipped surface. The method changes are all
+skill/agent-surface prose with **zero `add.py` engine change** (the engine records the
+`## Strategy` slot and the gate, never drives the loop or gates on the strategy); this
+release also carries one **concurrency fix** to the installer's lock (see *Fixed*).
+
+### Persona-as-PM strategy loop — `strategy.md` (new guide)
+- **DISCUSS → OPTIMIZE → CONVERGE** — a new `strategy.md` guide drives a persona-framed
+  loop that fills a milestone's `## Strategy` slot with a sequenced, optimized task DAG,
+  converging on the *existing* six-dimension confidence self-score (no new bar invented).
+- **`add-advisor` refute at CONVERGE** — a high-uncertainty milestone spawns the advisor
+  in refute mode to break the strategy before it's recorded; advisory (it cannot block),
+  reusing the existing refute mode. The advisor's `direction` beat now names a milestone
+  strategy as a refutable artifact alongside a task bundle.
+- **risk-proportional depth ladder** — one legible rule: micro/`--tiny` skips the loop at
+  zero added per-turn cost · multi-task low-uncertainty runs the loop · high-uncertainty
+  adds the refute. It is the skill's judgment, never an engine gate; strategy stays SOFT
+  and security stays HARD-STOP.
+- **persona-at-intake** — `intake.md` now loads the **fitting persona** before it sizes a
+  request (match-else-seed, advisory), so the persona that owns the intake report also
+  shapes the sizing.
+
+### Fold completion + shipped-surface sweep
+- the **scenarios fold** finishes — four remaining shipped residuals of the §2→§4 retirement
+  are fixed, each defect class pinned by a new guard.
+- a **shipped-surface** CI sweep derives the published file set from the packaging manifests
+  and fails on any dead chapter/section reference across every shipped surface.
+- CI/deps: `actions/setup-python` 6→7, `actions/setup-node` 6→7, `@clack/prompts` 1.6.0→1.7.0.
+
+### Fixed
+- **stale-lock reclaim could unlink a LIVE lock** (mutual-exclusion violation). The reclaim
+  path gated its unlink on inode identity alone, assuming a fresh replacement lock always
+  gets a new inode. Linux (ext4/tmpfs) **reuses freed inode numbers**, so a delayed racer
+  could match the crashed generation's inode against a *live* holder's replacement lock and
+  delete it — putting two processes inside the critical section at once. Reclaim now requires
+  the file to be **both** the observed inode **and** still stale, so a live or
+  heartbeat-refreshed lock is never mistaken for a dead one. Fixed at all four reclaim sites
+  in `_installer.py` and mirrored into the `bin/cli.js` npm twin, which carried the identical
+  guard. `O_EXCL`/`wx` remains the sole mutual-exclusion primitive and a genuinely crashed
+  lock still self-heals. Surfaced as an intermittent `peak=2` on the Linux CI runner only.
+
+## [2.3.0] — 2026-07-24
+
+Minor: three waves — a **signal graph** view over the task DAG, the **§2
+Scenarios fold** into §4, and a **call-lean pass** that kills the two measured
+WM1 freeze/scope call sinks. Engine changes are additive; templates migrate
+in place (no manual task-file edits).
+
+### Signal graph — one addressable node for every note/todo/delta
+- **unified signal model** — note, todo, and spec-delta collapse into ONE
+  addressable `signal` node (status + edges), projected as a VIEW, not a new
+  store; `_signals` reader.
+- **`graph --signals`** — opt-in overlay renders signals on the task DAG;
+  **exit-criteria** render as `ec_` *delivered-by* nodes (a milestone's own
+  criteria appear as ✓/○ nodes wired to the tasks that meet them).
+- **`graph --html`** — emits a self-rendering HTML page to tmp (Mermaid inline,
+  no external host).
+- **atomicity signal** — the freeze SEEDS a persistent atomicity signal into the
+  task's todos instead of an ephemeral print, so the nudge survives the session.
+
+### §2 Scenarios folded into §4 — one place for cases
+- the standalone **§2 SCENARIOS** section is **retired in place**: pass/fail cases
+  now live with the tests in **§4 · TESTS & SCENARIOS** (primary-case rigor). The
+  §3–§7 numbers are unchanged so the freeze parser and every §-reference keep
+  working — the §1→§3 jump is intentional.
+- **PROJECT.md** gains a managed `ADD:SPECS` pointer block (init/migrate inject it
+  from the 5-DD spec set); foundation references reconciled to the `.add/specs/`
+  model; the generated **CLAUDE.md** block finalized in the generator.
+- the Step-2 Scenarios book chapter folds into Step-4; `add-flow.png` retired.
+
+### Call-lean pass — the WM1 freeze/scope sinks die at the source
+- **freeze-flag slot** — `PLAN.md.tmpl` §3 carries a drafted-blank *Least-sure
+  flag* slot; the first freeze no longer fails `unflagged_freeze` (0/6 reps in the
+  re-measure, was 3/3). The unfilled part-menu placeholder still never satisfies
+  the gate — the floor holds.
+- **scope-first freeze** — a §3 Scope that resolves to zero cover is now refused
+  `scope_unresolved` AT the freeze with a paste-ready fix, instead of surfacing
+  later as `scope_violation` → re-cross → re-gate. UNDECLARED stays grandfathered;
+  greenfield `[MISSING]` tokens still freeze; a `.add/tasks/` token gets a
+  task-dir teach note.
+- **scope-walk prunes** — `.venv` · `venv` · `.tox` · `.mypy_cache` · `.ruff_cache`
+  · `.eggs` and any `*.egg-info` dir are pruned from the scope walk, so an
+  in-workspace virtualenv or `pip install -e .` metadata is never read as an
+  out-of-scope write. `dist`/`build` stay watched (can be a real write-set). The
+  untouched-Scope-default warning now self-explains (a note, not a blocker; clears
+  only by editing the Scope line — re-cross does not clear it).
+- **honest fidelity meter** — the artifact-blind LLM `spec_fidelity` metric is
+  replaced by a deterministic `requirement_coverage` (frozen per-WM checklists +
+  probes, no LLM in the metric path); `oracle_pass_rate` promoted to the headline;
+  the judge demoted to an advisory `code_quality_annotation`.
+- **§3 Build-strategy relabel** — *Scope (may touch)* is the HARD scope-lock; the
+  rest (Strategy · Regression floor · Persona) is SOFT/optional. `MILESTONE.md`
+  gains a drafted-blank `## Strategy` slot.
+
+Retired (no CLI/install surface change): the standalone **§2 SCENARIOS** section
+(folded into §4) · the **ccsk / rule-file** mode · `add-flow.png`.
+
+Pinned by `test_release_2_3_0.py`. `ENGINE_MD5` re-aimed to `60eef504…`
+(scope refusal + walk prunes); the four tooling twins stay byte-identical;
+full tooling suite green (2277 tests).
+
 ## [2.2.0] — 2026-07-22
 
 Minor: the Direction beat gains a **fable reasoning discipline** — a prompt-only

package/GETTING-STARTED.md

@@ -200,7 +200,7 @@ python3 .add/tooling/add.py new-task transfer --title "Transfer money between my
 > any build. Plain `init` skips that gate, which is fine here: by hand, the
 > human IS the one driving every step.
 
-This scaffolds `.add/tasks/transfer/PLAN.md` — **one file holding all seven phase
+This scaffolds `.add/tasks/transfer/PLAN.md` — **one file holding all six phase
 sections** — plus empty `tests/` and `src/` folders, and makes it the active task
 at phase `specify`. Open it in your editor; you'll fill it top to bottom.
 
@@ -234,21 +234,6 @@ Confirm every assumption (no FX, no daily limit in v1). Then:
 python3 .add/tooling/add.py advance
 ```
 
-### Phase 2 — Scenarios (https://pilotspace.github.io/ADD/04-step-2-scenarios/)
-
-In **§2**, turn each rule into a Given/When/Then. For every rejection, assert what
-must stay **unchanged**:
-
-```gherkin
-Scenario: insufficient funds
-  Given A has 20, mine
-  When I transfer 50 from A to B
-  Then it is rejected "insufficient_funds"
-  And no balance changes
-```
-
-Then `python3 .add/tooling/add.py advance`.
-
 ### Phase 3 — Contract (https://pilotspace.github.io/ADD/05-step-3-plan/)
 
 In **§3**, fix the external shape and **freeze** it (`Status: FROZEN @ v1`):
@@ -264,9 +249,24 @@ A frozen contract is the decision point that makes the AI build safe. Then advan
 
 ### Phase 4 — Tests, red first (https://pilotspace.github.io/ADD/06-step-4-tests/)
 
-Write one test per scenario into `.add/tasks/transfer/tests/`, then **run them and
-confirm they FAIL** — there's no code yet. A test that passes now is testing
-nothing. This is red/green TDD: red before green. Then advance.
+**§4 · TESTS & SCENARIOS** is where pass/fail cases live — with the tests that
+prove them. Write one test per §1 Must/Reject. For every rejection, also assert
+what must stay **unchanged**.
+
+A readable case, for a human who needs one:
+
+```gherkin
+Scenario: insufficient funds
+  Given A has 20, mine
+  When I transfer 50 from A to B
+  Then it is rejected "insufficient_funds"
+  And no balance changes
+```
+
+The test plan is the canonical encoding — a Given/When/Then block is for a human
+reader, never ceremony. Write the tests into `.add/tasks/transfer/tests/`, then
+**run them and confirm they FAIL** — there's no code yet. A test that passes now
+is testing nothing. This is red/green TDD: red before green. Then advance.
 
 ### Phase 5 — Build (https://pilotspace.github.io/ADD/07-step-5-build/)
 

package/agents/add-advisor.md

@@ -25,8 +25,9 @@ beat keeps moving. Personas carry the expertise; you carry independent, first-pr
   when uncertain — catch the plausible-but-wrong before the human or the gate does.
 
 Every mode serves EVERY beat — the spawn names the beat + mode, and you calibrate to it:
-**direction** (propose the bundle plan · refute the draft so the human freezes the stronger
-shape), **build** (decide approach forks mid-flight · pressure-test a strategy or a support-
+**direction** (propose the bundle plan · refute the draft — a task bundle OR a high-uncertainty
+milestone **strategy** — so the human freezes the stronger shape), **build** (decide approach
+forks mid-flight · pressure-test a strategy or a support-
 worker slice partition against the frozen contract), **verify** (refute the earned-green ·
 judge whether the evidence supports the verdict). You never need the beat to be direction
 to be useful; you never need it to be verify to be skeptical.

package/bin/cli.js

@@ -39,7 +39,7 @@ function parseArgs(argv) {
   // hint only echoes flags the user actually chose (shortest true command).
   const args = { _: [], force: false, check: false, noSkill: false, stage: null, name: null,
                  yes: false, nonInteractive: false, global: false, globalData: false,
-                 fromGlobalData: false, ruleFile: false, lockTimeout: null };
+                 fromGlobalData: false, lockTimeout: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--force") args.force = true;
@@ -61,9 +61,6 @@ function parseArgs(argv) {
     // already provides the `add` skill, so a plugin bootstrap uses this to materialize
     // .add/tooling/ into the project without a duplicate .claude/skills/add.
     else if (a === "--no-skill") args.noSkill = true;
-    // --rule-file: write the ADD block to .claude/rules/add-workflows.md + reference it from
-    // CLAUDE.md instead of inlining (auto-on for ccsk projects with a .ccsk/ dir).
-    else if (a === "--rule-file") args.ruleFile = true;
     else if (a === "--stage" || a === "--name") {
       const v = argv[++i];
       // fail loudly on a trailing/abutting flag — never silently drop a value
@@ -263,126 +260,6 @@ function writeAgentPointer(target, profile) {
   }
 }
 
-// --- rule-file mode: ccsk-style relocation of the CLAUDE.md block ---------------------
-// Mirror of add.py / _installer.py rule-file logic (twins by duplication). For ccsk projects
-// (.ccsk/ dir) or an explicit --rule-file, the ADD pointer goes to .claude/rules/add-workflows.md
-// and CLAUDE.md keeps only a reference bullet. CLAUDE-only — AGENTS.md/.clinerules stay inline.
-const RULES_FILE_REL = path.join(".claude", "rules", "add-workflows.md");
-const WORKFLOW_HEADINGS = ["Rules & Workflows", "Workflows", "Rules"];
-const RULE_REF_LINE = "- ADD (AI-Driven Development) Workflows rules: ./.claude/rules/add-workflows.md";
-
-// True when the ADD block belongs in .claude/rules/add-workflows.md instead of inline.
-// Re-derived from disk: explicit flag, a ccsk project (.ccsk/), or a rule file already present.
-function ruleFileMode(root, flag) {
-  if (flag) return true;
-  try {
-    if (fs.existsSync(path.join(root, ".ccsk")) &&
-        fs.statSync(path.join(root, ".ccsk")).isDirectory()) return true;
-    if (fs.existsSync(path.join(root, RULES_FILE_REL))) return true;
-  } catch (_e) { /* fail-soft */ }
-  return false;
-}
-
-// Remove an inline ADD:BEGIN..END region (migration), collapsing the gap. An unterminated
-// BEGIN is left as-is rather than eating the rest of the file.
-function stripInlineBlock(text) {
-  const begin = text.indexOf(GUIDE_BEGIN);
-  if (begin === -1) return text;
-  let end = text.indexOf(GUIDE_END, begin);
-  if (end === -1) return text;
-  end += GUIDE_END.length;
-  const head = text.slice(0, begin).replace(/\n+$/, "");
-  const tail = text.slice(end).replace(/^\n+/, "");
-  if (head && tail) return head + "\n\n" + tail;
-  return head || tail;
-}
-
-// Insert the ADD rule-file bullet under an existing Workflows/Rules heading, or append a fresh
-// '## Workflows' section. Caller guarantees the bullet is absent.
-function insertRuleReference(text) {
-  const lines = text.split("\n");
-  let headingIdx = -1;
-  for (let i = 0; i < lines.length; i++) {
-    const m = lines[i].match(/^(#{1,6})\s+(.*?)\s*$/);
-    if (m && WORKFLOW_HEADINGS.some((h) => m[2].trim().toLowerCase() === h.toLowerCase())) {
-      headingIdx = i;
-      break;
-    }
-  }
-  if (headingIdx === -1) {
-    const body = text.replace(/\n+$/, "");
-    const sep = body ? "\n\n" : "";
-    return body + sep + "## Workflows\n\n" + RULE_REF_LINE + "\n";
-  }
-  const level = lines[headingIdx].match(/^(#{1,6})/)[1].length;
-  let end = lines.length;
-  for (let j = headingIdx + 1; j < lines.length; j++) {
-    const m = lines[j].match(/^(#{1,6})\s+/);
-    if (m && m[1].length <= level) { end = j; break; }
-  }
-  let insertAt = headingIdx + 1;
-  for (let j = headingIdx + 1; j < end; j++) {
-    if (lines[j].trim()) insertAt = j + 1;
-  }
-  lines.splice(insertAt, 0, RULE_REF_LINE);
-  return lines.join("\n");
-}
-
-// Make CLAUDE.md reference the ADD rule file under a Workflows/Rules heading, migrating any prior
-// inline ADD block out. created|updated|unchanged|skipped; .bak on change; fail-soft.
-function ensureClaudeReference(claudeMd) {
-  try {
-    const existed = fs.existsSync(claudeMd);
-    const current = existed ? fs.readFileSync(claudeMd, "utf8") : "";
-    let next = stripInlineBlock(current);
-    if (next.indexOf("add-workflows.md") === -1) next = insertRuleReference(next);
-    if (!next.endsWith("\n")) next += "\n";
-    if (next === current) return "unchanged";
-    if (existed) fs.writeFileSync(claudeMd + ".bak", current);
-    fs.writeFileSync(claudeMd, next);
-    return existed ? "updated" : "created";
-  } catch (e) {
-    warn("could not write CLAUDE.md — " + (e && e.message ? e.message : e) + "; skipped");
-    return "skipped";
-  }
-}
-
-// Rule-file variant of writeAgentPointer for the Claude profile: write the ADD pointer block to
-// .claude/rules/add-workflows.md and leave a reference in CLAUDE.md. Fail-soft.
-function writeRuleFilePointer(target, profile) {
-  const rulesPath = path.join(target, RULES_FILE_REL);
-  const block = agentPointerBlock(profile);
-  try {
-    if (fs.existsSync(rulesPath)) {
-      const current = fs.readFileSync(rulesPath, "utf8");
-      const begin = current.indexOf(GUIDE_BEGIN);
-      let next;
-      if (begin !== -1) {
-        const endIdx = current.indexOf(GUIDE_END, begin);
-        if (endIdx !== -1) {
-          next = current.slice(0, begin) + block + current.slice(endIdx + GUIDE_END.length);
-        } else {
-          next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
-        }
-      } else {
-        next = current.replace(/\n+$/, "") + "\n\n" + block + "\n";
-      }
-      if (next !== current) {
-        fs.writeFileSync(rulesPath + ".bak", current);
-        fs.writeFileSync(rulesPath, next);
-      }
-    } else {
-      fs.mkdirSync(path.dirname(rulesPath), { recursive: true });
-      fs.writeFileSync(rulesPath, block + "\n");
-    }
-  } catch (e) {
-    warn("could not write " + RULES_FILE_REL + " — " + (e && e.message ? e.message : e) + "; skipped");
-    return "skipped";
-  }
-  ensureClaudeReference(path.join(target, "CLAUDE.md"));
-  return "ok";
-}
-
 // --- interactive layer (clack on a real TTY; plain text everywhere else) -----
 // Designed-for-failure: any doubt (non-TTY, CI, --yes, a failed import, an
 // un-promptable stream) degrades to the EXACT plain-text path below. The clack
@@ -650,16 +527,7 @@ function dropFiles(args, target, profile, intent) {
   // Agent detection: write THE detected agent's integration file (a marker-delimited
   // pointer init's sync-guidelines later supersedes) + tailor the closing next-step.
   // Best-effort + fail-soft — never aborts the successful drop above.
-  // Rule-file mode (ccsk projects / --rule-file) relocates the CLAUDE.md pointer to
-  // .claude/rules/add-workflows.md + a reference — CLAUDE-only; other agents stay inline.
-  if (profile.integration_file === "CLAUDE.md" && ruleFileMode(target, args.ruleFile)) {
-    if (fs.existsSync(path.join(target, ".ccsk"))) {
-      log("  ccsk detected — ADD rules go to .claude/rules/add-workflows.md");
-    }
-    writeRuleFilePointer(target, profile);
-  } else {
-    writeAgentPointer(target, profile);
-  }
+  writeAgentPointer(target, profile);
 
   // Gemini CLI auto-loads GEMINI.md, not AGENTS.md — so for the gemini profile we ALSO merge
   // .gemini/settings.json (context.fileName) to load the AGENTS.md pointer. Fail-soft + idempotent.
@@ -1341,6 +1209,28 @@ function agedReclaimTickets(dir, lockFileName, staleAfterSeconds, nowMs) {
     }).sort();
 }
 
+// True iff `p` is STILL the exact stale generation identified by `observedIno` AND still stale —
+// the guard that gates a reclaim UNLINK. Mirror of _installer.py:_still_stale_generation.
+//
+// Inode NUMBER alone is NOT a stable identity across a delete+recreate: Linux (ext4/tmpfs)
+// aggressively REUSES freed inode numbers, so a live holder's fresh replacement lock can reuse the
+// crashed file's inode. A reclaimer that trusts inode identity alone then unlinks a LIVE lock whose
+// inode merely coincides with the crashed generation it observed — two holders end up inside the
+// critical section at once (the peak=2 double-hold; reproduced on Linux CI, never on macOS APFS,
+// which does not reuse inodes in a short window).
+//
+// Re-verifying that the CURRENT file is itself still stale (mtime age > `staleAfterSeconds`)
+// distinguishes a live reused-inode holder (age ~0, or heartbeat-refreshed) from the crashed
+// generation we meant to reclaim. The "wx" create remains the SOLE mutual-exclusion primitive;
+// this only prevents a live file being mistaken for a dead one.
+function stillStaleGeneration(p, observedIno, staleAfterSeconds, nowMs) {
+  const now = nowMs === undefined ? Date.now() : nowMs;
+  let cur = null;
+  try { cur = fs.statSync(p); }
+  catch (_e) { return false; }                  // vanished — nothing to reclaim
+  return cur.ino === observedIno && (now - cur.mtimeMs) / 1000 > staleAfterSeconds;
+}
+
 // 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;
@@ -1565,9 +1455,10 @@ function acquireUpdateLock(home, { timeout = null } = {}, env = process.env) {
           // brand-new, not-yet-stale ticket for the SAME generation, so A and C would BOTH
           // believe they are the sole reclaimer — the exact double-hold bug this ticket
           // mechanism was built to prevent, reintroduced one level down).
-          let currentTino = null;
-          try { currentTino = fs.statSync(ticketPath).ino; } catch (_e) { /* already gone */ }
-          if (currentTino === tst.ino) {
+          // Same reuse guard as the main lock: only unlink a ticket STILL at its observed inode
+          // AND still aged past the ticket-stale threshold (a freed inode number can be reused
+          // by a fresh, live ticket for a new generation).
+          if (stillStaleGeneration(ticketPath, tst.ino, LOCK_TICKET_STALE_SECONDS)) {
             try { fs.unlinkSync(ticketPath); } catch (_e) {}   // already gone — harmless
           }
           try { ticketFd = fs.openSync(ticketPath, "wx"); } catch (_e) {}   // someone else won it
@@ -1594,9 +1485,12 @@ function acquireUpdateLock(home, { timeout = null } = {}, env = process.env) {
           // generation we ticketed for; otherwise our ticket is moot — leave the (unrelated,
           // currently live) file completely alone and let the loop's own open/EEXIST/age logic
           // re-evaluate reality fresh on the next iteration.
-          let currentIno = null;
-          try { currentIno = fs.statSync(lockPath).ino; } catch (_e) { /* already gone */ }
-          if (currentIno === st.ino) {
+          // Re-verify STALENESS, not just inode identity: a freed inode number is REUSED by
+          // Linux (ext4/tmpfs), so a live holder's fresh reused-inode lock must never be
+          // unlinked on a bare inode match. Only remove it if it is STILL the observed inode
+          // AND still stale — a live/heartbeated file (age < staleAfterMs) is spared, closing
+          // the peak=2 double-hold.
+          if (stillStaleGeneration(lockPath, st.ino, staleAfterMs / 1000)) {
             try { fs.unlinkSync(lockPath); } catch (_e) {}   // already gone — harmless
           }
         } finally {
@@ -1728,9 +1622,10 @@ function acquireProjectLock(addDir, env = process.env) {
           // mechanism was built to prevent, reintroduced one level down). Exactly one extra
           // self-heal attempt — never a second, matching M7's own "no poll, ever" discipline
           // already governing the main lock's own reclaim above.
-          let currentTino = null;
-          try { currentTino = fs.statSync(ticketPath).ino; } catch (_e) { /* already gone */ }
-          if (currentTino === tst.ino) {
+          // Same reuse guard as the main lock: only unlink a ticket STILL at its observed inode
+          // AND still aged past the ticket-stale threshold (a freed inode number can be reused
+          // by a fresh, live ticket for a new generation).
+          if (stillStaleGeneration(ticketPath, tst.ino, PROJECT_LOCK_TICKET_STALE_SECONDS)) {
             try { fs.unlinkSync(ticketPath); } catch (_e) {}   // already gone — harmless
           }
           try { ticketFd = fs.openSync(ticketPath, "wx"); } catch (_e) {}   // someone else won it
@@ -1756,9 +1651,12 @@ function acquireProjectLock(addDir, env = process.env) {
           // moot — leave the (unrelated, currently live) file completely alone and let the
           // single retry below observe reality fresh (EEXIST -> fail-fast, per M7 — this lock
           // never polls a live holder).
-          let currentIno = null;
-          try { currentIno = fs.statSync(lockPath).ino; } catch (_e) { /* already gone */ }
-          if (currentIno === st.ino) {
+          // Re-verify STALENESS, not just inode identity: a freed inode number is REUSED by
+          // Linux (ext4/tmpfs), so a live holder's fresh reused-inode lock must never be
+          // unlinked on a bare inode match. Only remove it if it is STILL the observed inode
+          // AND still stale — a live/heartbeated file (age < staleAfterMs) is spared, closing
+          // the peak=2 double-hold.
+          if (stillStaleGeneration(lockPath, st.ino, staleAfterMs / 1000)) {
             try { fs.unlinkSync(lockPath); } catch (_e) {}   // already gone — harmless
           }
         } finally {
@@ -1978,6 +1876,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  stillStaleGeneration: stillStaleGeneration,
   detectAgent: detectAgent,
   detectAgentEnriched: detectAgentEnriched,
   readinessLine: readinessLine,
@@ -1985,7 +1884,4 @@ module.exports = {
   scopeOptions: scopeOptions,
   writeIntentNote: writeIntentNote,
   writeGeminiSettings: writeGeminiSettings,
-  ruleFileMode: ruleFileMode,
-  ensureClaudeReference: ensureClaudeReference,
-  writeRuleFilePointer: writeRuleFilePointer,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pilotspace/add",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "ADD (AI-Driven Development) 2.0. The agent is the hands; ADD is the memory, judgment, and conscience — a minimal, state-tracked skill: one freeze per feature, trust from passing tests, state on disk so context rot never survives a new session.",
   "bin": {
     "add": "bin/cli.js"

package/skill/add/SKILL.md

@@ -3,7 +3,7 @@ name: add
 description: >-
   ADD (AI-Driven Development) — a minimal, state-tracked workflow: the AI writes
   the code, the human owns direction and verification. Drives every feature through
-  one lean PLAN.md: Specify → Scenarios → Plan → Tests → Build → Verify → Observe,
+  one lean PLAN.md: Specify → Plan → Tests & Scenarios → Build → Verify → Observe,
   red/green TDD built in. Use whenever a repo has `.add/`, or the user says "add",
   "start a task", "next phase", "specify this feature", "ADD method", "AI-driven
   development", or wants spec/tests-first discipline over vague-prompt coding. Also
@@ -15,7 +15,7 @@ argument-hint: "status | init | continue | --todo <text> | [describe new short g
 license: MIT
 metadata:
   author: add
-  version: "2.0.0"
+  version: "2.4.0"
 ---
 
 # ADD — memory · judgment · conscience (the agent is the hands)
@@ -70,9 +70,9 @@ confirms. Unsharp intent? **Interview before you size** (`intake.md`). A milesto
 Every task is three beats (seven steps, folded), three engine calls, ONE human decision:
 
 1. **DIRECTION** — load the domain-fit persona (seed via add-worker persona-mode if none), then compose
-   the whole bundle in ONE silent draft — §1–§3 + §5-scope, no per-section narration; §4 then runs red — in PLAN.md: §1 rules + ranked ⚠ flag (co-specify) ·
-   §2 scenarios (optional gherkin — §4 is canonical) · §3 PLAN (grounding → frozen contract shape → build-strategy + Scope + Target) ·
-   §4 red suite — one test per Must & per Reject (a Must/Reject encoded in neither §2 nor §4 = §1 not understood — stop); run red for the RIGHT reason; fill each `covers:` key. Then the ONE approval,
+   the whole bundle in ONE silent draft — §1·§3 + §5-scope, no per-section narration; §4 then runs red — in PLAN.md: §1 rules + ranked ⚠ flag (co-specify) ·
+   §3 PLAN (grounding → frozen contract shape → build-strategy + Scope + Target) ·
+   §4 TESTS & SCENARIOS — the red suite (cases live here; optional inline gherkin when a human needs it): one test per Must & per Reject (a Must/Reject encoded in no §4 test = §1 not understood — stop); minor behaviors are prose build-guidance, not gated; run red for the RIGHT reason; fill each `covers:` key. Then the ONE approval,
    presented lowest-confidence-first: `add.py freeze` (a setup session's baseline `lock` IS this approval).
 2. **BUILD** — code in `src/` until every red is green; change no test, no frozen contract; stay
    inside the §3 Scope. A test OUTSIDE your suite failing? `add.py locate` names the owning node, the
@@ -100,6 +100,7 @@ confirmable delta the human confirms rewrites `SOUL.md` (the human is the only w
 - §3 FROZEN → auto-gated run `run.md` · subagent roster + pipelines (agent-call-preferred, the
   default execution mode) → `phases/verify.md` · self-score → `phases/direction.md`
 - UI/experience surface → UDD loop `design.md` · milestone goal unmet at `milestone-done` → `loop.md`
+- multi-task / high-uncertainty milestone → persona-framed strategy loop `strategy.md` (fills the `## Strategy` slot; micro/`--tiny` → skip)
 - graduation · release · monorepo green-bars → persona-owned playbooks, `beyond.md` ·
   the persona loop (`.add/personas/`) → `docs/18-personas.md` · `sensitivity:`/`advisor-gate-relax` → `phases/verify.md`
 

package/skill/add/beyond.md

@@ -20,6 +20,10 @@ prose. Load it (or the one guide you need) only when a trigger fires.
   Tool-agnostic; the engine never renders.
 - Tasks all done but the milestone **goal** unmet → `milestone-done` holds it open; the loop turns open
   deltas + extras into the next tasks until the goal is met — `loop.md`.
+- **A multi-task / high-uncertainty milestone** needs its task DAG sequenced before the tasks are built →
+  the persona-framed **strategy loop** (DISCUSS → OPTIMIZE → CONVERGE): the persona loaded at intake fills
+  the milestone's `## Strategy` slot with the optimized plan, converging on the six-dimension self-score —
+  `strategy.md`. SOFT/advisory, never a gate; a micro / `--tiny` milestone skips it (drafted-blank).
 - **Graduating mvp → production** — co-specify interview → draft ≥1 production milestone →
   human confirm → then `stage production`. Guarded (`stage_no_roadmap`); the FINAL step, never a
   bare flip. The quality-auditor persona carries the readiness playbook.

package/skill/add/deltas.md

@@ -43,7 +43,7 @@ If a learning touches two, ask "which competency, once updated, would have PREVE
 
 ```
 emit (OBSERVE)        human review
-   open  ───────────▶  folded     (merged into PROJECT.md; version bumps)
+   open  ───────────▶  folded     (merged into its `.add/specs/<dd>` spec; version bumps)
          └──────────▶  rejected   (deliberately NOT consolidated — trail kept)
 ```
 

package/skill/add/design.md

@@ -42,7 +42,7 @@ Record **before** review-domain: project **defaults** in DESIGN.md's `## Design
 
 ### 1 · review-domain
 Start from the **domain**, not a blank canvas. Read the domain model — entities, flows, the
-ubiquitous language in `PROJECT.md` / `GLOSSARY.md` — and derive **which screens** the feature needs
+ubiquitous language in `.add/specs/domain.md` / `GLOSSARY.md` — and derive **which screens** the feature needs
 + each screen's **regions**. Map each entity to a *presentational* component (owns no domain
 decision). Output: the screen list + regions.
 

package/skill/add/intake.md

@@ -4,6 +4,23 @@ Before a task exists, ADD turns a raw request into correctly-sized, versioned sc
 **intake level** (the per-task flow is phases 0–7; intake is the step *before* a task). You
 (the AI) **propose**; the human **confirms**. Never create scope without a confirmed proposal.
 
+## Load the fitting persona first
+
+Intake is a decision — size it WITH the project's expertise, not generically. Before you
+analyze or size, load the fitting persona (the PM / product-direction lens), exactly as
+`design.md` loads the design-fit persona:
+
+- **match** a persona in `.add/personas/` by role/flow (frontmatter, else description-match)
+  — e.g. a `product-lead` / `method-product-owner` lens;
+- **none fits?** seed from `.add/personas-teacher/` via the add agent in persona mode, then
+  load — offered, **never required**;
+- the persona shapes the framing, the latent-requirement read, and the sizing tradeoffs. It
+  is **advisory**: it never lowers the `ask_human` floor, the frozen-scope tie-break, or the
+  security-always-escalates rule.
+
+No fitting persona and none seeded? Proceed generically — intake still runs. The persona already
+OWNS the intake report (`gate-udd.md`); loading it here makes it own the SIZING too, so the two agree.
+
 ## Analyze the request before you size it
 
 A raw request is rarely a task yet — it is intent wrapped in prose. ADD's first job is not to

package/skill/add/phases/build.md

@@ -5,6 +5,28 @@ acceptance check — passes, without changing any test or the contract. This is
 AI leads; §1–§4 removed all ambiguity. Write code into `.add/tasks/<slug>/src/` (a non-coding
 task writes its artifact to the path its §5 Scope declares).
 
+## The reasoning discipline — build's slice of the arc (definitions: `phases/direction.md`)
+
+**Fluent ≠ true** holds in code: a diff feels done in proportion to how much you wrote, not how
+much you verified — a green you haven't refuted is a claim, not evidence. Run the arc per batch:
+
+- **FRAME** — restate the batch's tests and the frozen §3 clause they cover before writing a line.
+- **GROUND** — open every anchor before editing it; a recalled file/symbol/flag is `[PRIOR]`
+  until re-confirmed against the live tree THIS session; a live read outranks memory.
+- **REASON** — name the mechanism ("because…"), simulate one concrete input through the change
+  before committing it; when a red survives a fix, hold a second hypothesis instead of patching harder.
+- **ATTACK** — before presenting green: re-run the suite fresh, then reviewer-read your own diff
+  hunting the cheap falsifying input (file · line · values). An earned green is one you tried to
+  kill. Security findings stay HARD-STOP.
+- **DELIVER** — the green report leads with the outcome and tags its claims: a pass you ran THIS
+  session is `[OBSERVED]`; a remembered pass is `[PRIOR]` — never present it bare.
+- **Constraint loop on the §5 Scope allowlist** — don't eyeball it: list the files actually
+  touched (`git status` / diff) and check each against the declared Scope tokens mechanically
+  before the gate; a miss is `scope_violation` — caught by you, not by the engine.
+- **Follow-through (the Floor's second check)** — green tests ≠ the goal reached; simulate the
+  human's end state once — run the artifact under the BARE declared runtime — before calling
+  the batch done.
+
 ## Work in small batches
 
 Pick ONE task-sized slice, restate its tests, implement, iterate to green —