@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/bin/lib/state.cjs

@@ -14,7 +14,7 @@ const node_path_1 = __importDefault(require("node:path"));
 const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output, error } = ioMod;
+const { output, error, declineNoOp, formatDiagnosticToken } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const cliExitModule = require("./cli-exit.cjs");
 const { ExitError } = cliExitModule;
@@ -26,7 +26,9 @@ const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { parsePhaseFromProse, PHASE_NUMBER_TOKEN_SOURCE, phaseKeyFromToken, phaseKeyFromDir, isSentinelPhaseId, scopeToPhase, } = phaseIdMod;
+const { parsePhaseFromProse, PHASE_NUMBER_TOKEN_SOURCE, matchPhaseDirs, phaseKeyFromToken, phaseKeyFromDir, phaseHeadingPrefixSrcFor, PHASE_HEADING_BASELINE, isSentinelPhaseId, scopeToPhase, 
+// #2761 M3: owns the bracket milestone intro and canonical pad2 spelling.
+bracketMilestoneIntroSrcFor, } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParserMod = require("./roadmap-parser.cjs");
 // #3642: hasMilestoneSectioning no longer consumed here — its >=2 semantics answered sibling conflation, but this branch asks asserted-vs-section (>=1). It stays exported from roadmap-parser.cjs for its unit pins.
