@opengsd/gsd-core 1.14.0 → 1.16.0

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

@@ -71,7 +71,7 @@ const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
-const { readVerificationStatus } = verificationMod;
+const { readVerificationStatus, VerificationStatusError, failOnVerificationStatusError } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
 const { phaseKeyFromDir, phaseKeyFromToken, phaseMarkdownRegexSource } = phaseIdMod;
@@ -304,6 +304,8 @@ function containmentEnforcingVerificationFs(planningRoot) {
             return node_fs_1.default.readFileSync(filePath, encoding);
         },
         statSync(filePath) {
+            // #5118: a code-less containment throw here is NOT "phase directory
+            // not found" — readVerificationStatus falls through to `missing`.
             assertContained(filePath);
             return node_fs_1.default.statSync(filePath);
         },
@@ -917,7 +919,24 @@ function extractDependencyTokens(sectionBody) {
     const m = DEPENDS_ON_LINE_RE.exec(sectionBody);
     if (!m)
         return [];
-    return sortedUnique([...m[1].matchAll(/\d+(?:\.\d+)*/g)].map((t) => t[0]));
+    // #4764: phase REFERENCES, not digit runs — the same prose-anchored grammar
+    // init.manager's dep_phases extraction uses (owner: phase-id.cts's
+    // PHASE_DEP_REF_SOURCE). The whole-field token scrape this replaces pulled
+    // calendar dates, git shas and ledger ids in as dependencies. The grammar's
+    // capture group 1 already excludes the "Phase(s)" anchor word, so no
+    // prefix-strip literal is needed here. Self-exclusion (init.manager drops
+    // the row's own number) is deliberately NOT applied: this reader has no row
+    // context at the extraction site and reports informationally, it does not
+    // gate.
+    const refRe = new RegExp(phaseIdMod.PHASE_DEP_REF_SOURCE, 'gi');
+    const tokenRe = new RegExp(phaseIdMod.PHASE_NUMBER_TOKEN_SOURCE, 'g');
+    const tokens = [];
+    let refMatch;
+    while ((refMatch = refRe.exec(m[1])) !== null) {
+        for (const t of refMatch[1].matchAll(tokenRe))
+            tokens.push(t[0]);
+    }
+    return sortedUnique(tokens);
 }
 /**
  * This phase's own ROADMAP.md section body — milestone-scoped via the SAME
@@ -999,6 +1018,17 @@ function buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phaseDirLabel,
 }
 // ─── Entry points ─────────────────────────────────────────────────────────────
 function buildPlanningInspect(cwd) {
+    return buildPlanningInspectResult(cwd).payload;
+}
+/**
+ * #5118: the inspect payload plus the first verification report whose
+ * `status` is outside the closed set (`statusError`, or `null`) — the
+ * aggregate CARRIES the owner's error in its own result, and `planning
+ * inspect` fails with it instead of printing an answer computed over a
+ * report the owner refused.
+ */
+function buildPlanningInspectResult(cwd) {
+    let statusError = null;
     const diagnostics = [];
     const paths = planningPaths(cwd);
     const planningExists = node_fs_1.default.existsSync(paths.planning);
@@ -1061,8 +1091,8 @@ function buildPlanningInspect(cwd) {
         // GAP 2 (#2790 follow-up security review): `readVerificationStatus`
         // (`src/verification.cts`) is a shared owner with its own unguarded
         // `readFileSync` — a `*-VERIFICATION.md` symlinked outside the planning
-        // root would leak an unrecognized `status:` value verbatim via its
-        // "Unexpected verification status '<value>'" `next_action` string. Fixed
+        // root would leak its unrecognized `status:` value verbatim (today via
+        // the VerificationStatusError message, #5118). Fixed
         // from THIS consumer's side via the injectable `opts.fs` seam that
         // function already exposes, never by touching its signature — see
         // `containmentEnforcingVerificationFs`'s doc comment. This same seam's
@@ -1077,9 +1107,22 @@ function buildPlanningInspect(cwd) {
         // (`superseded`) rather than document text, and GAP 1's directory
         // containment check already covers the escaped-DIRECTORY case for it —
         // so it needs no fix of its own.
-        const verification = readVerificationStatus(phaseDir, {
-            fs: containmentEnforcingVerificationFs(paths.planning),
-        });
+        // #5118: an out-of-set report status is carried, not thrown past the
+        // other phases — the row reads `status: null` and the command fails with
+        // the first such error once the payload is built.
+        let verification;
+        try {
+            verification = readVerificationStatus(phaseDir, {
+                fs: containmentEnforcingVerificationFs(paths.planning),
+            });
+        }
+        catch (err) {
+            if (!(err instanceof VerificationStatusError))
+                throw err;
+            if (statusError === null)
+                statusError = err;
+            verification = { status: null, next_action: err.message, route: '' };
+        }
         const token = /^(\d+(?:\.\d+)*)/.exec(phase.dir);
         const phaseId = token ? token[1] : null;
         const { goal, dependencies } = buildPhaseGoalAndDependencies(cwd, roadmapDoc, phaseId, phase.dir, diagnostics);
@@ -1112,6 +1155,8 @@ function buildPlanningInspect(cwd) {
             verification: {
                 status: verification.status,
                 next_action: verification.next_action ?? null,
+                // #5118: additive — the bare command the owner routes this status to.
+                route: verification.route,
             },
             roadmap_acceptance: {
                 checkbox: checkboxByPhaseKey.has(phaseKeyFromDir(phase.dir))
@@ -1133,7 +1178,7 @@ function buildPlanningInspect(cwd) {
     const phaseScope = worstScope(snapshot.phaseDirs.scope, snapshot.phases.scope, ...phaseRows.map((p) => p.scope));
     const acceptedPhases = makeFraction(phaseRows.filter((p) => p.complete).length, phaseRows.length, phaseScope, 'progress.accepted_phases', diagnostics);
     const completedPlans = makeFraction(phaseRows.reduce((sum, p) => sum + p.summary_count, 0), phaseRows.reduce((sum, p) => sum + p.plan_count, 0), phaseScope, 'progress.completed_plans', diagnostics);
-    return {
+    const payload = {
         schema_version: PLANNING_INSPECT_SCHEMA_VERSION,
         generated_from: {
             cwd: toPosix(cwd),
@@ -1161,6 +1206,7 @@ function buildPlanningInspect(cwd) {
         },
         diagnostics,
     };
+    return { payload, statusError };
 }
 /**
  * `planning inspect` — emit the schema-v1 snapshot.
@@ -1170,7 +1216,12 @@ function buildPlanningInspect(cwd) {
  * transparently on stdout. Bypassing `output()` would lose that for free.
  */
 function cmdPlanningInspect(cwd, raw) {
-    output(buildPlanningInspect(cwd), raw);
+    const { payload, statusError } = buildPlanningInspectResult(cwd);
+    // #5118: a read-only aggregate over a refused report prints nothing and
+    // fails with the error's own reason (`verification_status_invalid`).
+    if (statusError)
+        failOnVerificationStatusError(statusError);
+    output(payload, raw);
 }
 const planningInspect = {
     PLANNING_INSPECT_SCHEMA_VERSION,

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

@@ -124,10 +124,12 @@ function buildPhaseSnapshot(phasesDir, dir, convention) {
     // report exactly like its legacy twin.
     const completionResult = isPhaseComplete(fullPhaseDir, { convention });
     const scanResult = scanPhasePlans(fullPhaseDir);
+    const statusError = completionResult.value.statusError;
     return {
         dir,
         complete: completionResult.value.complete,
         verificationStatus: completionResult.value.verification.status,
+        verificationStatusError: statusError ? { file: statusError.file, message: statusError.message } : null,
         planCount: scanResult.planCount,
         summaryCount: scanResult.summaryCount,
         scope: worstScope(completionResult.scope, scanResult.scope),
@@ -882,6 +884,22 @@ function buildCurrentMilestoneRoadmapPhaseIdsField(cwd, roadmapPath, convention)
     // and `bracketGroup` is 0. Inferring the convention from a matched bracket's
     // shape would run a repo-failing check against a repo that never opted in.
     const bracketGroup = convention === 'bracket' ? 1 : 0;
+    // #5007 (Phase 6 / ADR-4910 §8): already composed from `phaseHeadingPrefixSrcFor`
+    // directly, not a hand-rolled literal — the site's only marked defect was
+    // this doc comment's own prose quoting the pattern verbatim (fixed above),
+    // which is exactly what the drift detector matched. Audited against the
+    // design doc's suggested further swap onto `buildPhaseHeadingScanRegex`
+    // (the same owner `bracketGroup`/`phaseNumGroup` above hand-derives) and
+    // deliberately did NOT make that swap: the owner's regex requires a title
+    // (`${OPTIONAL_PHASE_TAG_SOURCE}\s*:\s*([^\n]+)` — at least one non-newline
+    // character after the colon), while this site's own tail is bare `:` with
+    // no title requirement. A live probe against this function (a `### Phase 3:`
+    // heading with no title text) confirms the current, pre-migration behavior
+    // DOES count that phase — swapping to the owner would silently drop it from
+    // W026's scan, and no existing test (including the ADR-612 census test
+    // pinned to this site by name) would catch that narrowing, since the census
+    // only pins `phaseHeadingPrefixSrcFor`'s own output, not this regex's tail.
+    // Kept as its own composition to preserve this exact byte-for-behavior.
     const phasePattern = new RegExp(`#{2,4}\\s*${phaseHeadingPrefixSrcFor(PHASE_HEADING_BASELINE.LABEL_ONLY, convention, Boolean(bracketGroup))}(${PHASE_NUMBER_TOKEN_SOURCE})(?:\\s*\\([^)\\n]{0,200}\\))?\\s*:`, 'gi');
     const value = [];
     for (const m of scoped.matchAll(phasePattern)) {

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

@@ -114,13 +114,18 @@ const PLANNING_LOCK_RETRY_ERRNOS = new Set([
  * two-readers-two-bases lesson).
  */
 function resolveEnvWorkstream() {
-    return process.env['GSD_WORKSTREAM'] ?? null;
+    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 = 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)) {
@@ -139,60 +144,73 @@ function planningDir(cwd, ws, project) {
 function planningRoot(cwd) {
     return node_path_1.default.join(cwd, '.planning');
 }
+const CONFIG_VALUE_ABSENT = Object.freeze({ present: false, value: undefined });
 /**
- * #3972: the ONE owner of "is this planning scope opted out of worktrees?" —
- * the effective `workflow.use_worktrees === false` read every
- * isolation-deciding surface must share (config-get's merged view is the
- * contract). Ladder: the scoped config's OWN key wins (planningDir is
- * project- and workstream-aware); otherwise the flat root's key, but only
- * under the GSD_WORKSTREAM env gate — config-get deliberately does NOT
- * inherit root under GSD_PROJECT alone, and this read must not diverge
- * (#3963). Strict `=== false` (never coerced); any read failure degrades to
- * "not opted out" (worktrees on — the fail-safe direction: the guard keeps
- * enforcing). Direct file reads only — never loadConfig, which normalizes
- * and rewrites config on paths that back sentinel writes.
+ * The value one config file sets at `keyPath`, if it sets one at all. Every
+ * segment must be an OWN property of a plain (non-null, non-array) object, so
+ * an absent, unreadable, or unparseable file — or a non-object anywhere on the
+ * path — does not set the key.
  */
-function worktreesOptedOut(cwd) {
-    // #3972 review: the WHOLE body is guarded — planningDir/planningRoot
-    // themselves throw on a GSD_PROJECT/GSD_WORKSTREAM value containing path
-    // separators or `..`, and this contract ("any failure degrades to not
-    // opted out — worktrees on, keep enforcing") must hold for that shape too.
+function ownConfigValue(configPath, keyPath) {
+    let node;
     try {
-        return worktreesOptedOutUnguarded(cwd);
+        node = JSON.parse(String(node_fs_1.default.readFileSync(configPath, 'utf8')));
     }
     catch {
-        return false;
+        return CONFIG_VALUE_ABSENT;
+    }
+    for (const key of keyPath) {
+        if (node === null || typeof node !== 'object' || Array.isArray(node))
+            return CONFIG_VALUE_ABSENT;
+        if (!Object.prototype.hasOwnProperty.call(node, key))
+            return CONFIG_VALUE_ABSENT;
+        node = node[key];
     }
+    return { present: true, value: node };
 }
-function worktreesOptedOutUnguarded(cwd) {
-    const readCfg = (p) => {
-        try {
-            return JSON.parse(String(node_fs_1.default.readFileSync(p, 'utf8')));
-        }
-        catch {
-            return null;
+/**
+ * #3972/#4975: the ONE scope-aware config read for surfaces that must answer
+ * with the value `config-get <keyPath>` reports but may not call loadConfig
+ * (it normalizes and rewrites config.json, spawns git, and prints warnings).
+ * Ladder: the scoped config's OWN key wins (planningDir is project- and
+ * workstream-aware); otherwise the flat root's key, but only under the
+ * GSD_WORKSTREAM env gate — config-get deliberately does NOT inherit root
+ * under GSD_PROJECT alone, and no reader of this ladder may diverge (#3963).
+ * An unreadable or unparseable file sets nothing, so the ladder moves on:
+ * under GSD_WORKSTREAM a broken workstream config inherits the root's key.
+ * That is the one place this read and config-get part ways — for a scoped
+ * config.json that exists but cannot be read or parsed, config-get fails
+ * with CONFIG_PARSE_FAILED instead of reporting a value.
+ * The value is returned uncoerced; each caller applies its own strict
+ * comparison. Never throws: planningDir/planningRoot reject a
+ * GSD_PROJECT/GSD_WORKSTREAM value containing path separators or `..`, and
+ * that shape resolves to "not present".
+ */
+function readScopedConfigValue(cwd, keyPath) {
+    try {
+        const scoped = ownConfigValue(node_path_1.default.join(planningDir(cwd), 'config.json'), keyPath);
+        if (scoped.present)
+            return scoped;
+        if (resolveEnvWorkstream() !== null) {
+            return ownConfigValue(node_path_1.default.join(planningRoot(cwd), 'config.json'), keyPath);
         }
-    };
-    const ownKey = (cfg) => {
-        if (cfg === null || typeof cfg !== 'object')
-            return { present: false, value: undefined };
-        const wf = cfg.workflow;
-        if (wf === null || typeof wf !== 'object' || Array.isArray(wf))
-            return { present: false, value: undefined };
-        const wfRec = wf;
-        return Object.prototype.hasOwnProperty.call(wfRec, 'use_worktrees')
-            ? { present: true, value: wfRec['use_worktrees'] }
-            : { present: false, value: undefined };
-    };
-    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']) {
-        const root = ownKey(readCfg(node_path_1.default.join(planningRoot(cwd), 'config.json')));
-        if (root.present)
-            return root.value === false;
     }
-    return false;
+    catch {
+        // Degrade to "not present" — see the contract above.
+    }
+    return CONFIG_VALUE_ABSENT;
+}
+/**
+ * #3972: the ONE owner of "is this planning scope opted out of worktrees?" —
+ * the effective `workflow.use_worktrees === false` read every
+ * isolation-deciding surface must share (config-get's merged view is the
+ * contract), resolved on the readScopedConfigValue ladder. Strict `=== false`
+ * (never coerced); a config that cannot be read never opts out by itself
+ * (worktrees on — the fail-safe direction: the guard keeps enforcing).
+ */
+function worktreesOptedOut(cwd) {
+    const { present, value } = readScopedConfigValue(cwd, ['workflow', 'use_worktrees']);
+    return present && value === false;
 }
 /**
  * #612: resolve `phase_id_convention` with the SAME workstream->root federation
@@ -300,8 +318,8 @@ 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
+// #4256: the todos directory — deliberately ROOT-SCOPED, like debug (#5042).
+// 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
@@ -325,6 +343,14 @@ function todosDirFrom(planningBase) {
 function todosDir(cwd) {
     return todosDirFrom(planningRoot(cwd));
 }
+// Debug sessions are shared project state: the workflow and debugger agent
+// write them under the root .planning/debug directory in every workstream.
+function debugDirFrom(planningBase) {
+    return node_path_1.default.join(planningBase, 'debug');
+}
+function debugDir(cwd) {
+    return debugDirFrom(planningRoot(cwd));
+}
 function planningPaths(cwd, ws) {
     const base = planningDir(cwd, ws);
     return {
@@ -335,14 +361,13 @@ function planningPaths(cwd, ws) {
         config: node_path_1.default.join(base, 'config.json'),
         phases: node_path_1.default.join(base, 'phases'),
         requirements: node_path_1.default.join(base, 'REQUIREMENTS.md'),
-        // #3149: the debug-session directory. Single source for both `state.load`'s
-        // `debug_dir` field and `init.debug`'s — previously each composed its own
-        // `path.join(planning, 'debug')` (DEFECT.GENERATIVE-FIX).
-        debug: node_path_1.default.join(base, 'debug'),
+        // #3149/#5042: the debug-session directory shared by state.load,
+        // init.debug, and the root-scoped writers.
+        debug: debugDir(cwd),
         // #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
+        // #4256: todos directory — deliberately ROOT-scoped like debug, while
+        // most other keys follow 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),
@@ -607,6 +632,7 @@ function findContextMdIn(absDirOrFiles) {
 }
 module.exports = {
     worktreesOptedOut,
+    readScopedConfigValue,
     createPlanningWorkspace,
     createSharedPointerAdapter,
     createSessionScopedPointerAdapter,
@@ -618,6 +644,8 @@ module.exports = {
     listAvailableWorkstreams,
     planningPaths,
     quickDirFrom,
+    debugDirFrom,
+    debugDir,
     todosDirFrom,
     todosDir,
     withPlanningLock,

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

@@ -27,6 +27,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.sha256File = sha256File;
 exports.findPristineByHash = findPristineByHash;
+exports.isCleanRelativePosixPath = isCleanRelativePosixPath;
+exports.gitExec = gitExec;
 exports.findPristineInGit = findPristineInGit;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
@@ -125,6 +127,14 @@ const GIT_MAX_COMMITS_PER_FILE = 100;
 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;
+/**
+ * #5105 review finding 1/4: shared containment guard AND the shared
+ * non-trimming `git` subprocess runner, exported so `uat.cts`'s
+ * `readBaselineAtHead` (byte-exact `git show HEAD:<path>` read) can route
+ * through the same bounded, `windowsHide`d, stderr-discarding call this
+ * module already uses, rather than maintaining a second private
+ * `execFileSync` wrapper that can drift from this one's timeout/maxBuffer.
+ */
 function isCleanRelativePosixPath(relPath) {
     if (!relPath || relPath.startsWith('/') || relPath.includes('\\') || relPath.includes('\0')) {
         return false;

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/profile-output.cjs

@@ -29,6 +29,7 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // ─── Constants ────────────────────────────────────────────────────────────────
 const DIMENSION_KEYS = [
     'communication_style', 'decision_speed', 'explanation_depth',
@@ -203,6 +204,7 @@ function buildClaudeMdWorkflowEnforcement(runtime) {
         'Before using Edit, Write, or other file-changing tools, start work through a GSD command so planning artifacts and execution context stay in sync.',
         '',
         'Use these entry points:',
+        `- \`${String((0, runtime_slash_cjs_1.formatGsdSlash)('fast', runtime))}\` for a trivial task inline, with no subagents and no PLAN.md`,
         `- \`${String((0, runtime_slash_cjs_1.formatGsdSlash)('quick', runtime))}\` for small fixes, doc updates, and ad-hoc tasks`,
         `- \`${String((0, runtime_slash_cjs_1.formatGsdSlash)('debug', runtime))}\` for investigation and bug fixing`,
         `- \`${String((0, runtime_slash_cjs_1.formatGsdSlash)('execute-phase', runtime))}\` for planned phase work`,
@@ -477,10 +479,11 @@ function generateSkillsSection(cwd) {
  */
 function extractSkillFrontmatter(content) {
     const result = { name: '', description: '' };
-    const fmMatch = content.match(/^---\s*\r?\n([\s\S]*?)\r?\n---/);
-    if (!fmMatch)
+    // The block is the one the one fence owner (`locateFrontmatterFence`) finds.
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence?.closed)
         return result;
-    const fmBlock = fmMatch[1];
+    const fmBlock = content.slice(fence.openEnd, fence.bodyEnd);
     const lines = fmBlock.split('\n');
     let currentKey = '';
     for (const line of lines) {

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

@@ -58,14 +58,9 @@ exports.eslintHasFatalError = eslintHasFatalError;
 exports.eslintJsonHasRule = eslintJsonHasRule;
 exports.defaultProveFailFirst = defaultProveFailFirst;
 exports.runProhibitionEnforcement = runProhibitionEnforcement;
-exports.routeProhibitionEnforcement = routeProhibitionEnforcement;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
-// Import the leaf I/O module directly (core.cjs re-export spine retired in epic #1267).
-// eslint-disable-next-line @typescript-eslint/no-require-imports
-const io = require("./io.cjs");
-const { output, error, ERROR_REASON } = io;
 const probe_core_cjs_1 = require("./probe-core.cjs");
 /**
  * READ-BACK ADAPTER (#1278, plan 01-03): reconstruct a `CheckDescriptor` from the flat scalar keys
@@ -730,53 +725,3 @@ function runProhibitionEnforcement(prohibition, check, options = {}) {
         ...(mode ? { mode } : {}),
     };
 }
-/**
- * Parse a `{ prohibition, check, mode }` request from a JSON file path or inline `--json` string.
- * Returns null on any parse failure (the caller surfaces a structured error, never a throw).
- */
-function parseRequest(args) {
-    // args[0] = 'check', args[1] = 'prohibition-enforcement', args[2] = <json-file-path | --json>
-    const jsonFlagIdx = args.indexOf('--json');
-    let payload = '';
-    if (jsonFlagIdx !== -1 && typeof args[jsonFlagIdx + 1] === 'string') {
-        payload = args[jsonFlagIdx + 1];
-    }
-    else if (typeof args[2] === 'string' && args[2]) {
-        try {
-            payload = node_fs_1.default.readFileSync(args[2], 'utf-8');
-        }
-        catch {
-            return null;
-        }
-    }
-    else {
-        return null;
-    }
-    try {
-        const parsed = JSON.parse(payload);
-        const checkRaw = parsed['check'];
-        const check = (checkRaw && typeof checkRaw === 'object')
-            ? checkRaw
-            : null;
-        const modeRaw = parsed['mode'];
-        const mode = typeof modeRaw === 'string' ? modeRaw : undefined;
-        return { prohibition: parsed['prohibition'] ?? null, check, ...(mode ? { mode } : {}) };
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * CLI surface: `gsd_run check prohibition-enforcement <request.json>` (or `--json '<inline>'`).
- * Parses the request, runs the producer, and emits the result as JSON. Honors the no-throw
- * contract: malformed input -> structured `error(...)`, never an uncaught throw.
- */
-function routeProhibitionEnforcement(args, raw) {
-    const req = parseRequest(args);
-    if (!req) {
-        error('prohibition-enforcement requires a JSON request: check prohibition-enforcement <request.json> | --json \'{"prohibition":{...},"check":{...}}\'', ERROR_REASON.SDK_MISSING_ARG);
-        return;
-    }
-    const result = runProhibitionEnforcement(req.prohibition, req.check, req.mode ? { mode: req.mode } : {});
-    output(result, raw, undefined);
-}

package/gsd-core/bin/lib/project-root.cjs

@@ -17,12 +17,28 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.setExplicitProjectRoot = setExplicitProjectRoot;
+exports.resolveProjectRoot = resolveProjectRoot;
 exports.findProjectRoot = findProjectRoot;
 exports.consentProjectRoot = consentProjectRoot;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const FIND_PROJECT_ROOT_MAX_DEPTH = 10;
+// #4894: an operator-supplied `--project-dir` IS the project root — the
+// dispatcher validates it and skips the ancestor walk-up for `cwd`, but code
+// that derives a root from a PHASE DIRECTORY (verification) never sees `cwd`.
+// The dispatcher records the validated root here, once per process, and those
+// callers resolve through `resolveProjectRoot`. `null` (the default, and what
+// the dispatcher sets when the flag is absent) leaves `findProjectRoot`'s
+// walk-up as the only source of truth, so no-flag behavior is unchanged.
+let explicitProjectRoot = null;
+function setExplicitProjectRoot(root) {
+    explicitProjectRoot = root;
+}
+function resolveProjectRoot(startDir) {
+    return explicitProjectRoot ?? findProjectRoot(startDir);
+}
 function findProjectRoot(startDir) {
     let resolvedStart;
     try {
@@ -43,12 +59,35 @@ function findProjectRoot(startDir) {
     catch {
         // fall through
     }
+    // A `.planning` that is itself a symlink is a deliberate hop into a separate
+    // tree (the documented "keep planning content out of the tracked repo"
+    // convention: `.planning -> ~/.gsd-external-planning/<project>/`, its own git
+    // repo). `fs.existsSync(d + '/.git')` DEREFERENCES `d`, so at `d ===
+    // <the .planning symlink path>` it finds the EXTERNAL store's `.git`, and
+    // both isInsideGitRepo/nearestGitRoot misread it as a crossed nested-child-
+    // repo boundary (#2843's guard). `fs.lstatSync` does not dereference its
+    // final path component, so it answers "is `d` ITSELF a symlink" (#4815).
+    //
+    // Deliberately scoped to a symlink named `.planning`, NOT any symlinked
+    // directory: a nested child repo reached through some other symlinked
+    // ancestor is still a real repo boundary, and skipping it would reopen
+    // #2843 through a different trigger.
+    function isSymlinkedPlanningDir(d) {
+        if (node_path_1.default.basename(d) !== '.planning')
+            return false;
+        try {
+            return node_fs_1.default.lstatSync(d).isSymbolicLink();
+        }
+        catch {
+            return false;
+        }
+    }
     // Walk upward, mirroring isInsideGitRepo from the CJS reference.
     function isInsideGitRepo(candidateParent) {
         let d = resolvedStart;
         while (d !== fsRoot) {
             try {
-                if (node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
+                if (!isSymlinkedPlanningDir(d) && node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
                     return true;
             }
             catch {
@@ -77,7 +116,7 @@ function findProjectRoot(startDir) {
             if (d === upTo)
                 break;
             try {
-                if (node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
+                if (!isSymlinkedPlanningDir(d) && node_fs_1.default.existsSync(d + node_path_1.default.sep + '.git'))
                     return d;
             }
             catch {