@opengsd/gsd-core 1.14.0 → 1.16.0

package/gsd-core/bin/lib/stale-bake-guard.cjs

@@ -21,22 +21,23 @@
 const fs = require('fs');
 const path = require('path');
 const os = require('os');
+const capabilityRegistry = require('./capability-registry.cjs');
+const { hostBehaviorsFor } = require('./runtime-name-policy.cjs');
+const { resolveConfigHomeFromDescriptor } = require('./runtime-homes.cjs');
+const { resolveActiveRuntime } = require('./runtime-slash.cjs');
 
 /**
- * Runtimes whose agent config is static frontmatter/TOML baked at install time.
- * MUST stay in sync with the bake paths in bin/install.js. The parity test in
- * tests/stale-bake-guard.test.cjs asserts this matches the runtimes that
- * actually emit a baked model: line id #2256 (opencode), #49/#2256 (codex),
- * and #2093 (kilo).
+ * Runtimes whose agent config is static frontmatter/TOML baked at install time,
+ * DERIVED from the runtime descriptors (`hostBehaviors.bakesStaticAgentModel`,
+ * #5169) instead of a hand-kept list: line id #2256 (opencode), #49/#2256
+ * (codex), and #2093 (kilo) declare it, and a new baking runtime does too.
  */
-const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(['codex', 'kilo', 'opencode']);
+const STATIC_FRONTMATTER_RUNTIMES = Object.freeze(
+  Object.keys(capabilityRegistry.runtimes)
+    .filter((id) => hostBehaviorsFor(id).bakesStaticAgentModel === true)
+    .sort(),
+);
 
-/** Per-runtime `gsd install` flag, for the remediation hint in the warning. */
-const INSTALL_FLAG_BY_RUNTIME = Object.freeze({
-  codex: '--codex',
-  opencode: '--opencode',
-  kilo: '--kilo',
-});
 
 const _warnedKeys = new Set();
 
@@ -64,7 +65,7 @@ function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtime
   const signal = detectStaleBake({ runtime, configMtimeMs, agentMtimeMs });
   if (!signal) return '';
   const configDate = new Date(configMtimeMs).toISOString();
