@opengsd/gsd-core 1.10.0 → 1.11.0

package/gsd-core/bin/lib/workstream-inventory-builder.cjs

@@ -16,30 +16,23 @@ exports.pickRollupWinners = pickRollupWinners;
 exports.isCompletedInventory = isCompletedInventory;
 exports.buildWorkstreamInventory = buildWorkstreamInventory;
 const node_path_1 = __importDefault(require("node:path"));
+const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 // Internal helpers
 function toPosixPath(p) {
     return p.split('\\').join('/');
 }
-/**
- * #2562: verification verdicts that DISQUALIFY a phase from `complete`, even
- * when its SUMMARY count meets its PLAN count. Deliberately scoped to the two
- * EXPLICIT failing verdicts the verifier emits — `missing`/`unknown` (verifier
- * off / not yet run) and `stale` (mtime-derived, #2348) are intentionally left
- * untouched so verifier-disabled projects do not regress to never-complete.
- *
- * #2645: `'unrecorded'` is NOT a verdict the verifier itself ever emits — it
- * is an internal sentinel `workstream-inventory.cts`'s verification-deletion
- * ledger substitutes for `'missing'` once that workstream has ADOPTED the
- * ledger (a `.verification-ledger.json` file exists for it) but has no
- * remembered entry for this specific phase. Pre-adoption (no ledger file at
- * all) still resolves to plain `'missing'`, which stays OUTSIDE this set —
- * that is what keeps a project untouched by this fix until it actually uses
- * the verifier at least once. Post-adoption, an unrecorded phase fails
- * CLOSED (counted here) rather than open, so a corrupt or evidence-absent
- * ledger entry can no longer be read as "safe to complete" the way a bare
- * `'missing'` sentinel is.
- */
-const FAILING_VERIFICATION_STATUSES = new Set(['gaps_found', 'human_needed', 'unrecorded']);
+// #2562/#2645's FAILING_VERIFICATION_STATUSES set (the verdicts that used to
+// disqualify a phase from `complete` when combined with a local
+// summary-count-meets-plan-count check) was removed by ADR-3180 §7.4
+// (#3186): `complete` is now the single canonical owner's verdict
+// (`PhaseFilesCount.complete`, computed via `isPhaseComplete` by the
+// I/O-capable caller — see the loop below), which already requires
+// `verification.status === 'passed'` unconditionally. Disk-strict (#2957)
+// deliberately DROPS the prior "verifier-disabled projects fall back to
+// summaries-met" tolerance that set existed to preserve — a phase with no
+// `*-VERIFICATION.md` (`missing`) is no longer treated as complete just
+// because its summaries meet its plan count. Disclosed in this phase's
+// changeset.
 /**
  * #2562 / Bug #2445 / #2645 review: pick ONE winning item per key from a
  * PRE-SORTED list — newest `mtimeMs` wins; on an exact tie the incumbent
@@ -127,11 +120,20 @@ function buildWorkstreamInventory(inputs) {
         const counts = countsMap.get(dir);
         const planCount = counts?.planCount ?? 0;
         const summaryCount = counts?.summaryCount ?? 0;
-        // #2562: SUMMARY≥PLAN parity is necessary but not sufficient — a phase whose
-        // verification verdict is an explicit failing one is still in progress.
-        const verificationStatus = counts?.verificationStatus ?? 'missing';
-        const summariesMeetPlans = summaryCount >= planCount && planCount > 0;
-        const status = summariesMeetPlans && !FAILING_VERIFICATION_STATUSES.has(verificationStatus)
+        // ADR-3180 §7.4 (issue #3186): routed through the single canonical owner
+        // (`isPhaseComplete`, src/verification.cts) — via `PhaseFilesCount.complete`,
+        // which the I/O-capable CALLER computes (this module is a PURE, I/O-free
+        // projection — see the module header: "No I/O. No async." — and cannot
+        // call the owner itself). The prior local derivation
+        // (`summaryCount >= planCount && planCount > 0` combined with a
+        // caller-supplied verification status) was this module's OWN completion
+        // verdict computed from raw counts — the exact "post-process a canonical
+        // result locally" bypass §7.4 rules out, and it reproduced the disk-strict
+        // headline case (#3168): a zero-plan phase with a passing verification
+        // read `pending` instead of `complete`. `complete` defaults to `false`
+        // when absent so a caller that has not been updated to pass it never
+        // silently reads as complete.
+        const status = (counts?.complete ?? false)
             ? 'complete'
             : planCount > 0
                 ? 'in_progress'
@@ -243,12 +245,31 @@ function buildWorkstreamInventory(inputs) {
         roadmap_phase_count: effectivePhaseCount,
         total_plans: totalPlans,
         completed_plans: completedPlans,
-        // The `Math.min` cap is unreachable under milestone scoping (the invariant
-        // above throws first) and survives only for the legacy unscoped path, where
-        // the denominator is a roadmap heading count that a caller cannot guarantee
-        // bounds the numerator.
-        progress_percent: effectivePhaseCount > 0
-            ? Math.min(100, Math.round((completedPhases / effectivePhaseCount) * 100))
-            : 0,
+        // `clampPercent`'s 100 ceiling is unreachable under milestone scoping (the
+        // invariant above throws first) and matters only for the legacy unscoped
+        // path, where the denominator is a roadmap heading count that a caller
+        // cannot guarantee bounds the numerator.
+        //
+        // #3217 (ADR-3180 §7.6 rule 4) — WRITTEN REASON this site is NOT migrated
+        // onto the `SCOPE` enum this phase: `buildWorkstreamInventory` is a pure
+        // projection (no I/O — see the module header) fed `BuildWorkstreamInventoryInputs`
+        // by `workstream-inventory.cts`. Its own `milestoneScoped` is a pre-ADR-3180
+        // bespoke boolean, not a `SCOPE` value, and its caller does not currently
+        // thread a real `listMilestonePhaseDirs` scope into these inputs. Doing
+        // this honestly requires ONE of: (a) widening `BuildWorkstreamInventoryInputs`
+        // with a `Scope` field and `WorkstreamInventory.progress_percent`'s type
+        // from `number` to `number | null` — the exact "re-architecting
+        // StateProjection/WorkstreamInventory return types" the design phase
+        // (`.gsd/phase/refactor-3217-completion-ratio-scoping/40-design.md`,
+        // "Known limits") states is OUT of this phase's scope; or (b) silently
+        // reusing `milestoneScoped` as a `Scope` stand-in, which would be exactly
+        // the kind of proxy-for-a-data-flow-property this same phase's guard
+        // section explicitly rejects (a `boolean` cannot distinguish TRUNCATED
+        // from UNSCOPED from UNREADABLE, so a caller could not tell which
+        // non-answer it got). Left un-migrated rather than done dishonestly;
+        // `workstream inventory`'s `progress_percent` can still render a number
+        // derived from an under-scoped set (A8 in the phase's test matrix is
+        // NOT covered here for that reason — see this phase's PR description).
+        progress_percent: (0, phase_lifecycle_cjs_1.clampPercent)(completedPhases, effectivePhaseCount),
     };
 }

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -27,10 +27,13 @@ const planScan = require("./plan-scan.cjs");
 const planningWorkspace = require("./planning-workspace.cjs");
 const { planningPaths, planningRoot, getActiveWorkstream } = planningWorkspace;
 const state_document_cjs_1 = require("./state-document.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- frontmatter.cjs is an export= CommonJS module
+const frontmatterMod = require("./frontmatter.cjs");
+const { extractFrontmatter, stripFrontmatter } = frontmatterMod;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
-const { readVerificationStatus } = verificationMod;
+const { isPhaseComplete } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
 const { phaseKeyFromDir, phaseKeyFromProse, parentPhaseKey } = phaseIdMod;
@@ -42,11 +45,28 @@ const workstream_inventory_builder_cjs_1 = require("./workstream-inventory-build
 function workstreamsRoot(cwd) {
     return node_path_1.default.join(planningRoot(cwd), 'workstreams');
 }
-function countRoadmapPhases(roadmapPath, fallbackCount) {
+/**
+ * #3185 (ADR-3180 Decision 1): count the phases the CURRENT milestone
+ * declares, not every `Phase` heading in the file.
+ *
+ * This previously matched `^#{2,4}\s+Phase\s+…` across the whole ROADMAP with
+ * no milestone window and no sentinel filter, so it counted 999.* backlog and
+ * Phase 0 headings and spanned every milestone the document had ever had.
+ * `getMilestonePhaseFilter` already computes exactly this number for the
+ * scoped window (`phaseCount`, sentinel-filtered), and `inspectWorkstream` in
+ * this same file already passes a resolved `currentVersion` to it — this
+ * function was the sibling copy that never got the fix.
+ */
+function countRoadmapPhases(roadmapPath, fallbackCount, cwd, ws, versionOverride) {
     try {
-        const roadmapContent = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
-        const matches = roadmapContent.match(/^#{2,4}\s+Phase\s+[\w][\w.-]*/gm);
-        return matches ? matches.length : fallbackCount;
+        if (!node_fs_1.default.existsSync(roadmapPath))
+            return fallbackCount;
+        if (!cwd)
+            return fallbackCount;
+        const filter = getMilestonePhaseFilter(cwd, versionOverride ?? null, null, ws ?? null);
+        // A pass-all degrade (phaseCount 0) means the window declared no phases —
+        // fall back rather than reporting a confident zero.
+        return filter.phaseCount > 0 ? filter.phaseCount : fallbackCount;
     }
     catch {
         return fallbackCount;
@@ -312,13 +332,30 @@ function writeVerificationLedger(wsDir, ledger) {
 function readStateProjection(statePath) {
     try {
         const stateContent = node_fs_1.default.readFileSync(statePath, 'utf-8');
+        // #3187: route Status/Current Phase/Last Activity through the single
+        // #1760 fallback-chain owner (state-document.cjs's stateFieldValue)
+        // instead of a frontmatter-blind stateExtractField(stateContent, …) call,
+        // mirroring cmdStateValidate/cmdStateSnapshot — a STATE.md whose fields
+        // live only in frontmatter is no longer projected as absent here.
+        const fm = extractFrontmatter(stateContent, statePath);
+        const body = stripFrontmatter(stateContent);
         return {
-            status: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Status') || 'unknown',
-            current_phase: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Current Phase'),
-            last_activity: (0, state_document_cjs_1.stateExtractField)(stateContent, 'Last Activity'),
+            status: (0, state_document_cjs_1.stateFieldValue)(fm, body, 'status', 'Status').value || 'unknown',
+            current_phase: (0, state_document_cjs_1.stateFieldValue)(fm, body, 'current_phase', 'Current Phase').value,
+            last_activity: (0, state_document_cjs_1.stateFieldValue)(fm, body, 'last_activity', 'Last Activity').value,
         };
     }
     catch {
+        // Read/parse failure (missing file, permission fault, etc.) degrades to
+        // an all-unknown projection — unchanged. Not widened to also carry a
+        // `scope` here: doing so would ripple `StateProjection`
+        // (workstream-inventory-builder.cjs) and every consumer of this
+        // read-only rollup — the design doc's blast-radius table rates
+        // `readStateProjection` "low"/Tier-2, and this call site's migration is
+        // scoped to routing the fallback chain, not to widening the return type.
+        // The existing all-unknown degrade already distinguishes "could not
+        // read" from any real field value; only its scope-vs-absence *reason*
+        // stays uncaptured, same as before this change.
         return {
             status: 'unknown',
             current_phase: null,
@@ -483,7 +520,16 @@ function inspectWorkstream(cwd, name, options = {}) {
     const rawPhaseEntries = [...phaseDirNames].sort().map(dir => {
         const phaseDir = node_path_1.default.join(p.phases, dir);
         const counts = countPhaseFiles(phaseDir);
-        const verificationResult = readVerificationStatus(phaseDir);
+        // ADR-3180 §7.4 (#3186): routed through the single canonical owner
+        // (`isPhaseComplete`, src/verification.cts) instead of calling
+        // `readVerificationStatus` directly and re-deriving "is this phase
+        // complete" locally from its `.status`. `completionResult.value.complete`
+        // is threaded down to the builder below (as `PhaseFilesCount.complete`)
+        // so `buildWorkstreamInventory` — a pure, I/O-free projection that
+        // cannot call the owner itself — consumes the owner's verdict rather
+        // than re-deriving a second one from summary/plan counts.
+        const completionResult = isPhaseComplete(phaseDir);
+        const verificationResult = completionResult.value.verification;
         // #3057 B3: routing is UNCHANGED — `liveVerificationStatus` below is still
         // `.status`, exactly as before, so the ledger/rollup logic that consumes
         // it is unaffected. This only makes an indeterminate staleness check
@@ -502,6 +548,12 @@ function inspectWorkstream(cwd, name, options = {}) {
             summaryCount: counts.summaryCount,
             inMilestone: isDirInCurrentMilestone(dir),
             liveVerificationStatus: verificationResult.status,
+            // ADR-3180 §7.4 (#3186): the owner's verdict, read live off disk — never
+            // ledger-adjusted (see the phaseFilesCounts map below; the ledger only
+            // ever substitutes a 'missing' status with a remembered one, and under
+            // disk-strict neither 'missing' nor 'unrecorded' is ever complete, so
+            // there is nothing for the ledger to override here).
+            complete: completionResult.value.complete,
         };
     });
     // #2645: only the directory Bug #2445's de-dup rollup would actually pick
@@ -573,6 +625,7 @@ function inspectWorkstream(cwd, name, options = {}) {
             summaryCount: entry.summaryCount,
             inMilestone: entry.inMilestone,
             verificationStatus,
+            complete: entry.complete,
         };
     });
     // The denominator is the union of what the roadmap DECLARES for the current
@@ -592,7 +645,7 @@ function inspectWorkstream(cwd, name, options = {}) {
     // declares in its Progress table but never scaffolded — the heading-only
     // count drops them, even when other headings exist. Union the declared rows
     // with the phase directories so neither source can silently shrink it.
-    let fallbackPhaseCount = countRoadmapPhases(p.roadmap, phaseDirNames.length);
+    let fallbackPhaseCount = countRoadmapPhases(p.roadmap, phaseDirNames.length, cwd, name, currentVersion);
     if (!scoped && progressRows.length > 0) {
         const union = new Set(progressRows.map(row => row.key));
         for (const entry of phaseFilesCounts)

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

@@ -134,8 +134,8 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
             }
             else {
                 try {
-                    const milestone = getMilestoneInfo(cwd);
-                    existingWsName = generateSlugInternal(milestone.name) || 'default';
+                    const milestone = getMilestoneInfo(cwd).value;
+                    existingWsName = generateSlugInternal(milestone?.name ?? null) || 'default';
                 }
                 catch {
                     existingWsName = 'default';

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -366,13 +366,24 @@ function normalizeCleanupManifestEntry(entry) {
         return null;
     const rawAllowedBases = Array.isArray(e.allowed_bases) ? e.allowed_bases : [];
     const allowedBases = Array.from(new Set([expectedBase, ...rawAllowedBases.filter((base) => typeof base === 'string' && base.length > 0)]));
-    return {
+    // #2596: liberal in what we accept — non-array, or non-string / empty
+    // elements, are dropped rather than coerced. An EMPTY result omits the field
+    // entirely, so "declared nothing" is indistinguishable from "not recorded":
+    // that ambiguity is already resolved as *unknown* by the per-plan submodule
+    // gate's own `[ -z "$PLAN_FILES" ]` rule, and inventing a second rule here
+    // would make an unrecorded plan look 100% out of scope.
+    const filesModified = (Array.isArray(e.files_modified) ? e.files_modified : [])
+        .filter((f) => typeof f === 'string' && f.trim().length > 0);
+    const normalized = {
         agent_id: typeof e.agent_id === 'string' ? e.agent_id : null,
         worktree_path: worktreePath,
         branch,
         expected_base: expectedBase,
         allowed_bases: allowedBases,
     };
+    if (filesModified.length > 0)
+        normalized.files_modified = filesModified;
+    return normalized;
 }
 function normalizeCleanupManifest(manifest) {
     let parsed = manifest;
@@ -461,6 +472,39 @@ function repoRootStillMidMerge(execGit, repoRoot) {
         return false; // ref not found — repoRoot is not mid-merge
     return true; // any other exit code (e.g. a fatal git error) — fail closed
 }
+// #2596: the single definition of "this file is an executor-written SUMMARY
+// artifact". Shared by `defaultFindSummaryFiles` (which walks for them to
+// rescue) and the scope advisory below (which must never flag them) — a plan's
+// declared `files_modified` never lists a SUMMARY, because the executor writes
+// it by orchestration contract, so a second copy of this rule would make the
+// advisory fire on essentially every wave.
+const SUMMARY_ARTIFACT_DIR = '.planning';
+const SUMMARY_ARTIFACT_SUFFIX = 'SUMMARY.md';
+/**
+ * Normalize one path for scope comparison. Applied to BOTH sides so a declared
+ * path and a git-reported path meet in the same shape: backslashes become
+ * slashes unconditionally (a backslash path is not a Windows-only input),
+ * a leading `./` and any trailing `/` are stripped. This is the single
+ * normalizer shared by the SUMMARY-artifact predicate and the scope advisory,
+ * so the two can never disagree about what `./a\b/` means.
+ */
+function normalizeScopePath(raw) {
+    return String(raw || '')
+        .replace(/\\/g, '/')
+        .trim()
+        .replace(/^\.\//, '')
+        .replace(/\/+$/, '');
+}
+/**
+ * True when a worktree-relative path is a SUMMARY artifact. Input may use
+ * either separator; normalization to POSIX is unconditional (backslash paths
+ * reach Linux too).
+ */
+function isSummaryArtifactRelPath(relPath) {
+    const normalized = normalizeScopePath(relPath);
+    return normalized.startsWith(`${SUMMARY_ARTIFACT_DIR}/`)
+        && normalized.endsWith(SUMMARY_ARTIFACT_SUFFIX);
+}
 /**
  * Walk <worktreePath>/.planning/ recursively and collect absolute paths of
  * all files whose names match *SUMMARY.md.  Returns [] when the directory
@@ -470,7 +514,7 @@ function repoRootStillMidMerge(execGit, repoRoot) {
  *   find "$WT/.planning" -name "*SUMMARY.md"
  */
 function defaultFindSummaryFiles(worktreePath) {
-    const planningDir = node_path_1.default.join(worktreePath, '.planning');
+    const planningDir = node_path_1.default.join(worktreePath, SUMMARY_ARTIFACT_DIR);
     const results = [];
     function walk(dir) {
         let entries;
@@ -485,7 +529,7 @@ function defaultFindSummaryFiles(worktreePath) {
             if (entry.isDirectory()) {
                 walk(full);
             }
-            else if (entry.isFile() && entry.name.endsWith('SUMMARY.md')) {
+            else if (entry.isFile() && entry.name.endsWith(SUMMARY_ARTIFACT_SUFFIX)) {
                 results.push(full);
             }
         }
@@ -588,6 +632,77 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
     }
     return { rescuedRelPaths, failures };
 }
+/**
+ * #2596: advisory codes emitted by the wave-cleanup gauntlet. Frozen and
+ * exported so tests assert on a code rather than on rendered prose (this repo
+ * forbids raw-text matching on test output).
+ */
+const WAVE_CLEANUP_WARNING = Object.freeze({
+    /** A committed path fell outside the plan's declared `files_modified`. */
+    SCOPE_OUT_OF_DECLARED: 'scope_out_of_declared',
+    /** The scope diff could not be computed, so conformance is unknown. */
+    SCOPE_CHECK_UNAVAILABLE: 'scope_check_unavailable',
+});
+/**
+ * The literal directory prefix a declared path covers, or `null` when the
+ * pattern begins with a glob metacharacter and therefore has no usable prefix.
+ *
+ * Deliberately literal-prefix only — NOT a glob engine. A hand-rolled
+ * `**`/`*`/`?` matcher inside a worktree-lifecycle module is an informal,
+ * undocumented pattern language living where no language belongs, and this
+ * repo forbids external deps in core. The submodule-intersection gate
+ * (`workflows/execute-phase/steps/per-plan-worktree-gate.md`) already ships
+ * exactly this glob-prefix rule; reusing it beats inventing a second one.
+ *
+ * `null` (no literal prefix, e.g. `*.md`) means "matches everything": for an
+ * ADVISORY, a false alarm costs more than a miss, so the ambiguous case
+ * suppresses rather than shouts.
+ */
+function declaredScopePrefix(declared) {
+    const globAt = declared.search(/[*?[]/);
+    if (globAt < 0)
+        return declared;
+    const literal = declared.slice(0, globAt).replace(/\/+$/, '');
+    return literal.length > 0 ? literal : null;
+}
+/**
+ * #2596: compare a branch's actual committed paths against the plan's declared
+ * scope. Pure — no git, no IO. Returns one warning per out-of-scope path, in
+ * the order the paths were given. Returns [] when nothing usable was declared:
+ * absence of data is not evidence of over-reach.
+ */
+function planWaveScopeConformance(changedPaths, declaredFiles, branch) {
+    if (!Array.isArray(declaredFiles))
+        return [];
+    const prefixes = [];
+    for (const declared of declaredFiles) {
+        if (typeof declared !== 'string')
+            continue;
+        const normalized = normalizeScopePath(declared);
+        if (!normalized)
+            continue;
+        prefixes.push(declaredScopePrefix(normalized));
+    }
+    if (prefixes.length === 0)
+        return [];
+    const warnings = [];
+    const seen = new Set();
+    for (const raw of Array.isArray(changedPaths) ? changedPaths : []) {
+        if (typeof raw !== 'string')
+            continue;
+        const changed = normalizeScopePath(raw);
+        if (!changed || seen.has(changed))
+            continue;
+        seen.add(changed);
+        if (isSummaryArtifactRelPath(changed))
+            continue;
+        const covered = prefixes.some((prefix) => (prefix === null || changed === prefix || changed.startsWith(`${prefix}/`)));
+        if (covered)
+            continue;
+        warnings.push({ code: WAVE_CLEANUP_WARNING.SCOPE_OUT_OF_DECLARED, branch, path: changed });
+    }
+    return warnings;
+}
 function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
     const execGit = deps.execGit || execGitDefault;
     const entries = Array.isArray(plan?.entries) ? plan.entries : [];
@@ -598,10 +713,12 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             reason: plan ? (plan.reason || 'missing_entries') : 'missing_plan',
             entries: [],
             pending: entries,
+            warnings: [],
         };
     }
     const results = [];
     const pending = [];
+    const allWarnings = [];
     let ok = true;
     // #2852: every per-entry failure site marks the SAME shape — status='blocked',
     // a reason code, the captured stderr, push to results, flip the overall `ok`
@@ -622,6 +739,7 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             status: 'pending',
             reason: null,
             stderr: '',
+            warnings: [],
         };
         const branchCheck = execGit(['-C', entry.worktree_path, 'rev-parse', '--abbrev-ref', 'HEAD'], { cwd: plan.repoRoot });
         if (!gitResultOk(branchCheck) || branchCheck.stdout.trim() !== entry.branch) {
@@ -652,6 +770,25 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             blockEntry(result, 'branch_contains_deletions', deletions.stdout);
             continue; // #2852: isolate
         }
+        // #2596: advisory scope conformance — does the branch's ACTUAL committed
+        // diff stay inside the scope the plan declared? Gated on a declared scope
+        // being present: with nothing declared there is nothing to compare, so no
+        // git subprocess is spent at all (and every pre-#2596 fixture, none of
+        // which declares one, issues exactly the git calls it always did).
+        //
+        // ADVISORY ONLY. Unlike the deletions check above, a finding here does NOT
+        // call blockEntry and does NOT touch `ok` — the merge proceeds. Promotion
+        // to a hard gate is a separate, disclosed change.
+        if (Array.isArray(entry.files_modified) && entry.files_modified.length > 0) {
+            const scopeDiff = execGit(['diff', '--name-only', `HEAD...${entry.branch}`], { cwd: plan.repoRoot });
+            const scopeWarnings = !gitResultOk(scopeDiff)
+                // A broken advisory must never become a gate: record that conformance
+                // is unknown rather than blocking (or, worse, silently passing).
+                ? [{ code: WAVE_CLEANUP_WARNING.SCOPE_CHECK_UNAVAILABLE, branch: entry.branch, path: null }]
+                : planWaveScopeConformance((scopeDiff.stdout || '').split('\n'), entry.files_modified, entry.branch);
+            result.warnings.push(...scopeWarnings);
+            allWarnings.push(...scopeWarnings);
+        }
         // Safety net: rescue uncommitted SUMMARY.md artifacts before the dirty check.
         // The executor leaves <quick_id>-SUMMARY.md uncommitted by contract — the
         // orchestrator commits it.  Mirrors quick.md shell fallback (#2296, #2070, #2838, #3804).
@@ -737,6 +874,7 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
         reason: ok ? 'ok' : 'cleanup_blocked',
         entries: results,
         pending,
+        warnings: allWarnings,
     };
 }
 function cmdWorktreeCleanupWave(cwd, args = []) {
@@ -777,6 +915,15 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
         process.exitCode = 1;
     }
 }
+/**
+ * #2596: split a `--files` value into declared paths. Whitespace-separated,
+ * matching the `PLAN_FILES` shape the per-plan worktree gate already builds
+ * with `jq -r '.files_modified // [] | join(" ")'`. Values are DATA compared
+ * against a diff — never opened, never passed to a shell.
+ */
+function parseDeclaredScopeFlag(raw) {
+    return String(raw || '').split(/\s+/).filter((token) => token.length > 0);
+}
 /**
  * Pure planner for the per-agent wave-manifest append.
  *
@@ -793,8 +940,9 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
  * rejected loudly — the reader dedups on that key, so a re-record would be
  * silently dropped (the failure mode this verb exists to eliminate). The
  * on-disk shape stays the existing 4-field entry (`agent_id`, `worktree_path`,
- * `branch`, `expected_base`) — no schema change; the reader re-derives
- * `allowed_bases`.
+ * `branch`, `expected_base`) unless `--files` declares a scope, in which case
+ * an optional `files_modified` is appended (#2596); the reader still
+ * re-derives `allowed_bases`.
  */
 function planWorktreeRecordAgent(manifestRaw, fields) {
     // 1. Write-strict required-field check (loud, with which flag is missing).
@@ -824,11 +972,13 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
     }
     // 2. Shared validation: run the candidate through the reader's normalizer.
     //    If it returns null the reader would drop this entry on read — reject now.
+    const declaredScope = parseDeclaredScopeFlag(fields.files);
     const candidate = {
         agent_id: agentId,
         worktree_path: worktreePath,
         branch,
         expected_base: base,
+        ...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
     };
     const entry = normalizeCleanupManifestEntry(candidate);
     if (!entry) {
@@ -917,6 +1067,11 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
         branch: entry.branch,
         expected_base: entry.expected_base,
     };
+    // #2596: only written when a scope was actually declared — conservative in
+    // what we send, so a blank --files leaves the 4-field shape untouched.
+    if (entry.files_modified && entry.files_modified.length > 0) {
+        recorded.files_modified = entry.files_modified;
+    }
     worktrees.push(recorded);
     return {
         ok: true,
@@ -928,7 +1083,7 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
 /**
  * CLI command: append a validated per-agent entry to a wave cleanup manifest.
  *
- * Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha>
+ * Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"]
  *
  * Fails loudly (non-zero exit + recovery hint on stderr) when a field is
  * missing/garbled or the manifest is absent/malformed, rather than appending an
@@ -943,7 +1098,7 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
     const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
     const manifestPath = flag('--manifest');
     if (!manifestPath) {
-        writeErr('Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha>\n');
+        writeErr('Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"]\n');
         process.exitCode = 2;
         return { ok: false, reason: 'usage', entry: null };
     }
@@ -965,6 +1120,7 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
         worktreePath: flag('--path'),
         branch: flag('--branch'),
         base: flag('--base'),
+        files: flag('--files'),
     });
     if (!plan.ok || plan.manifest === null) {
         writeErr(`[gsd] worktree.record-agent: ${plan.reason} — ${plan.hint || ''}\n`);
@@ -1008,11 +1164,13 @@ function planWorktreeCreate(fields) {
             entry: null,
         };
     }
+    const declaredScope = parseDeclaredScopeFlag(fields.files);
     const candidate = {
         agent_id: agentId,
         worktree_path: worktreePath,
         branch,
         expected_base: base,
+        ...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
     };
     const entry = normalizeCleanupManifestEntry(candidate);
     if (!entry) {
@@ -1140,7 +1298,7 @@ function executeWorktreeCreatePlan(plan, repoRoot, deps = {}) {
  * validated manifest entry so the worktree is immediately manageable by
  * `worktree cleanup-wave` / `worktree reap-orphans`.
  *
- * Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir>
+ * Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"]
  *
  * #2584 FIX 1 — ORDERING CONTRACT: every manifest read/parse/shape-validate/
  * plan step runs BEFORE the git side effect (step 5). The ONLY manifest
@@ -1160,7 +1318,7 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
     const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
     const manifestPath = flag('--manifest');
     if (!manifestPath) {
-        writeErr('Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir>\n');
+        writeErr('Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"]\n');
         process.exitCode = 2;
         return { ok: false, reason: 'usage' };
     }
@@ -1225,6 +1383,7 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         worktreePath: flag('--path'),
         branch: flag('--branch'),
         base: flag('--base'),
+        files: flag('--files'),
     });
     if (!plan.ok || !plan.entry) {
         writeErr(`[gsd] worktree.create: ${plan.reason} — ${plan.hint || ''}\n`);
@@ -1291,6 +1450,11 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         branch: plan.entry.branch,
         expected_base: plan.entry.expected_base,
     };
+    // #2596: only written when a scope was actually declared — conservative in
+    // what we send, so a blank --files leaves the 4-field shape untouched.
+    if (Array.isArray(plan.entry.files_modified) && plan.entry.files_modified.length > 0) {
+        recorded.files_modified = plan.entry.files_modified;
+    }
     const dedupeKey = `${recorded.worktree_path}\0${recorded.branch}`;
     const alreadyPresent = worktrees.some((existing) => {
         const normalized = normalizeCleanupManifestEntry(existing);
@@ -1677,6 +1841,9 @@ module.exports = {
     normalizeCleanupManifest,
     planWorktreeWaveCleanup,
     executeWorktreeWaveCleanupPlan,
+    WAVE_CLEANUP_WARNING,
+    planWaveScopeConformance,
+    isSummaryArtifactRelPath,
     cmdWorktreeCleanupWave,
     planWorktreeRecordAgent,
     cmdWorktreeRecordAgent,

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -28,6 +28,7 @@
     "verifier": true,
     "nyquist_validation": true,
     "ai_integration_phase": true,
+    "agent_hint_routing": true,
     "human_verify_mode": "end-of-phase",
     "auto_advance": false,
     "_auto_chain_active": false,

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -35,6 +35,7 @@
     "workflow.plan_chunked",
     "workflow.specless_probe_fallback",
     "workflow.plan_review_convergence",
+    "workflow.agent_hint_routing",
     "code_quality.fallow.enabled",
     "code_quality.fallow.scope",
     "code_quality.fallow.profile",
@@ -180,7 +181,12 @@
     {
       "topLevel": "model_policy",
       "source": "^model_policy\\.runtime_tiers\\.[a-zA-Z0-9_-]+\\.(opus|sonnet|haiku)$",
-      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku>"
+      "description": "model_policy.runtime_tiers.<runtime>.<opus|sonnet|haiku> (#3587)"
+    },
+    {
+      "topLevel": "phase_commit_docs",
+      "source": "^phase_commit_docs\\.\\d+[A-Z]?(?:\\.\\d+)*$",
+      "description": "phase_commit_docs.<phase-id> — per-phase commit_docs override (#3587). The <phase-id> segment is a hand-copy of the canonical PHASE_NUMBER_TOKEN_SOURCE grammar owned by src/phase-id.cts (#2128); this manifest is hand-maintained JSON so it cannot import that constant. Pinned against drift by the behavioral parity test in tests/commit-docs-bypass.test.cjs (folded 'phase-commit-docs' block, describe block 'E', #3587) — do not hand-edit this pattern without updating that test."
     }
   ]
 }