@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/bin/lib/external-job.cjs

@@ -219,6 +219,11 @@ function _isNonTerminal(status) {
  *  - Same `job_id` for the same `plan_id` -> allowed (status progression).
  *  - A prior job for the same `plan_id` that is already terminal -> allowed
  *    (the duplicate guard only protects against re-dispatching live work).
+ *  - If a SIBLING manifest (not the target) cannot be read or parsed, the
+ *    duplicate scan cannot be completed and may be hiding a live duplicate
+ *    -> refuse (`scan_incomplete`), naming the offending file's path so an
+ *    operator can quarantine or repair it. Never silently skip a sibling the
+ *    scan could not inspect.
  */
 function writeManifest(manifest, planningDir, opts = {}) {
     const fs = opts.fs ?? node_fs_1.default;
@@ -240,18 +245,28 @@ function writeManifest(manifest, planningDir, opts = {}) {
         try {
             raw = String(fs.readFileSync(p));
         }
-        catch {
-            continue;
+        catch (e) {
+            return {
+                ok: false,
+                kind: 'scan_incomplete',
+                message: `duplicate scan incomplete: failed to READ sibling manifest ${p} (${e.message}); quarantine or repair this file before retrying`,
+                offendingPath: p,
+            };
         }
         let existing;
         try {
             existing = JSON.parse(raw);
         }
-        catch {
+        catch (e) {
             if (p === target) {
                 return { ok: false, kind: 'malformed_existing', message: `target manifest ${p} is not valid JSON` };
             }
-            continue;
+            return {
+                ok: false,
+                kind: 'scan_incomplete',
+                message: `duplicate scan incomplete: failed to PARSE sibling manifest ${p} (${e.message}); quarantine or repair this file before retrying`,
+                offendingPath: p,
+            };
         }
         const samePlan = existing.plan_id === manifest.plan_id;
         const sameJob = existing.job_id === manifest.job_id;

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

@@ -195,6 +195,18 @@ function parseYamlRegion(yaml) {
  *   hold only an in-memory string; those dedup on a content digest instead.
  */
 function extractFrontmatter(content, sourcePath) {
+    // #2977: tolerate a single leading UTF-8 BOM (\uFEFF), which Windows tooling
+    // (PowerShell `>`/`Out-File` on PS 5.1, several editors) writes by default. Without this
+    // strip, the byte-0 `startsWith('---')` fence check below fails on the BOM and the whole
+    // parse collapses to {} — every frontmatter field silently disappears, and the engine
+    // proceeds as though the file had no frontmatter at all. The BOM is a single codepoint;
+    // stripping it here restores byte-0 alignment so the rest of the function is unchanged.
+    // Scope: BOM only. Arbitrary non-BOM content before the fence (leading whitespace/blank
+    // line/comment) is a separate product-intent decision (tolerate vs diagnose) left to a
+    // future change — this fix does not broaden the byte-0 fence rule beyond the BOM.
+    if (content.charCodeAt(0) === 0xFEFF) {
+        content = content.slice(1);
+    }
     // Match frontmatter only at byte 0 — a `---` block later in the document
     // body (YAML examples, horizontal rules) must never be treated as frontmatter.
     const headerEnd = content.startsWith('---\r\n') ? 5 : content.startsWith('---\n') ? 4 : -1;
@@ -607,29 +619,64 @@ function parseMustHavesBlock(content, blockName) {
     return items;
 }
 // ─── Frontmatter CRUD commands ────────────────────────────────────────────────
+// Shared base for 'plan' and 'plan-gap-closure' below — a plain array reference (not
+// FRONTMATTER_SCHEMAS.plan.required) because the object literal that defines
+// FRONTMATTER_SCHEMAS cannot refer to itself mid-initialization (TDZ).
+const PLAN_REQUIRED_FIELDS = ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'];
+// `requiredValues` is optional per schema: when a field name is a key here, the
+// field must be PRESENT AND strictly equal (===) to the given value to satisfy
+// the schema — presence alone is not enough. Every other required field (no
+// entry in requiredValues) keeps the original presence-only contract.
 const FRONTMATTER_SCHEMAS = {
-    plan: { required: ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'] },
+    plan: { required: PLAN_REQUIRED_FIELDS },
+    // #2847: gap-closure plans carry every 'plan' field PLUS gap_closure — the flag
+    // execute-phase --gaps-only filters on. A separate schema (not a change to
+    // 'plan') so standard/reviews-mode plans stay unaffected: they validate against
+    // 'plan' and are never required to declare or be checked for gap_closure.
+    // Derived from PLAN_REQUIRED_FIELDS (never hand-duplicated) so the two can't drift.
+    //
+    // requiredValues.gap_closure = true (not just presence): --gaps-only filters
+    // strictly on gap_closure === true (execute-phase.md, partial-wave.md), so a
+    // plan carrying `gap_closure: false` would pass a presence-only check and
+    // still be silently skipped at execute time — the exact symptom #2847
+    // reports, one value away. Presence-only was flagged in review as a live
+    // reproduction of the bug this schema exists to close.
+    'plan-gap-closure': {
+        required: [...PLAN_REQUIRED_FIELDS, 'gap_closure'],
+        // extractFrontmatter parses every scalar as a string (FrontmatterValue has
+        // no boolean member — `gap_closure: true` in YAML becomes the JS string
+        // "true", not the boolean true), so the required value is the string here.
+        requiredValues: { gap_closure: 'true' },
+    },
     summary: { required: ['phase', 'plan', 'subsystem', 'tags', 'duration', 'completed'] },
     verification: { required: ['phase', 'verified', 'status', 'score'] },
 };
 /**
- * Strip ALL frontmatter blocks from the start of `content`.
+ * Strip frontmatter blocks from the start of `content`.
+ *
+ * Handles CRLF line endings and, by default, multiple stacked blocks
+ * (corruption recovery): greedily strips consecutive `---...---` blocks
+ * separated by optional whitespace, so a doubled/tripled frontmatter header
+ * (e.g. from a botched merge) is fully removed, not just the first block.
  *
- * Handles CRLF line endings and multiple stacked blocks (corruption
- * recovery): greedily strips consecutive `---...---` blocks separated by
- * optional whitespace, so a doubled/tripled frontmatter header (e.g. from a
- * botched merge) is fully removed, not just the first block.
+ * Pass `{ once: true }` to stop after the first block. Callers whose input is
+ * an arbitrary user-authored document — rather than a GSD artefact with a
+ * known doubling failure mode — need this: a body that opens with a
+ * thematic-break-delimited section is lexically indistinguishable from a
+ * second frontmatter block, and the greedy loop deletes it silently (#2703).
  *
  * Canonical home for this primitive (#2143 audit dedup): previously
  * duplicated byte-identically in both `state.cts` and `state-transition.cts`.
  */
-function stripFrontmatter(content) {
+function stripFrontmatter(content, opts = {}) {
     let result = content;
     while (true) {
         const stripped = result.replace(/^\s*---\r?\n[\s\S]*?\r?\n---\s*/, '');
         if (stripped === result)
             break;
         result = stripped;
+        if (opts.once)
+            break;
     }
     return result;
 }
@@ -750,10 +797,19 @@ function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
     if (filePath.includes('\0')) {
         error('file path contains null bytes');
     }
-    const schema = FRONTMATTER_SCHEMAS[schemaName];
-    if (!schema) {
+    // Guard against prototype-chain keys (__proto__, constructor, toString, hasOwnProperty,
+    // valueOf, ...): a bare FRONTMATTER_SCHEMAS[schemaName] lookup resolves those to
+    // Object.prototype members instead of undefined, so a `!schema` check on the raw
+    // lookup never fires and the code crashes later on `schema.required.filter` with an
+    // uncaught TypeError instead of the intended "Unknown schema" message. Confirmed live
+    // with --schema __proto__. Now that --schema is agent-bound (agents/gsd-planner.md's
+    // $SCHEMA), this is reachable from prompt state, not just an unreachable literal.
+    // Checked and rejected BEFORE the lookup (rather than `?? undefined`-ing the lookup
+    // itself) so `schema`'s inferred type stays non-optional and needs no assertion below.
+    if (!Object.prototype.hasOwnProperty.call(FRONTMATTER_SCHEMAS, schemaName)) {
         error(`Unknown schema: ${schemaName}. Available: ${Object.keys(FRONTMATTER_SCHEMAS).join(', ')}`);
     }
+    const schema = FRONTMATTER_SCHEMAS[schemaName];
     const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
     const content = (0, shell_command_projection_cjs_1.platformReadSync)(fullPath);
     if (!content) {
@@ -771,9 +827,25 @@ function cmdFrontmatterValidate(cwd, filePath, schemaName, raw) {
     // Pass the resolved path so a truncated file is named in the diagnostic and deduplicated
     // per file rather than per content digest (#1882, ADR-1411 wiring clause).
     const fm = extractFrontmatter(content, fullPath);
-    const missing = schema.required.filter(f => fm[f] === undefined);
-    const present = schema.required.filter(f => fm[f] !== undefined);
-    output({ valid: missing.length === 0, missing, present, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
+    const requiredValues = schema.requiredValues || {};
+    // A field satisfies the schema when it is present AND — for fields with a
+    // requiredValues entry — strictly equal to that value. Absent and
+    // wrong-value both surface as `missing` (existing `missing`/`present`
+    // partition of `required` is unchanged — no consumer reads `present` to
+    // mean "physically exists regardless of value," confirmed by searching
+    // every caller before choosing this). But #2847 review: folding silently
+    // made "missing" misleading for a WRONG-valued field the plan author can
+    // plainly see in the file (e.g. `gap_closure: True`) — nothing told them
+    // the field is present but the VALUE is wrong, so they could loop trying
+    // to add a field that is already there. `invalidValue` names exactly that
+    // subset (present, but not the required value) so the message stays
+    // actionable without changing what `missing`/`present` mean.
+    const wrongValue = (f) => fm[f] !== undefined && Object.prototype.hasOwnProperty.call(requiredValues, f) && fm[f] !== requiredValues[f];
+    const satisfies = (f) => fm[f] !== undefined && !wrongValue(f);
+    const missing = schema.required.filter(f => !satisfies(f));
+    const present = schema.required.filter(f => satisfies(f));
+    const invalidValue = schema.required.filter(wrongValue);
+    output({ valid: missing.length === 0, missing, present, invalidValue, schema: schemaName }, raw, missing.length === 0 ? 'valid' : 'invalid');
 }
 module.exports = {
     extractFrontmatter,

package/gsd-core/bin/lib/gate-predicate-evaluator.cjs

@@ -18,11 +18,10 @@
  * non-zero check-command exit, which the workflow's two-step gate contract treats
  * as a step-1 command failure (routed per the gate's `onError`).
  *
- * Built-in kind (v1): `command-exit-zero` — run a declared command in a bounded
- * `sh -c` subprocess at the project root, inheriting the process env; exit 0 =>
- * pass, non-zero => block, timeout => block. The production runBoundedShell
- * binding is shell-command-projection.execTool (bounded spawnSync). See ADR-2008
- * for the full sandbox contract.
+ * Built-in kinds: `command-exit-zero` runs a declared command in a bounded
+ * `sh -c` subprocess; `artifact-frontmatter-equals` compares a declared value
+ * with frontmatter read through injected artifact dependencies. See ADR-2008
+ * for the full contracts.
  *
  * This is a leaf pure module: no fs, no child_process, no config — the subprocess
  * seam is injected so the evaluator is trivially testable without spawning.
@@ -35,7 +34,7 @@ const COMMAND_MAX_OUTPUT_CHARS = 2000;
 /** Hard cap on the declared command length (defense-in-depth against ARGV overflow / abuse). */
 const COMMAND_MAX_LENGTH = 4096;
 /** Predicate kinds this evaluator recognises (extensible — add to KIND_TABLE). */
-const EVALUATOR_KINDS = Object.freeze(['command-exit-zero']);
+const EVALUATOR_KINDS = Object.freeze(['command-exit-zero', 'artifact-frontmatter-equals']);
 /** Placeholders interpolated into a declared command, in addition to sh's own vars. */
 const INTERPOLATION_VAR_NAMES = Object.freeze(['PHASE_NUMBER', 'PHASE_DIR', 'PHASE_REQ_IDS']);
 // ─── Helpers ──────────────────────────────────────────────────────────────────
@@ -102,9 +101,53 @@ function evaluateCommandExitZero(predicate, ctx, deps) {
         details: { kind: 'command-exit-zero', exitCode: res.exitCode, signal: res.signal },
     };
 }
+// ─── Kind: artifact-frontmatter-equals ──────────────────────────────────────────
+function evaluateArtifactFrontmatterEquals(predicate, ctx, deps) {
+    const artifactSuffix = predicate['artifact'];
+    if (!isNonEmptyString(artifactSuffix)) {
+        throw new Error('artifact-frontmatter-equals predicate requires a non-empty string "artifact"');
+    }
+    const field = predicate['field'];
+    if (!isNonEmptyString(field)) {
+        throw new Error('artifact-frontmatter-equals predicate requires a non-empty string "field"');
+    }
+    const expectedValue = predicate['equals'];
+    if (expectedValue === undefined) {
+        throw new Error('artifact-frontmatter-equals predicate requires an "equals" key');
+    }
+    const targetDir = isNonEmptyString(ctx.phaseDir) ? ctx.phaseDir : ctx.cwd;
+    const filePath = deps.findPhaseArtifact(targetDir, artifactSuffix);
+    if (!filePath) {
+        return {
+            block: true,
+            message: `Artifact matching ${artifactSuffix} not found in ${targetDir}`,
+            details: { kind: 'artifact-frontmatter-equals', artifactNotFound: true },
+        };
+    }
+    const fm = deps.readFrontmatter(filePath);
+    const actualValue = fm[field];
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const expectedStr = typeof expectedValue === 'object' ? JSON.stringify(expectedValue) : String(expectedValue);
+    // eslint-disable-next-line @typescript-eslint/no-base-to-string
+    const actualStr = typeof actualValue === 'object' ? JSON.stringify(actualValue) : String(actualValue);
+    const matches = actualValue === expectedValue || (actualValue !== undefined && actualValue !== null && actualStr === expectedStr);
+    if (matches) {
+        return {
+            block: false,
+            message: `Frontmatter field "${field}" matches expected value (${expectedStr})`,
+            details: { kind: 'artifact-frontmatter-equals', match: true },
+        };
+    }
+    return {
+        block: true,
+        message: `Frontmatter field "${field}" in ${artifactSuffix} is ${actualStr}, expected ${expectedStr}`,
+        details: { kind: 'artifact-frontmatter-equals', match: false, actual: actualValue, expected: expectedValue },
+    };
+}
 // ─── Kind dispatch table ──────────────────────────────────────────────────────
 const KIND_TABLE = {
     'command-exit-zero': evaluateCommandExitZero,
+    'artifact-frontmatter-equals': evaluateArtifactFrontmatterEquals,
 };
 // ─── Public entry point ───────────────────────────────────────────────────────
 /**
@@ -133,6 +176,14 @@ function evaluatePredicate(predicate, context, deps) {
     if (typeof kind !== 'string' || kind.length === 0) {
         throw new Error('predicate.kind must be a non-empty string');
     }
+    if (kind === 'artifact-frontmatter-equals') {
+        if (typeof d.findPhaseArtifact !== 'function') {
+            throw new Error('predicate deps require a "findPhaseArtifact" function');
+        }
+        if (typeof d.readFrontmatter !== 'function') {
+            throw new Error('predicate deps require a "readFrontmatter" function');
+        }
+    }
     const handler = KIND_TABLE[kind];
     if (!handler) {
         throw new Error(`Unknown predicate kind: "${kind}". Known kinds: ${EVALUATOR_KINDS.join(', ')}`);

package/gsd-core/bin/lib/git-base-branch.cjs

@@ -18,7 +18,14 @@
  *   5. "main"  (last-resort default)
  *
  * Every git subprocess is bounded with a timeout (≤ 30 s); on timeout/error
- * the resolver degrades gracefully to the next tier — it never throws.
+ * the resolver degrades gracefully to the next tier — it never throws. Tier 5
+ * is reachable two ways that `resolveBaseBranch()` alone cannot tell apart: a
+ * repository that genuinely has no candidate branch (every git query on tiers
+ * 2-4 completed and cleanly answered "nothing"), or a total resolution
+ * failure (some query timed out / could not run). `resolveBaseBranchDiagnostics()`
+ * distinguishes the two via `verified`; `cmdGitBaseBranch` surfaces the
+ * unverified case as a stderr diagnostic without changing its stdout contract
+ * (#3057 B4).
  *
  * Pure/testable: all I/O is injectable via the `deps` argument so unit
  * tests can run without touching the real filesystem or spawning real git.
@@ -31,6 +38,7 @@ exports.readConfigBaseBranch = readConfigBaseBranch;
 exports.trySymbolicRef = trySymbolicRef;
 exports.tryRemoteShow = tryRemoteShow;
 exports.tryLocalBranch = tryLocalBranch;
+exports.resolveBaseBranchDiagnostics = resolveBaseBranchDiagnostics;
 exports.resolveBaseBranch = resolveBaseBranch;
 exports.gitWorktreeInfoInternal = gitWorktreeInfoInternal;
 exports.cmdGitBaseBranch = cmdGitBaseBranch;
@@ -115,7 +123,8 @@ function tryRemoteShow(cwd, execGit) {
         const branch = m[1];
         // git emits "(unknown)" when the remote is offline but the local cache
         // resolved it; treat that as non-authoritative and fall through.
-        if (!branch || branch === '(unknown)')
+        // No `!branch ||` guard: m[1] comes from the `(\S+)` capture group above, so it is never empty.
+        if (branch === '(unknown)')
             return null;
         return branch;
     }
@@ -153,41 +162,70 @@ function tryLocalBranch(cwd, execGit) {
     }
 }
 /**
- * Resolve the default/base branch for the repository at `cwd`.
+ * Resolve the default/base branch for the repository at `cwd`, along with
+ * whether the tier-5 last-resort default (if reached) was verified.
  *
  * Consults the full precedence ladder and always returns a non-empty string.
  * Never throws.
  */
-function resolveBaseBranch(cwd, deps) {
-    const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
+function resolveBaseBranchDiagnostics(cwd, deps) {
+    const rawExecGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
+    // A genuine execGit failure (timeout, or the call could not even spawn —
+    // e.g. git missing, surfaced as exitCode 127 with `error` set) is distinct
+    // from git completing and cleanly reporting a negative answer (non-zero
+    // exit with no useful output, or exit 0 with empty stdout). Only the former
+    // means a tier's answer was never actually obtained. Wrapping execGit here
+    // observes every tier's calls uniformly without changing trySymbolicRef /
+    // tryRemoteShow / tryLocalBranch's own return contracts.
+    let anyGitFailure = false;
+    const execGit = (args, opts) => {
+        const r = rawExecGit(args, opts);
+        if (r.timedOut || r.error)
+            anyGitFailure = true;
+        return r;
+    };
     // Derive .planning dir relative to cwd (mirrors planningDir() in planning-workspace.cjs)
     const planningDir = node_path_1.default.join(cwd, '.planning');
     // 1. Config override
     const configured = readConfigBaseBranch(planningDir, deps);
     if (configured)
-        return configured;
+        return { branch: configured, verified: true };
     // 2. symbolic-ref (fast, no network)
     const symref = trySymbolicRef(cwd, execGit);
     if (symref)
-        return symref;
+        return { branch: symref, verified: true };
     // 3. git remote show origin (authoritative when origin/HEAD unset)
     const remoteShow = tryRemoteShow(cwd, execGit);
     if (remoteShow)
-        return remoteShow;
+        return { branch: remoteShow, verified: true };
     // 4. Local branch existence
     const local = tryLocalBranch(cwd, execGit);
     if (local)
-        return local;
-    // 5. Last-resort default
-    return 'main';
+        return { branch: local, verified: true };
+    // 5. Last-resort default. `verified:false` when at least one tier-2/3/4
+    // execGit call timed out or failed to run — the default was never actually
+    // checked against this repository, it is just what's left after git could
+    // not answer (#3057 B4).
+    return { branch: 'main', verified: !anyGitFailure };
+}
+/**
+ * Resolve the default/base branch for the repository at `cwd`.
+ *
+ * Consults the full precedence ladder and always returns a non-empty string.
+ * Never throws. See {@link resolveBaseBranchDiagnostics} for a caller that
+ * needs to distinguish a verified answer from an unverified fallback.
+ */
+function resolveBaseBranch(cwd, deps) {
+    return resolveBaseBranchDiagnostics(cwd, deps).branch;
 }
 /**
  * Detect whether `cwd` sits inside a git worktree, and if so, return the
  * absolute path of the worktree root.
  */
-function gitWorktreeInfoInternal(cwd) {
+function gitWorktreeInfoInternal(cwd, deps) {
+    const execGit = deps?.execGit ?? shell_command_projection_cjs_1.execGit;
     try {
-        const insideResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--is-inside-work-tree'], { cwd, timeout: 5000 });
+        const insideResult = execGit(['rev-parse', '--is-inside-work-tree'], { cwd, timeout: 5000 });
         if (insideResult.exitCode !== 0) {
             return { inside: false, worktreeRoot: null };
         }
@@ -195,7 +233,7 @@ function gitWorktreeInfoInternal(cwd) {
         if (insideStdout !== 'true') {
             return { inside: false, worktreeRoot: null };
         }
-        const rootResult = (0, shell_command_projection_cjs_1.execGit)(['rev-parse', '--show-toplevel'], { cwd, timeout: 5000 });
+        const rootResult = execGit(['rev-parse', '--show-toplevel'], { cwd, timeout: 5000 });
         if (rootResult.exitCode !== 0) {
             return { inside: true, worktreeRoot: null };
         }
@@ -213,7 +251,12 @@ function gitWorktreeInfoInternal(cwd) {
  * Called by workflows via `gsd_run query git.base-branch`.
  */
 function cmdGitBaseBranch(cwd, _args, deps) {
-    const branch = resolveBaseBranch(cwd, deps);
+    const { branch, verified } = resolveBaseBranchDiagnostics(cwd, deps);
+    if (!verified) {
+        const writeDiagnostic = deps?.writeDiagnostic ?? ((s) => process.stderr.write(s));
+        writeDiagnostic(`⚠ git-base-branch: defaulted to 'main' WITHOUT verifying against this repository — ` +
+            `a git query timed out or could not run. See #3057.\n`);
+    }
     const write = deps?.write ?? ((s) => process.stdout.write(s));
     write(branch + '\n');
     return branch;