@pilotspace/add 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -4,6 +4,50 @@ 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

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

@@ -1209,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;
@@ -1433,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
@@ -1462,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 {
@@ -1596,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
@@ -1624,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 {
@@ -1846,6 +1876,7 @@ if (require.main === module) {
 }
 
 module.exports = {
+  stillStaleGeneration: stillStaleGeneration,
   detectAgent: detectAgent,
   detectAgentEnriched: detectAgentEnriched,
   readinessLine: readinessLine,

package/package.json

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

@@ -15,7 +15,7 @@ argument-hint: "status | init | continue | --todo <text> | [describe new short g
 license: MIT
 metadata:
   author: add
-  version: "2.3.0"
+  version: "2.4.0"
 ---
 
 # ADD — memory · judgment · conscience (the agent is the hands)
@@ -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/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/strategy.md

@@ -0,0 +1,54 @@
+# Strategy — the persona-framed PM loop that fills the `## Strategy` slot
+
+A multi-task or high-uncertainty milestone earns a plan over its tasks *before* they are
+built. This guide drives that plan: a short **DISCUSS → OPTIMIZE → CONVERGE** loop that fills
+the milestone's `## Strategy` slot (`MILESTONE.md`) with a sequenced, optimized task DAG.
+
+**Trigger:** a milestone with several tasks or real uncertainty, at intake or when it activates.
+**Skip:** a micro / `--tiny` milestone — a **drafted-blank** slot is valid, run nothing (risk-proportional).
+
+The persona already loaded at intake (`intake.md`) **drives** this loop — you don't re-select
+one. It frames the sequencing WITH the project's PM lens; it stays advisory throughout.
+
+## Run the loop (with the intake persona)
+
+1. **DISCUSS** — surface the task DAG: the dependencies, the shared/risky contracts, the
+   tradeoffs. Reflect the milestone goal, name what's in and out. Ask **one load-bearing
+   question per live lens** — an interview toward ~95% confidence, not a survey.
+2. **OPTIMIZE** — sequence the DAG. Fill the slot's four facets (defined there, not restated
+   here): **approach** (risk-first | dependency-first | first-slice-unblocks — and WHY) ·
+   the **freeze-first** contract(s) · the **parallel waves** behind those frozen contracts ·
+   the **first unblocking slice**. Name the alternative decompositions you rejected.
+3. **CONVERGE** — before you record, pressure-test the plan. If the milestone is
+   **high-uncertainty** (the sequencing is contested, or the self-score won't clear its bar),
+   spawn `add-advisor` in **refute** mode to try to **break** the strategy — the approach, the
+   freeze-first choice, the wave partition. Fold what survives; concede what holds. A
+   low-uncertainty / micro / `--tiny` milestone **skips** the spawn — no forced ceremony.
+   Then self-score with the existing six-dimension confidence self-score (`phases/direction.md`);
+   refine until it clears its bar (no dimension < 0.9 ≈ ~95% confident). Do **not** invent a
+   second threshold — that bar IS convergence. Record the converged plan in the `## Strategy` slot.
+
+The refute is **advisory**: the advisor hands back the concrete break — it **cannot block**.
+The human still confirms the strategy at the human decision point, through the persona-owned
+gate (`gate-udd.md`) — the persona decides the report's shape and cadence. Security stays **HARD-STOP**.
+
+## It stays SOFT
+
+The `## Strategy` slot is the **preferred** plan, exactly like a task's §5 Build-strategy: the
+build loop may deviate and records what it actually did. It is **advisory** — **never a new
+gate**, and it never lowers a floor. Security stays **HARD-STOP** everywhere. A milestone is
+never blocked on reaching a confidence bar; the bar guides the draft, it does not gate the work.
+
+## How deep? (risk-proportional)
+
+Loop depth scales with the milestone's risk/size — more risk/size, more depth:
+
+- **micro / `--tiny`** → skip the loop. A drafted-blank `## Strategy` is valid; the loop runs
+  nothing — **zero added per-turn cost**.
+- **multi-task, low-uncertainty** → run DISCUSS → OPTIMIZE → CONVERGE; no advisor.
+- **high-uncertainty** (contested sequencing, or the self-score won't clear its bar) → the full
+  loop **plus** the `add-advisor` refute at CONVERGE.
+
+This is the skill's judgment, reusing the Trigger / Skip and CONVERGE signals above — **never an
+engine gate** on `## Strategy`. The ladder is **SOFT**: a run may go deeper or shallower and
+records what it did. Security stays **HARD-STOP**.

package/tooling/add_engine/constants.py

@@ -82,7 +82,7 @@ def book_url(chapter: str) -> str:
 # `add.py guide` copy: per-phase (concrete next action, book chapter to read).
 # Keep the action wording aligned with each phase's EXIT line in the TASK template.
 PHASE_GUIDE = {
-    "direction": ("draft the Direction bundle top-to-bottom — §1 rules (Must / Reject + named codes / After, assumptions ranked lowest-confidence first) · §2 one scenario per rule · §3 the change PLAN: ground the real code, draft the contract, and DESCRIBE what this task will do (scope · ordered batches · approach — the plan-of-action the freeze report shows the human) · §4 red suite failing for the right reason; then the ONE approval: freeze --by <name> --cross",
+    "direction": ("draft the Direction bundle top-to-bottom — §1 rules (Must / Reject + named codes / After, assumptions ranked lowest-confidence first) · §3 the change PLAN: ground the real code, draft the contract, and DESCRIBE what this task will do (scope · ordered batches · approach — the plan-of-action the freeze report shows the human) · §4 red suite failing for the right reason, one case per rule (scenarios live here with the tests); then the ONE approval: freeze --by <name> --cross",
                   "03-step-1-specify.md"),
     "build":     ("write the minimum code to pass the tests; change no test and no contract",
                   "07-step-5-build.md"),

package/tooling/templates/GLOSSARY.md.tmpl

@@ -29,7 +29,7 @@ binding verdict: a §6 Advisor 3-lens verdict with Binding:yes — engine-enforc
 bounded self-heal: the verify-gate loop (heal-then-escalate) that gives a CONFIRMED cheat — mechanical tamper (the tripwire) or a reported earned-green failure (`add.py heal --reason`) — a chance to redo honestly before it stops: the engine returns the task to build, COUNTS the attempt, CAPS it at 3 (`HEAL_CAP`), and on the next confirmed cheat forces a HARD-STOP that escalates to the human. The counter is MONOTONIC — it never auto-resets (cmd_phase is unguarded, so a reset would be a zero-human cap bypass). The engine counts/caps/escalates; the AGENT does the honest re-build (never the engine). An honest build passes even at the cap (the cap bites a CONTINUED cheat, never a recovery); a gamed green is never auto-passed, never RISK-ACCEPTED-waived.
 onboarding: the install -> first-milestone path (formerly "on-ramp").
 primary flow: the solid forward path of the flow diagram — a phase starts only when its input exists (formerly "forward spine").
-ground: the phase-0 preamble before specify — the AI gathers the real current codebase a task touches (files, symbols, signatures, conventions) into a §0 grounding map; AI-owned, adds no gate (the one approval stays at the contract freeze).
+ground: the grounding pass that opens the direction phase — the AI gathers the real current codebase a task touches (files, symbols, signatures, conventions) into a §0 grounding map; AI-owned, adds no gate (the one approval stays at the contract freeze).
 grounding map / anchors: the §0 GROUND artifact — the real files/symbols/conventions a task touches plus the anchors the frozen contract cites; task-specific delta only (defers to PROJECT.md / CONVENTIONS.md), surfaced by status/check (measure, never block).
 cross-cutting concern: a concern running through every step rather than being one step — security, testing, observability, cost (formerly "spine / continuous concern").
 working state: everything an agent loads each session — skill router, active phase, PROJECT/MILESTONE/TASK, state.json (formerly "state surface").

package/tooling/templates/MILESTONE.md.tmpl

@@ -40,7 +40,7 @@ Issues/Risks (shared): <traps in the shared code that feed each task's §1 expec
 ## Exit criteria (observable; map each to the task that delivers it)
 - [ ] User can <observable behavior — the SEEN outcome only, NOT the task's plan line>        (← <slug>)
 
-## Strategy   (AI-drafted WITH the human — the optimized task plan; SOFT/advisory like a task's Build-strategy; drafted-blank for a micro/--fast milestone)
+## Strategy   (AI-drafted WITH the human — the optimized task plan; SOFT/advisory like a task's Build-strategy; drafted-blank for a micro/--tiny milestone)
 > The persona-led strategy over THIS milestone's tasks — sequencing, freeze-first contracts,
 > parallel waves, the first unblocking slice, tradeoffs named. SOFT: the preferred plan; the
 > loop may deviate and records what it did. Drafted-blank is valid (risk-proportional).

package/tooling/templates/PLAN.md.tmpl

@@ -3,7 +3,7 @@
 slug: {{slug}} · created: {{date}} · stage: {{stage}}
 milestone: {{milestone}}
 autonomy: {{autonomy}}   <!-- manual<conservative<auto — lower for high-risk (`add.py autonomy set`); a `component: <name>` line joins that root to §3 Scope; task edges: `--depends-on`/`--extends`/`--relates-to`; high-risk/method-defining? declare `risk: high` on the slug line; headless agent-crossed freeze? declare `gate_mode: ai-plan-verify` here (human floor: security|data|architecture never AI-frozen) -->
-phase: direction   <!-- direction→build→verify→done; direction drafts §1–§4 (rules · scenarios · change plan · red suite) to the ONE freeze -->
+phase: direction   <!-- direction→build→verify→done; direction drafts §1–§4 (rules · change plan · red suite) to the ONE freeze -->
 
 > One file = one task — an ATOMIC node: persist the interface (contract · red suite · scope · verdict); reason everything else in-context, don't write essays. The phase marker above is the single source of truth (`add.py phase`).