@@ -34,7 +36,7 @@ const { getMilestoneInfo, extractCurrentMilestone, isMilestoneBoundedInRoadmap,
 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");
-const { planningDir, planningPaths } = planningWorkspace;
+const { planningDir, planningPaths, resolvePhaseIdConvention } = planningWorkspace;
 const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
@@ -53,8 +55,19 @@ function isUnparseableFrontmatter(existingFm) {
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const scanPhasePlans = require("./plan-scan.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtilsMod = require("./core-utils.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planDependencyGraphMod = require("./plan-dependency-graph.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete } = verificationMod;
+// #4129: the single owner of "count the ROADMAP's milestone Complete rows"
+// (phase-lifecycle.cts) — reused for the completed-phases numerator floor so
+// this scan cannot grow a second ROADMAP parser. Pure computation module (no
+// I/O), so it introduces no cycle on this path.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLifecycleMod = require("./phase-lifecycle.cjs");
+const { deriveProgressFromRoadmap } = phaseLifecycleMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -75,7 +88,7 @@ const project_root_cjs_1 = require("./project-root.cjs");
 // it introduces no cycle on this path.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const milestoneLockMod = require("./milestone-lock.cjs");
-const { transitionCore, applyStatePreservation, sliceCurrentPositionSection } = stateTransitionMod;
+const { transitionCore, applyStatePreservation, sliceCurrentPositionSection, stateReplaceProgressPercent, formatProgressMachineSegment } = stateTransitionMod;
 // #3699: the frontmatter-key <-> body-field routing behind `state update`'s
 // failure explanation, and the classification table it falls back to.
 const { getFieldClassification, getFrontmatterBodySource, frontmatterKeyForBodyField } = stateTransitionMod;
@@ -280,7 +293,7 @@ function cmdStateGet(cwd, section, raw) {
         // Try to find markdown section or field
         const fieldEscaped = (0, pattern_cjs_1.escapeRegex)(section);
         // Check for **field:** value (bold format)
-        const boldPattern = new RegExp(`\\*\\*${fieldEscaped}:\\*\\*\\s*(.*)`, 'i');
+        const boldPattern = new RegExp(`^[ \\t]*\\*\\*${fieldEscaped}:\\*\\*[ \\t]*(.*)`, 'im');
         const boldMatch = content.match(boldPattern);
         if (boldMatch) {
             output({ [section]: boldMatch[1].trim() }, raw, boldMatch[1].trim());
@@ -308,13 +321,10 @@ function readTextArgOrFile(cwd, value, filePath, label) {
         return value;
     // Path traversal guard: ensure file resolves within project directory
     // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
-    const { validatePath } = require('./security.cjs');
-    const pathCheck = validatePath(filePath, cwd, { allowAbsolute: true });
-    if (!pathCheck.safe) {
-        throw new Error(`${label} path rejected: ${pathCheck.error}`);
-    }
+    const { assertWithinRoot, PathAcceptance } = require('./security.cjs');
+    const contained = assertWithinRoot(filePath, cwd, `${label} path`, PathAcceptance.AbsoluteInsideRoot);
     try {
-        return node_fs_1.default.readFileSync(pathCheck.resolved, 'utf-8').trimEnd();
+        return node_fs_1.default.readFileSync(contained, 'utf-8').trimEnd();
     }
     catch {
         throw new Error(`${label} file not found: ${filePath}`);
@@ -483,7 +493,31 @@ function cmdStateUpdate(cwd, field, value) {
         // (#3345's direction) — reported separately from `updated` because this
         // command's contract is a single-field boolean, not a per-field array.
         const reconciled = reconcileReportedFields(statePath, preWriteState, updated ? [field] : [], divergedFields);
-        updated = reconciled.includes(field);
+        // #4488: `updateCore` itself already told us whether it matched the field
+        // (`updated`, captured above `readModifyWriteStateMd` runs it) — that is a
+        // real signal, not a guess. `reconcileReportedFields` answers a DIFFERENT
+        // question ("what changed on disk") and, per its own docstring, reports
+        // `[]` whenever `preWriteState.fm` is `undefined`. That happens in two
+        // known cases, both of which mean "no snapshot was ever captured", not
+        // "nothing happened": (a) `readModifyWriteStateMd`'s #948 no-op guard
+        // fires because the transform's output was byte-identical to the input —
+        // the requested value already equals what's on disk, so the field WAS
+        // found and there was simply nothing left to change; (b)
+        // `applyPostSyncPreservation`'s `isUnparseableFrontmatter` early return —
+        // the ORIGINAL frontmatter block was malformed, so preservation never
+        // runs, yet `readModifyWriteStateMd` still persists the transform's raw
+        // output via `platformWriteSync`. In neither case did preservation
+        // discard or rewrite what the transform wrote, so trusting the
+        // transform's own `updated` signal here is never a false positive.
+        // Collapsing either case into the same `false` as "field not found" is
+        // the #4488 bug — `explainUpdateFailure` then reports a message that is
+        // actively false (it tells the caller to add a line that is already
+        // there). Every other `false` origin (case-D fallback did not apply, or
+        // the transform genuinely found nothing) is unaffected: there
+        // `preWriteState.fm` is defined (a normal sync ran) or `updated` was
+        // already false before this line.
+        const noopBecauseAlreadyCorrect = updated && preWriteState.fm === undefined;
+        updated = reconciled.includes(field) || noopBecauseAlreadyCorrect;
         const preserved = reconciled.filter((f) => f !== field);
         if (updated) {
             // #3699 case D: surfaced so a caller can tell "wrote the body source" from
@@ -520,6 +554,42 @@ function cmdStateUpdate(cwd, field, value) {
     }
 }
 // ─── State Progression Engine ────────────────────────────────────────────────
+/**
+ * The "I could not read the plan position" message, DERIVED from
+ * `STATE_FIELD_SCHEMA.current_plan.acceptedShapes` rather than transcribed
+ * beside it.
+ *
+ * The accepted-shape set had two owners: the parser branches in
+ * `advancePlanCore` and an English list hand-written here. Nothing coupled
+ * them, so adding a branch left this message stale and removing one left it
+ * advertising a shape that errors — and no test could see either. ADR-3473
+ * §8.3 is "one implementation per rule"; the schema row is that one owner, and
+ * rows 23/24/25 already hold the parser to it.
+ *
+ * `Plan: N of M` is spelled out separately because there is no schema row for
+ * the body-only `Plan` field: `buildStateFrontmatter` never reads it into
+ * frontmatter, so it has no `current_*` key to hang a row on. That asymmetry is
+ * the schema's, not this function's.
+ */
+function advancePlanShapeError() {
+    const shapes = stateMdSchemaMod.STATE_FIELD_SCHEMA['current_plan']?.acceptedShapes ?? [];
+    const spellings = shapes.map((shape) => (shape === 'N'
+        ? '`Current Plan: N` with `Total Plans in Phase: M`'
+        : `\`Current Plan: ${shape}\``));
+    // The body-only `Plan` field has no schema row to derive from:
+    // `buildStateFrontmatter` never reads it into frontmatter, so there is no
+    // `current_*` key to hang a row on. Its ONE accepted spelling is named here.
+    //
+    // `Plan: N` with a `Total Plans in Phase: M` sibling is deliberately NOT
+    // listed (#3791 review round 6, M2): the parser does not accept it. A
+    // revision of this PR added both the branch and this spelling together, on
+    // the reasoning that the message must advertise exactly what the parser
+    // accepts. That reasoning still holds — which is why removing the branch
+    // removes the spelling in the same commit. The invariant is the lockstep,
+    // not the length of the list.
+    spellings.push('`Plan: N of M`');
+    return `Cannot read the plan position from STATE.md. Expected one of: ${spellings.join(', ')}.`;
+}
 /**
  * Replace a STATE.md field with fallback field name support.
  * Tries `primary` first, then `fallback` (if provided), returns content unchanged
@@ -541,6 +611,86 @@ function stateReplaceFieldWithFallback(content, primary, fallback, value) {
         `This may indicate STATE.md was externally modified or uses an unexpected format.\n`);
     return content;
 }
+/**
+ * #4067: disk-derived plan-completion answer for advance-plan's phase-complete
+ * guard.
+ *
+ * `advancePlanCore` decides "phase complete" purely from STATE.md's scalar plan
+ * counter (`currentPlan >= totalPlans`). That counter cannot represent
+ * wave-parallel execution — a stale counter carried over from the prior phase
+ * (the reported trigger: `Plan: 7 of 7` surviving into a 10-plan phase) or a
+ * counter raced by N concurrent executors both let the phase-complete branch
+ * fire while sibling plans are mid-flight. This helper answers the completion
+ * question from disk instead, exactly the way `state update-progress`
+ * recalculates it: every plan in the Current Position phase's directory has a
+ * SUMMARY.md.
+ *
+ * Single-derivation discipline: plan/summary counting is owned by
+ * `scanPhasePlans` (src/plan-scan.cts, ADR-3180 §7.5) — this helper consumes
+ * it, never re-derives. It deliberately does NOT consult `isPhaseComplete`
+ * (§7.4): that owner answers the *verification* question (passing
+ * `*-VERIFICATION.md`), a different question from "are all plans executed?".
+ * Blocked summaries (#3345) are filtered from the pairing set with the same
+ * shared predicate `scanPhasePlans` uses, so the named outstanding list can
+ * never disagree with the count-based decision.
+ *
+ * FAIL-OPEN contract: returns `null` when the disk answer is UNAVAILABLE — no
+ * readable phases dir, no directory matching the position phase, or a scan
+ * whose scope is not COMPLETE (the scan may be blind to plans it knows exist).
+ * `null` means "the caller must fall back to the counter-derived decision",
+ * NOT "plans are outstanding"; worlds the seam cannot see (STATE.md with no
+ * Current Position `Phase:` line, milestone-archived layouts) keep today's
+ * behavior rather than being newly refused.
+ *
+ * Returns `{ dir, outstanding, planCount, summaryCount }` where `outstanding`
+ * is empty when every plan on disk is summarized (vacuously so for a zero-plan
+ * phase — #3168's zero-plan-phase posture). `planCount`/`summaryCount` are the
+ * countable disk facts behind `outstanding` (live plan files; summaries after
+ * the #3345 blocked filter) — #4093's recovery decline reports them to a
+ * caller whose STATE.md has lost its labeled plan position, so the suggested
+ * repair values are computed from the SAME set `outstanding` was, and can
+ * never disagree with a count-based decision either.
+ */
+function scanOutstanding(phasesDir, dir) {
+    const phaseDirPath = node_path_1.default.join(phasesDir, dir);
+    const scan = scanPhasePlans(phaseDirPath);
+    if (scan.scope !== SCOPE.COMPLETE)
+        return null;
+    // Blocked summaries (#3345) are filtered with the same shared predicate
+    // scanPhasePlans uses for its own count, so the named outstanding list can
+    // never disagree with a count-based decision.
+    const countableSummaries = scan.summaryFiles.filter((f) => !planDependencyGraphMod.isSummaryFileBlocked(node_path_1.default.join(phaseDirPath, f)));
+    const outstanding = coreUtilsMod.findUnsummarizedPlans(scan.planFiles, countableSummaries);
+    return { dir, outstanding, planCount: scan.planFiles.length, summaryCount: countableSummaries.length };
+}
+function unsummarizedPlansForPositionPhase(cwd, positionPhase) {
+    const phasesDir = planningPaths(cwd).phases;
+    // #3185 (ADR-3180 Decision 1): "which phase directories exist" is owned by
+    // listMilestonePhaseDirs — no hand-rolled readdirSync here. The owner
+    // handles an absent phasesDir as a real empty and refuses sentinels.
+    //
+    // Two passes, narrowest first: the CURRENT-MILESTONE window (so an archived
+    // milestone's stale `01-*` directory cannot shadow the live one), then —
+    // only when the window cannot answer (no bounded ROADMAP, or the position
+    // phase is simply not in it) — an unscoped read, which the owner documents
+    // as a real answer. This is a lookup of ONE phase token STATE.md names, not
+    // a milestone enumeration, so the unscoped retry is in-contract.
+    const convention = resolvePhaseIdConvention(cwd);
+    const windowed = listMilestonePhaseDirs(phasesDir, { cwd, phaseIdConvention: convention });
+    const candidateDirs = windowed.scope === SCOPE.COMPLETE ? windowed.value : [];
+    // Canonical phase-token → directory matching (phase-id owner, #2562): both
+    // sides of the comparison derived by the same function, never a local regex.
+    const { matches } = matchPhaseDirs(candidateDirs, positionPhase, convention);
+    if (matches.length > 0)
+        return scanOutstanding(phasesDir, matches[0]);
+    const unscoped = listMilestonePhaseDirs(phasesDir);
+    if (unscoped.scope !== SCOPE.COMPLETE)
+        return null;
+    const retry = matchPhaseDirs(unscoped.value, positionPhase, convention);
+    if (retry.matches.length === 0)
+        return null;
+    return scanOutstanding(phasesDir, retry.matches[0]);
+}
 function cmdStateAdvancePlan(cwd, raw) {
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
@@ -567,6 +717,16 @@ function cmdStateAdvancePlan(cwd, raw) {
     // STATE.md lock, so the position read and the claim read cannot interleave
     // with another session's Current Position write.
     let milestoneConflict = null;
+    // #4067: set when the disk-derived guard declines the phase-complete branch —
+    // named here so the post-lock output path can report it without re-deriving.
+    // Holder (not a bare let) so TypeScript's closure-unaware narrowing cannot
+    // collapse the post-lock read to `never` — the callback assigns it.
+    const outstandingRef = { value: null };
+    // #4093: the position phase token the callback resolved (Current Position
+    // `Phase:` line first, frontmatter `current_phase` as fallback), carried out
+    // so the generic parse-failure decline can derive recovery facts from disk
+    // without re-reading STATE.md outside the lock. Same holder idiom as above.
+    const positionPhaseRef = { value: null };
     const wrote = readModifyWriteStateMd(statePath, (content) => {
         // advance-plan has no phase argument of its own — the phase it advances is
         // whatever ## Current Position names. Compare that against the milestone
@@ -576,6 +736,17 @@ function cmdStateAdvancePlan(cwd, raw) {
         const body = stripFrontmatter(content);
         const positionScope = matchCurrentPositionSection(body) ?? body;
         const positionPhase = parseProsePhaseField((0, state_document_cjs_1.stateExtractField)(positionScope, 'Phase')).phase;
+        // #4093: a Current Position section with ZERO labeled fields has no
+        // `Phase:` line either; frontmatter `current_phase` is the documented
+        // survivor of body drift (the reporter's document still carried it, and
+        // `buildStateFrontmatter` re-derives it from the body only when the body
+        // HAS the line). It feeds the recovery DECLINE only — never a write.
+        let fmPhase = null;
+        if (positionPhase === null) {
+            const fmToken = extractFrontmatter(content, statePath)['current_phase'];
+            fmPhase = typeof fmToken === 'string' && fmToken.trim() !== '' ? fmToken.trim() : null;
+        }
+        positionPhaseRef.value = positionPhase ?? fmPhase;
         if (positionPhase !== null) {
             milestoneConflict = milestoneLockMod.checkMilestonePosition(cwd, positionPhase);
             if (milestoneConflict) {
@@ -583,10 +754,53 @@ function cmdStateAdvancePlan(cwd, raw) {
             }
         }
         const result = transitionCore(content, intent, deps);
+        // #4067: the transform's phase-complete branch is decided by STATE.md's
+        // scalar plan counter, which can neither carry a stale value across phases
+        // nor represent wave-parallel execution. Before letting that branch write
+        // "Phase complete — ready for verification", re-decide from disk (the same
+        // source state.update-progress recalculates from): every plan in the
+        // position phase's directory must have a SUMMARY.md. A non-empty
+        // outstanding list declines the ENTIRE write — STATE.md is returned
+        // byte-identical, so the decline is idempotent and safe for any number of
+        // concurrent callers (the disk answer is re-read under the STATE.md lock
+        // each call; the counter stays display-only). `null` (disk answer
+        // unavailable) fails open to the counter-derived decision, so every
+        // world this seam cannot see keeps today's behavior.
+        if (result.data?.['advanced'] === false
+            && result.data?.['reason'] === 'last_plan'
+            && positionPhase !== null) {
+            const diskAnswer = unsummarizedPlansForPositionPhase(cwd, positionPhase);
+            if (diskAnswer !== null && diskAnswer.outstanding.length > 0) {
+                outstandingRef.value = diskAnswer;
+                resultData = result.data;
+                precomputedUpdated = [];
+                return content;
+            }
+        }
         resultData = result.data;
         precomputedUpdated = result.updated;
         return result.content;
     }, cwd, { divergedFields, preWriteState });
+    // #4067 decline path: plans remain unexecuted on disk. Shaped like the
+    // existing `last_plan` decline (advanced:false + machine-readable reason,
+    // exit 0) rather than a hard error — the caller did nothing wrong and
+    // STATE.md needs no repair; the remaining plans' executors will re-run this
+    // command, and the final one finds a fully-summarized phase and completes it.
+    const plansOutstanding = outstandingRef.value;
+    if (plansOutstanding !== null) {
+        declineNoOp(raw, 'advanced', 'plans_outstanding', `state advance-plan skipped — phase-complete declined: ${plansOutstanding.outstanding.length} plan(s) in .planning/phases/${plansOutstanding.dir} have no SUMMARY.md (${plansOutstanding.outstanding.join(', ')}). STATE.md was left unchanged; re-run once every plan has executed and written its summary.`, {
+            advanced: false,
+            phase_dir: plansOutstanding.dir,
+            outstanding_plans: plansOutstanding.outstanding,
+            milestone_conflict: milestoneConflict,
+        });
+        return;
+    }
+    // `!resultData` is a type guard, not a second failure mode: the callback
+    // above assigns it unconditionally and only runs once STATE.md is known to
+    // exist (the missing-file case returns "STATE.md not found" earlier), and
+    // every `advancePlanCore` return path sets `data`. So the message below is
+    // the one a caller can actually receive.
     if (!resultData || resultData['error']) {
         // #3807: a multi-`Phase:` Current Position section carries its own cause
         // and its own remedy (name the candidates; the caller resolves them).
@@ -598,7 +812,70 @@ function cmdStateAdvancePlan(cwd, raw) {
             }, raw, undefined);
             return;
         }
-        output({ error: 'Cannot parse Current Plan or Total Plans in Phase from STATE.md' }, raw, undefined);
+        // #3791 review round 6 (B1): the document carries both plan-position
+        // spellings with DIFFERENT numbers. Same posture as the case above — name
+        // the candidates and let the caller resolve them. Advancing either one
+        // would write a number into the other that nothing derived for it.
+        if (resultData && resultData['reason'] === 'ambiguous_plan_position') {
+            output({
+                error: 'STATE.md carries two plan positions with different numbers — refusing to advance either. Resolve them to a single current plan and re-run.',
+                reason: resultData['reason'],
+                plan_candidates: resultData['plan_candidates'],
+            }, raw, undefined);
+            return;
+        }
+        // #4093: the generic terminus — no accepted labeled plan-position shape
+        // parsed anywhere in the document (the reporter's case: ## Current
+        // Position drifted to pure narrative prose with zero labeled fields).
+        // Every OTHER refusal above carries a machine-readable reason and the
+        // evidence to act on; this one stranded the caller at a bare sentence
+        // with no recovery path. Give it the same posture: a `reason` the caller
+        // can branch on, plus — when the position phase can be resolved and its
+        // directory scanned — the disk-derived facts and the exact labeled lines
+        // to re-insert. Nothing is WRITTEN: STATE.md is returned byte-identical
+        // (the callback already returned the original content for this path),
+        // so the decline is idempotent and no repair is guessed into the file —
+        // the caller (human or agent) applies the suggested lines and re-runs.
+        // Disk is the recovery source per #4067's posture; the values below are
+        // computed from the SAME `scanOutstanding` counts the plans_outstanding
+        // guard uses, so the two declines can never disagree about a phase.
+        const positionToken = positionPhaseRef.value;
+        const diskFacts = positionToken !== null
+            ? unsummarizedPlansForPositionPhase(cwd, positionToken)
+            : null;
+        if (diskFacts === null) {
+            // No resolvable phase (no Phase: line, no current_phase frontmatter, or
+            // no matching phase directory / incomplete scan): keep today's shape
+            // error, plus the reason so callers can tell this refusal from the
+            // ambiguous_* ones without string-matching the sentence.
+            output({ error: advancePlanShapeError(), reason: 'plan_position_unreadable' }, raw, undefined);
+            return;
+        }
+        const planCount = diskFacts.planCount;
+        const summarized = diskFacts.summaryCount;
+        // A summarized count below the plan count means the next plan to execute
+        // is summarized+1; an equal count means the phase is done on disk and the
+        // position line should say so (current = total; the next advance-plan run
+        // takes the #4067-guarded phase-complete branch from it). Zero plan files
+        // means disk has no opinion — suggest nothing rather than `1 of 0`.
+        const payload = {
+            error: advancePlanShapeError(),
+            reason: 'plan_position_unreadable',
+            phase_dir: diskFacts.dir,
+            disk: { plan_count: planCount, summarized_count: summarized },
+        };
+        if (planCount > 0) {
+            const current = summarized < planCount ? summarized + 1 : planCount;
+            payload['suggested'] = {
+                current_plan: current,
+                total_plans: planCount,
+                lines: [`Current Plan: ${current}`, `Total Plans in Phase: ${planCount}`],
+            };
+            payload['error'] =
+                `${advancePlanShapeError()} Disk for phase ${diskFacts.dir}: ${summarized} of ${planCount} plan(s) summarized. ` +
+                    `Re-insert a labeled plan position at the top of ## Current Position (e.g. Current Plan: ${current} with Total Plans in Phase: ${planCount}), then re-run.`;
+        }
+        output(payload, raw, undefined);
         return;
     }
     // ADR-3408 §8.4 (D4): reconcile `advancePlanCore`'s own success list against
@@ -803,7 +1080,7 @@ function computeUpdateProgressPreview(statePath, cwd) {
     const existingFm = extractFrontmatter(preContent, statePath);
     const preBody = stripFrontmatter(preContent);
     const storedMilestone = typeof existingFm['milestone'] === 'string' ? existingFm['milestone'] : null;
-    const builtFm = buildStateFrontmatter(preBody, cwd, storedMilestone, readStoredTotalPhases(existingFm));
+    const builtFm = buildStateFrontmatter(preBody, cwd, storedMilestone, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm));
     const progress = builtFm['progress'];
     const percent = progress && typeof progress['percent'] === 'number' ? progress['percent'] : null;
     const completedPlans = progress && typeof progress['completed_plans'] === 'number' ? progress['completed_plans'] : null;
@@ -844,7 +1121,39 @@ function cmdStateUpdateProgress(cwd, raw) {
         // excluded sentinels, unlike the owner). The owner already handles an
         // absent phasesDir as a real empty, so the fs.existsSync guard folds
         // into it.
-        const { value: phaseDirs, scope } = listMilestonePhaseDirs(phasesDir, { cwd });
+        //
+        // #2761 (round-11 BLOCKER, single-derivation hygiene): `phaseIdConvention`
+        // threaded explicitly (resolved ambiently off `cwd` — this call site has
+        // no `ws` of its own, same contract `resolvePhaseIdConvention` uses
+        // elsewhere in this file, e.g. the `phaseConvention` ONCE-and-THREAD
+        // pattern at ~:2267/:2300) rather than left `undefined`.
+        //
+        // This does NOT change `phaseScope` — `scope` (roadmap-parser.cts
+        // `getMilestonePhaseFilter`) is assigned at :1979/:2030, both BEFORE
+        // `headingConvention` resolves at ~:2048, so the #3217 withhold gate a
+        // few lines below is convention-independent either way (verified
+        // empirically: forcing `phaseIdConvention: null` here left every
+        // `state update-progress` assertion in
+        // tests/adr-612-bracket-phase-counting.test.cjs's round-11 BLOCKER block
+        // unchanged). What DOES depend on convention is `phaseDirs`/`totalPlans`
+        // — the enumerated `.value` these two lines feed into the #3233
+        // zero-plans no-op check just below. The actual `percent` this command
+        // reports/writes comes from a separate, already-correctly-threaded scan
+        // (`computeUpdateProgressPreview` -> `buildStateFrontmatter`, which
+        // resolves its own `phaseConvention` at :2267). Threading here removes a
+        // second, silent, lazily-resolved answer for the SAME question that scan
+        // already answers explicitly — the single-derivation discipline this
+        // file's own :2300 comment states as a rule — rather than fixing an
+        // observed defect. #2761 round-12: the #3233 gate IS the one place this
+        // is observable, so it — not the reported percent — is what
+        // tests/adr-612-bracket-phase-counting.test.cjs's round-12 addition to
+        // the round-11 BLOCKER block pins: a bracket milestone with no plans on
+        // disk versus a decoy directory outside the milestone window that must
+        // not be swept in by a pass-all degrade.
+        const { value: phaseDirs, scope } = listMilestonePhaseDirs(phasesDir, {
+            cwd,
+            phaseIdConvention: cwd ? resolvePhaseIdConvention(cwd) : null,
+        });
         phaseScope = scope;
         for (const dir of phaseDirs) {
             const { planCount } = scanPhasePlans(node_path_1.default.join(phasesDir, dir));
@@ -861,10 +1170,10 @@ function cmdStateUpdateProgress(cwd, raw) {
         // never read, and STATE.md's Progress field goes stale with no
         // user-visible signal beyond it. Mirrors the established
         // `[gsd-tools] WARNING:` stderr convention this file already uses
-        // (stateReplaceFieldWithFallback above) for a comparable silent no-op.
-        process.stderr.write(`[gsd-tools] WARNING: state update-progress skipped — phase scope is ${phaseScope}, not complete. ` +
-            `STATE.md's Progress field was left unchanged.\n`);
-        output({ updated: false, reason: `phase scope is ${phaseScope}, not complete` }, raw, 'false');
+        // (stateReplaceFieldWithFallback above) for a comparable silent no-op —
+        // now routed through the shared `declineNoOp` helper (#3957) so the
+        // pairing is structural rather than hand-written per arm.
+        declineNoOp(raw, 'updated', `phase scope is ${phaseScope}, not complete`, `state update-progress skipped — phase scope is ${phaseScope}, not complete. STATE.md's Progress field was left unchanged.`);
         return;
     }
     // #3233: zero plans in the current-milestone phases means there is nothing to
@@ -876,9 +1185,7 @@ function cmdStateUpdateProgress(cwd, raw) {
     // ("nothing to measure" ≠ "0% done"). The legitimate 0% case (plans exist,
     // none summarized → clampPercent(0, N>0) = 0) is unaffected: totalPlans > 0.
     if (totalPlans === 0) {
-        process.stderr.write(`[gsd-tools] WARNING: state update-progress skipped — no plans found in current-milestone phases (0 plans). ` +
-            `STATE.md's Progress field was left unchanged (milestone archived?).\n`);
-        output({ updated: false, reason: 'no plans found in current-milestone phases — STATE.md left unchanged (milestone archived?)' }, raw, 'false');
+        declineNoOp(raw, 'updated', 'no plans found in current-milestone phases — STATE.md left unchanged (milestone archived?)', `state update-progress skipped — no plans found in current-milestone phases (0 plans). STATE.md's Progress field was left unchanged (milestone archived?).`);
         return;
     }
     // #3583: percent AND the completed/total counts reported alongside it both
@@ -889,48 +1196,30 @@ function cmdStateUpdateProgress(cwd, raw) {
     // disagrees with its own completed/total.
     const preview = computeUpdateProgressPreview(statePath, cwd);
     if (preview.withheld) {
-        process.stderr.write(`[gsd-tools] WARNING: state update-progress skipped — ${preview.reason}\n`);
-        output({ updated: false, reason: preview.reason }, raw, 'false');
+        declineNoOp(raw, 'updated', preview.reason, `state update-progress skipped — ${preview.reason}`);
         return;
     }
     const { percent, completedPlans: fmCompletedPlans, totalPlans: fmTotalPlans } = preview;
-    const barWidth = 10;
-    const filled = Math.round(percent / 100 * barWidth);
-    const bar = '█'.repeat(filled) + '░'.repeat(barWidth - filled);
-    const progressStr = `[${bar}] ${percent}%`;
+    const progressStr = formatProgressMachineSegment(percent);
     let updated = false;
     readModifyWriteStateMd(statePath, (content) => {
-        // #2177: match against the BODY only. With /i the patterns below would
-        // otherwise hit the YAML frontmatter `progress:` key first (and `\s*` would
-        // eat its newline, mangling the nested block), while the body Progress: line
-        // — which frontmatter `percent` is re-derived from on every write — stays
-        // stale and silently reverts the update.
-        const body = stripFrontmatter(content);
-        const fmPrefix = content.slice(0, content.length - body.length);
-        // Swap only the machine segment ("[bar] NN%" or bare "NN%"), preserving any
-        // descriptive suffix an agent authored, e.g. "(2/4 plans done; blocked on…)".
-        const machineSegment = /(?:\[[^\]\r\n]*\][ \t]*)?\d{1,3}%/;
-        const replaceValue = (value) => machineSegment.test(value)
-            ? value.replace(machineSegment, progressStr)
-            : progressStr;
-        // Try **Progress:** bold format first, then plain Progress: format.
-        const boldProgressPattern = /(\*\*Progress:\*\*[ \t]*)([^\r\n]*)/i;
-        const plainProgressPattern = /^(Progress:[ \t]*)([^\r\n]*)/im;
-        const pattern = boldProgressPattern.test(body)
-            ? boldProgressPattern
-            : plainProgressPattern.test(body)
-                ? plainProgressPattern
-                : null;
-        if (!pattern)
+        const result = stateReplaceProgressPercent(content, percent);
+        if (result === null)
             return content;
         updated = true;
-        return fmPrefix + body.replace(pattern, (_match, prefix, value) => `${prefix}${replaceValue(value)}`);
+        return result;
     }, cwd);
     if (updated) {
         output({ updated: true, percent, completed: fmCompletedPlans, total: fmTotalPlans, bar: progressStr }, raw, progressStr);
     }
     else {
-        output({ updated: false, reason: 'Progress field not found in STATE.md' }, raw, 'false');
+        // #3957: the frontmatter progress data was already confirmed present a
+        // few lines above (computeUpdateProgressPreview didn't withhold) — what's
+        // actually missing here is the BODY `Progress:`/`**Progress:**` line
+        // itself. The prior 'Progress field not found in STATE.md' reason named
+        // the wrong layer and silently discarded percent/completed/total, which
+        // the sibling success arm above reports from the same preview.
+        declineNoOp(raw, 'updated', 'no Progress: line found in STATE.md body to update (frontmatter progress data is unaffected)', 'state update-progress skipped — no Progress: line found in STATE.md body to update (frontmatter progress data is unaffected).', { percent, completed: fmCompletedPlans, total: fmTotalPlans });
     }
 }
 function cmdStateAddDecision(cwd, options, raw) {
@@ -1236,7 +1525,15 @@ function cmdStateResolveBlocker(cwd, text, raw) {
         output({ error: 'text required' }, raw, undefined);
         return;
     }
-    let resolved = false;
+    // #3957: track section-found and bullet-matched SEPARATELY. Previously
+    // `resolved` was set unconditionally as soon as the heading was located —
+    // before checking whether any bullet line actually matched `text` — so a
+    // call naming a non-existent blocker reported `resolved: true` (a false
+    // success). Only a real bullet match makes `resolved` true and the
+    // rewrite happen; otherwise the transform returns `content` unchanged
+    // (this repo's established no-op-return idiom).
+    let sectionFound = false;
+    let matched = false;
     readModifyWriteStateMd(statePath, (content) => {
         // ADR-1372 T6: find Blockers/Concerns section via tokenizeHeadings; stop at level 2 or 3.
         // Mirrors /(###?\s*(?:Blockers|Blockers\/Concerns|Concerns)\s*\n)([\s\S]*?)(?=\n###?|\n##[^#]|$)/i
@@ -1244,6 +1541,7 @@ function cmdStateResolveBlocker(cwd, text, raw) {
         const i = hs.findIndex(h => (h.level === 2 || h.level === 3) && /^(?:Blockers|Blockers\/Concerns|Concerns)$/i.test(h.text));
         if (i === -1)
             return content;
+        sectionFound = true;
         const h = hs[i];
         const ls = content.split('\n');
         const hl = ls[h.line - 1];
@@ -1260,24 +1558,48 @@ function cmdStateResolveBlocker(cwd, text, raw) {
         const filtered = lines.filter(line => {
             if (!line.startsWith('- '))
                 return true;
-            return !line.toLowerCase().includes(text.toLowerCase());
+            // Case-insensitive substring match — unchanged from before the fix;
+            // only whether a match occurred is now tracked accurately.
+            const isMatch = line.toLowerCase().includes(text.toLowerCase());
+            if (isMatch)
+                matched = true;
+            return !isMatch;
         });
+        if (!matched)
+            return content;
         let newBody = filtered.join('\n');
         // If section is now empty, add placeholder
         if (!newBody.trim() || !newBody.includes('- ')) {
             newBody = 'None\n';
         }
-        resolved = true;
         return content.slice(0, bs) + newBody + content.slice(se);
     }, cwd);
-    if (resolved) {
+    if (matched) {
         output({ resolved: true, blocker: text }, raw, 'true');
     }
+    else if (!sectionFound) {
+        declineNoOp(raw, 'resolved', 'no Blockers/Concerns section found in STATE.md', 'state resolve-blocker skipped — no Blockers/Concerns section found in STATE.md.');
+    }
     else {
-        output({ resolved: false, reason: 'Blockers section not found in STATE.md' }, raw, 'false');
+        // `formatDiagnosticToken` only guards the STDERR disclosure — the JSON
+        // `reason` field can embed `text` raw since output()'s own
+        // JSON.stringify serialization already escapes it correctly.
+        declineNoOp(raw, 'resolved', `no blocker matching ${text} found in the Blockers section`, `state resolve-blocker skipped — no blocker matching ${formatDiagnosticToken(text)} found in the Blockers section.`);
     }
 }
 function cmdStateRecordSession(cwd, options, raw) {
+    // #4186: a bare invocation is a usage error, not a heartbeat write. The
+    // pre-#4186 handler accepted zero arguments and still refreshed
+    // `Last session` / `Last Date` / `last_updated` — a caller probing the
+    // command's signature (the way other subcommands encourage) silently
+    // mutated STATE.md. Mirrors `state update`'s required-arg guard
+    // (cmdStateUpdate: `error('field and value required for state update')`),
+    // including its ordering: validation precedes the STATE.md existence
+    // check. Either flag suffices — `--resume-file` alone carries an explicit
+    // value the handler must persist.
+    if (!options.stopped_at && (options.resume_file === undefined || options.resume_file === null)) {
+        error('stopped-at or resume-file required for state record-session');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -1516,8 +1838,22 @@ function cmdStateRecordSession(cwd, options, raw) {
             result['created'] = true;
         output(result, raw, 'true');
     }
+    else if (updated.length === 0) {
+        // Nothing was ever attempted — no --stopped-at/--resume-file supplied
+        // and no existing Last session/Last Date/Stopped At/Resume File labels
+        // to touch.
+        declineNoOp(raw, 'recorded', 'no session fields found in STATE.md to update', 'state record-session skipped — no session fields found in STATE.md to update.');
+    }
     else {
-        output({ recorded: false, reason: 'No session fields found in STATE.md' }, raw, 'false');
+        // #3957: `updated` (pre-reconciliation) was non-empty — a rewrite
+        // matched a session field and reported it as changed — but
+        // `reconcileReportedFields` found the persisted bytes byte-identical to
+        // what was already on disk (the matched field's supplied value equals
+        // its already-recorded value), so nothing actually changed. Distinct
+        // from the "nothing was ever attempted" case above: the prior single
+        // reason collapsed both into 'No session fields found in STATE.md',
+        // which was simply wrong for this case.
+        declineNoOp(raw, 'recorded', 'the matched session field(s) already held the reported value — no bytes changed', 'state record-session skipped — the matched session field(s) already held the reported value; no bytes changed.');
     }
 }
 /**
@@ -1819,7 +2155,56 @@ function cmdStateSnapshot(cwd, raw) {
 // ROADMAP phase token against an on-disk phase directory — moved to the
 // phase-id owner module in #2562 so every consumer derives BOTH sides of a
 // phase comparison from the same function (see phase-id.cts). Imported at the
-// top of this file; call sites below are unchanged.
+// top of this file; call sites below are unchanged. #612 threads the optional
+// `convention` through that owner's `phaseKeyFromDir` (see phase-id.cts) rather
+// than re-deriving a bracket-aware key here.
+/**
+ * #612: is the asserted milestone bounded to a heading in this ROADMAP?
+ *
+ * The legacy rule matches STATE's milestone STRING (`v2.0`) inside a heading.
+ * The ADR-canonical bracket milestone heading is `## [GSD.02] Foundation` — a
+ * name, no version — so that rule finds nothing, the milestone reads as
+ * unbounded, and total_phases falls back to the on-disk directory count. Under
+ * the bracket convention the milestone integer in the bracket is matched against
+ * the `vN` of the milestone string instead (READING-B parity). Gated, and only
+ * consulted after the legacy rule has already failed, so no non-bracket repo
+ * changes answer.
+ */
+function isMilestoneBounded(roadmapRaw, milestone, convention) {
+    // #3184: preserve roadmap-parser's canonical legacy answer and compose the
+    // gated bracket extension on top of it. Re-deriving the version-heading
+    // grammar here would restore the boundary drift that #3184 removed.
+    if (isMilestoneBoundedInRoadmap(roadmapRaw, String(milestone).trim()))
+        return true;
+    if (convention !== 'bracket')
+        return false;
+    const vMatch = String(milestone).trim().match(/^v(\d+)/i);
+    const milestoneInt = vMatch ? parseInt(vMatch[1], 10) : NaN;
+    if (!Number.isSafeInteger(milestoneInt))
+        return false;
+    // Canonical spelling only — see the note in roadmap-parser's scoping branch.
+    // Accepting `0*N` here bounded a milestone whose phases were invisible, which
+    // un-suppressed a progress percent computed off an unscoped disk count.
+    // #2761 M3: that padding rule and the grammar both come from the owner's
+    // `bracketMilestoneIntroSrcFor`. This line and roadmap-parser's selector were
+    // character-identical re-typings of one pattern, so "canonical spelling only"
+    // was a convention two files had to keep agreeing on by hand — and the drift
+    // guard could not see either copy.
+    // #612 round-4 (Major 1, F12): fence-aware via tokenizeHeadings, not a raw
+    // `.test(roadmapRaw)` — a FENCED `[GSD.02]` example heading (the ONLY one
+    // in the document, with no real section for the asserted milestone at
+    // all) previously bounded a milestone that isn't actually in the roadmap,
+    // un-suppressing a percent computed off the wrong (prior-milestone-plus-
+    // whole-disk) phase set. tokenizeHeadings never produces a token for a
+    // fenced line, so a fenced-only example can no longer satisfy this test.
+    const bracketMilestoneHeadingRe = new RegExp(`^${bracketMilestoneIntroSrcFor(milestoneInt)}`, 'i');
+    // #612 round-5 (Minor 1): skip ≤3-space-indented tokens — `h.offset` is
+    // tokenizeHeadings' LINE-START offset, not the `#` character, so an
+    // indented heading here would bound a milestone the line-start-anchored
+    // raw predecessor never matched. Restores raw parity; see roadmap-parser's
+    // matching selector-reconstruction comment for the full rationale.
+    return (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(roadmapRaw).some((h) => h.level <= 3 && roadmapRaw[h.offset] === '#' && bracketMilestoneHeadingRe.test(h.text));
+}
 /**
  * Extract the set of retired/folded phase keys from a ROADMAP milestone scope
  * (#1514). A retired phase is struck through with GFM strikethrough,
@@ -1841,16 +2226,31 @@ function cmdStateSnapshot(cwd, raw) {
  * decimal, and project-code IDs are detected alike. Returns canonical keys
  * (see phaseKeyFromToken).
  */
-function extractRetiredPhaseNumbers(scope) {
+function extractRetiredPhaseNumbers(scope, convention) {
     const retired = new Set();
     const isChecklistOrHeading = /^\s*(?:[-*+]\s*\[[ xX]\]|#{1,6}\s)/;
-    for (const line of scope.split(/\r?\n/)) {
+    // #612: the retirement filter has to widen with the counter it protects. The
+    // canonical #1514 gesture strikes the checklist BULLET and leaves the detail
+    // heading intact, so a bracket-form retirement went undetected and the phase
+    // stayed in the denominator forever — a shipped bracket milestone could never
+    // reach 100%. Same selection rule as the counter: a non-bracket repo compiles
+    // the bare `Phase\s+` this line spelled before.
+    const introSrc = phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention);
+    const phaseRefRe = new RegExp(`^[\\s*_]*${introSrc}([\\w][\\w.-]*)`, 'i');
+    // #612 round-5 (Major 1): fence-aware on the BRACKET path only — a fenced
+    // AUTHORING EXAMPLE of the #1514 retirement gesture, spelled in bracket
+    // form, must not retire a real phase. Reuses markdown-sectionizer's
+    // single-owner stripFencedCode rather than a second fence parser. Legacy
+    // stays the raw `scope`, byte-identical — its own fenced-example hazard is
+    // pre-existing and out of scope.
+    const scanScope = convention === 'bracket' ? (0, markdown_sectionizer_cjs_1.stripFencedCode)(scope).text : scope;
+    for (const line of scanScope.split(/\r?\n/)) {
         if (!isChecklistOrHeading.test(line))
             continue;
         const strikeSpan = /~~([^~]*?)~~/g;
         let s;
         while ((s = strikeSpan.exec(line)) !== null) {
-            const phaseRef = /^[\s*_]*Phase\s+([\w][\w.-]*)/i.exec(s[1]);
+            const phaseRef = phaseRefRe.exec(s[1]);
             // Require a digit so struck prose like ~~Phase Overview~~ is ignored.
             if (phaseRef && /\d/.test(phaseRef[1]))
                 retired.add(phaseKeyFromToken(phaseRef[1]));
@@ -1858,12 +2258,110 @@ function extractRetiredPhaseNumbers(scope) {
     }
     return retired;
 }
+/**
+ * #612 (round-4 fix): the single shared implementation for the phase-heading
+ * counter `buildStateFrontmatter` (read path) and `cmdStateSync` (write
+ * path) each built inline as an independent copy. The comment at each call
+ * site already claimed "the two counters must see the same phases or
+ * `state json` and `state sync` report different totals for one repo
+ * (#3242 Bug B)" — this makes that invariant STRUCTURAL (one implementation,
+ * two call sites) instead of two copies a future edit could silently
+ * diverge.
+ *
+ * Two DELIBERATELY DIFFERENT counting strategies, selected by `convention`:
+ *
+ * - BRACKET: counts via `tokenizeHeadings(scope)` at levels 2-4 (mirroring
+ *   `getMilestonePhaseFilter`'s own level bound, `roadmap-parser.cts:1090`),
+ *   testing each heading's (hash-stripped, fence-STRIPPED-by-construction)
+ *   text against the phase-heading-intro grammar directly. Fence-aware by
+ *   construction — `tokenizeHeadings` never produces a token for a fenced
+ *   line — closing round-4's Major 1: a fenced EXAMPLE phase heading in the
+ *   preamble (`` ### [GSD.02] 05: Example phase `` inside a
+ *   ` ```markdown ` block) previously inflated this count via the raw regex
+ *   below, which ran over the whole scope STRING with no fence awareness at
+ *   all (F9, F10 — `total_phases` read 3 where the milestone has 2 real
+ *   phases). The producer (`extractCurrentMilestone`'s returned scope
+ *   string) is deliberately NOT changed — every other consumer of that
+ *   string needs its full content fidelity, and the legacy path's identity
+ *   forbids touching the string all consumers share; this fixes the
+ *   COUNTING, not the scope.
+ *
+ * - LEGACY (any non-bracket convention, including unresolved/null): retain
+ *   the existing raw `content.exec()` counting strategy. On the read path,
+ *   route sentinel exclusion through #3185's canonical predicate; the sync
+ *   path intentionally retains its pre-existing absence of that exclusion.
+ *
+ * `applyConventionTokenSentinelRules` makes the remaining convention-specific
+ * asymmetry explicit. Both read and sync exclude bare bracket token 999; only
+ * the read path excludes canonical legacy sentinels. Both bracket paths also
+ * retain the bracket-id and bare-0 rules. Sharing the implementation therefore
+ * cannot silently move either convention's total.
+ */
+function countRoadmapPhaseHeadings(scope, convention, retiredPhaseNums, applyConventionTokenSentinelRules) {
+    let count = 0;
+    if (convention === 'bracket') {
+        const introSrc = phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, true);
+        const phaseHeadingPattern = new RegExp(`^${introSrc}([\\w][\\w.-]*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'i');
+        for (const h of (0, markdown_sectionizer_cjs_1.tokenizeHeadings)(scope)) {
+            if (h.level < 2 || h.level > 4)
+                continue;
+            const m = phaseHeadingPattern.exec(h.text);
+            if (!m)
+                continue;
+            const bracketId = m[1];
+            const token = m[2];
+            // Only count tokens that contain at least one digit — excludes
+            // pure-word section headings (Overview, Details) while keeping
+            // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
+            if (!/\d/.test(token))
+                continue;
+            // #612 READING-B: a bracket heading carries its sentinel in the
+            // bracket, so `### [GSD.999] 01:` is an icebox item even though its
+            // token is `01`.
+            if (bracketId && isSentinelPhaseId(`${bracketId}-${token}`, 'bracket'))
+                continue;
+            // #612: under bracket the token rule composes with the bracket-id
+            // check as the engine's {0, 999} sentinel set.
+            if (bracketId && /^0\b/.test(token))
+                continue;
+            if (applyConventionTokenSentinelRules && /^999\b/.test(token))
+                continue;
+            // #1514: retired/folded phases are struck through in the ROADMAP;
+            // exclude them from the denominator (they can never be completed).
+            if (retiredPhaseNums.has(phaseKeyFromToken(token)))
+                continue;
+            count++;
+        }
+        return count;
+    }
+    // LEGACY stays on the pre-round-4 raw exec loop. #3185 owns the read-path
+    // sentinel predicate; sync deliberately preserves its prior behavior.
+    const phaseHeadingPattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, true)}([\\w][\\w.-]*)(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
+    let m;
+    while ((m = phaseHeadingPattern.exec(scope)) !== null) {
+        const token = m[1];
+        if (!/\d/.test(token))
+            continue;
+        if (applyConventionTokenSentinelRules && isSentinelPhaseId(token))
+            continue;
+        if (retiredPhaseNums.has(phaseKeyFromToken(token)))
+            continue;
+        count++;
+    }
+    return count;
+}
 /**
  * Extract machine-readable fields from STATE.md markdown body and build
  * a YAML frontmatter object. Allows hooks and scripts to read state
  * reliably via `state json` instead of fragile regex parsing.
  */
-function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPhases) {
+function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPhases, 
+// #4094: the stored siblings of storedTotalPhases, threaded from each call
+// site exactly the same way — see readStoredProgressCounter below. Under the
+// #3354/#3573 withhold condition the disk scan returns null for all four
+// counters, and these stored values are what the progress block falls back
+// to (else the keys are omitted).
+storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
     // #2956: scope `Phase` extraction to ## Current Position (mirrors the read
     // path in cmdStateSnapshot and the Stopped At / Paused At ## Session scoping
     // below). Phase canonically lives in ## Current Position (templates/state.md);
@@ -1953,6 +2451,10 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
     // from the pre-existing frontmatter fields parsed above, a path this phase
     // does not touch and which predates listMilestonePhaseDirs entirely.
     let diskScope = SCOPE.COMPLETE;
+    // #612: resolved ONCE per call, federated workstream -> root, and shared by
+    // the heading counter, the retirement filter and the retired-directory skip so
+    // no two of them can split on different answers.
+    const phaseConvention = cwd ? resolvePhaseIdConvention(cwd) : null;
     if (cwd) {
         try {
             const phasesDir = planningPaths(cwd).phases;
@@ -1973,7 +2475,7 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                         roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(roadmapPath);
                         if (roadmapRaw !== null) {
                             roadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-                            retiredPhaseNums = extractRetiredPhaseNumbers(roadmapScope);
+                            retiredPhaseNums = extractRetiredPhaseNumbers(roadmapScope, phaseConvention);
                         }
                     }
                     catch { /* fall through: no roadmap scope → no retired exclusion */ }
@@ -1984,7 +2486,11 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                     // CURRENT (stored) milestone" — routed through the canonical owner
                     // instead of a hand-rolled readdirSync + isDirInMilestone filter
                     // (which also never excluded sentinels, unlike the owner).
-                    const { value: allMatchingDirs, scope: phaseDirScope } = listMilestonePhaseDirs(phasesDir, { cwd, versionOverride: storedMilestone ?? null });
+                    const { value: allMatchingDirs, scope: phaseDirScope } = listMilestonePhaseDirs(phasesDir, {
+                        cwd,
+                        versionOverride: storedMilestone ?? null,
+                        phaseIdConvention: phaseConvention,
+                    });
                     // Bug #2445: when stale phase dirs from a prior milestone remain in
                     // .planning/phases/ alongside new dirs with the same phase number,
                     // de-duplicate by normalized phase number keeping exactly one dir
@@ -1996,7 +2502,7 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                         // artifact; drop it from the disk phase set so it counts toward
                         // neither the denominator nor the numerator (mirrors the heading
                         // exclusion below). Project-code-aware via phaseKeyFromDir.
-                        if (retiredPhaseNums.size > 0 && retiredPhaseNums.has(phaseKeyFromDir(dir)))
+                        if (retiredPhaseNums.size > 0 && retiredPhaseNums.has(phaseKeyFromDir(dir, phaseConvention)))
                             continue;
                         // #3185: dedup grouping routed through the canonical phaseKeyFromDir
                         // (src/phase-id.cts) instead of a local leading-digits regex that
@@ -2005,7 +2511,7 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                         // so a `PROJ-05`/`PROJ-05-slug` pair never deduped) and on
                         // multi-segment milestone dirs. Same key surface used two lines
                         // above for the retiredPhaseNums exclusion, so both filters agree.
-                        const key = phaseKeyFromDir(dir);
+                        const key = phaseKeyFromDir(dir, phaseConvention);
                         if (!seenPhaseNums.has(key)) {
                             seenPhaseNums.set(key, dir);
                         }
@@ -2046,34 +2552,21 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                         // own comment on that field). Folding this consumer onto the raw
                         // summaries-met flag was the exact "consolidate two of three and
                         // leave the third" gap §7.4's forcing function rules out.
-                        if (isPhaseComplete(phaseDir).value.complete)
+                        // #612: `phaseConvention` threaded so a bracket phase dir resolves
+                        // and scopes its verification report like its legacy twin — the
+                        // read-side half of the same thread cmdStateSync gets below.
+                        if (isPhaseComplete(phaseDir, { convention: phaseConvention }).value.complete)
                             diskCompletedPhases++;
                     }
-                    // Count phase headings from ROADMAP using a digit-containing pattern
-                    // that matches both numeric phases (01, 05.1) and project-code phases
-                    // (PROJ-42, CK-05) but excludes pure-word section headers like
-                    // `## Phase Overview:` or `## Phase Details:` — single source of
-                    // truth for total_phases (#549).
-                    let roadmapPhaseCount = 0;
-                    if (roadmapScope !== null) {
-                        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-                        const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/gi;
-                        let m;
-                        while ((m = phaseHeadingPattern.exec(roadmapScope)) !== null) {
-                            // Only count tokens that contain at least one digit — excludes
-                            // pure-word section headings (Overview, Details) while keeping
-                            // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
-                            // Also exclude sentinel phases (0 and 999.x backlog).
-                            // #3185: canonical sentinel predicate (SENTINEL_RANGES [0,999]) — this was a local 999-only literal that admitted Phase 0.
-                            if (!/\d/.test(m[1]) || isSentinelPhaseId(m[1]))
-                                continue;
-                            // #1514: retired/folded phases are struck through in the ROADMAP;
-                            // exclude them from the denominator (they can never be completed).
-                            if (retiredPhaseNums.has(phaseKeyFromToken(m[1])))
-                                continue;
-                            roadmapPhaseCount++;
-                        }
-                    }
+                    // Count phase headings from ROADMAP — single source of truth for
+                    // total_phases (#549). #612 round-4: shared with cmdStateSync's
+                    // identical-purpose counter via countRoadmapPhaseHeadings (above
+                    // extractRetiredPhaseNumbers). The shared helper composes its
+                    // fence-aware bracket strategy with #3185's canonical legacy
+                    // sentinel predicate for this read-path call.
+                    const roadmapPhaseCount = roadmapScope !== null
+                        ? countRoadmapPhaseHeadings(roadmapScope, phaseConvention, retiredPhaseNums, true)
+                        : 0;
                     cached = (() => {
                         // #1761 read-path: mirror the cmdStateSync guard (#1794). When the
                         // asserted milestone version can't be bounded to a versioned ROADMAP
@@ -2098,7 +2591,7 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                             // the prior inline regex had no boundary assertion after the
                             // version token, so `v2.0` matched inside `v2.0.1` (#2562-class
                             // defect, design row 17).
-                            milestoneBounded = isMilestoneBoundedInRoadmap(roadmapRaw, String(assertedMilestoneVersion).trim());
+                            milestoneBounded = isMilestoneBounded(roadmapRaw, String(assertedMilestoneVersion).trim(), phaseConvention);
                         }
                         // #2828: distinguish a FLAT unmilestoned roadmap (no milestone sectioning
                         // at all — only Phase headings) from a MILESTONED-but-unbounded one
@@ -2140,7 +2633,7 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                         // the disk count is the only source and remains correct.
                         const milestonedButUnbounded = !milestoneBounded && roadmapHasAnyMilestoneSection;
                         if (milestonedButUnbounded) {
-                            process.stderr.write(`gsd: warning — milestone '${String(assertedMilestoneVersion ?? '').trim()}' is asserted in STATE.md but matches no ROADMAP heading, and the ROADMAP carries milestone section(s) — one (#3642) or several (#3354) — none matching it; the whole-document count would attribute a foreign section's phases to this milestone and the on-disk phase-directory count would understate the declared total, so progress.total_phases is left at its stored value. (#3354/#3642)\n`);
+                            process.stderr.write(`gsd: warning — milestone '${String(assertedMilestoneVersion ?? '').trim()}' is asserted in STATE.md but matches no ROADMAP heading, and the ROADMAP carries milestone section(s) — one (#3642) or several (#3354) — none matching it; the whole-document count would attribute a foreign section's phases to this milestone and the on-disk phase-directory count would understate the declared total, so the progress counters (total_phases, completed_phases, total_plans, completed_plans) are left at their stored values. (#3354/#3642/#4094)\n`);
                         }
                         // #3573: the roadmap-absent sibling of the #3354 shape. With ROADMAP.md
                         // absent/unreadable the #549 heading counter never ran (roadmapScope
@@ -2157,21 +2650,59 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                             typeof storedMilestone === 'string' &&
                             storedMilestone.trim() !== '';
                         if (roadmapAbsentWithAssertedMilestone) {
-                            process.stderr.write(`gsd: warning — milestone '${storedMilestone.trim()}' is asserted in STATE.md but ROADMAP.md is absent or unreadable, so the phase-heading total cannot be derived; the on-disk phase-directory count would understate the declared total, so progress.total_phases is left at its stored value. (#3573)\n`);
+                            process.stderr.write(`gsd: warning — milestone '${storedMilestone.trim()}' is asserted in STATE.md but ROADMAP.md is absent or unreadable, so the phase-heading total cannot be derived; the on-disk phase-directory count would understate the declared total, so the progress counters (total_phases, completed_phases, total_plans, completed_plans) are left at their stored values. (#3573) (#4094)\n`);
                         }
+                        // #4094: the withhold condition covers ALL FOUR progress counters,
+                        // not just total_phases. completed_phases / total_plans /
+                        // completed_plans are accumulated from the exact same phaseDirs
+                        // walk as total_phases (same loop, same scope, same filters), so
+                        // whenever that walk's scope is known-untrustworthy — the exact
+                        // condition #3354 established — they are equally untrustworthy.
+                        // Pre-#4094 only totalPhases was nulled here, so every resyncing
+                        // write silently clobbered the three stored siblings with the
+                        // under-scoped disk numbers.
+                        const diskCountsWithheld = milestonedButUnbounded || roadmapAbsentWithAssertedMilestone;
+                        // #4129: floor the completed-phases numerator at the ROADMAP's own
+                        // milestone Complete-row count. The disk numerator counts ONLY
+                        // phase dirs whose *-VERIFICATION.md routes `passed` (isPhaseComplete,
+                        // #2957 disk-strict — the gate stays untouched), so a completed
+                        // phase whose verification reads `stale` (a SUMMARY committed or
+                        // edited after it, #2348 clean-commit-time clock) or `missing`
+                        // (pre-verification era, hand-flipped ROADMAP row) drops out of the
+                        // count forever — while every other surface (the ROADMAP row
+                        // `phase complete` just flipped, the body `Completed Phases` field
+                        // completePhaseCore derives from deriveProgressFromRoadmap) still
+                        // asserts the phase complete. max(disk, ROADMAP) keeps the disk
+                        // signal for gap detection (a verification-passed phase whose ROADMAP
+                        // row is not yet flipped still counts) while never UNDER-counting
+                        // what the ROADMAP asserts. Scoped exactly like the denominator:
+                        // the same milestone window (roadmapScope), the same
+                        // safeToUseRoadmapCount gate, and never under the #3354/#3573
+                        // withhold — a whole-document Complete-row count must not leak
+                        // through an untrustworthy scope. Reuses deriveProgressFromRoadmap
+                        // (phase-lifecycle.cts, the one owner of "read the Progress table")
+                        // — no second ROADMAP parser here. A ROADMAP without a canonical
+                        // `## Progress` table resolves no table → floor inert (disk count
+                        // stands), the owner's own answer to "what is countable".
+                        const roadmapCompletedPhases = roadmapScope !== null && safeToUseRoadmapCount && !diskCountsWithheld
+                            ? deriveProgressFromRoadmap(roadmapScope).completedPhases
+                            : null;
+                        const flooredCompletedPhases = roadmapCompletedPhases !== null
+                            ? Math.max(diskCompletedPhases, roadmapCompletedPhases)
+                            : diskCompletedPhases;
                         return {
                             // The two WITHHOLD shapes (#3354 milestoned-but-unbounded, #3573
                             // roadmap-absent-with-asserted-milestone) must be evaluated BEFORE
                             // safeToUseRoadmapCount — in the #3573 shape milestoneBounded is
                             // vacuously true (its gate requires roadmapRaw), so the safe-count
                             // arm would otherwise swallow the withhold.
-                            totalPhases: (milestonedButUnbounded || roadmapAbsentWithAssertedMilestone)
+                            totalPhases: diskCountsWithheld
                                 ? null
                                 : (safeToUseRoadmapCount ? Math.max(phaseDirs.length, roadmapPhaseCount) : phaseDirs.length),
                             milestoneBounded,
-                            completedPhases: diskCompletedPhases,
-                            totalPlans: diskTotalPlans,
-                            completedPlans: diskTotalSummaries,
+                            completedPhases: diskCountsWithheld ? null : flooredCompletedPhases,
+                            totalPlans: diskCountsWithheld ? null : diskTotalPlans,
+                            completedPlans: diskCountsWithheld ? null : diskTotalSummaries,
                             phaseDirScope,
                         };
                     })();
@@ -2189,9 +2720,31 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
                 else if (storedTotalPhases !== null && storedTotalPhases !== undefined) {
                     totalPhases = storedTotalPhases;
                 }
-                completedPhases = cached.completedPhases;
-                totalPlans = cached.totalPlans;
-                completedPlans = cached.completedPlans;
+                // #4094: the same withhold-then-fall-back-to-stored pattern for the
+                // three sibling counters. They are derived from the identical
+                // phaseDirs walk, so cached.* === null here means the SAME withheld
+                // condition — keep the stored frontmatter value when the caller can
+                // supply it; else leave null (key omitted). Note completedPhases /
+                // completedPlans have NO body-annotation fallback (only the totals
+                // have body annotations), so an unstored-withheld counter is omitted.
+                if (cached.completedPhases !== null) {
+                    completedPhases = cached.completedPhases;
+                }
+                else if (storedCompletedPhases !== null && storedCompletedPhases !== undefined) {
+                    completedPhases = storedCompletedPhases;
+                }
+                if (cached.totalPlans !== null) {
+                    totalPlans = cached.totalPlans;
+                }
+                else if (storedTotalPlans !== null && storedTotalPlans !== undefined) {
+                    totalPlans = storedTotalPlans;
+                }
+                if (cached.completedPlans !== null) {
+                    completedPlans = cached.completedPlans;
+                }
+                else if (storedCompletedPlans !== null && storedCompletedPlans !== undefined) {
+                    completedPlans = storedCompletedPlans;
+                }
                 milestoneUnbounded = cached.milestoneBounded === false;
                 diskScope = cached.phaseDirScope;
             }
@@ -2240,19 +2793,19 @@ function buildStateFrontmatter(bodyContent, cwd, storedMilestone, storedTotalPha
             progressPercent = parseInt(pctMatch[1], 10);
     }
     let normalizedStatus = (0, state_document_cjs_1.normalizeStateStatus)(status, pausedAt);
-    // #3578: normalizeStateStatus matches 'complete' as a case-insensitive
-    // SUBSTRING, so the phase-completion prose cmdStateCompletePhase writes to
-    // the body (`Phase ${N} complete`) collapses to the milestone-level
-    // 'completed' status even when other phases remain open. Phase-level
-    // prose must never decide milestone-level status — completedPhases /
-    // totalPhases / diskScope, already derived above from a disk scan, are
-    // the authority on whether the MILESTONE is actually done. Only override
-    // when: (a) normalizeStateStatus actually landed on 'completed'; (b) the
-    // raw prose is UNAMBIGUOUSLY phase-completion prose — the anchored
-    // pattern below deliberately excludes "All phases complete" (no `\S+`
-    // phase token) and milestone-close prose like "v1.0 milestone complete"
-    // (no leading "phase"); and (c) the counters are trustworthy (a COMPLETE
-    // disk scope, both counts are finite numbers, and a positive
+    // #3578: the declared status vocabulary (#4186) recognizes
+    // `Phase ${N} complete` (state.cts's own phase-completion write) and maps
+    // it to `completed`, so the phase-completion prose still collapses to the
+    // milestone-level status even when other phases remain open — this guard
+    // demotes it back. Phase-level prose must never decide milestone-level
+    // status — completedPhases / totalPhases / diskScope, already derived above
+    // from a disk scan, are the authority on whether the MILESTONE is actually
+    // done. Only override when: (a) normalizeStateStatus actually landed on
+    // 'completed'; (b) the raw prose is UNAMBIGUOUSLY phase-completion prose —
+    // the anchored pattern below deliberately excludes "All phases complete"
+    // (no `\S+` phase token) and milestone-close prose like "v1.0 milestone
+    // complete" (no leading "phase"); and (c) the counters are trustworthy (a
+    // COMPLETE disk scope, both counts are finite numbers, and a positive
     // denominator) and affirmatively disagree with 'completed'. In every
     // other case normalizedStatus is left exactly as normalizeStateStatus
     // returned it.
@@ -2483,12 +3036,21 @@ function readStateHeadFreshness(cwd, stateHead) {
  * instead of being clobbered by the on-disk phase-directory count.
  */
 function readStoredTotalPhases(existingFm) {
+    return readStoredProgressCounter(existingFm, 'total_phases');
+}
+/**
+ * #4094: the three sibling readers of readStoredTotalPhases, one per progress
+ * counter the #3354/#3573 withhold now protects. All four counters come from
+ * the same disk-scan walk and are withheld together; these readers feed the
+ * stored-value fallback for the three that previously had none.
+ */
+function readStoredProgressCounter(existingFm, key) {
     if (!existingFm || typeof existingFm !== 'object')
         return null;
     const progress = existingFm['progress'];
     if (!progress || typeof progress !== 'object')
         return null;
-    const raw = progress['total_phases'];
+    const raw = progress[key];
     if (raw === null || raw === undefined)
         return null;
     if (typeof raw === 'string' && raw.trim() === '')
@@ -2496,6 +3058,84 @@ function readStoredTotalPhases(existingFm) {
     const n = Number(raw);
     return Number.isFinite(n) ? n : null;
 }
+function readStoredCompletedPhases(existingFm) {
+    return readStoredProgressCounter(existingFm, 'completed_phases');
+}
+function readStoredTotalPlans(existingFm) {
+    return readStoredProgressCounter(existingFm, 'total_plans');
+}
+function readStoredCompletedPlans(existingFm) {
+    return readStoredProgressCounter(existingFm, 'completed_plans');
+}
+/**
+ * #4129: is this authoritativeFm value a PARTIAL progress intent? The #2736
+ * seam was string-only (names); #4129 extends it with one object direction —
+ * the `progress` key carrying the sub-keys a transition resolved
+ * authoritatively (completePhase's ROADMAP-derived completed_phases/percent).
+ * Anything else keeps the seam's existing contract untouched.
+ */
+function isPartialProgressIntent(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * #4129: merge a PARTIAL progress intent (see isPartialProgressIntent) into a
+ * frontmatter object's `progress` block. Sub-keys are accepted only when they
+ * are a declared `progress.*` row in FIELD_CLASSIFICATION — the single policy
+ * source (ADR-3408 §8.5) decides which leaves exist; an intent may not invent
+ * one. Returns whether anything changed.
+ *
+ * `completedOnlyRaise` (both application sites use it): completed counters
+ * apply only when strictly greater than what is already in the block, so no
+ * intent can LOWER a count another trustworthy signal already established —
+ * at the pre-preservation site the disk derivation's own count (a
+ * verification-passed phase whose ROADMAP row drifted behind), at the
+ * post-preservation re-assert the #2969 monotonic property preservation just
+ * enforced. `percent` follows its sibling: it is applied when a completed
+ * counter moved this call (the intent percent was computed from the intent
+ * counters and is coherent with them) or when the block has no percent to
+ * lose (a repair, never a regression of an upstream withhold — the withhold
+ * nulled percent upstream precisely so no write would re-assert one over
+ * untrustworthy counts; here the intent's own counts ARE the trustworthy
+ * source, the post-completion ROADMAP).
+ */
+function applyAuthoritativeProgressSubkeys(fm, intent, opts) {
+    const current = fm['progress'];
+    const base = isPartialProgressIntent(current)
+        ? { ...current }
+        : {};
+    let changed = false;
+    let completedMoved = false;
+    for (const [subkey, value] of Object.entries(intent)) {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            continue;
+        if (!getFieldClassification(`progress.${subkey}`))
+            continue;
+        const isCompletedCounter = subkey === 'completed_phases' || subkey === 'completed_plans';
+        if (isCompletedCounter && opts.completedOnlyRaise) {
+            const currentNum = (0, state_document_cjs_1.toFiniteNumber)(base[subkey]);
+            if (currentNum !== null && currentNum >= value)
+                continue;
+        }
+        if (isCompletedCounter && !Object.is(base[subkey], value))
+            completedMoved = true;
+        if (!Object.is(base[subkey], value)) {
+            base[subkey] = value;
+            changed = true;
+        }
+    }
+    // percent: applied only when a completed counter moved (coherent with the
+    // counters that just landed) or when no percent exists to contradict.
+    const intentPercent = intent['percent'];
+    if (typeof intentPercent === 'number' && Number.isFinite(intentPercent) && (completedMoved || (0, state_document_cjs_1.toFiniteNumber)(base['percent']) === null)) {
+        if (!Object.is(base['percent'], intentPercent)) {
+            base['percent'] = intentPercent;
+            changed = true;
+        }
+    }
+    if (changed)
+        fm['progress'] = base;
+    return changed;
+}
 function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanentEmptyFallback) {
     // Read existing frontmatter BEFORE stripping — it may contain values
     // that the body no longer has (e.g., Status field removed by an agent).
@@ -2533,7 +3173,7 @@ function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanent
     // milestoned-but-unbounded withhold can preserve it across the write
     // (the derived progress sub-block replaces the stored one wholesale below,
     // so an omitted key would otherwise DELETE the stored value).
-    const derivedFm = buildStateFrontmatter(body, cwd, storedMilestone, readStoredTotalPhases(existingFm));
+    const derivedFm = buildStateFrontmatter(body, cwd, storedMilestone, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm));
     // Preserve existing frontmatter status when body-derived status is 'unknown'.
     // This prevents a missing Status: field in the body from overwriting a
     // previously valid status (e.g., 'executing' → 'unknown').
@@ -2701,11 +3341,22 @@ function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanent
     // parenthetical (`Closer-ruling measurement (D1a)` → `D1a`) — never runs
     // the final word on a field the transition just resolved. The prose parser
     // remains the fallback for genuinely unknown prose only.
+    // #4129: the `progress` key carries a PARTIAL block (the object direction of
+    // this seam — see applyAuthoritativeProgressSubkeys) for the same reason:
+    // completePhase holds the POST-completion ROADMAP, and the disk scan this
+    // function drives reads the PRE-completion one. The intent is applied as a
+    // FLOOR here too (completedOnlyRaise): a derivation that already counted
+    // MORE completed phases than the ROADMAP table asserts (verification-passed
+    // phases whose table rows drifted behind) must not be lowered by the intent
+    // — the two signals agree on direction (up), never on subtraction.
     if (authoritativeFm) {
         for (const [key, value] of Object.entries(authoritativeFm)) {
             if (typeof value === 'string' && value.trim().length > 0) {
                 derivedFm[key] = value;
             }
+            else if (key === 'progress' && isPartialProgressIntent(value)) {
+                applyAuthoritativeProgressSubkeys(derivedFm, value, { completedOnlyRaise: true });
+            }
         }
     }
     // #3257: propagate full-line frontmatter comments from the extracted source onto the
@@ -3282,6 +3933,10 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
     // (equal), so the #1695 restore fires and would put the stale pre-transition
     // name back over the authoritative one. Intent beats both the prose
     // re-derivation and the curated restore — the transition just resolved it.
+    // #4129: for the `progress` key the re-assert is a FLOOR, not an override —
+    // the #2969 monotonic property preservation just enforced (completed
+    // counters never move down) must not be undone by the intent, so completed
+    // sub-keys apply only-raise here (see applyAuthoritativeProgressSubkeys).
     let authoritativeReasserted = false;
     if (authoritativeFm) {
         for (const [key, value] of Object.entries(authoritativeFm)) {
@@ -3289,8 +3944,14 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
                 preservation.postFm[key] = value;
                 authoritativeReasserted = true;
             }
+            else if (key === 'progress' && isPartialProgressIntent(value)) {
+                if (applyAuthoritativeProgressSubkeys(preservation.postFm, value, { completedOnlyRaise: true })) {
+                    authoritativeReasserted = true;
+                }
+            }
         }
     }
+    let finalContent = syncedContent;
     if (preservation.mutated || authoritativeReasserted) {
         // #3742: preservation RESTORES frontmatter keys the body-derived rebuild
         // could not produce (e.g. `current_phase` on a layout with no body
@@ -3311,9 +3972,15 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
         }
         const yamlStr = reconstructFrontmatter(preservation.postFm);
         const body = stripFrontmatter(syncedContent);
-        return `---\n${yamlStr}\n---\n\n${body}`;
+        finalContent = `---\n${yamlStr}\n---\n\n${body}`;
+    }
+    const persistedPercent = (0, state_document_cjs_1.toFiniteNumber)(preservation.postFm['progress'] && preservation.postFm['progress']['percent']);
+    if (persistedPercent !== null) {
+        const reconciled = stateReplaceProgressPercent(finalContent, persistedPercent);
+        if (reconciled !== null)
+            finalContent = reconciled;
     }
-    return syncedContent;
+    return finalContent;
 }
 /**
  * ADR-3408 §8.3 — the ONE write-seam composition: `syncStateFrontmatter` then
@@ -3858,7 +4525,7 @@ function cmdStateJson(cwd, raw) {
     // reports the phase-directory count while the persisted file preserves the
     // stored total, exactly the write/read divergence #3354 closed for its shape.
     const storedMilestoneJson = typeof existingFm['milestone'] === 'string' ? existingFm['milestone'] : null;
-    const built = buildStateFrontmatter(body, cwd, storedMilestoneJson, readStoredTotalPhases(existingFm));
+    const built = buildStateFrontmatter(body, cwd, storedMilestoneJson, readStoredTotalPhases(existingFm), readStoredCompletedPhases(existingFm), readStoredTotalPlans(existingFm), readStoredCompletedPlans(existingFm));
     // ADR-3408 §8.5 / D3: route stopped_at / paused_at / status / current_phase /
     // current_phase_name / current_plan through the SAME `preserve-when-unchanged`
     // executor the write path uses (`applyPreserveWhenUnchanged`), instead of a
@@ -3947,6 +4614,26 @@ function cmdStateJson(cwd, raw) {
  * Fixes: #1102 (plan counts), #1103 (status/last_activity), #1104 (body text).
  */
 function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
+    // #4138: `--phase` is this verb's one required argument, and an invocation
+    // that names no phase must fail closed BEFORE any read-modify-write runs —
+    // previously the missing flag flowed through as null and the transition
+    // serialised `String(null)` into the body (`Phase: null — EXECUTING`,
+    // `Status: Executing Phase null`, `last_activity_desc: Phase null execution
+    // started`) while the post-sync frontmatter rebuild dropped current_phase /
+    // current_phase_name entirely, so a single argument-less call un-set the
+    // phase identity. The guard mirrors the sibling usage errors that already
+    // exit non-zero (`state update`'s "field and value required", the router's
+    // "unexpected positional argument" / "Invalid --plans value"), NOT
+    // `cmdStateMilestoneSwitch`'s `output({error})` form, which exits 0 — the
+    // issue's Expected is explicit: "Exit non-zero with a usage message and
+    // write nothing." Empty and whitespace-only values are the same missing
+    // argument (CONTRIBUTING.md CLI matrix); a flag-shaped `--phase --name x`
+    // resolves to null in parseNamedArgs and lands here too. Runs before the
+    // STATE.md existence check so argument validation always precedes I/O, and
+    // before claimMilestonePhase so no phase-"null" milestone claim is taken.
+    if (phaseNumber == null || String(phaseNumber).trim() === '') {
+        error('phase required (--phase <N>)');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -3960,7 +4647,11 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     // #1230 post-sync preservation, and the no-op write guard.
     const intent = {
         kind: 'beginPhase',
-        phaseNumber,
+        // The guard above made this non-null/non-empty; `error` is never-returning
+        // at runtime but this module's destructured io binding does not narrow CFA,
+        // so the narrowed fact is restated once (cmdStateUpdate's `field as string`
+        // idiom, state.cts:782).
+        phaseNumber: phaseNumber,
         phaseName: phaseName ?? null,
         planCount: planCount ?? null,
     };
@@ -4256,6 +4947,12 @@ function updatePerformanceMetricsSection(content, cwd, phaseNum, planCount, summ
  * Updates Status to "Ready to execute", Total Plans, Last Activity.
  */
 function cmdStatePlannedPhase(cwd, phaseNumber, phaseName, planCount, raw) {
+    // #4383: mirror begin-phase's command-boundary guard. A missing phase must
+    // fail before even looking up STATE.md so no invalid invocation can enter
+    // the read-modify-write path and serialize a null/blank phase identity.
+    if (phaseNumber == null || String(phaseNumber).trim() === '') {
+        error('phase required (--phase <N>)');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -4271,7 +4968,7 @@ function cmdStatePlannedPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     // still owns the lock, the #1230 preservation, and the no-op write guard.
     const intent = {
         kind: 'plannedPhase',
-        phaseNumber,
+        phaseNumber: phaseNumber,
         phaseName: phaseName ?? null,
         planCount: planCount ?? null,
     };
@@ -4558,10 +5255,28 @@ function cmdStateValidate(cwd, raw, opts = {}) {
         emit({ valid: false, warnings, scope });
         return;
     }
+    // #612: #3208 replaced this lookup's `startsWith` prefix test with the
+    // canonical key comparison — which is the right surface, and is exactly why it
+    // now needs the convention. `phaseKeyFromDir` refuses to read a bracket
+    // directory without an explicit signal (a bracket dir is string-
+    // indistinguishable from the legacy letter-prefixed-decimal family, ADR-2121),
+    // so un-threaded it returns the WHOLE dir name as the key —
+    // `GSD.02-05-delta` -> `GSD.02-5-DELTA` — while `selectedPhaseKey` is the bare
+    // `05` that `parsePhaseFromProse` yields. The two sides of one comparison were
+    // derived under different conventions, which is #2562's defect class and the
+    // thing this file's other three `phaseKeyFromDir` call sites already thread
+    // against. Un-threaded, a bracket repo whose phase directory plainly exists
+    // reports `no phase directory matches phase 05` and `valid: false` — a
+    // wrong-and-confident answer on precisely the repos this convention supports.
+    // Resolved here rather than reusing a caller's value because cmdStateValidate
+    // has no other convention-dependent read. Non-bracket conventions (null,
+    // 'milestone-prefixed', unresolvable) are byte-identical to the un-threaded
+    // call by construction: `extractPhaseToken` branches only on `=== 'bracket'`.
+    const validateConvention = resolvePhaseIdConvention(cwd);
     let phaseDirPath;
     try {
         const entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true });
-        const phaseDir = entries.find(entry => entry.isDirectory() && phaseKeyFromDir(entry.name) === selectedPhaseKey);
+        const phaseDir = entries.find(entry => entry.isDirectory() && phaseKeyFromDir(entry.name, validateConvention) === selectedPhaseKey);
         if (!phaseDir) {
             warnings.push(stateDiagnostic('S004', SEVERITY.WARNING, `Cannot validate phase drift: no phase directory matches phase ${currentPhase}`, 'Create a phase directory matching the current phase or correct current_phase'));
             emit({ valid: false, warnings, scope });
@@ -4609,7 +5324,10 @@ function cmdStateValidate(cwd, raw, opts = {}) {
         // ("verification passed" drift), not a false S007.
         const files = node_fs_1.default.readdirSync(phaseDirPath);
         const phaseDirBaseName = node_path_1.default.basename(phaseDirPath);
-        const verificationFiles = scopeToPhase(files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md')), phaseDirBaseName);
+        // #612: `validateConvention` threaded (already resolved above for
+        // `phaseKeyFromDir`) so the S006/S007 scan scopes bracket dirs by
+        // their real token instead of the include-everything fail-safe.
+        const verificationFiles = scopeToPhase(files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md')), phaseDirBaseName, validateConvention);
         for (const vf of verificationFiles) {
             try {
                 const vContent = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDirPath, vf), 'utf-8');
@@ -4730,22 +5448,51 @@ function cmdStateSync(cwd, options, raw) {
     let syncRoadmapScope = null;
     let syncRoadmapRaw = null;
     let syncRetiredPhaseNums = new Set();
+    const syncConvention = resolvePhaseIdConvention(cwd);
     try {
         const roadmapRaw = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(planningDir(cwd), 'ROADMAP.md'));
         if (roadmapRaw !== null) {
             syncRoadmapRaw = roadmapRaw;
             syncRoadmapScope = extractCurrentMilestone(roadmapRaw, cwd);
-            syncRetiredPhaseNums = extractRetiredPhaseNumbers(syncRoadmapScope);
+            syncRetiredPhaseNums = extractRetiredPhaseNumbers(syncRoadmapScope, syncConvention);
         }
     }
     catch { /* fall through: no roadmap scope → no retired exclusion */ }
+    // #2761 Major 1 (round-2 adversarial review): this disk scan fed
+    // totalDiskPlans/totalDiskSummaries/diskCompletedPhases/syncTotalPhases
+    // below UNFILTERED — no milestone-window filter, unlike
+    // buildStateFrontmatter's identical-purpose scan a few hundred lines above
+    // (`:1698`). One command (`state sync`) therefore wrote TWO contradictory
+    // numbers into the same STATE.md: frontmatter total_phases/completed_phases
+    // milestone-scoped correctly (via the READ derivation), body Progress
+    // percent computed from the whole disk. On the ADR-canonical version-less
+    // bracket fixture (4 dirs, 3 complete; asserted milestone = 2 phases, both
+    // complete): body wrote 75% where 100% is true (repro3).
+    //
+    // GATED on `syncConvention === 'bracket'` — an unconditional filter would
+    // ALSO move LEGACY sync percents, since the milestone-scoping-vs-whole-disk
+    // divergence this fixes is engine-wide, not bracket-specific; the gate
+    // keeps legacy byte-identical, which is the binding constraint here. This
+    // is a DEVIATION from an earlier "mirror :1698 unconditionally" phrasing —
+    // deliberate, not an oversight: legacy repos are DOWNSTREAM of a Progress
+    // percent that has read this way for a long time, and moving it as a side
+    // effect of a bracket-only PR is out of this fix's scope.
+    // Upstream #3185 made `listMilestonePhaseDirs` the sole phase-directory
+    // enumeration owner; it delegates window membership to
+    // getMilestonePhaseFilter. Cache that owner's bracket result as a set and
+    // compose it with this scan, rather than restoring the retired direct
+    // parser dependency. Legacy retains this scan's prior pass-all behavior.
+    const syncMilestonePhaseDirs = syncConvention === 'bracket'
+        ? new Set(listMilestonePhaseDirs(phasesDir, { cwd, phaseIdConvention: syncConvention }).value)
+        : null;
     // Scan all phases
     let entries;
     try {
         entries = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
             .filter(e => e.isDirectory())
             .map(e => e.name)
-            .filter(name => !(syncRetiredPhaseNums.size > 0 && syncRetiredPhaseNums.has(phaseKeyFromDir(name))))
+            .filter(name => !(syncRetiredPhaseNums.size > 0 && syncRetiredPhaseNums.has(phaseKeyFromDir(name, syncConvention))))
+            .filter(name => syncMilestonePhaseDirs === null || syncMilestonePhaseDirs.has(name))
             .sort();
     }
     catch {
@@ -4771,7 +5518,10 @@ function cmdStateSync(cwd, options, raw) {
         // was a second, independent consumer of the same raw field the initial
         // migration missed — without it, `state sync` and `state json` disagreed
         // on completed_phases for the identical disk state.
-        if (isPhaseComplete(dirPath).value.complete)
+        // #612: `syncConvention` threaded — the write-side half of
+        // buildStateFrontmatter's thread above, so `state sync` and `state json`
+        // keep agreeing on completed_phases under the bracket convention.
+        if (isPhaseComplete(dirPath, { convention: syncConvention }).value.complete)
             diskCompletedPhases++;
         // Track the highest phase with incomplete plans (or any plans)
         const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));
@@ -4793,28 +5543,18 @@ function cmdStateSync(cwd, options, raw) {
         }
     }
     // Determine total phases from ROADMAP (may be larger than realized disk dirs).
-    // Mirrors the logic in buildStateFrontmatter so both report consistent percents (#3242 Bug B).
-    // DEAD catch removed (#2245 audit): every operation in this block is a regex
-    // exec/test over an already-read string plus pure Set/Math ops — none of
-    // which can throw — so the try/catch could never be triggered.
+    // #612 round-4: shares countRoadmapPhaseHeadings with buildStateFrontmatter
+    // (defined just above extractRetiredPhaseNumbers) so both report
+    // consistent totals off the SAME implementation, not two independently
+    // maintained copies (#3242 Bug B).
+    // #612 round-5: bracket sync enables the same bare-token 999 exclusion as
+    // the read path and getMilestonePhaseFilter, preventing frontmatter/body
+    // disagreement. Non-bracket conventions still pass false, preserving the
+    // pre-existing legacy sync behavior while #3185 remains the read-path owner.
     let syncTotalPhases = null;
-    let roadmapPhaseCount = 0;
-    if (syncRoadmapScope !== null) {
-        // #1729: `(?:\s*\([^)\n]{0,200}\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
-        const phaseHeadingPattern = /#{2,4}\s*Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]{0,200}\))?\s*:/gi;
-        let m;
-        while ((m = phaseHeadingPattern.exec(syncRoadmapScope)) !== null) {
-            // Only count tokens that contain at least one digit — excludes
-            // pure-word section headings (Overview, Details) while keeping
-            // numeric phases (01, 05.1) and project-code IDs (PROJ-42).
-            if (!/\d/.test(m[1]))
-                continue;
-            // #1514: retired/folded phases are struck through; exclude from total.
-            if (syncRetiredPhaseNums.has(phaseKeyFromToken(m[1])))
-                continue;
-            roadmapPhaseCount++;
-        }
-    }
+    const roadmapPhaseCount = syncRoadmapScope !== null
+        ? countRoadmapPhaseHeadings(syncRoadmapScope, syncConvention, syncRetiredPhaseNums, syncConvention === 'bracket')
+        : 0;
     if (roadmapPhaseCount > 0) {
         syncTotalPhases = Math.max(entries.length, roadmapPhaseCount);
     }
@@ -4834,8 +5574,9 @@ function cmdStateSync(cwd, options, raw) {
     if (versionStr !== null && syncRoadmapRaw !== null) {
         // #3184: routed through the single owner (roadmap-parser.cjs) instead of
         // a hand-rolled, unbounded-substring re-derivation — see the identical
-        // fix in buildStateFrontmatter above.
-        milestoneBounded = isMilestoneBoundedInRoadmap(syncRoadmapRaw, versionStr);
+        // fix in buildStateFrontmatter above. #612 composes its gated bracket
+        // extension on top inside isMilestoneBounded.
+        milestoneBounded = isMilestoneBounded(syncRoadmapRaw, versionStr, syncConvention);
     }
     let percent = null;
     if (!milestoneBounded) {
@@ -4853,6 +5594,20 @@ function cmdStateSync(cwd, options, raw) {
         // it here (discarding `.value`, which duplicates `entries`'s own
         // retired-phase-filtered listing) gets the real scope without changing
         // the disk-scan totals computed above.
+        //
+        // #2761 (round-11 M2 follow-up): deliberately NOT threading
+        // `phaseIdConvention` here, unlike the other call sites this same PR
+        // converts. Only `.scope` is consumed (the `.value` directory list is
+        // thrown away), and inside `getMilestonePhaseFilter` `scope` is computed
+        // from `extractCurrentMilestoneScoped`/`classifyMilestoneWindow` BEFORE
+        // `headingConvention` is resolved — `phaseIdConvention` only reaches the
+        // heading/dir MEMBERSHIP scan (`scanMilestonePhaseIds`, `isDirInMilestone`)
+        // that produces `.value`, never the scope discriminator itself. So the
+        // `undefined` default here (lazy resolve-from-config) and an explicitly
+        // threaded `syncConvention` would compute the identical `scope` either
+        // way — there is no silent-inherit exposure to close at this site, only
+        // at sites (milestone.cts, cmdStateUpdateProgress above) that also
+        // consume `.value`.
         const syncScope = listMilestonePhaseDirs(phasesDir, { cwd, versionOverride: versionStr }).scope;
         if (syncScope !== SCOPE.COMPLETE) {
             changes.push(`Progress: skipped — milestone phase scope is "${syncScope}", not COMPLETE (#3217)`);