@opengsd/gsd-core 1.15.0 → 1.17.0

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

@@ -25,7 +25,7 @@ const coreUtils = require("./core-utils.cjs");
 const { normalizeLineEndings } = coreUtils;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningWorkspace = require("./planning-workspace.cjs");
-const { planningDir, quickDirFrom, todosDir } = planningWorkspace;
+const { planningDir, quickDirFrom, debugDir, todosDir } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
 // #4378 (roll-in): scanSeeds publishes the SAME canonical seed identity the
@@ -33,7 +33,7 @@ const frontmatter = require("./frontmatter.cjs");
 // does not require this module, so the edge is acyclic.
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const commandsModule = require("./commands.cjs");
-const { extractFrontmatter, FRONTMATTER_UNPARSEABLE, spliceFrontmatter } = frontmatter;
+const { extractFrontmatter, frontmatterBlock, spliceFrontmatter, isFrontmatterWriteRefusal } = frontmatter;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
 const { PHASE_NUMBER_TOKEN_SOURCE, scopeToPhase } = phaseIdMod;
@@ -46,6 +46,11 @@ const shell_command_projection_cjs_2 = require("./shell-command-projection.cjs")
 const io = require("./io.cjs");
 const { output, error: ioError } = io;
 const command_arg_projection_cjs_1 = require("./command-arg-projection.cjs");
+// #5118: the verification-status owner's report reader and closed enum.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const verificationMod = require("./verification.cjs");
+const { reportStatusOf, VERIFICATION_STATUS, VerificationStatusError } = verificationMod;
+const clock_cjs_1 = require("./clock.cjs");
 // The SCOPE BOUNDARY convention's filename (`agents/gsd-executor.md`), shared
 // verbatim with the #2287 phase-boundary reader in `uat.cts`.
 const DEFERRED_ITEMS_FILENAME = 'deferred-items.md';
@@ -257,19 +262,27 @@ function deriveOpenQuestionsDigest(questions) {
 }
 // ─── scanDebugSessions ────────────────────────────────────────────────────────
 /**
- * Scan .planning/debug/ for open sessions.
+ * #4869: gsd-debugger's archive_session step appends every resolved session to
+ * this file in the debug directory. It is a document, not a session: it has no
+ * frontmatter, so its status would derive `unknown` and read as open forever.
+ * Excluded by this fixed name only. Any other file with missing or unparseable
+ * frontmatter is still an open session. Every shipped debug-directory reader
+ * excludes the same name from active sessions (#5011).
+ */
+const DEBUG_KNOWLEDGE_BASE_FILENAME = 'knowledge-base.md';
+/**
+ * Scan the root-scoped .planning/debug/ directory supplied by the caller for open sessions.
  * Open = status NOT in ['resolved', 'complete'].
- * Ignores the resolved/ subdirectory.
+ * Ignores the resolved/ subdirectory and the debugger's knowledge base.
  */
