@pareto4/pp-core 1.11.0 → 1.12.0

package/pp-core/bin/lib/roadmap.cjs

@@ -11,7 +11,6 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
-const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
@@ -19,11 +18,11 @@ const { output, error } = ioMod;
 const phaseIdMod = require("./phase-id.cjs");
 const { escapeRegex, normalizePhaseName, phaseMarkdownRegexSource, phaseMarkdownRegexSourceExact, phaseTokenMatches } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
-const phaseLocatorMod = require("./phase-locator.cjs");
-const { findPhaseInternal } = phaseLocatorMod;
+const phaseScopeMod = require("./phase-scope.cjs");
+const { resolvePhaseForRead } = phaseScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserModule = require("./roadmap-parser.cjs");
-const { stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone } = roadmapParserModule;
+const { stripShippedMilestones, extractCurrentMilestone, replaceInCurrentMilestone, buildPlansSummaryLinePattern, PHASE_SECTION_SCAN } = roadmapParserModule;
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -375,12 +374,69 @@ function cmdRoadmapAnalyze(cwd, raw) {
     output(result, raw, undefined);
 }
 // ─── cmdRoadmapUpdatePlanProgress ─────────────────────────────────────────────
+/**
+ * The status a phase carries between its last executed wave and the
+ * `execute:post` governance gate (D-08-15).
+ *
+ * Every plan has a SUMMARY, and nothing has yet recorded the phase as governed.
+ * It is deliberately a third literal, distinct from both neighbours:
+ *   - `In Progress` — plans remain unexecuted;
+ *   - `Built`       — all plans executed, governance not yet granted;
+ *   - `Complete`    — written ONLY by `phase.complete`, after the execute:post
+ *                     gate returned without halting (D-08-13).
+ *
+ * A reader (or an auditor) can therefore tell "the code exists" from "the code
+ * was allowed to ship" by looking at one cell.
+ */
+const ROADMAP_BUILT_STATUS = 'Built';
+/**
+ * Refresh a phase's ROADMAP.md plan rows, executed count and status from disk.
+ *
+ * D-08-12: this handler can NOT write phase-level completion. It never ticks the
+ * phase checkbox, never writes a `(completed <date>)` stamp, never writes the
+ * `Complete` status cell and never writes `plans complete`. Those four surfaces
+ * belong to `phase.complete` (`src/phase.cts` `cmdPhaseComplete`), which the
+ * execute-phase workflow reaches only AFTER the `execute:post` gate dispatch
+ * returned without halting (D-08-13).
+ *
+ * Why it was narrowed — VA-R2-F2, measured: completion used to be INFERRED here
+ * from a file count (`summaryCount >= planCount`), and both call sites run per
+ * wave, several waves before governance runs. The round-2 fixture caught the
+ * consequence: ROADMAP.md read `Complete 2/2` for a phase whose blocking
+ * `vault.trace` gate had halted, while STATE.md still read `status: executing`.
+ * A file count is evidence that plans were built; it is not evidence that the
+ * phase was governed, and this verb is no longer allowed to confuse the two.
+ *
+ * D-08-32 — AND IT MAY NOT UNWRITE ONE EITHER. D-08-12 closed the forward
+ * direction and left the reverse open: on the live UAT fixture, phase 1 read
+ * `| 2/2 | Complete    | 2026-09-16 |` after a governed completion, and a single
+ * `roadmap update-plan-progress 1` demoted it to `Built` and erased the date.
+ * A completion date is the one stored fact that distinguishes "the code exists"
+ * from "the code was allowed to ship", and a counter that can silently delete it
+ * makes the record unusable as a record.
+ *
+ * So: a phase is GOVERNED when its progress row's Status cell reads `Complete`
+ * (case-insensitive, trimmed) OR its Plans summary line already says
+ * `plans complete`. Both are read from the UNMODIFIED content before any write.
+ * On a governed phase this verb refreshes the executed-count cell and nothing
+ * else — Status, Completed and the summary line are left exactly as
+ * `phase.complete` wrote them. Un-governing a phase (a plan added after
+ * completion) is a `phase`-family action, not this counter's.
+ *
+ * And on EVERY path, governed or not, the Completed cell is never assigned. It
+ * is `phase.complete`'s cell (D-08-12); a `-` placeholder is the template's own
+ * not-complete marker, and blanking it is still a write to a cell this verb does
+ * not own.
+ *
+ * `status` and `built` in the JSON output stay count-derived, so this verb still
+ * never REPORTS `Complete`; `governed` says whether it preserved a row.
+ */
 function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
     if (!phaseNum) {
         error('phase number required for roadmap update-plan-progress');
     }
     const roadmapPath = planningPaths(cwd).roadmap;
