refactor(#3186): one shared phase-completion predicate, disk-strict (#3306)

* docs(#3186): record the disk-strict completion decision in ADR-3180 7.4

The maintainer decided #2957 on 2026-08-08: disk state is authoritative and a
ROADMAP checkbox is a human annotation with no machine authority. Section 7.4
still carried the OPEN QUESTION and was marked blocked, so the contract said one
thing and the tracker another.

Recorded per section 7's own rule - a behavior not stated there is not decided,
and amending a rule is an ADR amendment rather than a code change with a comment.
The decision comment names Phase 4's PR as the carrier of this edit and makes it
an acceptance criterion that the text be in the tree before implementation
begins, so this lands first, alone, ahead of any code.

Also clears the stale blocked-on-2957 row in the guard roster.

* refactor(#3186): one shared phase-completion predicate, disk-strict

isPhaseComplete in verification.cts becomes the single owner. It calls
readVerificationStatus UNCONDITIONALLY - plan count is not a precondition - so a
zero-plan phase with a passing VERIFICATION.md is complete. That is #3168: init
gated the read on a plan count and synthesized a not_required sentinel, so
phase.complete succeeded while init.manager reported incomplete for the same
phase.

The guard, built and run before scope was fixed per Amendment 3, found 9
re-derivations where the ADR named 3. Four were unnamed, including one in the
prompt layer: mvp-phase.md ORed a ticked checkbox with disk status, which under
disk-strict is the divergence itself.

Per the #2957 decision, a ticked ROADMAP checkbox is a human annotation with no
machine authority. The overrides in roadmap analyze and init manager are deleted
rather than generalized; the user's checkbox stays in ROADMAP.md, only its
authority goes.

scanPhasePlans.completed and buildWorkstreamInventory are deliberately NOT folded
- they answer 'are all plans summarized', which is a different question, and
folding them would either over-report completion or invert the dependency
direction between Phase 1's owner and this one.

Verified on the remote runner.

* fix(#3186): close seven review findings and record the missing-verdict rule

The isolated review reproduced a write-path regression I introduced: migrating
cmdRoadmapUpdatePlanProgress dropped its summaryCount>=planCount gate, so a phase
with a fresh passing verification plus a newly-added unsummarized plan reported
complete AND wrote a checkbox into ROADMAP.md while phase complete refused. The
owner stays right per 7.4 - plan count is not a completion precondition - so the
gate is restored at the write site as an explicit composition, mirroring the
separate 2648 unexecuted-plan gate cmdPhaseComplete already carries.

The spec axis was right that my 0.x-split reasoning was too permissive. The 2957
decision names buildStateFrontmatter as one of the three that must converge, and
buildWorkstreamInventory combined a summaries-met local with verification data to
decide the same verdict - Decision 4(c)'s named bypass, and it reproduced 3168 in
a third surface. Both now route through the owner. The raw scanPhasePlans helper
stays: it answers are-plans-summarized, which genuinely is a different question.

Maintainer decision recorded in 7.4: a missing verdict is not a passing one, so
an absent VERIFICATION.md means not complete everywhere. That retires 2645's
verifier-disabled tolerance and inverts its Goodhart incentive - deleting the
evidence now lowers completion instead of raising it.

Guard hardened: block-form count gates and algebraic restatements are caught, and
the header now discloses its remaining limits instead of overclaiming.

Verified on the remote runner.

* fix(#3186): route state sync through the owner and catch bare completed reads

The matrix found 52 failures. 51 were fixtures asserting the old semantics: a
phase with plans and summaries but no VERIFICATION.md used to count complete and
correctly no longer does. Each fixture now carries a passing verification where
that is what the test was actually about, rather than having its assertion
weakened.

The 52nd was a real 10th re-derivation the guard could not see. cmdStateSync
destructured scanPhasePlans().completed directly - a bare field read, not a
comparison - and used it as a completion verdict, so state sync and state json
disagreed on completed_phases for identical disk state. Routed through the owner.

Guard gains shape (d): any read of .completed off a scanPhasePlans() result
outside plan-scan.cts, in chained, destructured and indirect forms, function
scoped with no line window. It cannot tell a summaries-met read from a completion
read - that is data flow - so it flags every one and requires a written-reason
exemption, which is the same discipline shapes a-c already use. The blind spot is
disclosed in the header rather than overclaimed.

The emitted-attribution failure was also mine, not pre-existing: the mvp-phase.md
checkbox-OR removal moves emitted bytes, acknowledged in tests/emitted-drift-acks.

Verified on the remote runner.

* test(#3186): give the nested-plans sync fixture a passing verification

Last 3 matrix failures were one failure echoing up two describe levels. Phase
01-alpha had plans and summaries but no VERIFICATION.md, so under disk-strict
completed stayed 0 and no Progress change was emitted - correct new behavior, not
a regression.

Added the passing verification rather than dropping the Progress expectation, so
the test still covers what #3257 is about: that a nested plans/ layout is counted
and not undercounted. Probe against the built lib confirms
Progress: 0% -> 50% alongside Total Plans in Phase: 0 -> 3.

* chore(#3186): backfill changeset PR number

pr:0 placeholder replaced with the real number now that #3306 exists.

---------

Co-authored-by: sim <sim@local>

src/roadmap.cts

@@ -32,13 +32,13 @@ const { planningPaths, withPlanningLock, findContextMdIn } = planningWorkspace;
 import scanPhasePlans = require('./plan-scan.cjs');
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import coreUtils = require('./core-utils.cjs');
-const { countMatchedSummaries } = coreUtils;
+const { countMatchedSummaries, findUnsummarizedPlans } = coreUtils;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import frontmatter = require('./frontmatter.cjs');
 const { extractFrontmatter, parseMustHavesBlock } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 import verificationMod = require('./verification.cjs');
-const { readVerificationStatus } = verificationMod;
+const { isPhaseComplete } = verificationMod;
 
 // ─── Types ────────────────────────────────────────────────────────────────────
 
@@ -411,7 +411,14 @@ function cmdRoadmapAnalyze(cwd: string, raw: boolean): void {
       hasContext = counts.hasContext;
       hasResearch = counts.hasResearch;
 
-      if (summaryCount >= planCount && planCount > 0) diskStatus = 'complete';
+      // ADR-3180 §7.4 (issue #3186, disk-strict, #3168 fix): route "is this
+      // phase complete" through the canonical owner (`isPhaseComplete`),
+      // which calls readVerificationStatus UNCONDITIONALLY — plan count is
+      // NOT a precondition, so a zero-plan phase with a passing
+      // `*-VERIFICATION.md` reports complete here too, not just via
+      // `phase.complete`.
+      const completionResult = isPhaseComplete(path.join(phasesDir, dirMatch));
+      if (completionResult.value.complete) diskStatus = 'complete';
       else if (summaryCount > 0) diskStatus = 'partial';
       else if (planCount > 0) diskStatus = 'planned';
       else if (hasResearch) diskStatus = 'researched';
@@ -419,21 +426,24 @@ function cmdRoadmapAnalyze(cwd: string, raw: boolean): void {
       else diskStatus = 'empty';
     }
 
-    // Check ROADMAP checkbox status.
-    // #3537: padding-tolerant fragment — the heading discovered above may use
-    // a different padding than the summary-bullet checkbox below it (mixed
-    // padding inside one ROADMAP is legal and seen in real projects).
+    // Check ROADMAP checkbox status. #3537: padding-tolerant fragment — the
+    // heading discovered above may use a different padding than the
+    // summary-bullet checkbox below it (mixed padding inside one ROADMAP is
+    // legal and seen in real projects).
+    //
+    // ADR-3180 §7.4 (disk-strict, #2957, maintainer decision 2026-08-08):
+    // `roadmapComplete` is reported below as metadata ONLY — it carries NO
+    // machine authority over `diskStatus`. The override that used to trust a
+    // ticked checkbox over disk file structure is DELETED, not generalized
+    // (#2957: "a ticked ROADMAP checkbox is a human annotation with no
+    // machine authority"). A phase marked complete solely by a ticked
+    // checkbox — no passing `*-VERIFICATION.md`, plans outstanding — now
+    // reports incomplete; this is the deliberate Tier-2 break (ADR-3180 §7.4
+    // Decision 3).
     const checkboxPattern = new RegExp(`-\\s*\\[(x| )\\]\\s*.*Phase\\s+${phaseMarkdownRegexSource(phaseNum)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
     const checkboxMatch = content.match(checkboxPattern);
     const roadmapComplete = checkboxMatch ? checkboxMatch[1] === 'x' : false;
 
-    // If roadmap marks phase complete, trust that over disk file structure.
-    // Phases completed before GSD tracking (or via external tools) may lack
-    // the standard PLAN/SUMMARY pairs but are still done.
-    if (roadmapComplete && diskStatus !== 'complete') {
-      diskStatus = 'complete';
-    }
-
     phases.push({
       number: phaseNum,
       name: phaseName,
@@ -570,10 +580,34 @@ function cmdRoadmapUpdatePlanProgress(cwd: string, phaseNum: string | null | und
   // completion date until the phase's verification status is 'passed', matching
   // cmdPhaseComplete's gate (phase.cts:1436). Previously the checkbox fired the
   // moment the last plan summary landed — before gsd-verifier had verified.
+  //
+  // ADR-3180 §7.4 (issue #3186, disk-strict): routed through the canonical
+  // owner (`isPhaseComplete`) instead of hand-rolling `summaryCount >=
+  // planCount && verificationPassed` locally — the owner calls
+  // readVerificationStatus UNCONDITIONALLY, so `isComplete` here always
+  // agrees with `roadmap analyze` / `init manager` / `phase complete` for
+  // the same phase (ADR-3180 §7.4's headline: one predicate for the read
+  // path and the write path).
   const phaseDir = path.join(cwd, phaseInfo!.directory);
-  const verificationResult = readVerificationStatus(phaseDir);
-  const verificationPassed = verificationResult.status === 'passed';
-  const isComplete = summaryCount >= planCount && verificationPassed;
+  const completionResult = isPhaseComplete(phaseDir);
+  const verificationResult = completionResult.value.verification;
+  // #2648 precedent, applied at this write site (ADR-3180 §7.4 / #3186):
+  // `isPhaseComplete` deliberately carries NO plan-count precondition — the
+  // owner's `complete` is exactly `verification.status === 'passed'`, and
+  // that must stay true (disk-strict: a zero-plan phase with a passing
+  // `*-VERIFICATION.md` IS complete, #3168). But `readVerificationStatus`'s
+  // staleness check only compares SUMMARY mtimes against the verification
+  // file — it has no idea a NEW plan was added after the file was written,
+  // so a still-fresh `passed` verification says nothing about a plan added
+  // afterward. This command WRITES a checkbox and a completion date into
+  // ROADMAP.md, a materially stronger claim than "verification passed" —
+  // mirroring cmdPhaseComplete's own fail-closed plan-coverage gate
+  // (phase.cts:~1995, #2648: "a coverage gate that passes when it cannot
+  // read the plans is no gate at all"), composed explicitly here rather than
+  // folded into the predicate: complete AND all plans executed.
+  const coverageScan = scanPhasePlans(phaseDir);
+  const unsummarizedPlans = findUnsummarizedPlans(coverageScan.planFiles, coverageScan.summaryFiles);
+  const isComplete = completionResult.value.complete && unsummarizedPlans.length === 0;
   // #3057 B3: routing above is unchanged (an indeterminate staleness check
   // still routes as if nothing were stale) — this only makes the fact visible
   // to whatever reads this command's JSON output.