-function scanDebugSessions(planDir) {
-    const debugDir = node_path_1.default.join(planDir, 'debug');
-    if (!node_fs_1.default.existsSync(debugDir))
+function scanDebugSessions(debugPath) {
+    if (!node_fs_1.default.existsSync(debugPath))
         return { items: [], acknowledged: 0 };
     const results = [];
     let acknowledged = 0;
     let files;
     try {
-        files = node_fs_1.default.readdirSync(debugDir, { withFileTypes: true });
+        files = node_fs_1.default.readdirSync(debugPath, { withFileTypes: true });
     }
     catch {
         return { items: [{ scan_error: true, slug: '', status: '', updated: '', hypothesis: '' }], acknowledged: 0 };
@@ -279,10 +292,12 @@ function scanDebugSessions(planDir) {
             continue;
         if (!entry.name.endsWith('.md'))
             continue;
-        const filePath = node_path_1.default.join(debugDir, entry.name);
+        if (entry.name === DEBUG_KNOWLEDGE_BASE_FILENAME)
+            continue;
+        const filePath = node_path_1.default.join(debugPath, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'debug session file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, node_path_1.default.dirname(debugPath), 'debug session file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -291,9 +306,9 @@ function scanDebugSessions(planDir) {
         // document at this read boundary, same seam as `src/uat.cts`'s
         // `readNormalizedDocument` — `platformReadSync` performs no line-ending
         // normalization itself, and extractFrontmatter/status-derivation below
-        // degrade a lone-CR file's frontmatter to `unknown`, which every scan
-        // in this module treats as "not open" (fail-open, the permissive
-        // direction) rather than a real parse gap.
+        // degrade a lone-CR file's frontmatter to `unknown`, which this scan
+        // reports as an open session (#4869) — so an un-normalized resolved
+        // session would resurface as open.
         const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
         if (rawContent === null)
             continue;
@@ -591,9 +606,11 @@ function scanTodos(todosBase) {
     }
     const displayFiles = openFiles.slice(0, 5);
     for (const { entry, content, fm } of displayFiles) {
-        // Extract first line of body after frontmatter
-        const bodyMatch = content.replace(/^---[\s\S]*?---\r?\n?/, '');
-        const firstLine = (0, text_lines_cjs_1.splitLines)(bodyMatch.trim())[0] || '';
+        // Extract first line of body after frontmatter — the block `extractFrontmatter` read above
+        // (the one fence owner), so a `---` inside a value cannot end it early.
+        const block = frontmatterBlock(content);
+        const todoBody = block ? block.rest : content;
+        const firstLine = (0, text_lines_cjs_1.splitLines)(todoBody.trim())[0] || '';
         const summary = (0, security_cjs_1.sanitizeForDisplay)(firstLine.slice(0, 100));
         results.push({
             filename: (0, security_cjs_1.sanitizeLabel)(entry.name),
@@ -816,9 +833,9 @@ function scanUatGaps(planDir, cwd) {
             // document at this read boundary, same seam as `src/uat.cts`'s
             // `readNormalizedDocument` — `platformReadSync` performs no line-ending
             // normalization itself, and extractFrontmatter/status-derivation below
-            // degrade a lone-CR file's frontmatter to `unknown`, which every scan
-            // in this module treats as "not open" (fail-open, the permissive
-            // direction) rather than a real parse gap.
+            // degrade a lone-CR file's frontmatter to `unknown`, which this scan
+            // reports as an open gap unless `result: all_pass` (#4869 triage) — so
+            // an un-normalized terminal UAT would resurface as open.
             const rawContent = (0, shell_command_projection_cjs_1.platformReadSync)(safeFilePath);
             if (rawContent === null)
                 continue;
@@ -897,8 +914,10 @@ function scanVerificationGaps(planDir, cwd) {
                 continue;
             const content = normalizeLineEndings(rawContent);
             const fm = extractFrontmatter(content, safeFilePath);
-            const status = (fm.status || 'unknown').toLowerCase();
-            if (status !== 'gaps_found' && status !== 'human_needed')
+            // #5118: the owner's report reader judges `status` — exact match, no
+            // case folding; an out-of-set value throws VerificationStatusError.
+            const status = reportStatusOf(fm, safeFilePath);
+            if (status !== VERIFICATION_STATUS.GAPS_FOUND && status !== VERIFICATION_STATUS.HUMAN_NEEDED)
                 continue;
             if (isAuditItemAcknowledged(fm, { snapshotKey: 'status', currentValue: status })) {
                 acknowledged++;
@@ -1074,8 +1093,10 @@ function scanDeferredItems(planDir, cwd) {
 function auditOpenArtifacts(cwd) {
     const planDir = planningDir(cwd);
     const debugSessions = (() => {
+        // #5042: debug sessions are shared project state; workflow writers use
+        // the root .planning/debug directory even when a workstream is active.
         try {
-            return scanDebugSessions(planDir);
+            return scanDebugSessions(debugDir(cwd));
         }
         catch {
             return { items: [{ scan_error: true, slug: '', status: '', updated: '', hypothesis: '' }], acknowledged: 0 };
@@ -1098,7 +1119,7 @@ function auditOpenArtifacts(cwd) {
         }
     })();
     const todos = (() => {
-        // #4256: the ONE root-scoped category — todos are shared project state,
+        // #4256: todos are shared project state, like debug sessions (#5042),
         // so the close gate reads todosDir(cwd) (the root), not the workstream-
         // scoped planDir every other scan below receives. Reading planDir here
         // made audit-open print "All artifact types clear. Safe to proceed."
@@ -1130,7 +1151,11 @@ function auditOpenArtifacts(cwd) {
         try {
             return scanVerificationGaps(planDir, cwd);
         }
-        catch {
+        catch (err) {
+            // #5118: an out-of-set report status is the owner's hard error, not a
+            // scan failure to fold into a sentinel — let it reach the CLI seam.
+            if (err instanceof VerificationStatusError)
+                throw err;
             return { items: [{ scan_error: true, phase: '', file: '', status: '' }], acknowledged: 0 };
         }
     })();
@@ -1399,6 +1424,26 @@ function resolvePhaseTargetDir(planDir, cwd, phase, archivedMilestone) {
  * artifact identifier that resolves outside the project is refused before
  * any read or write is attempted.
  */
+/**
+ * #4802: splice the acknowledgement marker, surfacing `spliceFrontmatter`'s
+ * write refusal (the one owner of that decision) as an `ioError` naming the
+ * file — an unparseable frontmatter block is NOT an empty one, and splicing
+ * over it would discard every field the author actually wrote.
+ */
+function spliceAcknowledgement(content, fm, fileLabel) {
+    try {
+        return spliceFrontmatter(content, fm);
+    }
+    catch (err) {
+        if (!isFrontmatterWriteRefusal(err))
+            throw err;
+        if (err.code === 'FRONTMATTER_UNPARSEABLE') {
+            ioError(`refusing to acknowledge — the frontmatter of "${fileLabel}" is not parseable YAML (splicing would discard every other frontmatter field); fix the YAML syntax error first, then re-run`);
+        }
+        ioError(`refusing to acknowledge "${fileLabel}" — ${err.message}`);
+        throw err; // unreachable — ioError throws
+    }
+}
 function cmdAuditAcknowledge(cwd, args, raw) {
     // args already has the family + subcommand tokens stripped by the caller
     // (audit-command-router.cts:147 passes `hubArgs.slice(2)`), so validation
@@ -1418,7 +1463,9 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     // All declared flags above are value flags, so each resolves to `string |
     // null` at runtime; the cast narrows away the `boolean` arm of
     // ParsedNamedArgs's value type that this call site never produces.
-    const at = atFlag || new Date().toISOString().slice(0, 10);
+    // #4905: without --at, the operator-facing local calendar day (#2136)
+    // through the clock seam, which honors the GSD_NOW_MS pin (#474).
+    const at = atFlag || clock_cjs_1.realClock.localToday();
     const planDir = planningDir(cwd);
     const markerBase = { milestone: milestone, at };
     // #3078-CR MEDIUM 2: every `fs.readFileSync` in this function (below, and
@@ -1479,13 +1526,6 @@ function cmdAuditAcknowledge(cwd, args, raw) {
         }
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
         const fm = extractFrontmatter(content, safeFilePath);
-        // #4802: an unparseable frontmatter block is NOT an empty one — splicing
-        // the marker-marked object over the file would discard every field the
-        // author actually wrote. Refuse and name the file (the write-path
-        // counterpart of the read-side FRONTMATTER_UNPARSEABLE contract).
-        if (fm[FRONTMATTER_UNPARSEABLE] === true) {
-            ioError(`refusing to acknowledge — the frontmatter of "${file}" is not parseable YAML (splicing would discard every other frontmatter field); fix the YAML syntax error first, then re-run`);
-        }
         // Mixed-frame fix (security review, 4th instance on this branch): the
         // splice above and below stays keyed to RAW `content` (raw byte offsets
         // must not shift), but `scanUatGaps`/`scanContextQuestions` now derive
@@ -1516,7 +1556,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             currentValue = deriveOpenQuestionsDigest(deriveOpenQuestions(normalizedContent, fm));
         }
         fm.audit_acknowledged = { ...markerBase, [snapshotKey]: currentValue };
-        const newContent = spliceFrontmatter(content, fm);
+        const newContent = spliceAcknowledgement(content, fm, file);
         (0, shell_command_projection_cjs_2.platformWriteSync)(safeFilePath, newContent);
         output({ acknowledged: true, category, phase, file, [snapshotKey]: currentValue }, raw, 'true');
         return;
@@ -1645,18 +1685,12 @@ function cmdAuditAcknowledge(cwd, args, raw) {
         return; // unreachable — ioError throws — satisfies TS control-flow analysis
     }
     const presenceOnly = category === 'todos';
-    const fm = createIfMissing ? fmForCreate : extractFrontmatter(node_fs_1.default.readFileSync(safeFilePath, 'utf-8'), safeFilePath);
-    // #4802: same unparseable-frontmatter refusal as the phase-scoped branch —
-    // createIfMissing never reaches this extract (it only fires when the file is
-    // absent), so an existing file with broken YAML refuses instead of splicing
-    // a near-empty object over every field the author wrote.
-    if (!createIfMissing && fm[FRONTMATTER_UNPARSEABLE] === true) {
-        ioError(`refusing to acknowledge — the frontmatter of "${safeFilePath}" is not parseable YAML (splicing would discard every other frontmatter field); fix the YAML syntax error first, then re-run`);
-    }
+    const existingContent = createIfMissing ? '' : node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
+    const fm = createIfMissing ? fmForCreate : extractFrontmatter(existingContent, safeFilePath);
     fm.audit_acknowledged = presenceOnly ? { ...markerBase } : { ...markerBase, [snapshotKey]: currentValue };
-    const newContent = createIfMissing
-        ? spliceFrontmatter('', fm)
-        : spliceFrontmatter(node_fs_1.default.readFileSync(safeFilePath, 'utf-8'), fm);
+    // #4802: createIfMissing splices into '' (no block to refuse on); an existing
+    // file with broken YAML is refused by `spliceAcknowledgement`.
+    const newContent = spliceAcknowledgement(existingContent, fm, safeFilePath);
     (0, shell_command_projection_cjs_2.platformWriteSync)(safeFilePath, newContent);
     output({ acknowledged: true, category, ...(presenceOnly ? {} : { [snapshotKey]: currentValue }) }, raw, 'true');
 }

package/gsd-core/bin/lib/broken-windows.cjs

@@ -7,10 +7,10 @@
  * When `workflow.windows_enforce` is true, `/gsd-ship` blocks while any entry is
  * `open`; an entry can be `waived` only with a recorded reason or `fixed`.
  *
- * LEAF MODULE — imports node:fs + node:path, plus two compiled sibling lib
- * modules require()d at runtime: workstream-inventory.cjs (the #4487
- * milestone stamp) and capability-lock.cjs (the #3780 cross-process ledger
- * lock). No other src/ imports.
+ * LEAF MODULE — imports node:fs + node:path, the leaf frontmatter-fence.cjs (the one
+ * frontmatter fence owner), plus two compiled sibling lib modules require()d at runtime:
+ * workstream-inventory.cjs (the #4487 milestone stamp) and capability-lock.cjs (the #3780
+ * cross-process ledger lock). No other src/ imports.
  *
  * Storage format (`.planning/WINDOWS.md`):
  *   ---
@@ -68,6 +68,7 @@ exports.cmdWindowsWaive = cmdWindowsWaive;
 exports.cmdWindowsMarkFixed = cmdWindowsMarkFixed;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const workstreamInventory = require("./workstream-inventory.cjs");
 // ─── Constants ─────────────────────────────────────────────────────────────
@@ -385,21 +386,20 @@ function locateJsonBlock(raw, expectedTotal) {
  * structural deviation — fail-closed on drift.
  */
 function parseFrontmatterStrict(raw) {
-    if (!raw.startsWith('---\n') && !raw.startsWith('---\r\n')) {
+    // The block is the one the one fence owner finds (`locateFrontmatterFence`).
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(raw);
+    if (!fence) {
         throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, 'Ledger missing frontmatter opening ---');
     }
-    const headerEnd = raw.startsWith('---\r\n') ? 5 : 4;
-    const closeIdx = raw.indexOf('\n---', headerEnd);
-    if (closeIdx === -1) {
+    if (!fence.closed) {
         throw new WindowsError(exports.REASON.WINDOWS_LEDGER_MALFORMED, 'Ledger missing frontmatter closing ---');
     }
-    const yamlBody = raw.slice(headerEnd, closeIdx);
+    const yamlBody = raw.slice(fence.openEnd, fence.bodyEnd);
     const out = {};
     for (const rawLine of yamlBody.split(/\r?\n/)) {
-        // #3116: the `\n---` scan leaves the final line's CR attached on a CRLF
-        // ledger, and `.` never matches CR, so the key: value regex below fails on
-        // it. Strip the trailing CR per line so the rest of `raw` (which
-        // parseJsonBlock also slices by byte offset) is unaffected.
+        // #3116: strip a trailing CR per line (`.` never matches CR, so the key: value regex
+        // below would fail on it) without touching the rest of `raw`, which parseJsonBlock also
+        // slices by byte offset.
         const line = rawLine.replace(/\r$/, '');
         if (line.trim() === '')
             continue;

package/gsd-core/bin/lib/capability-activation.cjs

@@ -32,7 +32,7 @@ function _getNestedConfigValue(config, dotKey) {
     return { found: true, value: current };
 }
 const _warnedRawConfigPaths = new Set();
-function _readRawConfigKey(filePath, dotKey) {
+function _readRawConfigKey(filePath, dotKey, quiet = false) {
     try {
         const raw = node_fs_1.default.readFileSync(filePath, 'utf8');
         let parsed;
@@ -40,7 +40,7 @@ function _readRawConfigKey(filePath, dotKey) {
             parsed = JSON.parse(raw);
         }
         catch {
-            if (!_warnedRawConfigPaths.has(filePath)) {
+            if (!quiet && !_warnedRawConfigPaths.has(filePath)) {
                 _warnedRawConfigPaths.add(filePath);
                 try {
                     process.stderr.write(`gsd-tools: warning: failed to parse ${filePath} as JSON — skipping for activation resolution\n`);
@@ -67,9 +67,14 @@ function _readRawConfigKey(filePath, dotKey) {
  *   3. Root config.json at planningRoot(cwd)/config.json (only if path differs).
  *   4. registry.configSchema[dotKey].default — schema default.
  *   5. Absent → { found: false, value: undefined }.
+ *
+ * `quiet: true` (default false) suppresses the one-time stderr warning for a config.json that is
+ * not valid JSON: a gate reads its switch quietly (a malformed config is simply "key absent"), it
+ * never writes to stderr (#5139).
  */
 function resolveConfigKey(dotKey, opts) {
     const { config, cwd, registry } = opts;
+    const quiet = opts.quiet === true;
     // Level 1: loadConfig result
     const fromConfig = _getNestedConfigValue(config, dotKey);
     if (fromConfig.found)
@@ -78,11 +83,11 @@ function resolveConfigKey(dotKey, opts) {
     if (cwd) {
         const wsConfigPath = node_path_1.default.join(planningDir(cwd), 'config.json');
         const rootConfigPath = node_path_1.default.join(planningRoot(cwd), 'config.json');
-        const fromWs = _readRawConfigKey(wsConfigPath, dotKey);
+        const fromWs = _readRawConfigKey(wsConfigPath, dotKey, quiet);
         if (fromWs.found)
             return { found: true, value: fromWs.value };
         if (wsConfigPath !== rootConfigPath) {
-            const fromRoot = _readRawConfigKey(rootConfigPath, dotKey);
+            const fromRoot = _readRawConfigKey(rootConfigPath, dotKey, quiet);
             if (fromRoot.found)
                 return { found: true, value: fromRoot.value };
         }