-    const phaseInfo = findPhaseInternal(cwd, phaseNum);
+    const phaseInfo = resolvePhaseForRead(cwd, phaseNum);
     if (!phaseInfo) {
         error(`Phase ${phaseNum} not found`);
     }
@@ -390,59 +446,91 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         output({ updated: false, reason: 'No plans found', plan_count: 0, summary_count: 0 }, raw, 'no plans');
         return;
     }
-    const isComplete = summaryCount >= planCount;
-    const status = isComplete ? 'Complete' : summaryCount > 0 ? 'In Progress' : 'Planned';
-    const today = clock_cjs_1.realClock.today();
+    const built = summaryCount >= planCount;
+    const status = built ? ROADMAP_BUILT_STATUS : summaryCount > 0 ? 'In Progress' : 'Planned';
     if (!node_fs_1.default.existsSync(roadmapPath)) {
         output({ updated: false, reason: 'ROADMAP.md not found', plan_count: planCount, summary_count: summaryCount }, raw, 'no roadmap');
         return;
     }
+    // Hoisted out of the locked section so the JSON output can report it
+    // (D-08-32); assigned exactly once, inside the lock, from the content read
+    // there.
+    let governedPhase = false;
     // Wrap entire read-modify-write in lock to prevent concurrent corruption
     withPlanningLock(cwd, () => {
         let roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
         const phasePattern = phaseMarkdownRegexSource(phaseNum);
         // Progress table row: update Plans/Status/Date columns (handles 4 or 5 column tables)
         const tableRowPattern = new RegExp(`^(\\|\\s*${phasePattern}\\.?\\s[^|]*(?:\\|[^\\n]*))$`, 'im');
+        // Update plan count in phase detail section. The three recognised spellings,
+        // the phase-number boundary, the phase-section bound and the same-line tail
+        // all live in `buildPlansSummaryLinePattern` (src/roadmap-parser.cjs, D-08-33)
+        // — the same builder `cmdPhaseComplete` uses. Two writers, one reading of
+        // what "this phase's Plans line" means.
+        const planCountPattern = buildPlansSummaryLinePattern(phaseNum);
+        // ── D-08-32: is this phase already GOVERNED? ─────────────────────────────
+        // BOTH reads run against the UNMODIFIED content, before any write, so the
+        // answer cannot be contaminated by this call's own edits.
+        const governedByRow = (() => {
+            const rowMatch = roadmapContent.match(tableRowPattern);
+            if (!rowMatch)
+                return false;
+            const cells = rowMatch[0].split('|').slice(1, -1);
+            // Same column arithmetic as the write below: Status is index 3 on a
+            // 5-column table and index 2 on a 4-column one.
+            const statusCell = cells.length === 5 ? cells[3] : cells.length === 4 ? cells[2] : undefined;
+            return statusCell !== undefined && statusCell.trim().toLowerCase() === 'complete';
+        })();
+        const governedByLine = (() => {
+            // Scoped exactly as the WRITE is (`replaceInCurrentMilestone`): a
+            // `plans complete` line inside an archived <details> milestone says
+            // nothing about the phase in the active one.
+            const lastClose = roadmapContent.lastIndexOf('</details>');
+            const scoped = lastClose === -1 ? roadmapContent : roadmapContent.slice(lastClose + '</details>'.length);
+            const lineMatch = scoped.match(planCountPattern);
+            if (!lineMatch)
+                return false;
+            const value = lineMatch[0].slice(lineMatch[1].length);
+            return /plans\s+complete/i.test(value);
+        })();
+        const governed = governedByRow || governedByLine;
+        governedPhase = governed;
         roadmapContent = roadmapContent.replace(tableRowPattern, (fullRow) => {
             const cells = fullRow.split('|').slice(1, -1); // drop leading/trailing empty from split
-            const dateShape = /^\d{4}-\d{2}-\d{2}$/;
+            // The Completed cell is `phase.complete`'s to fill (D-08-12) and is NEVER
+            // assigned here, on any branch (D-08-32) — not even to blank it. A `-`
+            // placeholder is the template's own not-complete marker and survives.
+            // The Status cell is written only when the phase is NOT governed; on a
+            // governed row only the executed count is refreshed.
+            // Both padded cells carry a TRAILING space as well as a leading one: the
+            // cells are re-joined on a bare `|`, so ` ${status.padEnd(11)}` rendered
+            // an 11-character status as `| In Progress|` — a malformed table cell
+            // observed in three consecutive live runs of this verb.
             if (cells.length === 5) {
                 // 5-col: Phase | Milestone | Plans | Status | Completed
                 cells[2] = ` ${summaryCount}/${planCount} `;
-                cells[3] = ` ${status.padEnd(11)}`;
-                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
-                const existingDate5 = cells[4].trim();
-                cells[4] = isComplete
-                    ? (dateShape.test(existingDate5) ? cells[4] : ` ${today} `)
-                    : '  ';
+                if (!governed)
+                    cells[3] = ` ${status.padEnd(11)} `;
             }
             else if (cells.length === 4) {
                 // 4-col: Phase | Plans | Status | Completed
                 cells[1] = ` ${summaryCount}/${planCount} `;
-                cells[2] = ` ${status.padEnd(11)}`;
-                // Preserve only a valid ISO date (#1161: idempotent; self-heal garbage)
-                const existingDate4 = cells[3].trim();
-                cells[3] = isComplete
-                    ? (dateShape.test(existingDate4) ? cells[3] : ` ${today} `)
-                    : '  ';
+                if (!governed)
+                    cells[2] = ` ${status.padEnd(11)} `;
             }
             return '|' + cells.join('|') + '|';
         });
-        // Update plan count in phase detail section.
-        // Three recognised forms (all tolerated; canonical template uses the first):
-        //   `**Plans**: N plans`  — bold word + outer colon (gsd-core/templates/roadmap.md)
-        //   `**Plans:** N plans`  — bold "Plans:" (colon inside bold)
-        //   `Plans: N plans`      — plain text header
-        const planCountPattern = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*|(?:^|\\n)Plans:)\\s*)[^\\n]+`, 'i');
-        const planCountText = isComplete
-            ? `${summaryCount}/${planCount} plans complete`
-            : `${summaryCount}/${planCount} plans executed`;
-        roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
-        // If complete: check checkbox
-        if (isComplete) {
-            const checkboxPattern = new RegExp(`(-\\s*\\[)[ ](\\]\\s*.*Phase\\s+${phasePattern}[:\\s][^\\n]*)`, 'i');
-            roadmapContent = replaceInCurrentMilestone(roadmapContent, checkboxPattern, `$1x$2 (completed ${today})`);
+        // Always "executed", never "complete" (D-08-12): this is a count of the
+        // SUMMARY files on disk, not a statement that the phase was governed.
+        // And on a GOVERNED phase the line is not rewritten at all (D-08-32) —
+        // demoting `2/2 plans complete` to `2/2 plans executed` would delete the
+        // very distinction D-08-12 introduced the two wordings to preserve.
+        if (!governed) {
+            const planCountText = `${summaryCount}/${planCount} plans executed`;
+            roadmapContent = replaceInCurrentMilestone(roadmapContent, planCountPattern, `$1${planCountText}`);
         }
+        // The phase checkbox is NOT ticked here under any count (D-08-12).
+        // `phase.complete` ticks it, after the execute:post gate (D-08-13).
         // Mark completed plan checkboxes (e.g. "- [ ] 50-01-PLAN.md", "- [ ] 50-01:", or "- [ ] **50-01**")
         for (const summaryFile of phaseInfo.summaries) {
             const planId = summaryFile.replace('-SUMMARY.md', '').replace('SUMMARY.md', '');
@@ -490,8 +578,17 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
             //
             // Pattern A: anchor to bare `Plans:` header (preferred).
             // Pattern B: fallback to bold summary when no bare header exists.
-            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
-            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])[\\s\\S]*?(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
+            //
+            // BOTH anchors carry the same phase-section bound as the summary-line
+            // builder (`PHASE_SECTION_SCAN`, D-08-33). They did not, and the omission
+            // was the F2 defect wearing a second hat: given a phase whose section has
+            // NO Plans anchor of either shape, the unbounded lazy scan found the next
+            // phase's anchor and inserted THIS phase's plan rows into THAT phase's
+            // checklist — a plan row asserting membership of a phase it has nothing to
+            // do with. Bounded, a phase with no anchor simply gets no rows, which is
+            // the honest outcome.
+            const insertRowsPatternA = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])${PHASE_SECTION_SCAN}(?:^|\\n)(?:Plans:)[^\\n]*)`, 'i');
+            const insertRowsPatternB = new RegExp(`(#{2,4}\\s*Phase\\s+${phasePattern}(?=[:\\s])${PHASE_SECTION_SCAN}(?:\\*\\*Plans\\*\\*:|\\*\\*Plans:\\*\\*)[^\\n]*)`, 'i');
             const sortedMissing = [...missingPlans].sort();
             const newRows = sortedMissing.map(p => `- [ ] ${p}`).join('\n');
             const inserter = (match) => `${match}\n${newRows}`;
