@opengsd/gsd-core 1.13.0 → 1.15.0

package/gsd-core/bin/lib/adr-parser.cjs

@@ -52,6 +52,7 @@ const CANONICAL_HEADERS = {
         'recommendation',
         'strategy',
         'decision outcome',
+        'locked decisions',
     ],
     considered_options: [
         'considered options',
@@ -190,7 +191,8 @@ function normalizeAdrHeader(raw) {
         .toLowerCase()
         .replace(/[\s:._-]+/g, ' ')
         .replace(/[^\w\s]/g, '')
-        .trim();
+        .trim()
+        .replace(/^\d+(?:\s+\d+)*\s+/, '');
 }
 // Normalized synonym index (audit M7). classifyHeader receives an ALREADY-normalized
 // header (via normalizeAdrHeader), but historically compared it against the RAW synonym
@@ -402,7 +404,7 @@ function parseCliArgs(argv) {
 }
 function main(argv) {
     const opts = parseCliArgs(argv);
-    const safePath = (0, security_cjs_1.requireSafePath)(opts.input, node_path_1.default.resolve(opts.projectDir), 'ADR input path', { allowAbsolute: true });
+    const safePath = (0, security_cjs_1.requireSafePath)(opts.input, node_path_1.default.resolve(opts.projectDir), 'ADR input path', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
     const content = node_fs_1.default.readFileSync(safePath, 'utf8');
     const parsed = parseAdrMarkdown(content, { sourcePath: opts.input ?? undefined, format: opts.format });
     process.stdout.write(JSON.stringify(parsed, null, 2));

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

@@ -31,7 +31,8 @@ exports.CANONICAL_EXACT = new Set([
     'STATE-ARCHIVE.md', // state.cts's cmdStatePrune writes this at the .planning/ root
     'milestone.lock', // #3311: milestone (phase + session) claim (src/milestone-lock.cts); persistent, unlike the transient STATE.md.lock/WAITING.json
     'state.json', // #3227: machine-readable state contract published at step boundaries (src/state-contract.cts)
-    'skill-manifest.json', // init.cts routeSkillManifest --write (project-scoped planning root, #3964)
+    'skill-manifest.json', // init.cts cmdSkillManifest --write (project-scoped planning root, #3964)
+    'PATTERNS.md', // #4282: graduated cross-phase patterns (workflows/graduation.md, `patterns` target) -- distinct from the per-phase NN-PATTERNS.md (templates/README.md)
 ]);
 // Pattern-match canonical file names (regex tests on the basename)
 // Each pattern includes the name of the workflow that produces it as a comment.

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

@@ -25,10 +25,15 @@ 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 } = planningWorkspace;
+const { planningDir, quickDirFrom, todosDir } = planningWorkspace;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const frontmatter = require("./frontmatter.cjs");
-const { extractFrontmatter, spliceFrontmatter } = frontmatter;
+// #4378 (roll-in): scanSeeds publishes the SAME canonical seed identity the
+// list-seeds gate derives — one grammar, two surfaces, no drift. commands.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;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
 const { PHASE_NUMBER_TOKEN_SOURCE, scopeToPhase } = phaseIdMod;
@@ -277,7 +282,7 @@ function scanDebugSessions(planDir) {
         const filePath = node_path_1.default.join(debugDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'debug session file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'debug session file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -387,7 +392,7 @@ function scanQuickTasks(planDir) {
         const taskDir = node_path_1.default.join(quickDir, dirName);
         let safeTaskDir;
         try {
-            safeTaskDir = (0, security_cjs_1.requireSafePath)(taskDir, planDir, 'quick task dir', { allowAbsolute: true });
+            safeTaskDir = (0, security_cjs_1.requireSafePath)(taskDir, planDir, 'quick task dir', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -399,7 +404,7 @@ function scanQuickTasks(planDir) {
         if (summaryPath && node_fs_1.default.existsSync(summaryPath)) {
             let safeSum;
             try {
-                safeSum = (0, security_cjs_1.requireSafePath)(summaryPath, planDir, 'quick task summary', { allowAbsolute: true });
+                safeSum = (0, security_cjs_1.requireSafePath)(summaryPath, planDir, 'quick task summary', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -475,7 +480,7 @@ function scanThreads(planDir) {
         const filePath = node_path_1.default.join(threadsDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'thread file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'thread file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -522,9 +527,16 @@ function scanThreads(planDir) {
  * Scan .planning/todos/pending/ for pending todos.
  * Returns array of { filename, priority, area, summary }.
  * Display limited to first 5 + count of remainder.
+ *
+ * #4256: takes the ROOT-scoped todos base (`todosDir(cwd)`), NOT the
+ * workstream-scoped planning dir the other scans use — todos are shared
+ * project state (the migrateToWorkstreams contract keeps them at
+ * .planning/todos/), so the close gate must read the root or it clears
+ * vacuously under a workstream. The requireSafePath boundary below moves
+ * with the base.
  */
-function scanTodos(planDir) {
-    const pendingDir = node_path_1.default.join(planDir, 'todos', 'pending');
+function scanTodos(todosBase) {
+    const pendingDir = node_path_1.default.join(todosBase, 'pending');
     if (!node_fs_1.default.existsSync(pendingDir))
         return { items: [], acknowledged: 0 };
     let files;
@@ -550,7 +562,7 @@ function scanTodos(planDir) {
         const filePath = node_path_1.default.join(pendingDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'todo file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, todosBase, 'todo file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -595,6 +607,14 @@ function scanTodos(planDir) {
     }
     return { items: results, acknowledged };
 }
+// #4378 (roll-in): true when the filename is a well-formed seed name —
+// `SEED-` prefix, `.md` suffix, and no control bytes anywhere in between (the
+// scanSeeds admission filter passes such names through to the identity
+// derivation; a name with an embedded control byte falls back to its raw
+// stem exactly as the pre-canonical code did).
+function seedIdMatchRawName(name) {
+    return !/[\u0000-\u001f\u007f]/.test(name);
+}
 // ─── scanSeeds ────────────────────────────────────────────────────────────────
 /**
  * Scan .planning/seeds/SEED-*.md for unimplemented seeds.
@@ -622,7 +642,7 @@ function scanSeeds(planDir) {
         const filePath = node_path_1.default.join(seedsDir, entry.name);
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'seed file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'seed file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -646,16 +666,18 @@ function scanSeeds(planDir) {
             acknowledged++;
             continue;
         }
-        // Extract seed_id from filename or frontmatter. The regex match is
-        // `\w`/hyphen-constrained (safe by construction, like `archived_milestone`)
-        // but the fallback taken when a filename doesn't fully match — e.g. a
-        // `SEED-`-prefixed, `.md`-suffixed name with a control byte SOMEWHERE in
-        // the middle, which still passes the `startsWith`/`endsWith` filter above
-        // — is the raw, unconstrained basename. Both branches are routed through
-        // sanitizeLabel below.
-        const seedIdMatch = entry.name.match(/^(SEED-[\w-]+)\.md$/);
-        const seed_id = seedIdMatch ? seedIdMatch[1] : node_path_1.default.basename(entry.name, '.md');
-        const slug = (0, security_cjs_1.sanitizeLabel)(seed_id.replace(/^SEED-/, ''));
+        // #4378 (roll-in): the canonical identity comes from the SAME derivation
+        // the list-seeds surface uses — frontmatter `id:` when it matches a seed
+        // grammar (legacy `SEED-NNN` or date-suffixed `SEED-YYMMDD-xxx`), else the
+        // filename's id prefix, else the whole stem. The old fused
+        // filename-stem id (e.g. `SEED-081-region` for `SEED-081-region.md`)
+        // disagreed with list-seeds and misfiled deferrals; publishing the
+        // canonical id keeps the two surfaces answering identically. The raw-
+        // basename fallback for control-byte-bearing names is preserved.
+        const stem = node_path_1.default.basename(entry.name, '.md');
+        const derived = commandsModule.deriveSeedIdentity(stem, fm.id);
+        const seed_id = seedIdMatchRawName(entry.name) ? derived.seed_id : stem;
+        const slug = (0, security_cjs_1.sanitizeLabel)(derived.slug);
         let title = (0, security_cjs_1.sanitizeForDisplay)(fm.title || '');
         if (!title) {
             const headingMatch = content.match(/^#\s*(.+)$/m);
@@ -785,7 +807,7 @@ function scanUatGaps(planDir, cwd) {
             const filePath = node_path_1.default.join(target.fullPath, file);
             let safeFilePath;
             try {
-                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'UAT file', { allowAbsolute: true });
+                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'UAT file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -858,7 +880,7 @@ function scanVerificationGaps(planDir, cwd) {
             const filePath = node_path_1.default.join(target.fullPath, file);
             let safeFilePath;
             try {
-                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'VERIFICATION file', { allowAbsolute: true });
+                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'VERIFICATION file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -920,7 +942,7 @@ function scanContextQuestions(planDir, cwd) {
             const filePath = node_path_1.default.join(target.fullPath, file);
             let safeFilePath;
             try {
-                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'CONTEXT file', { allowAbsolute: true });
+                safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'CONTEXT file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             }
             catch {
                 continue;
@@ -1008,7 +1030,7 @@ function scanDeferredItems(planDir, cwd) {
             continue;
         let safeFilePath;
         try {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'deferred items file', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'deferred items file', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         }
         catch {
             continue;
@@ -1076,8 +1098,13 @@ function auditOpenArtifacts(cwd) {
         }
     })();
     const todos = (() => {
+        // #4256: the ONE root-scoped category — todos are shared project state,
+        // 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."
+        // with pending todos on disk under a workstream.
         try {
-            return scanTodos(planDir);
+            return scanTodos(todosDir(cwd));
         }
         catch {
             return { items: [{ scan_error: true, filename: '', priority: '', area: '', summary: '' }], acknowledged: 0 };
@@ -1421,7 +1448,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             ioError(`no phase directory found for phase "${phase}"${archivedMilestone ? ` (archived-milestone "${archivedMilestone}")` : ''}`);
         }
         const filePath = node_path_1.default.join(targetDir, file);
-        const safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'audit acknowledge target', { allowAbsolute: true });
+        const safeFilePath = (0, security_cjs_1.requireSafePath)(filePath, planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: ${file}`);
         if (category === 'deferred_items') {
@@ -1452,6 +1479,13 @@ 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
@@ -1503,7 +1537,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     if (category === 'debug_sessions') {
         if (!slug)
             ioError('--slug is required for --category debug_sessions');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'debug', `${slug}.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
+        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'debug', `${slug}.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: debug/${slug}.md`);
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
@@ -1512,7 +1546,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     else if (category === 'threads') {
         if (!slug)
             ioError('--slug is required for --category threads');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'threads', `${slug}.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
+        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'threads', `${slug}.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: threads/${slug}.md`);
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
@@ -1521,16 +1555,60 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     else if (category === 'seeds') {
         if (!seedId)
             ioError('--seed-id is required for --category seeds');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'seeds', `${seedId}.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
-        if (!node_fs_1.default.existsSync(safeFilePath))
+        // #4378 (roll-in): `--seed-id` arrives as whichever id an audit/list
+        // surface published — the canonical identity (frontmatter `id:` or the
+        // derived prefix, e.g. `SEED-081`, `SEED-260914-k3x`) or, for callers
+        // scripted against pre-canonical output, the full filename stem. Resolve
+        // by scanning the seeds directory and matching each candidate's derived
+        // identity (falling back to the literal stem), then prove the winner with
+        // requireSafePath exactly like every other acknowledge target. The direct
+        // `seeds/<seedId>.md` build stays as the final fallback so a genuine
+        // miss still reports the same "file not found" error as before.
+        const seedsAckDir = node_path_1.default.join(planDir, 'seeds');
+        let ackCandidate = null;
+        let ackEntries = [];
+        try {
+            ackEntries = node_fs_1.default.readdirSync(seedsAckDir).filter((n) => n.startsWith('SEED-') && n.endsWith('.md'));
+        }
+        catch {
+            ackEntries = [];
+        }
+        for (const name of ackEntries) {
+            const stem = node_path_1.default.basename(name, '.md');
+            let fmId;
+            try {
+                const rawAck = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(seedsAckDir, name));
+                if (rawAck !== null)
+                    fmId = extractFrontmatter(normalizeLineEndings(rawAck), node_path_1.default.join(seedsAckDir, name)).id;
+            }
+            catch {
+                fmId = undefined;
+            }
+            const { seed_id: derivedAckId } = commandsModule.deriveSeedIdentity(stem, fmId);
+            if (derivedAckId === seedId || stem === seedId) {
+                ackCandidate = name;
+                break;
+            }
+        }
+        if (ackCandidate !== null) {
+            safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(seedsAckDir, ackCandidate), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
+        }
+        else {
+            safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(seedsAckDir, `${seedId}.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             ioError(`file not found: seeds/${seedId}.md`);
+        }
         const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
         currentValue = (extractFrontmatter(content, safeFilePath).status || 'dormant').toLowerCase();
     }
     else if (category === 'todos') {
         if (!filename)
             ioError('--filename is required for --category todos');
-        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'todos', 'pending', filename), planDir, 'audit acknowledge target', { allowAbsolute: true });
+        // #4256: todos are root-scoped shared state — derive the todos base and
+        // pass it as BOTH the path base and the requireSafePath boundary. The
+        // old workstream-scoped planDir boundary would refuse a root todos file
+        // outright, and even a path fix alone would have thrown here.
+        const rootTodos = todosDir(cwd);
+        safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(rootTodos, 'pending', filename), rootTodos, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(safeFilePath))
             ioError(`file not found: todos/pending/${filename}`);
         currentValue = ''; // presence-only — see scanTodos
@@ -1538,14 +1616,14 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     else if (category === 'quick_tasks') {
         if (!quickDir)
             ioError('--dir is required for --category quick_tasks');
-        const taskDir = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'quick', quickDir), planDir, 'audit acknowledge target dir', { allowAbsolute: true });
+        const taskDir = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(planDir, 'quick', quickDir), planDir, 'audit acknowledge target dir', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
         if (!node_fs_1.default.existsSync(taskDir))
             ioError(`directory not found: quick/${quickDir}`);
         // Shared with scanQuickTasks (#3458 follow-up) so the reader and this
         // writer can never disagree about which file is the task's record.
         const resolvedSummaryPath = resolveQuickTaskSummaryFile(taskDir, quickDir);
         if (resolvedSummaryPath) {
-            safeFilePath = (0, security_cjs_1.requireSafePath)(resolvedSummaryPath, planDir, 'audit acknowledge target', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(resolvedSummaryPath, planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             const content = node_fs_1.default.readFileSync(safeFilePath, 'utf-8');
             currentValue = (extractFrontmatter(content, safeFilePath).status || 'unknown').toLowerCase();
         }
@@ -1556,7 +1634,7 @@ function cmdAuditAcknowledge(cwd, args, raw) {
             // acknowledgment's own snapshot of "no summary exists yet", which
             // self-invalidates the moment a real SUMMARY.md is written (the
             // scanner then reads THAT file's own status instead).
-            safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(taskDir, `${quickDir}-SUMMARY.md`), planDir, 'audit acknowledge target', { allowAbsolute: true });
+            safeFilePath = (0, security_cjs_1.requireSafePath)(node_path_1.default.join(taskDir, `${quickDir}-SUMMARY.md`), planDir, 'audit acknowledge target', security_cjs_1.PathAcceptance.AbsoluteInsideRoot);
             currentValue = 'missing';
             createIfMissing = true;
             fmForCreate = { status: 'missing' };
@@ -1568,6 +1646,13 @@ function cmdAuditAcknowledge(cwd, args, raw) {
     }
     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`);
+    }
     fm.audit_acknowledged = presenceOnly ? { ...markerBase } : { ...markerBase, [snapshotKey]: currentValue };
     const newContent = createIfMissing
         ? spliceFrontmatter('', fm)