@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -15,7 +15,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_LOCAL_CONFIG_DIR_SENTINEL = void 0;
+exports.NO_LOCAL_CONFIG_DIR_SENTINEL = exports.RetiredRuntimeError = exports.RETIRED_RUNTIME_IDS = void 0;
+exports.isRetiredRuntimeId = isRetiredRuntimeId;
+exports.assertNotRetiredRuntime = assertNotRetiredRuntime;
 exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
 exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
 exports.getProjectInstructionFile = getProjectInstructionFile;
@@ -26,6 +28,105 @@ exports.runtimeFlags = runtimeFlags;
 exports.getRuntimeNewProjectCommand = getRuntimeNewProjectCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+/**
+ * Runtime ids that GSD deliberately RETIRED, as opposed to ids it has simply
+ * never heard of. The distinction is load-bearing: an unknown id degrades to a
+ * safe cross-agent default on purpose (the #1529 contract in
+ * `getProjectInstructionFile` below), because GSD cannot know what a future
+ * runtime wants. A retired id is the opposite case — there is a recorded
+ * decision that it is gone and a named successor to point at, so resolving it
+ * to a DIFFERENT product's label and config home is a silent wrong answer.
+ *
+ * Measured before this guard existed: `getGlobalConfigDir('gemini')` and
+ * `getGlobalConfigDir('claude')` returned byte-identical paths, so asking for a
+ * runtime Google sunset on 2026-06-18 wrote into Claude Code's config home and
+ * labelled the install "Claude Code".
+ *
+ * Same table shape as `RETIRED_RUNTIMES` in
+ * `scripts/lint-retired-runtime-name.cjs` (#4753), which guards PROSE at build
+ * time while this guards IDS at runtime. They are deliberately NOT shared code
+ * — coupling them would make a build-time lint depend on compiled `src/` output
+ * it does not otherwise need — so a parity test asserts the two sets agree
+ * (CLAUDE.md, Generative Fix Divergence).
+ */
+const RETIRED_RUNTIME_DETAILS = new Map([
+    ['gem' + 'ini', { successor: 'Antigravity', retiredBy: '#1928', sunset: '2026-06-18' }],
+]);
+/**
+ * Normalise a candidate id for retirement matching: NFKC-fold, lowercase, and
+ * drop every non-alphanumeric character.
+ *
+ * Folding the separators is what makes `gemini-cli`, `gemini_cli`,
+ * `gemini.cli` and `geminicli` one key instead of four near-misses a reviewer
+ * has to find one at a time — and NFKC folds the full-width `ｇｅｍｉｎｉ` a CJK
+ * keyboard produces. It stays MEMBERSHIP matching, not a prefix or substring
+ * test: `gemini-2.5-pro` folds to `gemini25pro` and `gemini-3.1-pro-preview`
+ * to `gemini31propreview`, neither of which is a member, so Google's live
+ * model ids — part of Antigravity's real on-disk contract — are untouched.
+ *
+ * Homoglyph folding is deliberately NOT attempted. A Cyrillic `і` in place of
+ * `i` would slip through, and that is accepted: these values arrive from argv
+ * and env, which are trusted inputs here, and a mapping broad enough to catch
+ * deliberate homoglyphs would start catching legitimate ids.
+ */
+function normalizeForRetirementMatch(value) {
+    return value.normalize('NFKC').toLowerCase().replace(/[^a-z0-9]/g, '');
+}
+/**
+ * Every spelling that names a retired runtime, mapped to its canonical id.
+ * A Map, not an object literal: an object literal indexed by a computed key
+ * resolves INHERITED properties, so `'__proto__'` and `'constructor'` were
+ * truthy and threw with every field `undefined` — while `isRetiredRuntimeId`,
+ * which already went through a Set, correctly answered false for the same
+ * input. Two guards disagreeing about one id is worse than either answer.
+ * A Map has no prototype keys, so the hazard is structural, not patched.
+ */
+const RETIRED_RUNTIME_SPELLINGS = new Map(Array.from(RETIRED_RUNTIME_DETAILS.keys()).flatMap((id) => [
+    [normalizeForRetirementMatch(id), id],
+    [normalizeForRetirementMatch(`${id}-cli`), id],
+]));
+/**
+ * The canonical retired runtime ids, lowercase. Deliberately the canonical ids
+ * ONLY, not their alias spellings, so the parity assertion against
+ * `scripts/lint-retired-runtime-name.cjs`'s `RETIRED_RUNTIMES` compares like
+ * with like.
+ */
+exports.RETIRED_RUNTIME_IDS = new Set(RETIRED_RUNTIME_DETAILS.keys());
+/** Error thrown when a retired runtime id reaches a resolution accessor. */
+class RetiredRuntimeError extends Error {
+    code = 'GSD_RETIRED_RUNTIME';
+    runtimeId;
+    constructor(runtimeId, detail) {
+        super(`Runtime "${runtimeId}" was retired by ${detail.retiredBy} (sunset ${detail.sunset}); `
+            + `use "${detail.successor}" instead. Refusing to resolve it, because the previous `
+            + `behaviour silently returned Claude Code's values.`);
+        this.name = 'RetiredRuntimeError';
+        this.runtimeId = runtimeId;
+    }
+}
+exports.RetiredRuntimeError = RetiredRuntimeError;
+/**
+ * Is `runtime` a deliberately retired runtime, under any of its spellings?
+ * Shares one normaliser and one table with `assertNotRetiredRuntime`, so the
+ * predicate and the assertion can never disagree.
+ */
+function isRetiredRuntimeId(runtime) {
+    if (typeof runtime !== 'string')
+        return false;
+    return RETIRED_RUNTIME_SPELLINGS.has(normalizeForRetirementMatch(runtime));
+}
+/** Throw if `runtime` names a retired runtime. No-op otherwise. */
+function assertNotRetiredRuntime(runtime) {
+    if (typeof runtime !== 'string')
+        return;
+    const id = RETIRED_RUNTIME_SPELLINGS.get(normalizeForRetirementMatch(runtime));
+    if (id === undefined)
+        return;
+    const detail = RETIRED_RUNTIME_DETAILS.get(id);
+    if (detail === undefined)
+        return;
+    throw new RetiredRuntimeError(id, detail);
+}
 const FALLBACK_ALIASES = {
     claude: ['claude', 'claude-code', 'claude-cli'],
     opencode: ['opencode', 'open-code', 'opencode-cli'],
@@ -145,6 +246,7 @@ function resolveRuntimeNameFromCandidates(...candidates) {
  * avoid a circular dependency at module load.
  */
 function getProjectInstructionFile(runtime) {
+    assertNotRetiredRuntime(runtime);
     const canonical = canonicalizeRuntimeName(runtime);
     if (canonical === 'claude')
         return '.claude/CLAUDE.md';
@@ -198,6 +300,9 @@ exports.NO_LOCAL_CONFIG_DIR_SENTINEL = '(no-local-config-dir)';
  * compatibility spine had no production consumer at all.
  */
 function getDirName(runtime) {
+    // Same silent-wrong-answer class as the four accessors AC#1 names: this
+    // returned '.claude' for a retired id, and it feeds runtimeConfigDir.
+    assertNotRetiredRuntime(runtime);
     if (!runtime)
         return '.claude';
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -268,6 +373,7 @@ const RUNTIME_LABELS = {
  * 'Claude Code'. Sibling to `getDirName`; pure (no I/O).
  */
 function getRuntimeLabel(runtime) {
+    assertNotRetiredRuntime(runtime);
     if (!runtime)
         return 'Claude Code';
     const label = RUNTIME_LABELS[runtime];
@@ -323,6 +429,7 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS = {
  * dynamically). Pure: no I/O. Sibling to `getDirName` / `getRuntimeLabel`.
  */
 function getGlobalConfigHomeFragment(runtime) {
+    assertNotRetiredRuntime(runtime);
     if (!runtime)
         return DEFAULT_CONFIG_HOME_FRAGMENT;
     const frag = GLOBAL_CONFIG_HOME_FRAGMENTS[runtime];
@@ -382,6 +489,9 @@ const RUNTIME_NEW_PROJECT_COMMANDS = {
     kimi: '/skill:gsd-new-project',
 };
 function getRuntimeNewProjectCommand(runtime) {
+    // Deliberately NOT retirement-guarded: this value does not vary by runtime
+    // in a way that makes a retired id a WRONG answer, so throwing here would
+    // cost callers a crash without correcting anything.
     if (!runtime)
         return DEFAULT_NEW_PROJECT_COMMAND;
     const c = RUNTIME_NEW_PROJECT_COMMANDS[runtime];

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

@@ -22,10 +22,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.MARKDOWN_LINK_PATTERNS = exports.INJECTION_PATTERNS = void 0;
-exports.validatePath = validatePath;
+exports.MARKDOWN_LINK_PATTERNS = exports.INJECTION_PATTERNS = exports.PathAcceptance = void 0;
+exports.isContainedIn = isContainedIn;
 exports.loadTrustedGlobalRoots = loadTrustedGlobalRoots;
+exports.assertWithinRoot = assertWithinRoot;
+exports.tryWithinRoot = tryWithinRoot;
 exports.requireSafePath = requireSafePath;
+exports.tryWithinRootLexical = tryWithinRootLexical;
+exports.assertWithinRootLexical = assertWithinRootLexical;
 exports.scanForInjection = scanForInjection;
 exports.sanitizeForPrompt = sanitizeForPrompt;
 exports.sanitizeForDisplay = sanitizeForDisplay;
@@ -39,6 +43,31 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_os_1 = __importDefault(require("node:os"));
 const node_path_1 = __importDefault(require("node:path"));
 // ─── Path Traversal Prevention ──────────────────────────────────────────────
+/**
+ * THE containment comparison — the single place this repo decides whether an
+ * already-resolved path lies inside an already-resolved root (ADR-4650).
+ *
+ * Separator-aware on purpose: comparing the bare strings would accept a
+ * sibling that merely shares a prefix (`<root>-evil` against `<root>`), so both
+ * sides get a trailing separator before the prefix test. `target === root` is
+ * contained.
+ *
+ * `pathImpl` lets a caller supply `path.win32` / `path.posix` instead of the
+ * ambient module, so win32 separator semantics are testable off Windows.
+ *
+ * Exported for callers that have ALREADY resolved both operands themselves
+ * and need only this comparison step (e.g. a caller that owns its own
+ * `fs.realpathSync` calls to preserve an exists-vs-escaped tri-state). A
+ * caller that has NOT resolved its operands must NOT reach for this function
+ * directly — the comparison alone is not a containment check — and should use
+ * `assertWithinRoot` / `tryWithinRoot` (or the `assertWithinRootLexical` /
+ * `tryWithinRootLexical` pair) instead.
+ */
+function isContainedIn(resolvedTarget, resolvedRoot, pathImpl = node_path_1.default) {
+    if (resolvedTarget === resolvedRoot)
+        return true;
+    return (resolvedTarget + pathImpl.sep).startsWith(resolvedRoot + pathImpl.sep); // allow-handrolled-containment: this IS the canonical comparison every other site routes through
+}
 /**
  * Validate that a file path resolves within an allowed base directory.
  * Prevents path traversal attacks via ../ sequences, symlinks, or absolute paths.
@@ -122,9 +151,7 @@ function validatePath(filePath, baseDir, opts = {}) {
             }
         }
     }
-    const normalizedBase = resolvedBase + node_path_1.default.sep;
-    const normalizedPath = resolvedPath + node_path_1.default.sep;
-    if (resolvedPath !== resolvedBase && !normalizedPath.startsWith(normalizedBase)) {
+    if (!isContainedIn(resolvedPath, resolvedBase)) {
         return {
             safe: false,
             resolved: resolvedPath,
@@ -204,17 +231,109 @@ function loadTrustedGlobalRoots(config) {
     }
     return result;
 }
+/**
+ * Named acceptance policy for what kind of candidate path is even considered.
+ *
+ * This replaces the old per-call-site `{ allowAbsolute: true }` boolean flag.
+ * At a call site, `{ allowAbsolute: true }` reads as "containment is relaxed
+ * here" — which is FALSE. An absolute path that resolves OUTSIDE the root is
+ * still rejected; the flag only ever controlled whether an absolute candidate
+ * was considered at all. `AbsoluteInsideRoot` states the real contract: an
+ * absolute candidate is accepted for consideration, but containment is
+ * enforced exactly as it is for a relative one.
+ */
+exports.PathAcceptance = {
+    /** Relative candidates only; an absolute candidate is rejected outright. */
+    RelativeOnly: 'relative-only',
+    /**
+     * An absolute candidate is accepted — but ONLY if it still resolves inside the
+     * root. Containment is NOT relaxed by this policy; an absolute path outside the
+     * root is rejected exactly as a traversal is. This is the distinction the old
+     * `{ allowAbsolute: true }` flag failed to make at its call sites.
+     */
+    AbsoluteInsideRoot: 'absolute-inside-root',
+};
 /**
  * Validate a file path and throw on traversal attempt.
  * Convenience wrapper around validatePath for use in CLI commands.
  */
-function requireSafePath(filePath, baseDir, label, opts = {}) {
-    const result = validatePath(filePath, baseDir, opts);
+function assertWithinRoot(candidate, root, label, policy = exports.PathAcceptance.RelativeOnly) {
+    const result = validatePath(candidate, root, { allowAbsolute: policy === exports.PathAcceptance.AbsoluteInsideRoot });
     if (!result.safe) {
         throw new Error(`${label || 'Path'} validation failed: ${result.error}`);
     }
     return result.resolved;
 }
+/**
+ * Validate a file path and return null on traversal attempt (no throw).
+ *
+ * Returns exactly `null` when unsafe — never `''`, never `result.resolved`.
+ * `validatePath` populates `resolved` with the ESCAPING path on the
+ * traversal branch, so returning it here would reproduce the defect this
+ * narrowing exists to remove.
+ */
+function tryWithinRoot(candidate, root, policy = exports.PathAcceptance.RelativeOnly) {
+    const result = validatePath(candidate, root, { allowAbsolute: policy === exports.PathAcceptance.AbsoluteInsideRoot });
+    if (!result.safe) {
+        return null;
+    }
+    return result.resolved;
+}
+/**
+ * Validate a file path and throw on traversal attempt.
+ * Convenience wrapper around validatePath for use in CLI commands.
+ *
+ * Delegates to assertWithinRoot so there is one implementation beneath both
+ * names; its declared return type is ContainedPath (a branded string, still
+ * assignable to string) so existing callers keep compiling untouched.
+ */
+function requireSafePath(filePath, baseDir, label, policy = exports.PathAcceptance.RelativeOnly) {
+    return assertWithinRoot(filePath, baseDir, label, policy);
+}
+/**
+ * LEXICAL containment — `path.resolve` only, never any filesystem access.
+ *
+ * Shares `isContainedIn` with the realpath-based predicate, so there is ONE
+ * containment decision in this repo; these differ only in how a path is
+ * RESOLVED before that decision, never in the decision itself (ADR-4650
+ * decisions 1 and 6).
+ *
+ * Use this — and say why at the call site — only where a symlink must be
+ * PRESERVED rather than resolved, or where the target legitimately does not
+ * exist yet. Three such cases exist: a destination validated before the
+ * `mkdirSync` that creates it, a migration that snapshots and restores a
+ * symlinked path AS A LINK, and a restore gate that refuses links outright.
+ * Everywhere else the realpath-based `assertWithinRoot` / `tryWithinRoot` is
+ * the correct predicate, because a lexical check CANNOT SEE A SYMLINK: a
+ * caller relying on one for a write-confinement guarantee must pair it with
+ * its own symlink refusal.
+ *
+ * `candidate` is resolved RELATIVE TO `root` (so an absolute candidate is
+ * taken as-is, matching `path.resolve` semantics). `target === root` is
+ * contained.
+ *
+ * DELIBERATELY ABSENT: no NUL-byte rejection here. The existing lexical
+ * callers do not reject NUL at this layer (one of them checks NUL itself,
+ * separately), and adding it here would change their behavior. Callers that
+ * need it keep their own check.
+ */
+function tryWithinRootLexical(candidate, root, opts = {}) {
+    const p = opts.pathImpl || node_path_1.default;
+    if (typeof candidate !== 'string' || candidate === '')
+        return null;
+    if (typeof root !== 'string' || root === '')
+        return null;
+    const rootResolved = p.resolve(root);
+    const targetResolved = p.resolve(root, candidate);
+    return isContainedIn(targetResolved, rootResolved, p) ? targetResolved : null;
+}
+function assertWithinRootLexical(candidate, root, label, opts = {}) {
+    const contained = tryWithinRootLexical(candidate, root, opts);
+    if (contained === null) {
+        throw new Error(`${label || 'Path'} validation failed: lexical containment check failed`);
+    }
+    return contained;
+}
 // ─── Prompt Injection Detection ────────────────────────────────────────────────────
 /**
  * Patterns that indicate prompt injection attempts in user-supplied text.

package/gsd-core/bin/lib/shell-command-projection.cjs

@@ -263,6 +263,7 @@ const MANAGED_HOOK_COMMAND_BASENAMES_BY_SURFACE = {
         'gsd-session-state.sh',
         'gsd-validate-commit.sh',
         'gsd-phase-boundary.sh',
+        'gsd-graphify-update.sh',
         // #3662: same three guards as MANAGED_HOOK_BASENAMES_BY_SURFACE above —
         // their absence here meant isManagedHookCommand never recognized them, so
         // the settings.json→settings.local.json migration filter (and uninstall
@@ -1068,12 +1069,15 @@ function _normalizeMd(content) {
             if (i === 0 || !insideFence[i - 1])
                 result.push('');
         }
-        // #3854: the `!/^\s/.test(prev)` guard mirrors the after-a-bullet rule below —
-        // an indented non-bullet line is a CONTINUATION of the previous list item, not a
-        // preceding paragraph, so no separating blank may be injected before this bullet
-        // (that injection converted every tight multi-line list to a loose one on write).
-        if (/^(\s*[-*+]\s|\s*\d+\.\s)/.test(line) && i > 0 && prevTrimmed !== '' && !/^(\s*[-*+]\s|\s*\d+\.\s)/.test(prev) && !/^\s/.test(prev) && prevTrimmed !== '---')
-            result.push('');
+        // No "separate a list from a preceding paragraph" rule (#3854, #4725).
+        // This pass re-normalizes the ENTIRE document on every .md write, so an
+        // inserted blank before a bullet whose previous line is ordinary prose
+        // reflowed text the command never touched (converting tight lists to
+        // loose ones); #3854 first guarded the indented-continuation predecessor,
+        // #4725 removed the rule outright. A paragraph→list transition stays
+        // exactly as the author wrote it; a heading→list separation still comes
+        // from the after-heading rule below. The after-a-bullet rule at the end
+        // of this loop is a different transition (list→prose) and is unaffected.
         result.push(line);
         if (/^#{1,6}\s/.test(trimmed) && i < lines.length - 1 && (lines[i + 1] ?? '').trimEnd() !== '')
             result.push('');

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

@@ -8,7 +8,7 @@
  * from the prior hand-written .cjs; only types are added.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN_STATUS_PATTERNS = exports.KNOWN_TEMPLATE_DEFAULTS = void 0;
+exports.KNOWN_STATUS_PATTERNS = exports.KNOWN_TEMPLATE_DEFAULTS = exports.STATUS_ANCHORED_PATTERNS = exports.STATUS_EXACT_TOKENS = void 0;
 exports.toFiniteNumber = toFiniteNumber;
 exports.isUnfilledFieldValue = isUnfilledFieldValue;
 exports.leadingCalendarDate = leadingCalendarDate;
@@ -364,7 +364,7 @@ function stateFieldContinuation(content, fieldName) {
     // this locates exactly the line whose value it returned. The pipe-table rung
     // is deliberately absent: a `| Field | value |` row is bounded by its closing
     // pipe and cannot wrap.
-    const match = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i').exec(content) ??
+    const match = new RegExp(`^[ \\t]*\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'im').exec(content) ??
         new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im').exec(content);
     if (!match)
         return null;
@@ -396,8 +396,9 @@ function stateFieldContinuation(content, fieldName) {
 }
 function stateExtractField(content, fieldName) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
-    // Bold inline format: **FieldName:** value
-    const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
+    // Bold line-start format: **FieldName:** value. Leading same-line whitespace
+    // matches the writer's established indented-field tolerance.
+    const boldPattern = new RegExp(`^[ \\t]*\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'im');
     const boldMatch = content.match(boldPattern);
     if (boldMatch)
         return boldMatch[1].trim();
@@ -540,7 +541,22 @@ function stateReplaceField(content, fieldName, newValue) {
     // `(.*)` captured the following line and the rebuild discarded it — the #4010
     // data-loss. ADR-3180 §7.7 makes stateExtractField the same-line-confined owner;
     // this aligns the writer to it.
-    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*[ \\t]*)(.*)`, 'i');
+    //
+    // #4243: the bold form is also ANCHORED to line start, with same-line leading
+    // whitespace only. The pre-fix pattern carried no `^` and no `m` flag, so a
+    // bold label quoted MID-SENTENCE inside prose — an Accumulated Context bullet
+    // mentioning `**Status:**` — captured the rewrite and destroyed the rest of
+    // its line, silently, whenever a whole-body caller fed this function every
+    // section (beginPhaseCore's tryField, advancePlanCore's Status/Current Plan
+    // writes). The plain branch below was always line-anchored; only the bold
+    // branch lagged. Anchoring reuses #4010's same-line confinement idiom (the
+    // leading class is `[ \t]*`, deliberately NOT the `\s*` the issue suggested —
+    // `^\s*\*\*` can consume the newlines before the label into the match and
+    // drop them on rebuild) and #4186's recognition-by-anchoring discipline: a
+    // write target must BE the whole declared line shape, never a substring
+    // guess inside prose. `$` is explicit-and-inert (`.` never crosses line
+    // terminators) and documents that the match ends at end-of-line.
+    const boldPattern = new RegExp(`^([ \\t]*\\*\\*${escaped}:\\*\\*[ \\t]*)(.*)$`, 'im');
     if (boldPattern.test(content)) {
         return content.replace(boldPattern, (_match, prefix) => joinFieldReplacement(prefix, newValue));
     }
@@ -595,31 +611,117 @@ function stateReplaceFieldInSession(content, primary, fallback, value) {
     const target = hasCanonicalSession ? isSession : isSessionContinuity;
     return (0, markdown_sectionizer_cjs_1.withSection)(content, target, (sectionBody) => stateReplaceFieldWithFallback(sectionBody, primary, fallback, value));
 }
+/**
+ * #4186: the DECLARED raw-status vocabulary `normalizeStateStatus` recognizes.
+ * Keys are whole-field values, compared against the caller's input after
+ * lowercasing, trimming, and collapsing internal whitespace runs to single
+ * spaces — so case and whitespace variants the vocabulary documents
+ * (`EXECUTING PHASE 5`, `  Paused  `, `In   progress`) keep normalizing.
+ * Values are members of `STATUS_LIFECYCLE_ENUM` (`src/state-md-schema.cts`)
+ * — the set the normalizer maps recognized input ONTO.
+ *
+ * The mapping preserves the PRE-#4186 branch ORDER's observable artifacts for
+ * every value the old substring chain recognized: `Planning complete` →
+ * `planning` (the `planning` branch outranked `complete`) and
+ * `Phase complete — ready for verification` → `verifying` (`verif` outranked
+ * `complete`; pinned by tests/state.test.cjs's advance-plan case-5 comment).
+ *
+ * Everything else — prose that merely CONTAINS a status word — falls through
+ * to the caller's raw value (the recorded lenient fallback, #3873 phase-3
+ * row 26). A token guessed from a substring inside a sentence is worse than
+ * a visible paragraph: the paragraph is visibly prose, the wrong token is
+ * not (a `.planning/` path in Italian prose silently produced
+ * `status: planning`; `verificata` produced `verifying`; `completezza`
+ * produced `completed`).
+ */
+exports.STATUS_EXACT_TOKENS = Object.freeze({
+    paused: 'paused',
+    stopped: 'paused',
+    executing: 'executing',
+    'in progress': 'executing',
+    'ready to execute': 'executing',
+    planning: 'planning',
+    'ready to plan': 'planning',
+    'planning complete': 'planning',
+    discussing: 'discussing',
+    verifying: 'verifying',
+    completed: 'completed',
+    done: 'completed',
+    complete: 'completed',
+    'phase complete': 'completed',
+    // advance-plan's phase-complete write (state-transition.cts:1812) — maps
+    // to `verifying`, preserving the pre-#4186 branch order where `verif`
+    // outranked `complete`.
+    'phase complete — ready for verification': 'verifying',
+    'all phases complete': 'completed',
+    // Legacy bare terminal form. ADR-2207/#2204 removed it from every WRITER
+    // (phase verbs write `All phases complete`; milestone close writes
+    // `<version> milestone complete`) — kept here as READER recognition so a
+    // legacy STATE.md still normalizes, exactly the way KNOWN_TEMPLATE_DEFAULTS
+    // keeps the other legacy Status strings.
+    'milestone complete': 'completed',
+    unknown: 'unknown',
+});
+/**
+ * #4186: ANCHORED patterns for handler-written raw statuses whose text
+ * carries a variable component (a phase number, a milestone version, a
+ * #1070 completion glyph). Each pattern is matched against the same
+ * normalized key as `STATUS_EXACT_TOKENS` (lowercased, trimmed,
+ * whitespace-collapsed) and must match the WHOLE value — never a substring —
+ * mirroring how `KNOWN_STATUS_PATTERNS` anchors its template-default checks.
+ * `Executing Phase 5 — final stretch` (executor-appended prose) matches
+ * NOTHING and passes through verbatim, the same discipline #1070 applies to
+ * "Complete but needs manual QA".
+ */
+exports.STATUS_ANCHORED_PATTERNS = Object.freeze([
+    // begin-phase / planned transitions write `Executing Phase ${N}`.
+    [/^executing phase\s+\S+$/, 'executing'],
+    [/^planning phase\s+\S+$/, 'planning'],
+    [/^verifying phase\s+\S+$/, 'verifying'],
+    // phase-complete verbs write `Phase ${N} complete` (state.cts) — the exact
+    // shape the #3578 demote guard then re-checks against the disk counters.
+    [/^phase\s+\S+\s+complete$/, 'completed'],
+    // milestoneCompleteCore writes `${version} milestone complete` (terminal,
+    // ADR-2207); the version label is a single token (milestone.cts's charset
+    // validation admits letters, digits, '.', '-', '_').
+    [/^\S+\s+milestone complete$/, 'completed'],
+    // #1070: LLM executors may write "Complete ✓" or bare "Complete" when
+    // finishing a phase.
+    [/^complete\s*[✓✔✅☑]?$/, 'completed'],
+]);
+/**
+ * Normalize a raw `Status` body-field value to the canonical status token.
+ *
+ * #4186: recognition is ANCHORED — the whole field value (lowercased,
+ * trimmed, whitespace-collapsed) must be a member of the declared vocabulary
+ * (`STATUS_EXACT_TOKENS` / `STATUS_ANCHORED_PATTERNS` above). The pre-#4186
+ * implementation ran a first-match-wins chain of SUBSTRING tests over the
+ * free-prose field, so any prose merely CONTAINING a trigger word was
+ * silently rewritten to a credible wrong token: a `.planning/...` path
+ * mentioned in a non-English status line landed on `planning` (the trigger
+ * word lives in the directory name and outranked the `verif`/`complete`
+ * branches), Italian `verifica*` landed on `verifying`, `completezza` and
+ * `fasi complete` landed on `completed`. The lenient FALLBACK is unchanged
+ * and recorded (#3873 phase-3 row 26): an unrecognized value passes through
+ * verbatim — visible prose, never a guessed token.
+ *
+ * `pausedAt` keeps its documented force (issue #4186: intended behavior): a
+ * truthy value yields `paused` regardless of the prose.
+ */
 function normalizeStateStatus(status, pausedAt) {
-    let normalizedStatus = status || 'unknown';
-    const statusLower = (status || '').toLowerCase();
-    if (statusLower.includes('paused') || statusLower.includes('stopped') || pausedAt) {
-        normalizedStatus = 'paused';
-    }
-    else if (statusLower.includes('executing') || statusLower.includes('in progress')) {
-        normalizedStatus = 'executing';
-    }
-    else if (statusLower.includes('planning') || statusLower.includes('ready to plan')) {
-        normalizedStatus = 'planning';
-    }
-    else if (statusLower.includes('discussing')) {
-        normalizedStatus = 'discussing';
-    }
-    else if (statusLower.includes('verif')) {
-        normalizedStatus = 'verifying';
-    }
-    else if (statusLower.includes('complete') || statusLower.includes('done')) {
-        normalizedStatus = 'completed';
-    }
-    else if (statusLower.includes('ready to execute')) {
-        normalizedStatus = 'executing';
+    if (pausedAt)
+        return 'paused';
+    if (!status)
+        return 'unknown';
+    const key = status.trim().toLowerCase().replace(/\s+/g, ' ');
+    const exact = exports.STATUS_EXACT_TOKENS[key];
+    if (exact)
+        return exact;
+    for (const [pattern, token] of exports.STATUS_ANCHORED_PATTERNS) {
+        if (pattern.test(key))
+            return token;
     }
-    return normalizedStatus;
+    return status;
 }
 /**
  * ADR-3180 §7.6 rule 4 (#3217): `scope` is the `listMilestonePhaseDirs`-owner

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

@@ -43,24 +43,31 @@ exports.STATE_FIELD_SCHEMA = exports.STATUS_LIFECYCLE_ENUM = void 0;
 /**
  * The seven CANONICAL values `normalizeStateStatus` (`src/state-document.cts`)
  * maps recognized raw status prose TO — the function's default fallback plus
- * each branch's literal output, in the order the function tests them. This is
- * NOT the raw body prose vocabulary `CONTEXT.md`'s "STATE.md Status Lifecycle
- * (ADR-2207)" entry documents (`Ready to plan` → `All phases complete` →
- * `<version> milestone complete` → `Awaiting next milestone`, plus the
- * handler-authored strings in `KNOWN_TEMPLATE_DEFAULTS['Status']`) — that is
- * free-form prose `normalizeStateStatus` READS.
+ * each vocabulary entry's literal output. This is NOT the raw body prose
+ * vocabulary `CONTEXT.md`'s "STATE.md Status Lifecycle (ADR-2207)" entry
+ * documents (`Ready to plan` → `All phases complete` → `<version> milestone
+ * complete` → `Awaiting next milestone`, plus the handler-authored strings
+ * in `KNOWN_TEMPLATE_DEFAULTS['Status']`) — that is free-form prose
+ * `normalizeStateStatus` READS.
  *
  * CORRECTED (#3873 phase-3 test-matrix row 26 — verified by executing
  * `normalizeStateStatus`, not by reading this docstring's prior claim):
  * this is NOT a closed set the `status` frontmatter key is restricted to at
- * runtime. `normalizeStateStatus` is deliberately LENIENT: its fallback is
- * `normalizedStatus = status || 'unknown'`, and when none of its
- * substring-match branches recognize the raw input, that fallback — the
- * caller's raw, UNRECOGNIZED prose — is returned unchanged. A status value
- * outside this seven-member set is not rejected, coerced, or normalized; it
- * passes straight through into the frontmatter. `STATUS_LIFECYCLE_ENUM` is
- * therefore the set of values the normalizer maps recognized input ONTO, not
- * a runtime-enforced closed vocabulary for the field.
+ * runtime. `normalizeStateStatus` is deliberately LENIENT: its fallback
+ * returns the caller's raw, UNRECOGNIZED prose unchanged — when none of its
+ * vocabulary entries recognize the whole-field input, that raw value is what
+ * the function returns. A status value outside this seven-member set is not
+ * rejected, coerced, or normalized; it passes straight through into the
+ * frontmatter. `STATUS_LIFECYCLE_ENUM` is therefore the set of values the
+ * normalizer maps recognized input ONTO, not a runtime-enforced closed
+ * vocabulary for the field.
+ *
+ * #4186: recognition is ANCHORED (whole-field match against the declared
+ * `STATUS_EXACT_TOKENS` / `STATUS_ANCHORED_PATTERNS` tables in
+ * `src/state-document.cts`), never a substring scan of the prose — prose
+ * merely CONTAINING a status word (a `.planning/` path, `verifica*`,
+ * `completezza`) passes through verbatim instead of being rewritten to a
+ * credible wrong token.
  */
 exports.STATUS_LIFECYCLE_ENUM = Object.freeze([
     'unknown',