@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/bin/lib/planning-snapshot.cjs

@@ -41,7 +41,15 @@ const planningWorkspace = require("./planning-workspace.cjs");
 // `phase_id_convention` reader, from the same §7 owner module `planningPaths`
 // comes from. Resolved once in `buildPlanningSnapshot` — see the
 // `phaseIdConvention` field's comment for why one resolution point matters.
-const { planningPaths, planningRoot, resolvePhaseIdConvention } = planningWorkspace;
+// #4257: `resolveEnvWorkstream` is that same module's ONE owner of the env
+// workstream discriminator `planningDir` applies — the name W002's scope
+// clause prints comes from the same resolution point that scoped the reads.
+const { planningPaths, planningRoot, resolvePhaseIdConvention, resolveEnvWorkstream } = planningWorkspace;
+// #4257: canonical CommonMark code strippers (markdown-sectionizer is the
+// repo's T0 structural seam, adopted per the #2365 composition order — fenced
+// blocks first, then inline spans) so the `statePhaseTokens` harvest sees
+// PROSE, not quoted literals.
+const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatterMod = require("./frontmatter.cjs");
@@ -109,9 +117,12 @@ function worstScope(...scopes) {
  * uncorrelated (isPhaseComplete's readability check never re-derives or
  * requires scanPhasePlans, and vice versa).
  */
-function buildPhaseSnapshot(phasesDir, dir) {
+function buildPhaseSnapshot(phasesDir, dir, convention) {
     const fullPhaseDir = node_path_1.default.join(phasesDir, dir);
-    const completionResult = isPhaseComplete(fullPhaseDir);
+    // #612: the snapshot's single federated convention resolution rides into
+    // completion, so a bracket phase dir resolves and scopes its verification
+    // report exactly like its legacy twin.
+    const completionResult = isPhaseComplete(fullPhaseDir, { convention });
     const scanResult = scanPhasePlans(fullPhaseDir);
     return {
         dir,
@@ -160,9 +171,11 @@ function buildPhaseSnapshot(phasesDir, dir) {
  *   a whole-body fallback, together.
  * - `statePhaseTokens` scans the WHOLE document (`verify.cts`'s exact
  *   `PHASE_NUMBER_TOKEN_SOURCE` regex, relocated verbatim from
- *   `verify.cts:1731-1735`), not just the Current Position section, so it is
- *   NOT degraded to `TRUNCATED` by a missing section header — it stays
- *   `COMPLETE` whenever the file itself was read successfully.
+ *   `verify.cts:1731-1735`; #4257 adds the left word boundary and the
+ *   fenced-block/inline-span strip — see the harvest site's comment), not
+ *   just the Current Position section, so it is NOT degraded to `TRUNCATED`
+ *   by a missing section header — it stays `COMPLETE` whenever the file
+ *   itself was read successfully.
  */
 function buildStateFields(statePath) {
     let content;
@@ -222,7 +235,30 @@ function buildStateFields(statePath) {
         scope: currentPositionScope,
     });
     const statePhaseTokens = {
-        value: [...content.matchAll(new RegExp(`[Pp]hase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})`, 'g'))].map((m) => m[1]),
+        // #4257: harvest PROSE phase references, not every literal token match.
+        // Two precisions over the pre-#4257 verbatim relocation of verify.cts's
+        // scan (which was `[Pp]hase\s+(TOKEN)`, unanchored, over the raw file):
+        //
+        // 1. Strip fenced code blocks, then inline code spans (the #2365
+        //    composition order, via the canonical markdown-sectionizer seam) —
+        //    a token inside backticks is a QUOTED LITERAL (a ledger row quoting
+        //    `` `/gsd-execute-phase 5` `` or `` `- [ ] **Phase 40:` `` from a
+        //    sibling roadmap), not a reference. Pinned tradeoff: a GENUINE
+        //    reference written in backticks stops counting too — a quoted
+        //    literal and a reference are indistinguishable inside a code span.
+        // 2. Left word boundary `(?<![-\w])` — the `-phase 5` tail of GSD's own
+        //    command names (`/gsd-execute-phase 5`, bare or in prose) is a
+        //    command mention, not a reference, and word-suffixed carriers
+        //    (`myphase 5`) never were references. `Phase 5` at line start,
+        //    `**Phase 5:**`, `(Phase 5)`, `[Phase 5]`, and `### Phase 5:` all
+        //    still harvest — the char before `Phase` is not in `[-\w]`.
+        //
+        // Still scans the WHOLE document (frontmatter included — the `Phase: 3`
+        // field syntax never matched, `phase` is followed by a colon, not `\s`),
+        // still `COMPLETE` whenever the file itself was read successfully.
+        value: [
+            ...(0, markdown_sectionizer_cjs_1.stripInlineCode)((0, markdown_sectionizer_cjs_1.stripFencedCode)(content).text).matchAll(new RegExp(`(?<![-\\w])[Pp]hase\\s+(${PHASE_NUMBER_TOKEN_SOURCE})`, 'g')),
+        ].map((m) => m[1]),
         scope: SCOPE.COMPLETE,
     };
     return { currentPhaseLabel, statePhaseTokens, stateStatus };
@@ -632,7 +668,7 @@ function buildRoadmapBracketIncoherencesField(roadmapPath, convention) {
  * deliberate fail-open match to the pre-migration behavior, not a scope
  * degradation, since the original never surfaced these failures either.
  */
-function buildResearchValidationStatusField(phasesDir, phaseDirNames, enumerationScope) {
+function buildResearchValidationStatusField(phasesDir, phaseDirNames, enumerationScope, convention) {
     const value = phaseDirNames.map((dir) => {
         const fullPhaseDir = node_path_1.default.join(phasesDir, dir);
         let files;
@@ -646,7 +682,9 @@ function buildResearchValidationStatusField(phasesDir, phaseDirNames, enumeratio
         // phase-numbered-artifact predicates, so a stray cross-phase
         // -RESEARCH.md/-VALIDATION.md sitting in the wrong directory cannot flip
         // this phase's flags — mirrors core-utils.cts's getPhaseFileStats.
-        const scopedFiles = scopeToPhase(files, dir);
+        // #612: the snapshot's federated convention threaded, so a bracket dir
+        // scopes by its real token instead of the include-everything fail-safe.
+        const scopedFiles = scopeToPhase(files, dir, convention);
         const researchFile = scopedFiles.find((f) => f.endsWith('-RESEARCH.md'));
         const hasValidationMd = scopedFiles.some((f) => f.endsWith('-VALIDATION.md'));
         let hasValidationArchitecture = false;
@@ -963,6 +1001,11 @@ function buildPlanningSnapshot(cwd) {
     // See the `phaseIdConvention` field's comment for why one resolution point is
     // load-bearing rather than a micro-optimisation.
     const phaseIdConvention = resolvePhaseIdConvention(cwd) ?? null;
+    // #4257: the workstream `planningPaths(cwd)` just scoped every read to
+    // (its `planningDir` call applies this exact discriminator when handed no
+    // `ws`), resolved through the same owner so W002's scope clause names the
+    // scope the valid set was ACTUALLY built from.
+    const workstream = resolveEnvWorkstream();
     const milestone = getMilestoneInfo(cwd);
     // #612: deliberately LEFT to `listMilestonePhaseDirs`'s own lazy resolve —
     // this call is byte-identical to upstream's.
@@ -976,9 +1019,14 @@ function buildPlanningSnapshot(cwd) {
     // genuinely differ, and substituting one for the other would silently re-scope
     // `phaseDirs` — a change this PR does not need and no test covers. The
     // federation guarantee PR-2 exists to deliver is delivered where it is
-    // observable: in the rules that read `snapshot.phaseIdConvention`.
+    // observable: in the rules that read `snapshot.phaseIdConvention`. Per-phase
+    // completion and the research/validation scoping below deliberately use the
+    // FEDERATED `phaseIdConvention` (the same value `snapshot.phaseIdConvention`
+    // publishes), while `phaseDirs` keeps `listMilestonePhaseDirs`'s lazy
+    // PROJECT-only resolve — the divergence documented above is unchanged by
+    // this thread. No behavior change.
     const phaseDirs = listMilestonePhaseDirs(paths.phases, { cwd });
-    const phasesValue = phaseDirs.value.map((dir) => buildPhaseSnapshot(paths.phases, dir));
+    const phasesValue = phaseDirs.value.map((dir) => buildPhaseSnapshot(paths.phases, dir, phaseIdConvention));
     const stateFields = buildStateFields(paths.state);
     const allPhaseDirNames = buildAllPhaseDirNamesField(paths.phases);
     const roadmapDeclared = buildRoadmapDeclaredPhasesField(paths.roadmap, phaseIdConvention);
@@ -1001,7 +1049,7 @@ function buildPlanningSnapshot(cwd) {
         stateStatus: stateFields.stateStatus,
         roadmapDeclaredPhases: roadmapDeclared.declared,
         roadmapPhaseCheckboxes: buildRoadmapPhaseCheckboxesField(paths.roadmap, phaseIdConvention),
-        researchValidationStatus: buildResearchValidationStatusField(paths.phases, phaseDirs.value, phaseDirs.scope),
+        researchValidationStatus: buildResearchValidationStatusField(paths.phases, phaseDirs.value, phaseDirs.scope, phaseIdConvention),
         milestoneArchiveStatus: buildMilestoneArchiveStatusField(cwd),
         planningRootFiles: buildPlanningRootFilesField(cwd),
         allPhaseDirNames,
@@ -1013,6 +1061,7 @@ function buildPlanningSnapshot(cwd) {
         phaseIdConvention,
         roadmapSentinelPhaseTokens: roadmapDeclared.sentinelTokens,
         roadmapBracketIncoherences: buildRoadmapBracketIncoherencesField(paths.roadmap, phaseIdConvention),
+        workstream,
     };
 }
 module.exports = {

package/gsd-core/bin/lib/planning-workspace.cjs

@@ -100,11 +100,32 @@ const PLANNING_LOCK_RETRY_ERRNOS = new Set([
     'ENOENT', // Docker overlay-fs: parent dir transiently missing during race
     'ESTALE', // NFS: stale file handle (self-resolves on retry)
 ]);
+/**
+ * #4257: the ONE owner of the env workstream discriminator `planningDir`
+ * itself applies when handed no `ws` argument. `planningPaths(cwd)` — and
+ * therefore every workstream-scoped `PlanningSnapshot` read — resolves its
+ * base through exactly this read, and the CLI bootstrap has already folded
+ * the stored active-workstream pointer into the env by the time any
+ * diagnostic runs (`resolveActiveWorkstream` → `applyResolvedWorkstreamEnv`,
+ * `active-workstream-store.cjs`). Exposed so a consumer that needs to NAME
+ * the scope those reads used (W002's warning message, via the snapshot's
+ * `workstream` field) derives it from the same resolution point instead of
+ * growing a second env read site that can drift (the #612 PR-2
+ * two-readers-two-bases lesson).
+ */
+function resolveEnvWorkstream() {
+    const value = process.env['GSD_WORKSTREAM']?.trim();
+    return value || null;
+}
 function planningDir(cwd, ws, project) {
     if (project === undefined)
-        project = process.env['GSD_PROJECT'] ?? null;
+        project = process.env['GSD_PROJECT']?.trim() || null;
+    else if (typeof project === 'string')
+        project = project.trim() || null;
     if (ws === undefined)
-        ws = process.env['GSD_WORKSTREAM'] ?? null;
+        ws = resolveEnvWorkstream();
+    else if (typeof ws === 'string')
+        ws = ws.trim() || null;
     // Reject path separators and traversal components in project/workstream names
     const BAD_SEGMENT = /[/\\]|\.\./;
     if (project && BAD_SEGMENT.test(project)) {
@@ -171,7 +192,7 @@ function worktreesOptedOutUnguarded(cwd) {
     const scoped = ownKey(readCfg(node_path_1.default.join(planningDir(cwd), 'config.json')));
     if (scoped.present)
         return scoped.value === false;
-    if (process.env['GSD_WORKSTREAM']) {
+    if (resolveEnvWorkstream() !== null) {
         const root = ownKey(readCfg(node_path_1.default.join(planningRoot(cwd), 'config.json')));
         if (root.present)
             return root.value === false;
@@ -284,6 +305,31 @@ function listAvailableWorkstreams(cwd) {
 function quickDirFrom(planningBase) {
     return node_path_1.default.join(planningBase, 'quick');
 }
+// #4256: the todos directory — deliberately ROOT-SCOPED, unlike every other
+// planningPaths key. Todos are shared project state by construction: the
+// migrateToWorkstreams contract keeps them among the shared files that "stay
+// in place" at .planning/todos/ (workstream.cts), and every workflow writer
+// writes that literal cwd-relative root path. The six todos readers
+// previously hand-composed `path.join(planningDir(cwd), 'todos', ...)`,
+// which silently re-scoped to .planning/workstreams/<ws>/todos/ — a
+// directory nothing creates — under a workstream, so todos went invisible
+// and audit-open passed the milestone-close gate vacuously. Same
+// two-composers-of-one-path shape the `debug` (#3149) and `quick` (#2142)
+// keys were introduced to eliminate (DEFECT.GENERATIVE-FIX).
+//
+// Exported as its own function pair (not only as a `planningPaths` key)
+// because `audit.cts`'s `scanTodos`/`cmdAuditAcknowledge` consume an
+// already-resolved todos base rather than a `cwd`, mirroring how #2142
+// exported `quickDirFrom` for `scanQuickTasks`. `todosDir` takes NO ws/project
+// parameter — todos have no workstream- or project-scoped form anywhere, so
+// there is no discriminator to thread. This is also the single root #4327's
+// future filename-containment guard should enforce against.
+function todosDirFrom(planningBase) {
+    return node_path_1.default.join(planningBase, 'todos');
+}
+function todosDir(cwd) {
+    return todosDirFrom(planningRoot(cwd));
+}
 function planningPaths(cwd, ws) {
     const base = planningDir(cwd, ws);
     return {
@@ -300,6 +346,11 @@ function planningPaths(cwd, ws) {
         debug: node_path_1.default.join(base, 'debug'),
         // #2142: quick-task directory, composed via the shared quickDirFrom helper.
         quick: quickDirFrom(base),
+        // #4256: todos directory — deliberately ROOT-scoped while the rest of
+        // this record follows the active workstream/project (todos are shared
+        // project state per the migrateToWorkstreams contract), composed via the
+        // shared todosDir helper so this key and every direct caller agree.
+        todos: todosDir(cwd),
     };
 }
 /**
@@ -567,10 +618,13 @@ module.exports = {
     createMemoryPointerAdapter,
     planningDir,
     planningRoot,
+    resolveEnvWorkstream,
     resolvePhaseIdConvention,
     listAvailableWorkstreams,
     planningPaths,
     quickDirFrom,
+    todosDirFrom,
+    todosDir,
     withPlanningLock,
     getActiveWorkstream,
     peekActiveWorkstream,

package/gsd-core/bin/lib/pr-branch-patterns.cjs

@@ -0,0 +1,57 @@
+"use strict";
+/**
+ * PR-branch `.planning/` path classification patterns — single source of
+ * truth (ADR-4910 §8, epic #4906 Phase 5; issues #4605, #4606).
+ *
+ * `gsd-core/workflows/pr-branch.md` cannot `require()` this module at
+ * runtime — a workflow markdown file has no module system, and its bash
+ * steps are copy-pasted text executed by whatever shell interprets the
+ * workflow. So the three exported constants below are mirrored VERBATIM
+ * into that file's `TRANSIENT_DIRS=`, `STRUCTURAL_RE=`, and
+ * `MILESTONE_PHASES_RE=` bash variable assignments, and
+ * `scripts/lint-pr-branch-pattern-drift.cjs` asserts the mirror never
+ * drifts from this file (compiled to `gsd-core/bin/lib/pr-branch-patterns.cjs`)
+ * as part of `npm run lint:ci`. Change a value here, then update
+ * `gsd-core/workflows/pr-branch.md` to match, or the drift guard fails.
+ *
+ * This module does not read the filesystem and has no dependencies (a leaf
+ * module, mirroring `src/secrets.cts` / `src/planning-scope.cts`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MILESTONE_PHASES_RE_SRC = exports.STRUCTURAL_RE_SRC = exports.TRANSIENT_DIRS_SRC = void 0;
+/**
+ * Space-separated list of `.planning/` subdirectory names that are reviewer
+ * noise (PLAN.md, SUMMARY.md, CONTEXT.md, RESEARCH.md, and friends) —
+ * filtered out of a PR branch in BOTH default and strict mode.
+ *
+ * Mirrored verbatim into `gsd-core/workflows/pr-branch.md`'s
+ * `TRANSIENT_DIRS="..."` assignment.
+ */
+exports.TRANSIENT_DIRS_SRC = 'phases quick research threads todos debug seeds codebase ui-reviews';
+/**
+ * Structural planning files — repository planning state, preserved in
+ * default mode and filtered out in strict mode. Anchored on both
+ * alternatives so `.planning/STATEX.md` and `.planning/STATE.md.bak` are
+ * NOT treated as structural. The `milestones` alternative matches only
+ * FILES directly under `.planning/milestones/` (e.g. `v1.0-ROADMAP.md`) —
+ * not a `<milestone>-phases/` subdirectory nested there. That subdirectory
+ * is reviewer noise, not structural state (#4605); it falls through to
+ * `MILESTONE_PHASES_RE_SRC` below instead.
+ *
+ * Mirrored verbatim into `gsd-core/workflows/pr-branch.md`'s
+ * `STRUCTURAL_RE="..."` assignment.
+ */
+exports.STRUCTURAL_RE_SRC = '^\\.planning/(STATE|ROADMAP|MILESTONES|PROJECT|REQUIREMENTS)\\.md$|^\\.planning/milestones/[^/]+\\.md$';
+/**
+ * Milestone-scoped phase-plan directories — the same reviewer noise as
+ * `TRANSIENT_DIRS_SRC`'s `phases` entry, but nested per-milestone once a
+ * project has passed at least one milestone:
+ * `.planning/milestones/<milestone>-phases/`. The milestone slug (`v1.0`,
+ * `m2`, ...) varies per project, so this is declared as a shape, not a
+ * literal path — a single path segment standing in for the slug, anchored
+ * the same way `STRUCTURAL_RE_SRC`'s alternatives are (#4605).
+ *
+ * Mirrored verbatim into `gsd-core/workflows/pr-branch.md`'s
+ * `MILESTONE_PHASES_RE="..."` assignment.
+ */
+exports.MILESTONE_PHASES_RE_SRC = '^\\.planning/milestones/[^/]+-phases/';

package/gsd-core/bin/lib/pristine-baseline.cjs

@@ -0,0 +1,182 @@
+"use strict";
+/**
+ * #4145: hash-first recovery for gsd-pristine/ baselines stored at an
+ * unexpected path.
+ *
+ * Some installs hold a pristine snapshot whose SHA-256 equals the hash recorded
+ * in backup-meta.json.pristine_hashes for a manifest-keyed file, but at a path
+ * that is not `path.join(pristineDir, relPath)` — e.g. stored without the
+ * `gsd-core/` top-level segment by an earlier release's writer. Both readers
+ * (verify-reapply-patches.cjs verifyFile and install.js saveLocalPatches)
+ * resolved strictly by that join, missed the snapshot, and reported
+ * ok_no_baseline / fell into regeneration that can never satisfy the recorded
+ * outgoing hash — a self-perpetuating gap.
+ *
+ * Hash equality with the recorded pristine_hashes entry is the same authority
+ * the #3657 drift guard already trusts, so a match cannot be the wrong
+ * baseline regardless of which release wrote it or where under gsd-pristine/
+ * it lives. This module owns the shared scan so the two readers cannot drift
+ * apart again (two private strict joins drifting is exactly the bug class).
+ *
+ * ADR-457: runtime module in src/*.cts, compiled to
+ * gsd-core/bin/lib/pristine-baseline.cjs.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sha256File = sha256File;
+exports.findPristineByHash = findPristineByHash;
+exports.findPristineInGit = findPristineInGit;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = __importDefault(require("node:crypto"));
+const node_child_process_1 = require("node:child_process");
+/**
+ * SHA-256 hex digest of a file's raw bytes. Byte-for-byte the same digest
+ * install.js fileHash() records into manifests and backup-meta.json.
+ */
+function sha256File(absPath) {
+    return node_crypto_1.default.createHash('sha256').update(node_fs_1.default.readFileSync(absPath)).digest('hex');
+}
+function walkSorted(dir, relPrefix, results) {
+    let entries;
+    try {
+        entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return; // absent or unreadable — nothing to scan here
+    }
+    entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    for (const entry of entries) {
+        // Never follow symlinks: gsd-pristine/ is installer-authored plain files;
+        // a link here is not a baseline and must not redirect the walk out of the
+        // tree (same posture as migration 004's walker).
+        if (entry.isSymbolicLink())
+            continue;
+        const rel = relPrefix ? `${relPrefix}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            walkSorted(node_path_1.default.join(dir, entry.name), rel, results);
+        }
+        else if (entry.isFile()) {
+            results.push(rel);
+        }
+    }
+}
+/**
+ * Find the first file under `pristineDir` (deterministic sorted walk) whose
+ * SHA-256 equals `recordedHash`, as a pristineDir-relative POSIX path.
+ *
+ * - `skip` is never returned — a single POSIX relPath string or a Set of them.
+ *   Callers pass the canonical path(s) they (or other files in the same run)
+ *   already own, so a file sitting at a canonical path is never adopted
+ *   through the scan. For the installer's relocation this is what prevents a
+ *   byte-identical canonical belonging to ANOTHER modified file from being
+ *   "rescued" away (relocated and deleted at its home path).
+ * - Multiple matches are byte-identical by sha-256 authority; sorted order
+ *   makes the choice deterministic.
+ * - Returns null when pristineDir is absent/unreadable or nothing matches.
+ */
+function findPristineByHash(pristineDir, recordedHash, skip) {
+    if (!pristineDir || typeof recordedHash !== 'string' || recordedHash.length === 0) {
+        return null;
+    }
+    const skipSet = skip instanceof Set ? skip : new Set(skip !== undefined ? [skip] : []);
+    const rels = [];
+    walkSorted(pristineDir, '', rels);
+    for (const rel of rels) {
+        if (skipSet.has(rel))
+            continue;
+        try {
+            if (sha256File(node_path_1.default.join(pristineDir, rel)) === recordedHash) {
+                return rel;
+            }
+        }
+        catch {
+            // unreadable candidate — keep scanning
+        }
+    }
+    return null;
+}
+/**
+ * #4135: recover a pristine baseline from the config dir's OWN git history,
+ * anchored by the recorded pristine_hashes entry.
+ *
+ * The #3407 promotion rule keeps only regeneration candidates byte-identical
+ * across the whole version span, so a multi-version update leaves
+ * gsd-pristine/ holding exactly the files upstream did NOT change — near-zero
+ * coverage precisely where upstream churned the most. On a git-managed config
+ * dir the outgoing bytes often still exist in history (the workflow's
+ * documented Option A), and pristine_hashes is the same authority every other
+ * resolution tier trusts: a blob whose SHA-256 equals the recorded hash cannot
+ * be the wrong baseline. This is read-only recovery (git log / git show only).
+ *
+ * Guarantees:
+ * - Only an EXACT sha-256 match with the recorded hash is ever returned.
+ * - Newest-first commit order (git log default) makes multi-match resolution
+ *   deterministic; byte-identical matches are interchangeable anyway.
+ * - Any failure (git absent, not a repository, empty history, unreadable
+ *   blob, subprocess timeout) yields null — never a throw — so the caller's
+ *   OK_NO_BASELINE posture is the universal fallback.
+ * - The walk is bounded: at most GIT_MAX_COMMITS_PER_FILE commits per file.
+ */
+const GIT_MAX_COMMITS_PER_FILE = 100;
+/** Per-subprocess bound in ms — an unbounded git call is an indefinite hang. */
+const GIT_SUBPROCESS_TIMEOUT_MS = 10_000;
+/** git log --format=%H output cap; 100 full shas are ~4 KB, this is headroom. */
+const GIT_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+function isCleanRelativePosixPath(relPath) {
+    if (!relPath || relPath.startsWith('/') || relPath.includes('\\') || relPath.includes('\0')) {
+        return false;
+    }
+    const segments = relPath.split('/');
+    return segments.every((seg) => seg.length > 0 && seg !== '.' && seg !== '..');
+}
+function gitExec(gitDir, args) {
+    return (0, node_child_process_1.execFileSync)('git', args, {
+        cwd: gitDir,
+        encoding: 'utf8',
+        timeout: GIT_SUBPROCESS_TIMEOUT_MS,
+        maxBuffer: GIT_MAX_BUFFER_BYTES,
+        // windowsHide (#685): a console-window flash per git call would spam the
+        // user on Windows for what is a background, read-only history walk.
+        windowsHide: true,
+        // stderr is discarded: "file absent in commit" is an expected walk outcome,
+        // not operator-visible diagnostics.
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+}
+function findPristineInGit(gitDir, relPath, recordedHash) {
+    if (!gitDir || typeof relPath !== 'string' || typeof recordedHash !== 'string'
+        || recordedHash.length === 0 || !isCleanRelativePosixPath(relPath)) {
+        return null;
+    }
+    let commits;
+    try {
+        const logOutput = gitExec(gitDir, ['log', '--format=%H', '--', relPath]).trim();
+        if (!logOutput)
+            return null;
+        commits = logOutput.split('\n').slice(0, GIT_MAX_COMMITS_PER_FILE);
+    }
+    catch {
+        return null; // git absent, not a repository, or the walk failed
+    }
+    for (const commit of commits) {
+        if (!/^[0-9a-f]{40}$/i.test(commit))
+            continue;
+        try {
+            const blob = gitExec(gitDir, ['show', `${commit}:${relPath}`]);
+            if (sha256String(blob) === recordedHash) {
+                return blob;
+            }
+        }
+        catch {
+            // blob absent in this commit (rename/add boundary) — keep walking
+        }
+    }
+    return null;
+}
+/** sha256 of a utf8 string, matching how manifest hashes are recorded. */
+function sha256String(content) {
+    return node_crypto_1.default.createHash('sha256').update(content, 'utf8').digest('hex');
+}

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

@@ -234,6 +234,12 @@ function analyzeCoverage(items, resolutions = [], validators) {
     const unresolved = merged.filter((i) => i.status === 'unresolved').length;
     const applicable = merged.length;
     const resolved = applicable - unresolved; // closed set: resolved-status + dismissed
+    // #4656: the unclassified soft-signal rows count toward `applicable` (the
+    // rollup is count-preserving and `resolved = applicable - unresolved` is a
+    // documented identity), so the count is exposed as a SIBLING field — the
+    // zero-applicable guards can then also fire when EVERY requirement is
+    // unclassified, the case the spec-phase/ui-phase docs promise to catch.
+    const unclassified = merged.filter((i) => i.category === 'unclassified').length;
     const byVerification = {};
     for (const tier of validators.verification)
         byVerification[tier] = 0;
@@ -242,7 +248,7 @@ function analyzeCoverage(items, resolutions = [], validators) {
             byVerification[i.verification] = (byVerification[i.verification] ?? 0) + 1;
         }
     }
-    return { items: merged, coverage: { applicable, resolved, unresolved, byVerification } };
+    return { items: merged, coverage: { applicable, resolved, unresolved, unclassified, byVerification } };
 }
 /**
  * The prohibition adapter's injected runtime validators (ADR-550 #5). There is no closed

package/gsd-core/bin/lib/prohibition-enforcement.cjs

@@ -362,6 +362,93 @@ function childEnv() {
 const NODE_TEST_TIMEOUT_MS = 30_000;
 const ESLINT_TIMEOUT_MS = 60_000;
 const CHECK_MAX_BUFFER = 16 * 1024 * 1024;
+/** Windows `taskkill` resolved by ABSOLUTE path — never a bare PATH-resolved name. A project
+ * directory used as the child's `cwd` could otherwise contain a planted `taskkill.exe`/`.bat`
+ * that Windows executable resolution picks up ahead of the real one (#3660 review, minor-9).
+ * Returns null (never a hardcoded fallback, per tests/hardcoded-paths.test.cjs) when neither env
+ * var is set -- not expected on a real Windows host (both are set by the OS itself), but a
+ * hostile/stripped env should degrade to "skip the reap" rather than guess a system path. */
+function taskkillPath() {
+    const root = process.env.SystemRoot || process.env.windir;
+    return root ? node_path_1.default.join(root, 'System32', 'taskkill.exe') : null;
+}
+/**
+ * Reap the process TREE rooted at `pid` after THIS call's own bound killed it (#3660: `node --test`
+ * forks a per-file WORKER by default since Node 22 — `execFileSync`'s `timeout` signals only the
+ * direct child/runner, never the worker, which is reparented to PID 1 and can busy-loop forever).
+ *
+ * POSIX: the child was spawned `detached` (its own process group, pgid === pid), so `-pid` addresses
+ * the whole group. ESRCH (group already gone) is swallowed — the subject may have exited on its own
+ * between the timeout firing and this call.
+ *
+ * Windows has no process-group equivalent; `taskkill /PID <pid> /T /F` walks the live process tree by
+ * parent-PID instead, which does not require the parent PID to still be alive. A non-zero exit means
+ * "nothing left to kill" (already gone, or never had descendants) — not a failure, so it is never
+ * escalated; there is no portable stronger primitive to escalate TO.
+ *
+ * Never throws — this runs from a `catch`/`finally` path and must not itself become the error.
+ */
+function reapDescendants(pid) {
+    if (typeof pid !== 'number' || pid <= 0)
+        return; // defensive: never signal pid 0 (self) or negative
+    if (process.platform === 'win32') {
+        const exe = taskkillPath();
+        if (!exe)
+            return; // no safe absolute path available -- best-effort, skip rather than guess
+        try {
+            // 5s bound (DEFECT.UNBOUNDED-SUBPROCESS): a local OS command, not a network call -- if
+            // taskkill itself hangs, this function's own "never throws" contract already treats that
+            // identically to any other failure (swallowed below), so a bounded timeout costs nothing
+            // and just prevents a stuck taskkill from blocking the caller forever.
+            (0, node_child_process_1.spawnSync)(exe, ['/PID', String(pid), '/T', '/F'], { stdio: 'ignore', windowsHide: true, timeout: 5_000 });
+        }
+        catch {
+            // best-effort: a missing taskkill.exe (or a timeout) is not this call's problem to escalate
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        // Swallows ESRCH (group already gone -- nothing to reap) and any other errno (e.g. EPERM) --
+        // this helper never throws regardless of cause; see the function's own doc comment above.
+    }
+}
+/**
+ * `execFileSync`, with descendant reaping layered on top. Same contract (same return value, throws
+ * the identical error) EXCEPT that when — and ONLY when — this call's OWN timeout killed the child,
+ * any descendants the child forked are also reaped.
+ *
+ * Gated on `error.code === 'ETIMEDOUT'`, NOT `error.signal`. `signal` is the field Node's own docs
+ * describe for this purpose, but it is not reliably populated across platforms/Node versions: on one
+ * real Linux CI run (Node 24) a genuine timeout-kill threw `{ signal: null, code: 'ETIMEDOUT',
+ * status: 7 }` — `signal` was simply absent, `code` was the only reliable marker (confirmed empirically
+ * before landing this; a macOS/Node run separately showed `signal: 'SIGTERM'` for the identical
+ * scenario, so neither field alone is safe to rely on everywhere — `code` was the one constant).
+ * Gating strictly on the timeout code (rather than reaping on every throw) matters: an ordinary
+ * non-zero exit (a real test/lint failure) has no `ETIMEDOUT` code — the child exited on its own, so a
+ * reap there would fire on every red run for no reason and, on POSIX, risks signalling a process group
+ * whose pgid was *already* recycled by something unrelated in the time since (the #3660 review's
+ * Blocker-3 defect in the prior attempt at this fix, PR #3681). Only the timeout-kill path is targeted.
+ *
+ * Spawns `detached` on POSIX so the reap above can address the whole process group; omitted on
+ * Windows (no such flag there — `@types/node`'s `ExecFileSyncOptions` doesn't declare `detached`
+ * either, hence the cast below, though libuv honors it identically to `spawnSync`).
+ */
+function execFileSyncReaping(file, args, options) {
+    const spawnOptions = process.platform === 'win32' ? options : { ...options, detached: true };
+    try {
+        return (0, node_child_process_1.execFileSync)(file, args, spawnOptions);
+    }
+    catch (e) {
+        const err = e;
+        if (typeof err.pid === 'number' && err.code === 'ETIMEDOUT') {
+            reapDescendants(err.pid);
+        }
+        throw e;
+    }
+}
 /** Resolve the effective timeout: only a POSITIVE override is honored — `0` (which Node treats as
  * "no timeout") or a negative value falls back to the bounded default, so the subprocess is ALWAYS
  * bounded (a `timeoutMs: 0` injection can never disable the bound). */
@@ -378,7 +465,7 @@ function posTimeout(timeoutMs, def) {
  */
 function runNodeTestWithSubject(check, cwd, subject, timeoutMs) {
     try {
-        return (0, node_child_process_1.execFileSync)(process.execPath, buildNodeTestArgs(check), {
+        return execFileSyncReaping(process.execPath, buildNodeTestArgs(check), {
             cwd,
             encoding: 'utf-8',
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -398,7 +485,7 @@ function defaultRunCheck(check, cwd, timeoutMs) {
         if (check.kind === 'node-test') {
             let out = '';
             try {
-                out = (0, node_child_process_1.execFileSync)(process.execPath, buildNodeTestArgs(check), {
+                out = execFileSyncReaping(process.execPath, buildNodeTestArgs(check), {
                     cwd,
                     encoding: 'utf-8',
                     stdio: ['ignore', 'pipe', 'pipe'],
@@ -422,7 +509,7 @@ function defaultRunCheck(check, cwd, timeoutMs) {
                 return { passed: false }; // eslint not installed -> fail closed, never throw
             let json = '';
             try {
-                json = (0, node_child_process_1.execFileSync)(process.execPath, [eslintCli, ...buildLintArgs(check)], {
+                json = execFileSyncReaping(process.execPath, [eslintCli, ...buildLintArgs(check)], {
                     cwd,
                     encoding: 'utf-8',
                     stdio: ['ignore', 'pipe', 'pipe'],
@@ -482,7 +569,7 @@ function defaultProveFailFirst(check, cwd, timeoutMs) {
                 return { provenFailFirst: false }; // eslint not installed -> fail closed, never throw
             let json = '';
             try {
-                json = (0, node_child_process_1.execFileSync)(process.execPath, [eslintCli, ...buildLintArgs({ ...check, target: fixture })], {
+                json = execFileSyncReaping(process.execPath, [eslintCli, ...buildLintArgs({ ...check, target: fixture })], {
                     cwd,
                     encoding: 'utf-8',
                     stdio: ['ignore', 'pipe', 'pipe'],