@@ -534,7 +631,11 @@ function cmdRoadmapUpdatePlanProgress(cwd, phaseNum, raw) {
         plan_count: planCount,
         summary_count: summaryCount,
         status,
-        complete: isComplete,
+        built,
+        // D-08-32: true when the phase was already governed and this call therefore
+        // refreshed the executed count only. `status`/`built` stay count-derived, so
+        // this verb still never REPORTS completion — it only says it preserved one.
+        governed: governedPhase,
     }, raw, `${summaryCount}/${planCount} ${status}`);
 }
 // ─── cmdRoadmapAnnotateDependencies ───────────────────────────────────────────
@@ -560,7 +661,7 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
         output({ updated: false, reason: 'ROADMAP.md not found' }, raw, 'no roadmap');
         return;
     }
-    const phaseInfo = findPhaseInternal(cwd, phaseNum);
+    const phaseInfo = resolvePhaseForRead(cwd, phaseNum);
     if (!phaseInfo || phaseInfo.plans.length === 0) {
         output({ updated: false, reason: 'no plans found for phase', phase: phaseNum }, raw, 'no plans');
         return;
@@ -730,6 +831,7 @@ function cmdRoadmapAnnotateDependencies(cwd, phaseNum, raw) {
     }, raw, updated ? `annotated ${waves.length} wave(s), ${crossCuttingTruths.length} constraint(s)` : 'skipped (already annotated or no plan list)');
 }
 module.exports = {
+    ROADMAP_BUILT_STATUS,
     cmdRoadmapGetPhase,
     getRoadmapPhaseWithFallback,
     cmdRoadmapAnalyze,

package/pp-core/bin/lib/runtime-hooks-surface.cjs

@@ -45,7 +45,7 @@ const reset = '\x1b[0m';
 // ---------------------------------------------------------------------------
 const GSD_COPILOT_HOOK_FILE = 'pp-session.json';
 const GSD_COPILOT_SESSION_MSG_PRESENT = 'pp-core: .planning/STATE.md present - review the current phase and any blockers before acting.';
-const GSD_COPILOT_SESSION_MSG_ABSENT = 'pp-core: no .planning/ workflow found - run /pp-new-project to start a tracked workflow.';
+const GSD_COPILOT_SESSION_MSG_ABSENT = 'pp-core: no .planning/ workflow found - run /pp-init to start a tracked workflow.';
 const GSD_COPILOT_SESSION_HOOK_BASH = 'if [ -f .planning/STATE.md ]; then ' +
     `printf '%s' '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_PRESENT}"}'; else ` +
     `printf '%s' '{"additionalContext":"${GSD_COPILOT_SESSION_MSG_ABSENT}"}'; fi`;

package/pp-core/bin/lib/shell-command-projection.cjs

@@ -166,6 +166,21 @@ const MANAGED_HOOK_BASENAMES_BY_SURFACE = {
         'pp-check-update.js',
     ]),
 };