-  const installFlag = INSTALL_FLAG_BY_RUNTIME[runtime] || `--${runtime}`;
+  const installFlag = `--${runtime}`;
   return [
     `gsd: model config in ${configPath} changed since agents were last baked (${configDate}).`,
     `     Static-frontmatter runtime '${runtime}' ignores the new model_overrides`,
@@ -74,44 +75,27 @@ function formatStaleBakeWarning({ runtime, configPath, configMtimeMs, agentMtime
 }
 
 /**
- * Pure: resolve the active runtime id from a parsed config object.
- * Returns the runtime string, or `'claude'` when unset (the spawn-time default
- * for which the guard is a no-op).
+ * Resolve the active runtime id for the guard: the SAME chain every consumer of
+ * "which runtime is this install" reads — GSD_RUNTIME → config.runtime →
+ * per-install `.gsd-runtime` marker → `'claude'` (#5169, #4690). Returns
+ * `'claude'` when nothing is declared (the spawn-time default for which the
+ * guard is a no-op).
  */
-function resolveRuntimeFromConfig(config) {
-  if (config && typeof config === 'object'
-      && typeof config.runtime === 'string' && config.runtime) {
-    return config.runtime;
-  }
-  return 'claude';
+function resolveRuntimeFromConfig(config, env = process.env) {
+  return resolveActiveRuntime(config, env);
 }
 
 /**
- * Resolve the install root for a runtime's agent files, honoring the same env
- * vars the installer does (CODEX_HOME, OPENCODE_CONFIG_DIR, KILO_CONFIG_DIR).
- * Returns the absolute directory or `null` for unsupported runtimes.
+ * Resolve the install root for a runtime's agent files from the runtime
+ * descriptor's `configHome` (the same resolution the installer uses), then
+ * append `agents` — the installer writes agents to `<configHome>/agents`
+ * (plural; #2093). Returns the absolute directory or `null` for runtimes that
+ * do not bake a static agent model.
  */
 function resolveAgentDir(runtime, { env = process.env, homedir = os.homedir } = {}) {
-  if (runtime === 'opencode') {
-    const base = (env.OPENCODE_CONFIG_DIR && String(env.OPENCODE_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'opencode');
-    // #2093 fix: the installer writes agents to `<base>/agents` (plural — see
-    // bin/install.js's universal `agentsDest = path.join(targetDir, 'agents')`,
-    // verified against a live `--opencode --global` install). The prior
-    // singular `agent` never matched the real install output, so this guard's
-    // `findOldestAgentMtime` always hit ENOENT and warnIfStaleBake was a
-    // silent no-op for opencode in production — discovered while wiring the
-    // parallel kilo entry below (same bake mechanism, #2093).
-    return path.join(base, 'agents');
-  }
-  if (runtime === 'kilo') {
-    const base = (env.KILO_CONFIG_DIR && String(env.KILO_CONFIG_DIR).trim()) || path.join(homedir(), '.config', 'kilo');
-    return path.join(base, 'agents');
-  }
-  if (runtime === 'codex') {
-    const base = (env.CODEX_HOME && String(env.CODEX_HOME).trim()) || path.join(homedir(), '.codex');
-    return path.join(base, 'agents');
-  }
-  return null;
+  if (!STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return null;
+  const configHome = capabilityRegistry.runtimes[runtime].runtime.configHome;
+  return path.join(resolveConfigHomeFromDescriptor(configHome, { env, home: homedir() }), 'agents');
 }
 
 /**
@@ -168,8 +152,8 @@ function findOldestAgentMtime(runtime, { env = process.env, homedir = os.homedir
   for (const entry of entries) {
     if (!entry.isFile()) continue;
     if (!entry.name.startsWith('gsd-')) continue;
-    const isAgentFile = ((runtime === 'opencode' || runtime === 'kilo') && entry.name.endsWith('.md'))
-      || (runtime === 'codex' && (entry.name.endsWith('.toml') || entry.name.endsWith('.md')));
+    const bakedExts = hostBehaviorsFor(runtime).bakedAgentFileExtensions;
+    const isAgentFile = Array.isArray(bakedExts) && bakedExts.some((ext) => entry.name.endsWith(ext));
     if (!isAgentFile) continue;
     try {
       const st = fsStatSync(path.join(dir, entry.name));
@@ -209,7 +193,7 @@ function warnIfStaleBake(cwd, options = {}) {
   } = options;
   try {
     const resolvedConfig = config || _readRuntimeConfig(cwd, { fsStatSync });
-    const runtime = resolveRuntimeFromConfig(resolvedConfig);
+    const runtime = resolveRuntimeFromConfig(resolvedConfig, env);
     if (!STATIC_FRONTMATTER_RUNTIMES.includes(runtime)) return false;
 
     const dedupKey = `${runtime}::${path.resolve(cwd || '.')}`;

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

@@ -73,6 +73,12 @@ exports.buildStateContract = buildStateContract;
 exports.publishStateContract = publishStateContract;
 const node_path_1 = __importDefault(require("node:path"));
 const node_fs_1 = __importDefault(require("node:fs"));
+// #5060: `phase-status.cjs` is a LOAD-TIME LEAF — no top-level requires of
+// its own (verification.cjs/plan-scan.cjs are required lazily, only inside
+// `phaseStatus()`) — so importing it here at top level does not reopen the
+// documented `state.cjs -> state-contract.cjs -> smart-entry.cjs -> state.cjs`
+// require cycle the file header warns about.
+const phase_status_cjs_1 = require("./phase-status.cjs");
 // ─── Public wire vocabulary ────────────────────────────────────────────────
 exports.STATE_CONTRACT_VERSION = '1.0.0';
 exports.STATE_CONTRACT_FLAVOR = 'core';
@@ -80,12 +86,14 @@ exports.STATE_CONTRACT_FLAVOR = 'core';
 exports.CONTRACT_KEY_ORDER = Object.freeze(['contract', 'flavor', 'milestone', 'phases', 'next', 'updated_at']);
 /** Key order of each emitted phase object — an observable, pinned by test. */
 exports.PHASE_KEY_ORDER = Object.freeze(['number', 'name', 'status']);
-/** Frozen three-value phase status vocabulary. Conservative in what we send (Postel's Law). */
-exports.PHASE_STATUS = Object.freeze({
-    COMPLETE: 'complete',
-    IN_PROGRESS: 'in_progress',
-    PENDING: 'pending',
-});
+/**
+ * Frozen three-value phase status vocabulary. Conservative in what we send
+ * (Postel's Law). #5060: identity-pinned to the Phase Status Module's own
+ * `WIRE_STATUS` — this is not a copy, it IS that frozen object, so
+ * `state-contract`'s `PHASE_STATUS` and `phase-status.cjs`'s `WIRE_STATUS`
+ * can never independently drift.
+ */
+exports.PHASE_STATUS = phase_status_cjs_1.WIRE_STATUS;
 /** Frozen `publishStateContract` result reasons. */
 exports.PUBLISH_REASON = Object.freeze({
     PUBLISHED: 'published',
@@ -146,17 +154,6 @@ function buildMilestone(cwd) {
 }
 // ─── phases: Progress-table (primary) enumerator ───────────────────────────
 const PHASE_CELL_RE = /^(\d+(?:\.\d+)*)\s*[.:)–—-]?\s*(.*)$/;
-function statusFromProgressCell(raw) {
-    const normalized = (raw ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
-    if (normalized === 'complete')
-        return exports.PHASE_STATUS.COMPLETE;
-    if (normalized === 'in progress')
-        return exports.PHASE_STATUS.IN_PROGRESS;
-    // Everything else — 'not started', 'deferred' (design row 12, lossy by
-    // design), '', and any unrecognized word — folds to pending. An
-    // unrecognized status must never reach the wire as a 4th value.
-    return exports.PHASE_STATUS.PENDING;
-}
 function phasesFromProgressTable(table) {
     const { isSentinelPhaseId } = owners();
     const phases = [];
@@ -169,7 +166,7 @@ function phasesFromProgressTable(table) {
         const m = PHASE_CELL_RE.exec(cell);
         const number = m ? m[1] : cell;
         const name = m && m[2].trim().length > 0 ? m[2].trim() : null;
-        phases.push({ number, name, status: statusFromProgressCell(row['Status']) });
+        phases.push({ number, name, status: (0, phase_status_cjs_1.parseRoadmapStatusCell)(row['Status']) });
     }
     return phases;
 }

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

@@ -30,6 +30,7 @@ const markdown_table_cjs_1 = require("./markdown-table.cjs");
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
 const markdown_sectionizer_cjs_1 = require("./markdown-sectionizer.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
+const planning_document_cjs_1 = require("./planning-document.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -536,29 +537,106 @@ function joinFieldReplacement(prefix, newValue) {
 function stateReplaceField(content, fieldName, newValue) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);
     // Bold inline format: **FieldName:** value
-    // The label-to-value gap is same-line whitespace only (`[ \t]*`, mirroring the
-    // read side at stateExtractField). `\s*` here matched `\n`, so on an empty field
-    // `(.*)` 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.
     //
-    // #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));
+    // #5007 (Phase 6 / ADR-4910 amendment): migrated off the hand-rolled
+    // `^([ \t]*\*\*${escaped}:\*\*[ \t]*)(.*)$` regex (which, per #4010/#4243
+    // below, already existed to fix real same-line-confinement and mid-prose
+    // data-loss bugs) onto `parsePlanningDoc` for LOCATING the field — same-
+    // line confinement AND fence/frontmatter exclusion (parseBoldFieldLine
+    // never matches inside a fenced block or frontmatter, which the removed
+    // regex could not tell apart from prose) — so this migration keeps
+    // #4010/#4243's fix and extends it, rather than replacing it with a
+    // weaker check.
+    //
+    // This does NOT go through the seam's `setFieldValue`/`serialize` write
+    // path. An earlier version of this migration did, via a since-removed
+    // `setFieldValue({ allowSeparator: true })` option (#5007) — that option
+    // spliced the caller's value across the FULL rest-of-line span
+    // (`valueSpan.start`..`trailingSpan.end`) to permit a value containing the
+    // grammar's ` — ` trailing-separator token (needed here: see the
+    // `${currentPhase} — COMPLETE` value below). It was removed after a
+    // failing-first reproduction proved it only avoided the write-time
+    // refusal: the bytes it writes are correct, but `parseBoldFieldLine`
+    // splits on ` — ` unconditionally on every read, with no escaping
+    // convention in this grammar to tell "atomic value containing the token"
+    // apart from "value plus hand-annotation". So the NEXT fresh
+    // `parsePlanningDoc` of that exact text — not the in-memory doc the
+    // option's own tests checked — silently re-truncates the value and
+    // demotes the rest to `trailingSpan`, with `findField`/`readNode`
+    // reporting a confident, wrong `ok: true` and no error. That is exactly
+    // the #4917 finding-2 corruption `setFieldValue`'s round-trip check
+    // exists to prevent, just moved one parse cycle downstream. This call
+    // site never reads STATE.md fields back through `parsePlanningDoc`/
+    // `findField` (reads go through `stateExtractField`'s own non-splitting
+    // regex, below), so it is safe HERE — but making that a shared, public
+    // option on the seam's `setFieldValue` was an attractive nuisance for any
+    // future `findField`/`readNode` caller (this same module already serves
+    // ROADMAP.md's `Plans`/`Depends on` fields that way). The full-rest-of-
+    // line splice is done locally, directly against `content`, instead —
+    // `parsePlanningDoc` is used only to locate the field's spans.
+    //
+    // Two deliberate deviations from a bare findField() call, both
+    // PRESERVING this function's own prior contract rather than adopting the
+    // seam's stricter defaults:
+    //
+    //  1. Label lookup here is case-INSENSITIVE (not findField's exact
+    //     match), mirroring the removed regex's `i` flag: callers in
+    //     state.cts/state-transition.cts pass a fieldName spelling that can
+    //     differ only in case from what a given template actually has (the
+    //     explicit 'Last Activity' / 'Last activity' fallback-call pairs at
+    //     those call sites), so a case-sensitive lookup would silently miss
+    //     matches the removed regex used to find.
+    //  2. Every write below replaces the FULL rest-of-line span
+    //     (`valueSpan.start`..`trailingSpan.end`) UNCONDITIONALLY, not only
+    //     when `newValue` contains the grammar's ` — ` separator token,
+    //     because `joinFieldReplacement` always discarded the OLD regex's
+    //     entire captured tail (`(.*)$` — both what the seam calls
+    //     `valueSpan` AND `trailingSpan`) and replaced it wholesale with the
+    //     new value. This call site never had a "preserve a hand-written
+    //     trailing annotation" contract, so writing anything narrower than
+    //     the full rest-of-line span here would be a NEW, untested behavior
+    //     this migration must not introduce as a side effect.
+    //
+    // Matching BOTH bold-placement spellings (`**Label:**` and `**Label**:`,
+    // `BOLD_FIELD_RE`) where the removed regex recognized only `**Label:**`
+    // is the same, already-precedented widening as the "Depends on"
+    // migration (src/phase.cts) — intentional, not scope creep.
+    //
+    // A parse failure, an absent/case-mismatched label, or a value containing
+    // a line break (\r/\n — would forge sibling structure on splice, the same
+    // hazard `setFieldValue` refuses unconditionally at #4917/ADR-4910
+    // Decision 2 & 4; this local splice has no seam call to inherit that
+    // refusal from, so it is re-checked here) falls through to the
+    // plain/pipe-table branches below unchanged — the same silent
+    // per-occurrence no-op-on-no-match contract the removed regex had for any
+    // input it didn't match.
+    const parsed = (0, planning_document_cjs_1.parsePlanningDoc)(content, 'STATE.md');
+    if (parsed.ok) {
+        let boldField = null;
+        for (const node of parsed.value.nodes) {
+            if (node.kind !== 'boldField')
+                continue;
+            if (node.label.toLowerCase() !== fieldName.toLowerCase())
+                continue;
+            boldField = node;
+            break;
+        }
+        if (boldField) {
+            // Replicates joinFieldReplacement's own `` `${newValue}` `` coercion
+            // (a caller may pass a non-string, e.g. a number, at the JS boundary
+            // even though the type signature says `string`) before the
+            // missing-separator normalization below: insert a single space when
+            // the existing label-to-value gap has none, so `**Status:**value`
+            // still becomes `**Status:** value` rather than gluing the two
+            // together.
+            const spacingText = parsed.value.source.slice(boldField.labelSpan.end, boldField.valueSpan.start);
+            const newValueStr = `${newValue}`;
+            const needsSeparator = newValueStr.length > 0 && !/[ \t]$/.test(spacingText);
+            const writeValue = `${needsSeparator ? ' ' : ''}${newValueStr}`;
+            if (!/[\r\n]/.test(writeValue)) {
+                return (content.slice(0, boldField.valueSpan.start) + writeValue + content.slice(boldField.trailingSpan.end));
+            }
+        }
     }
     // Plain line-start format: FieldName: value (same same-line confinement as above)
     const plainPattern = new RegExp(`(^${escaped}:[ \\t]*)(.*)`, 'im');

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

@@ -25,6 +25,7 @@ exports.getFieldClassification = getFieldClassification;
 exports.getPreserveWhenUnchangedFields = getPreserveWhenUnchangedFields;
 exports.openStateTransaction = openStateTransaction;
 exports.rebuildStateTransaction = rebuildStateTransaction;
+exports.createStateWriteIntent = createStateWriteIntent;
 exports.applyPreserveWhenUnchanged = applyPreserveWhenUnchanged;
 exports.applyStatePreservation = applyStatePreservation;
 exports.transitionCore = transitionCore;
@@ -401,6 +402,28 @@ function openStateTransaction(init) {
 function rebuildStateTransaction(init) {
     return createStateTransaction('rebuild', init, 'rebuildStateTransaction');
 }
+/**
+ * Extend an existing StateTransaction into a StateWriteIntent. The base
+ * transaction is REQUIRED — an absent base is a construction failure, mirroring
+ * `createStateTransaction`'s ADR-3473 §8.6 posture (do not tolerate null). `scope`
+ * defaults to the conservative `'narrow'`; `assertions` defaults to none. Frozen
+ * so an intent, like a transaction, cannot be mutated after construction.
+ */
+function createStateWriteIntent(transaction, init = {}) {
+    if (transaction === null || typeof transaction !== 'object' || Array.isArray(transaction)) {
+        const err = new Error('createStateWriteIntent: a base StateTransaction is required (build it with ' +
+            'openStateTransaction / rebuildStateTransaction first). Per ADR-4629 §8.1, an absent ' +
+            'transaction is a construction failure — do not tolerate null.');
+        err.code = 'STATE_WRITE_INTENT_TRANSACTION_REQUIRED';
+        throw err;
+    }
+    const assertions = Object.freeze((init.assertions ?? []).map((a) => Object.freeze({ field: a.field, requirement: a.requirement })));
+    return Object.freeze({
+        ...transaction,
+        assertions,
+        scope: init.scope ?? 'narrow',
+    });
+}
 /**
  * ADR-3408 §8.2: an unenforced `preserve-when-unchanged` row throws. Both
  * ends of this invariant are gsd-core's own source — a declared row the
@@ -1648,8 +1671,22 @@ function completePhaseCore(content, intent, deps) {
         body = statusAfter;
         updated.push('Status');
     }
-    // Current Plan — reset for the next phase.
-    const planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', 'Not started');
+    // Current Plan — reset for the next phase. #4823: when a Current Position
+    // section exists (the canonical layout, #2956 locator), the reset is scoped
+    // to it — the whole-body fallback 'Plan' run matched any hard-wrapped prose
+    // line starting with `plan:` anywhere in the document and rewrote it to
+    // 'Not started', silently destroying narrative. Legacy sectionless layouts
+    // (fields at top level, no section) keep the whole-body behavior unchanged:
+    // there is no section to scope to, and their fields are the intended
+    // targets.
+    let planAfter;
+    const positionScope = (0, state_document_cjs_1.stateCurrentPositionSlice)(body);
+    if (positionScope !== null) {
+        planAfter = (0, markdown_sectionizer_cjs_1.withSection)(body, (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position', (sectionBody) => (0, state_document_cjs_1.stateReplaceFieldWithFallback)(sectionBody, 'Current Plan', 'Plan', 'Not started'), { levelBounded: true });
+    }
+    else {
+        planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', 'Not started');
+    }
     if (planAfter !== body) {
         body = planAfter;
         updated.push('Current Plan');