+// This set must be a SUPERSET of every `MANAGED_HOOKS` name
+// (hooks/managed-hooks-registry.cjs, the authoritative list) that the
+// settings-json surface can register. `isManagedHookCommand` reads it, and the
+// uninstall filter plus the #338 migration read both go through that — so a
+// registry hook missing here is classified as a *user* hook and survives an
+// uninstall. Measured in a phase-9 fixture: two names were missing, leaving one
+// pp-core hook still wired to a script that persists (a live PreToolUse hook in
+// a project the operator believes is uninstalled, D-09-08) and one wired to a
+// script the same uninstall had just deleted.
+//
+// It cannot require() the registry: this module is a leaf compiled into
+// pp-core/bin/lib/, and Codex/Copilot/Cline installs ship no hooks/ dir beside
+// it. The pin that keeps the two in step therefore lives in
+// tests/shell-command-projection-dispatch.test.cjs, which drives the check from
+// MANAGED_HOOKS minus a named, reasoned exclusion table.
 const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
     'settings-json': new Set([
         'pp-check-update.js',
@@ -180,6 +195,15 @@ const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
         'pp-session-state.sh',
         'pp-validate-commit.sh',
         'pp-phase-boundary.sh',
+        // Registered by the Claude installer into the settings file (PreToolUse /
+        // PostToolUse / SessionStart) but absent from this set until phase 9.
+        'pp-worktree-path-guard.js',
+        'pp-graphify-update.sh',
+        // Registered on a settings-json-shaped surface by the marketplace plugin
+        // manifest (hooks/hooks.json, SessionStart); a classic install never wires
+        // it, so recognising it removes an entry that is there and changes nothing
+        // when it is not.
+        'pp-ensure-canonical-path.js',
     ]),
     'codex-toml': new Set([
         'pp-check-update.js',

package/pp-core/bin/lib/state-command-router.cjs

@@ -13,12 +13,19 @@
  * ADR-457 build-at-publish: the hand-written bin/lib/state-command-router.cjs
  * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
  * from the prior hand-written .cjs; only types are added.
+ *
+ * 261008-mwk: every subcommand declares the arguments it reads in STATE_ARG_SPECS,
+ * and routeStateCommand refuses anything else (reason `usage`) BEFORE dispatch, so
+ * a refused call writes nothing. The same entry feeds each handler's parseNamedArgs
+ * call, so the validator and the parser read one owner (D-1, D-6).
  */
 const command_aliases_cjs_1 = require("./command-aliases.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
 const { routeHubCommandFamily } = cjsCommandRouterAdapter;
 const command_arg_projection_cjs_1 = require("./command-arg-projection.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
 // ─── Types ────────────────────────────────────────────────────────────────────
 // Helper: extract string-only named arg value (value flags never return boolean).
 function strArg(opts, key) {
@@ -27,8 +34,69 @@ function strArg(opts, key) {
         return undefined;
     return v;
 }
+// ─── Argument specs (261008-mwk D-6) ──────────────────────────────────────────
+/**
+ * The arguments each state subcommand reads — one entry per registered subcommand
+ * (STATE_SUBCOMMANDS plus complete-phase). routeStateCommand validates argv against
+ * the entry before dispatch, and every handler's named-arg parse takes its flag
+ * lists from the same entry. A subcommand added without an entry reds the coverage
+ * pin in tests/state.test.cjs.
+ *
+ * planned-phase reads --phase and --plans only: cmdStatePlannedPhase has no name
+ * parameter, so a name flag would be parsed and dropped (D-4).
+ */
+const STATE_ARG_SPECS = Object.freeze({
+    load: {},
+    json: {},
+    'advance-plan': {},
+    'update-progress': {},
+    'signal-resume': {},
+    validate: {},
+    get: { maxPositionals: 1, verbatimPositionals: true, positionalLabel: 'at most one positional <section>' },
+    update: { maxPositionals: 2, verbatimPositionals: true, positionalLabel: 'at most two positionals <field> <value>' },
+    patch: { free: true },
+    'complete-phase': {
+        valueFlags: ['phase'],
+        maxPositionals: 1,
+        positionalExcludedBy: 'phase',
+        positionalLabel: '--phase <value> or one positional <phase>',
+    },
+    'begin-phase': { valueFlags: ['phase', 'name', 'plans'] },
+    'record-metric': { valueFlags: ['phase', 'plan', 'duration', 'tasks', 'files'] },
+    'add-decision': { valueFlags: ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file'] },
+    'add-blocker': { valueFlags: ['text', 'text-file'] },
+    'resolve-blocker': { valueFlags: ['text'] },
+    'record-session': { valueFlags: ['stopped-at', 'resume-file'] },
+    'signal-waiting': { valueFlags: ['type', 'question', 'options', 'phase'] },
+    'planned-phase': { valueFlags: ['phase', 'plans'] },
+    sync: { booleanFlags: ['verify'] },
+    prune: { valueFlags: ['keep-recent'], booleanFlags: ['dry-run'] },
+    'milestone-switch': { valueFlags: ['milestone', 'name'] },
+    'add-roadmap-evolution': { valueFlags: ['phase', 'action', 'after', 'note', 'note-file'], booleanFlags: ['urgent'] },
+});
+// Own-property lookup only: a subcommand named `constructor` or `__proto__` must
+// reach the hub's unknown-subcommand path, not an Object.prototype member.
+function specFor(sub) {
+    return Object.prototype.hasOwnProperty.call(STATE_ARG_SPECS, sub) ? STATE_ARG_SPECS[sub] : undefined;
+}
 // ─── Implementation ───────────────────────────────────────────────────────────
 function routeStateCommand({ state, args, cwd, raw, error }) {
+    // 261008-mwk D-1: refuse before dispatch, so a refused call runs no handler and
+    // writes nothing. Unknown subcommands fall through to the hub's own message.
+    const sub = args[1] || 'load';
+    const spec = specFor(sub);
+    if (spec) {
+        const verdict = (0, command_arg_projection_cjs_1.validateVerbArgs)(args.slice(2), spec, `state ${sub}`);
+        if (!verdict.ok) {
+            error(verdict.reason, io.ERROR_REASON.USAGE);
+            return;
+        }
+    }
+    // Every handler's named-arg parse reads its flag lists from the verb's spec (D-6).
+    const named = (verb) => {
+        const s = specFor(verb) ?? {};
+        return (0, command_arg_projection_cjs_1.parseNamedArgs)(args, s.valueFlags ?? [], s.booleanFlags ?? []);
+    };
     const parsePlans = (plans) => {
         const parsedPlans = plans == null ? null : Number.parseInt(plans, 10);
         if (plans != null && Number.isNaN(parsedPlans)) {
@@ -90,7 +158,7 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
             },
             'advance-plan': () => state.cmdStateAdvancePlan(cwd, raw),
             'record-metric': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'plan', 'duration', 'tasks', 'files']);
+                const a = named('record-metric');
                 state.cmdStateRecordMetric(cwd, {
                     phase: strArg(a, 'phase'),
                     plan: strArg(a, 'plan'),
@@ -101,7 +169,7 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
             },
             'update-progress': () => state.cmdStateUpdateProgress(cwd, raw),
             'add-decision': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']);
+                const a = named('add-decision');
                 state.cmdStateAddDecision(cwd, {
                     phase: strArg(a, 'phase'),
                     summary: strArg(a, 'summary'),
@@ -111,11 +179,11 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
                 }, raw);
             },
             'add-blocker': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text', 'text-file']);
+                const a = named('add-blocker');
                 state.cmdStateAddBlocker(cwd, { text: strArg(a, 'text'), text_file: strArg(a, 'text-file') }, raw);
             },
             'add-roadmap-evolution': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'action', 'after', 'note', 'note-file'], ['urgent']);
+                const a = named('add-roadmap-evolution');
                 state.cmdStateAddRoadmapEvolution(cwd, {
                     phase: strArg(a, 'phase'),
                     action: strArg(a, 'action'),
@@ -125,43 +193,43 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
                     urgent: a['urgent'] === true,
                 }, raw);
             },
-            'resolve-blocker': () => state.cmdStateResolveBlocker(cwd, strArg((0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text']), 'text'), raw),
+            'resolve-blocker': () => state.cmdStateResolveBlocker(cwd, strArg(named('resolve-blocker'), 'text'), raw),
             'record-session': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['stopped-at', 'resume-file']);
+                const a = named('record-session');
                 // Pass resume_file as-is (undefined when --resume-file was not provided) so
                 // cmdStateRecordSession can distinguish "caller explicitly passed a value" from
                 // "option was not supplied" and apply the template-default-only replacement guard.
                 state.cmdStateRecordSession(cwd, { stopped_at: strArg(a, 'stopped-at'), resume_file: strArg(a, 'resume-file') }, raw);
             },
             'begin-phase': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                const a = named('begin-phase');
                 state.cmdStateBeginPhase(cwd, strArg(a, 'phase'), strArg(a, 'name'), parsePlans(strArg(a, 'plans')), raw);
             },
             'signal-waiting': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['type', 'question', 'options', 'phase']);
+                const a = named('signal-waiting');
                 state.cmdSignalWaiting(cwd, strArg(a, 'type'), strArg(a, 'question'), strArg(a, 'options'), strArg(a, 'phase'), raw);
             },
             'signal-resume': () => state.cmdSignalResume(cwd, raw),
             'planned-phase': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                const a = named('planned-phase');
                 state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), parsePlans(strArg(a, 'plans')), raw);
             },
             validate: () => state.cmdStateValidate(cwd, raw),
             sync: () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['verify']);
+                const a = named('sync');
                 state.cmdStateSync(cwd, { verify: a['verify'] }, raw);
             },
             prune: () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['keep-recent'], ['dry-run']);
+                const a = named('prune');
                 state.cmdStatePrune(cwd, { keepRecent: strArg(a, 'keep-recent') || '3', dryRun: a['dry-run'] === true }, raw);
             },
             // complete-phase: CJS-only — no SDK counterpart.
             'complete-phase': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase']);
+                const a = named('complete-phase');
                 state.cmdStateCompletePhase(cwd, raw, strArg(a, 'phase') || args[2]);
             },
             'milestone-switch': () => {
-                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['milestone', 'name']);
+                const a = named('milestone-switch');
                 state.cmdStateMilestoneSwitch(cwd, strArg(a, 'milestone'), strArg(a, 'name'), raw);
             },
         },
@@ -169,4 +237,5 @@ function routeStateCommand({ state, args, cwd, raw, error }) {
 }
 module.exports = {
     routeStateCommand,
+    STATE_ARG_SPECS,
 };