@opengsd/gsd-core 1.16.0 → 1.18.0

package/gsd-core/bin/lib/task-command-router.cjs

@@ -12,6 +12,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const security_cjs_1 = require("./security.cjs");
+const tdd_test_files_cjs_1 = require("./tdd-test-files.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error, ERROR_REASON } = ioMod;
@@ -37,9 +38,7 @@ function isBehaviorAddingTaskContent(content) {
             .filter(Boolean);
         hasSourceFiles = fileLines.some((file) => !/\.md$/i.test(file) &&
             !/\.json$/i.test(file) &&
-            !/\.test\.[^.]+$/i.test(file) &&
-            !/\.spec\.[^.]+$/i.test(file) &&
-            !/(^|[\\/])tests?[\\/]/i.test(file) &&
+            !(0, tdd_test_files_cjs_1.isTestFilePath)(file) &&
             !/\.(yml|yaml|toml|ini|cfg|conf|properties)$/i.test(file) &&
             !/(^|[\\/])\.env(\..+)?$/i.test(file));
     }

package/gsd-core/bin/lib/tdd-red-evidence.cjs

@@ -10,6 +10,7 @@ exports.RedEvidenceReason = {
     TargetFailed: 'target_test_failed', Green: 'unexpected_green', Empty: 'zero_tests_discovered',
     NoFailure: 'nonzero_exit_without_test_failure', LoadFailure: 'fixture_or_load_failure',
     NoTarget: 'no_target_test_failure', Invalid: 'invalid_record', Unreadable: 'unreadable_record',
+    BuildFailure: 'build_failure',
 };
 /** Basename of a path-like string ('' for non-strings) — separators `/` and `\`. */
 function baseOf(p) {
@@ -59,6 +60,10 @@ function classifyRedEvidence(input) {
     };
     if (exitCode === 0)
         return { verdict: exports.RedEvidenceVerdict.Invalid, reason: exports.RedEvidenceReason.Green, evidence };
+    // A package that did not compile or load asserted nothing: refuse it as its own reason, ahead of
+    // the generic unusable-report refusal, because the fix is different (make the test compile).
+    if (report.buildFailed)
+        return { verdict: exports.RedEvidenceVerdict.Invalid, reason: exports.RedEvidenceReason.BuildFailure, evidence };
     if (!report.valid)
         return { verdict: exports.RedEvidenceVerdict.Invalid, reason: exports.RedEvidenceReason.Invalid, evidence };
     if (report.tests.length === 0)

package/gsd-core/bin/lib/tdd-test-files.cjs

@@ -0,0 +1,42 @@
+"use strict";
+/**
+ * The single definition of "a test file" for the TDD gate (#5106).
+ *
+ * Two places decide what a test file is: the behavior-adding check (`task-command-router.cts`) and
+ * the RED-commit pathspec in `workflows/execute-phase.md`. They were separate lists, so the pathspec
+ * learned the Go / Elixir / RSpec / pytest names in #4715 while the router never did, and a task
+ * listing only `placement_test.go` was classified behavior-adding — the gate then asked for a RED
+ * commit for the task that IS the RED commit.
+ *
+ * `TEST_FILE_PATHSPECS` is the list in git-pathspec spelling, which is what the workflow passes to
+ * `evaluation-scope --pathspec`; `isTestFilePath` evaluates the same list for a task's `<files>`.
+ * A test pins the workflow's pathspec flags to this array, so the two cannot drift apart again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TEST_FILE_PATHSPECS = void 0;
+exports.isTestFilePath = isTestFilePath;
+/** Git-pathspec spelling. A trailing `/` is a directory, anything else a basename glob. */
+exports.TEST_FILE_PATHSPECS = [
+    '*.test.*', '*.spec.*', 'tests/', '__tests__/',
+    '*_test.go', 'test_*.py', '*_test.py', '*_test.exs', '*_spec.rb', '*_test.rb',
+];
+/** Directory names a `<files>` entry may sit under. `test/` is the singular spelling many projects use. */
+const TEST_DIRECTORY_NAMES = new Set([
+    ...exports.TEST_FILE_PATHSPECS.filter((spec) => spec.endsWith('/')).map((spec) => spec.slice(0, -1)),
+    'test',
+]);
+function escapeRegex(text) {
+    return text.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+}
+/** A basename glob where `*` is any run of non-separator characters. */
+const FILE_GLOBS = exports.TEST_FILE_PATHSPECS
+    .filter((spec) => !spec.endsWith('/'))
+    .map((spec) => new RegExp(`^${spec.split('*').map(escapeRegex).join('[^/]*')}$`, 'i'));
+/** True when `file` (either separator) is a test file by the shared convention list. */
+function isTestFilePath(file) {
+    const segments = file.split(/[\\/]/).filter(Boolean);
+    const base = segments[segments.length - 1] ?? '';
+    if (FILE_GLOBS.some((glob) => glob.test(base)))
+        return true;
+    return segments.slice(0, -1).some((segment) => TEST_DIRECTORY_NAMES.has(segment.toLowerCase()));
+}

package/gsd-core/bin/lib/update-context.cjs

@@ -147,7 +147,24 @@ function resolveGlobalCandidate(fs, env, home, preferred) {
 /**
  * Pure resolver. Returns { installedVersion, scope, runtime, gsdDir }.
  */
-function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = '', preferredRuntime = '', }) {
+function resolveUpdateContext(opts) {
+    const base = resolveBaseUpdateContext(opts);
+    if (base.runtime !== 'opencode' || !base.gsdDir)
+        return base;
+    // The install records which OpenCode generation it targets; surface it when present.
+    const raw = opts.fs.readFile(node_path_1.default.join(base.gsdDir, 'gsd-install-state.json'));
+    if (raw == null)
+        return base;
+    try {
+        const hg = JSON.parse(raw).hostGeneration;
+        if (hg && hg.runtime === 'opencode' && (hg.generation === 1 || hg.generation === 2)) {
+            return { ...base, hostGeneration: hg.generation };
+        }
+    }
+    catch { /* an unreadable state file contributes nothing */ }
+    return base;
+}
+function resolveBaseUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = '', preferredRuntime = '', }) {
     // Expand a leading `~/` before any probe.
     preferredConfigDir = expandHome(preferredConfigDir, home);
     const preferred = preferredRuntime || inferPreferredRuntime({ fs, env, preferredConfigDir });

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

@@ -258,6 +258,11 @@ function reportStatusOf(fm, filePath) {
  * too): it re-runs the verifier, which regenerates VERIFICATION.md and its
  * digest (#4682, #4887).
  */
+/**
+ * The one remedy for a stale report (#4682 / #5118), shared by the route table and by the more specific
+ * diagnostic below so the two cannot drift: only re-running the verifier regenerates VERIFICATION.md.
+ */
+const STALE_REMEDY = 'Re-run execute-phase for this phase: it resumes at the verification gates and re-runs the verifier, regenerating VERIFICATION.md and its digest. verify-work alone cannot refresh a stale report.';
 const VERIFICATION_ROUTES = Object.freeze({
     passed: Object.freeze({
         next_action: 'Verification passed — continue.',
@@ -279,7 +284,7 @@ const VERIFICATION_ROUTES = Object.freeze({
     stale: Object.freeze({
         // #4682 / #5118: the only remedy for a stale report is re-running the
         // verifier; /gsd-verify-work on its own never rewrites VERIFICATION.md.
-        next_action: 'Verification is stale — covered source files changed after the verifier last ran. Re-run execute-phase for this phase: it resumes at the verification gates and re-runs the verifier, regenerating VERIFICATION.md and its digest. verify-work alone cannot refresh a stale report.',
+        next_action: `Verification is stale — covered source files changed after the verifier last ran. ${STALE_REMEDY}`,
         command: 'execute-phase',
         tail: '',
     }),
@@ -540,7 +545,7 @@ function phaseArtifactPaths(phaseDir, projectRoot) {
     const scan = scanPhasePlans(phaseDir);
     // Fail closed on a non-COMPLETE scan (unreadable phase dir, or an
     // unreadable nested plans/ dir) — a partial scan's invisible contents can
-    // never be proven covered (mirrors allCurrentArtifactsCovered's own
+    // never be proven covered (mirrors uncoveredCurrentArtifacts's own
     // fail-closed contract).
     if (scan.scope !== SCOPE.COMPLETE) {
         return { ok: false, reason: `phase directory scan is incomplete (scope: ${scan.scope}): ${phaseDir}` };
@@ -849,9 +854,9 @@ function computeCoveredDigest(projectRoot, coveredFiles, version = FINGERPRINT_V
  * each is represented in `coveredFiles` — matched by suffix (mirrors
  * `matchRequestedFile`'s convention) since `coveredFiles` holds
  * project-root-relative paths while the scan returns phase-relative
- * filenames. Returns `true` if every current plan/summary is covered,
- * `false` otherwise — callers only ever branch on this pass/fail, so no
- * caller needs which artifact was uncovered.
+ * filenames. Returns the current plans/summaries the report never declared
+ * (empty when every one is covered), so the stale diagnostic can name them (#4817); `null` when the
+ * scan itself was incomplete, which callers treat as stale.
  *
  * Fails CLOSED on an incomplete scan: `scanPhasePlans` never throws on a
  * readdir failure — it reports it via `scope` (`SCOPE.UNREADABLE` for the
@@ -860,18 +865,18 @@ function computeCoveredDigest(projectRoot, coveredFiles, version = FINGERPRINT_V
  * contract (`planning-scope.cts`): zero items under a non-`COMPLETE` scope
  * is a NON-answer, never "this phase has no plans." Branching on `scope`
  * here (rather than a try/catch, which this scan never triggers) is what
- * makes an unreadable `plans/` dir report `false` instead of silently
+ * makes an unreadable `plans/` dir report `null` (stale) instead of silently
  * treating its invisible contents as vacuously covered — the same
  * fail-open regression #3057 B3 fixed for the legacy path.
  */
-function allCurrentArtifactsCovered(phaseDir, coveredFiles) {
+function uncoveredCurrentArtifacts(phaseDir, coveredFiles) {
     const scan = scanPhasePlans(phaseDir);
     if (scan.scope !== SCOPE.COMPLETE)
-        return false;
+        return null;
     const coveredPosix = canonicalizeCoveredFiles(coveredFiles);
-    return [...scan.allPlanFiles, ...scan.summaryFiles].every((artifact) => {
+    return [...scan.allPlanFiles, ...scan.summaryFiles].filter((artifact) => {
         const artifactPosix = toPosix(artifact);
-        return coveredPosix.some((c) => c === artifactPosix || c.endsWith(`/${artifactPosix}`));
+        return !coveredPosix.some((c) => c === artifactPosix || c.endsWith(`/${artifactPosix}`));
     });
 }
 /**
@@ -943,6 +948,73 @@ function defaultPhaseCleanCommitTimesMs(phaseDir, files, execGitFn = shell_comma
     }
     return commitTimes;
 }
+/**
+ * #4857: which declared covered files changed since the report was written.
+ * `covered_digest` is one aggregate hash, so it can say THAT something moved
+ * but not what; this names the files by time instead — each covered file
+ * (report paths and, for v2+, shared planning documents excluded, exactly as
+ * the digest excludes them) whose clean commit time, or mtime when it is
+ * uncommitted or edited since, is newer than the report's own. A file that
+ * can no longer be statted counts as moved. Advisory only: it never decides
+ * staleness (the digest does), and an unreadable clock yields fewer names,
+ * never a wrong status. Timed through the same injectable resolver the
+ * legacy mtime check uses, rooted at the project so the covered paths
+ * (project-root-relative) resolve.
+ */
+function coveredFilesMovedSinceReport(projectRoot, phaseDir, reportPath, coveredFiles, version, fsImpl, resolver) {
+    const sharedRoots = version >= 2 ? sharedRootsFor(projectRoot, phaseDir, null) : [];
+    const files = canonicalizeCoveredFiles(coveredFiles, { version })
+        .filter((f) => !isVerificationReportPath(f) && !isSharedPlanningDoc(f, sharedRoots));
+    if (files.length === 0)
+        return [];
+    const reportRel = toPosix(node_path_1.default.relative(projectRoot, reportPath));
+    let commitTimes;
+    try {
+        commitTimes = resolver(projectRoot, [reportRel, ...files]);
+    }
+    catch {
+        commitTimes = new Map();
+    }
+    const timeOf = (rel) => {
+        const committed = commitTimes.get(rel);
+        if (committed !== undefined)
+            return committed;
+        try {
+            return fsImpl.statSync(node_path_1.default.join(projectRoot, rel)).mtimeMs;
+        }
+        catch {
+            return null;
+        }
+    };
+    const reportTime = timeOf(reportRel);
+    if (reportTime === null)
+        return [];
+    return files.filter((rel) => {
+        const t = timeOf(rel);
+        return t === null || t > reportTime;
+    });
+}
+/** At most this many uncovered artifact names are spelled out in `next_action`; the rest are counted. */
+const STALE_NAMED_ARTIFACT_LIMIT = 5;
+function staleNextAction(detail) {
+    const name = (items) => {
+        const shown = items.slice(0, STALE_NAMED_ARTIFACT_LIMIT).map((a) => io.formatDiagnosticToken(a));
+        const more = items.length - shown.length;
+        return `${shown.join(', ')}${more > 0 ? ` and ${more} more` : ''}`;
+    };
+    const reasons = [];
+    if (detail.moved.length > 0) {
+        reasons.push(`covered source files changed after the verifier last ran: ${name(detail.moved)}`);
+    }
+    else if (detail.digestMoved) {
+        reasons.push('covered source files changed after the verifier last ran');
+    }
+    if (detail.uncovered.length > 0) {
+        reasons.push(`the report never covered ${name(detail.uncovered)} (a current phase plan or summary it did not declare in covered_files)`);
+    }
+    const tail = detail.digestMoved ? '' : '; no covered file changed';
+    return `Verification is stale — ${reasons.join(', and ')}${tail}. ${STALE_REMEDY}`;
+}
 /**
  * The one result builder (#5118): every `VerificationStatusResult` is
  * projected from `VERIFICATION_ROUTES[status]` here — `route` (the bare
@@ -951,12 +1023,18 @@ function defaultPhaseCleanCommitTimesMs(phaseDir, files, execGitFn = shell_comma
  */
 function routeResult(status, ctx) {
     const entry = VERIFICATION_ROUTES[status];
+    const detail = status === VERIFICATION_STATUS.STALE && ctx.staleDetail
+        && (ctx.staleDetail.uncovered.length > 0 || ctx.staleDetail.moved.length > 0)
+        ? ctx.staleDetail
+        : undefined;
     return {
         status,
-        next_action: entry.next_action,
+        next_action: detail ? staleNextAction(detail) : entry.next_action,
         next_command: projectNextCommand(entry.command, ctx.runtime, `${ctx.phaseArg}${entry.tail}`),
         route: entry.command,
         ...(ctx.message !== undefined ? { message: ctx.message } : {}),
+        ...(detail && detail.uncovered.length > 0 ? { uncovered_artifacts: detail.uncovered } : {}),
+        ...(detail && detail.moved.length > 0 ? { moved_files: detail.moved } : {}),
         ...(ctx.staleCheckIndeterminate ? { staleCheckIndeterminate: true } : {}),
     };
 }
@@ -1396,12 +1474,13 @@ function readVerificationStatus(phaseDir, opts = {}) {
         typeof coveredDigestVal === 'string' &&
         coveredDigestVal.trim().length > 0;
     let staleCheckIndeterminate = false;
+    let staleDetail;
     let isStale;
     if (declaresFingerprint) {
         // Stated directly rather than relying on `null !== coveredDigestVal`
         // being true whenever the pair is malformed: `!hasWellFormedFingerprint`
         // fails closed explicitly, and its `||` short-circuit means
-        // computeCoveredDigest/allCurrentArtifactsCovered never run on a
+        // computeCoveredDigest/uncoveredCurrentArtifacts never run on a
         // malformed (wrong-shaped) `coveredFilesVal`. The two `||`s after it
         // short-circuit in turn: the live-directory re-scan (for a plan/summary
         // added AFTER verification and never declared in covered_files) only
@@ -1423,17 +1502,28 @@ function readVerificationStatus(phaseDir, opts = {}) {
             // #5095 (R1): v3's digest is computed over the declared set UNIONED
             // with the phase's own live artifacts — a plan/summary added after
             // fingerprinting already moves the digest itself, so the separate
-            // live-directory re-scan (`allCurrentArtifactsCovered`) is redundant
+            // live-directory re-scan (`uncoveredCurrentArtifacts`) is redundant
             // for v3 and is not run.
             isStale =
                 computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal;
+            if (isStale) {
+                const moved = coveredFilesMovedSinceReport(projectRoot, phaseDir, located.filePath, coveredFilesVal, storedVersion, fsImpl, phaseCleanCommitTimesMs);
+                if (moved.length > 0)
+                    staleDetail = { uncovered: [], moved, digestMoved: true };
+            }
         }
         else {
             // v1/v2: unchanged — the digest alone cannot see a plan/summary that
             // was never declared, so the live-directory re-scan still runs.
-            isStale =
-                computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal ||
-                    !allCurrentArtifactsCovered(phaseDir, coveredFilesVal);
+            const digestMoved = computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal;
+            const uncovered = uncoveredCurrentArtifacts(phaseDir, coveredFilesVal);
+            isStale = digestMoved || uncovered === null || uncovered.length > 0;
+            const moved = digestMoved
+                ? coveredFilesMovedSinceReport(projectRoot, phaseDir, located.filePath, coveredFilesVal, storedVersion, fsImpl, phaseCleanCommitTimesMs)
+                : [];
+            if ((uncovered !== null && uncovered.length > 0) || moved.length > 0) {
+                staleDetail = { uncovered: uncovered ? [...uncovered].sort() : [], moved, digestMoved };
+            }
         }
     }
     else {
@@ -1449,7 +1539,7 @@ function readVerificationStatus(phaseDir, opts = {}) {
     if (isStale) {
         // #4682 / #5118: the one stale route — execute-phase's verify_phase_goal
         // step re-runs the verifier, regenerating VERIFICATION.md and its digest.
-        return route(VERIFICATION_STATUS.STALE);
+        return route(VERIFICATION_STATUS.STALE, staleDetail ? { staleDetail } : {});
     }
     // 3. Route the writer-set member through the one table.
     return route(reportStatus, { staleCheckIndeterminate });

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

@@ -1147,6 +1147,38 @@ function unreadableFileVerdict(evidence, displayPath) {
         : { error: 'File unreadable', path: displayPath, read_error: evidence.reason };
     return (0, gate_verdict_cjs_1.gateUnreadable)(false, payload);
 }
+/**
+ * Issue #4927 — a PLAN.md can be cut off by a tool that still reported the write
+ * as successful (runtimes cap tool-call output; a ~450-line plan stopped inside
+ * an XML tag). The planner and the plan checker both run `verify plan-structure`
+ * on every plan, so this is where a silent partial write is caught, independent
+ * of what the write call returned.
+ *
+ * Three signals, each a strong sign of a partial file and none of them a shape a
+ * finished plan carries:
+ *   - the incremental-write sentinel (`<!-- gsd:write-continue -->`) left behind
+ *     (the planner's large-file fallback never removed it);
+ *   - `<tasks>` opened and never closed;
+ *   - the file ends inside a tag (`...</ta`). Prose such as `a < b` does not
+ *     match: a tag needs a name character straight after the `<` or `</`.
+ */
+function scanPlanTruncation(content) {
+    const errors = [];
+    const text = content || '';
+    if (/<!--\s*gsd:write-continue\s*-->/.test(text)) {
+        errors.push('Plan appears truncated: the incremental-write sentinel `<!-- gsd:write-continue -->` is still present — '
+            + 'the last section was never written. Finish the write (or re-write the plan) before treating it as complete.');
+    }
+    if (/<tasks>/.test(text) && !/<\/tasks>/.test(text)) {
+        errors.push('Plan appears truncated: `<tasks>` is opened but `</tasks>` never appears — the file was cut off before the task list ended.');
+    }
+    const trimmed = text.replace(/\s+$/, '');
+    const lastLt = trimmed.lastIndexOf('<');
+    if (lastLt !== -1 && trimmed.indexOf('>', lastLt) === -1 && /^<\/?[A-Za-z_!][^<>]{0,200}$/.test(trimmed.slice(lastLt))) {
+        errors.push(`Plan appears truncated: the file ends inside a tag (\`${trimmed.slice(lastLt).slice(0, 40)}\`) — the write stopped mid-payload.`);
+    }
+    return errors;
+}
 function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (!filePath) {
         error('file path required');
@@ -1172,6 +1204,8 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     const fm = extractFrontmatter(content, fullPath);
     const errors = [];
     const warnings = [];
+    // #4927: a plan the write tool reported as written but that ends mid-payload.
+    errors.push(...scanPlanTruncation(content));
     const required = ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'];
     for (const field of required) {
         if (fm[field] === undefined)
@@ -1220,7 +1254,8 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
             continue;
         if (!decisionCheckpointOffsets.some((offset) => offset < at)) {
             warnings.push('Task rated <reversibility rating="one-way"> has no preceding checkpoint:decision — '
-                + 'a one-way door must be confirmed before the agent walks through it');
+                + 'a one-way door must be confirmed before the agent walks through it (unless the decision is already settled '
+                + 'in CONTEXT.md, an ingested ADR, or an answered checkpoint)');
         }
     }
     const echoScan = scanNegativeGrepCommentEcho(content);

package/gsd-core/references/agent-contracts.md

@@ -33,7 +33,7 @@ This doc describes what IS, not what should be. Casing inconsistencies are docum
 | gsd-code-reviewer | Source-code review | No marker (writes REVIEW.md) | `gsd-core/workflows/code-review.md` reads REVIEW.md | artifact+query |
 | gsd-assumptions-analyzer | Assumption extraction | No marker (returns `## Assumptions` sections) | `gsd-core/workflows/discuss-phase-assumptions.md` reads the inline `## Assumptions` sections from the agent's return | structured-return |
 | gsd-doc-classifier | Planning-doc classification | No marker (writes `.planning/intel/classifications/*.json`) | `gsd-core/workflows/ingest-docs.md` reads the classification JSON | artifact+query |
-| gsd-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) | `.planning/tmp/verify-{doc_filename}.json` artifact, read by `gsd-core/workflows/docs-update.md` | artifact+query |
+| gsd-doc-verifier | Doc validation | No marker (writes JSON to `.planning/tmp/`) | `{project_root}/.planning/tmp/verify-{doc_key}.json` artifact (the orchestrator-assigned `result_path`, keyed by the doc's full relative path), read by `gsd-core/workflows/docs-update.md` | artifact+query |
 | gsd-doc-writer | Doc generation | No marker (writes docs directly) | generated doc files, consumed by `gsd-core/workflows/docs-update.md` and `gsd-core/workflows/docs-update/steps/dispatch-monorepo-packages.md` | artifact+query |
 | gsd-domain-researcher | Domain research | No marker (writes the AI-SPEC.md domain section via Edit) | `gsd-core/workflows/ai-integration-phase.md` reads the AI-SPEC.md section after the agent returns | artifact+query |
 | gsd-eval-auditor | Evaluation coverage audit | No marker (writes the REVIEW.md audit section) | `gsd-core/workflows/eval-review.md` reads REVIEW.md | artifact+query |

package/gsd-core/references/agent-skills-bootstrap.md

@@ -22,22 +22,41 @@ In your mandatory init step — right after `mandatory-initial-read.md` / the
    injection also runs (e.g. Claude Code). The guard is what keeps the two seams from
    doubling the block.
 
-2. **Query your configured skills.** Use **your own agent type** — the `name:` value in
-   your frontmatter (e.g. an agent whose frontmatter says `name: gsd-executor` queries
-   `gsd-executor`). The query is read-only and idempotent — it exits 0 with an empty
-   block when nothing is configured for your type:
+2. **Query your configured skills.** Use **your own agent type**: the one your agent
+   file states on its `agent_skills:` pointer line, as `(agent type: \`gsd-executor\`)`.
+   Do not read it from your frontmatter `name:` — Claude Code shows a subagent only the
+   body, the Kimi converter drops frontmatter, and Codex keeps it in a TOML key. Run the
+   query with `--skills-only`, in the **same bash call** as the launcher so `gsd_run` is
+   defined when it runs. Substitute your type for `<your-agent-type>`:
 
    ```bash
-   _AGENT_SKILLS=$(gsd_run query agent-skills <YOUR-FRONTMATTER-NAME> 2>/dev/null || true)
+   # 1. Launcher: paste the bash block from gsd-run-resolver.md here unless gsd_run
+   #    is already defined in this shell (@~/.claude/gsd-core/references/gsd-run-resolver.md).
+   # 2. Query:
+   _AGENT_SKILLS=$(gsd_run query agent-skills <your-agent-type> --skills-only)
    ```
 
-   The runtime `gsd_run` resolver is the standard one from
-   `_runtime-launcher.snippet.sh`; your own init already defines it.
+   Not every agent file defines `gsd_run`, so supply it as above rather than assuming
+   your init did. The query is read-only and idempotent. Its stderr and exit status stay
+   visible, so a missing launcher or a failed query is never mistaken for "nothing
+   configured".
 
 3. **Read every listed skill.** The block emits entries as `@<path>/SKILL.md`
    includes — `Read` each one before starting work. If the block is empty, there is
    nothing to do (zero overhead).
 
+## What the query returns, per runtime
+
+| Call | Claude | Non-Claude (Codex, Kimi, OpenCode, Kilo, …) |
+|---|---|---|
+| `query agent-skills <type> --skills-only` (the self-load) | configured skills, or an empty block | configured skills, or an empty block |
+| `query agent-skills <type>` (orchestrator-side `${AGENT_SKILLS_*}` injection) | configured skills, or an empty block | configured skills, or — when nothing is configured and the agent is installed — the agent's own **persona** (#2454, #4407) |
+
+On a non-Claude runtime the plain query can answer with the agent's whole persona
+(about 47 KB for the executor). `--skills-only` is what keeps the self-load from
+reading your own persona back into your context as if it were a skills block. Never
+run the query without it from inside an agent.
+
 ## What self-load does and does not cover
 
 | Skill form | Self-loads? | Notes |

package/gsd-core/references/git-integration.md

@@ -144,10 +144,10 @@ gsd_run query commit "docs({phase}-{plan}): complete [plan-name] plan" --files .
 </format>
 
 <format name="handoff">
-## Handoff (WIP)
+## Handoff (Pause)
 
 ```
-wip: [phase-name] paused at task [X]/[Y]
+docs(pause): [phase-name] paused at task [X]/[Y]
 
 Current: [task name]
 [If blocked:] Blocked: [reason]
@@ -156,7 +156,7 @@ Current: [task name]
 What to commit:
 
 ```bash
-gsd_run query commit "wip: [phase-name] paused at task [X]/[Y]" --files .planning/
+gsd_run query commit "docs(pause): [phase-name] paused at task [X]/[Y]" --files .planning/
 ```
 
 </format>

package/gsd-core/references/planner-reversibility.md

@@ -20,7 +20,7 @@ this turns out wrong three phases from now, what does undoing it cost?*
 |---|---|---|
 | `reversible` | Local and cheap — one file, one function, an implementation swapped behind a stable interface. | `reversible` decisions get no checkpoint and no flag; the task proceeds normally. |
 | `costly` | Undo touches many call sites or needs a coordinated change — a shared interface shape, a cross-module contract, a dependency major bump. | `costly` decisions are flagged in the plan so the reader sees the weight, but this does not block execution. |
-| `one-way` | Undo requires a data migration, breaks a published contract, or cannot be done at all — on-disk/wire format, public API shape, external-service lock-in, a schema other systems already read. | The planner inserts a `checkpoint:decision` **before** the dependent task, so the human confirms the door before the agent walks through it. |
+| `one-way` | Undo requires a data migration, breaks a published contract, or cannot be done at all — on-disk/wire format, public API shape, external-service lock-in, a schema other systems already read. | The planner inserts a `checkpoint:decision` **before** the dependent task, so the human confirms the door before the agent walks through it — unless the human already settled that decision (see *Already settled*). |
 
 **When unsure, rate it `reversible`.** The value of this feature is
 *discrimination*. A planner that rates everything `one-way` produces checkpoint
@@ -101,6 +101,21 @@ the same terms as any other ingested text (ADR-1577,
   carrying something that belongs in `<context>`, and long free text is where
   smuggled structure hides.
 
+## Already settled
+
+A `one-way` decision the human has **already settled** keeps its rating for the
+record and gets **no** new `checkpoint:decision`. It is settled when any of
+these records the human choosing this exact option:
+
+- the phase `CONTEXT.md` `<decisions>` block (discuss-phase output);
+- an ADR ingested with `--ingest`;
+- a `checkpoint:decision` earlier in this phase's plans that was already answered.
+
+Only a **newly surfaced** `one-way` decision — one nothing above records — earns a
+fresh checkpoint before the implementing task. If you cannot point at the record,
+treat the decision as newly surfaced. `gsd-planner` and this reference state the
+same rule; if they ever diverge, this file wins.
+
 ## Anti-patterns
 
 - **Everything is `one-way`.** The most common failure. Re-read the undo cost:
@@ -111,9 +126,8 @@ the same terms as any other ingested text (ADR-1577,
 - **A rationale that restates the rating.** "This is irreversible because it
   cannot be undone" tells the reader nothing. Name the migration, the contract,
   or the dependent system.
-- **Gating a decision already made.** If the phase CONTEXT.md records the human
-  choosing this exact option, the door is already walked through. Keep the
-  rating for the record; do not insert a checkpoint to re-ask.
+- **Gating a decision already made.** See *Already settled* below: a decision the
+  human has already settled does not earn a fresh checkpoint.
 - **Using the gate as a substitute for design.** The checkpoint buys deliberation
   on a door you must walk through. The better move, when available, is to *make
   the decision reversible* — put the format behind a writer seam, version the

package/gsd-core/references/planner-verify-command-grounding.md

@@ -16,6 +16,24 @@ preferred over `cd <dir> && npm run <script>` — it does not depend on the exec
 `prior_verify_commands` is empty and you cannot ground a path, say so in the plan instead of
 guessing one.
 
+**Run a count/match gate before it ships (#4927).** A gate you author — or one a `RESEARCH.md`
+hands you — that counts or matches text (`grep -c`, `grep -q`, `rg`, `test -n "$(grep …)"`) is a
+claim about the tree, and two defects are invisible to reading and take one command to expose. You
+have a shell when you author the plan, so run each such gate against the **current tree** and write
+the pre-change result next to it as its baseline (`# baseline at HEAD: 0`):
+
+- **It already passes at HEAD.** `grep -c "Agent" .planning/PROJECT.md` returned `6` before any work
+  existed, because the word sat in an unrelated row — the gate measures nothing and passes whether
+  or not the work happens. Fix the gate: anchor it to the new heading, key, or line the task
+  creates, or assert a delta from the recorded baseline.
+- **Its literal can never match the deliverable.** `grep` is case-sensitive, so `grep -c "quickstart"`
+  fails on a correct `## Quickstart`. Match the real casing of the text the task writes, or use
+  `-i` when casing is not part of the contract.
+
+A gate that is meant to prove a *negative* is checked the other way: it must pass after the work
+and its baseline must show the thing was there to remove. Only read-only commands are safe to run
+this way — run `grep`/`rg`/`test` gates; do not execute a gate that builds, installs, or writes.
+
 **Root-relative, never absolute (#4767).** The paths in your prompt's `<required_reading>` are
 absolute on purpose — a subagent's cwd may differ from the orchestrator's (#2376). That rule
 covers prompt *inputs* only. Every path in the plan *body* — `<files>`, `<verify>`, `<automated>`,

package/gsd-core/references/tdd.md

@@ -96,11 +96,12 @@ After completion, create SUMMARY.md with:
 2. Write test describing expected behavior (from `<behavior>` element)
 3. Run test - it MUST fail **intentionally** (#3770): the TARGET test you named must be the test that fails, on an assertion for the planned behavior. A nonzero exit alone is NOT RED — syntax errors, zero-test discovery, fixture crashes, parser errors, and unrelated assertions are INVALID_RED and must not authorize GREEN.
 4. Persist the RED evidence from the actual command: `{command, exitCode, output, targetTest, targetFile, expected, actual}`. Preserve the real exit status and unmodified report; record the planned expected result and observed actual result. Write the record inside the project directory; the classifier refuses a path outside it. It reads only these fields, so the further fields below stay in the record for review.
-   - Select evidence by **report format**, regardless of runner or package manager. The classifier has a shared TAP adapter for Node's built-in test runner and Vitest (`tap` / `tap-flat`), a JUnit XML adapter for Maven Surefire/Failsafe, a swift-testing console adapter for `swift test`, and a Python `unittest` text adapter. Other producers of these formats use the same adapters.
+   - Select evidence by **report format**, regardless of runner or package manager. The classifier has a shared TAP adapter for Node's built-in test runner and Vitest (`tap` / `tap-flat`), a JUnit XML adapter for Maven Surefire/Failsafe, a swift-testing console adapter for `swift test`, a Python `unittest` text adapter, and a `go test` text adapter. Other producers of these formats use the same adapters.
    - TAP: capture the complete reporter output, including its test plan. Node summary comments are optional. The report must start with its TAP output: capture the reporter's own stdout (for npm scripts, `npm run --silent`), not package-manager banners. Use the target test's exact name; when names repeat, use its qualified name as emitted in the report (`tap-flat` emits only the full `file > suite > test` name). Suite/file summary failures are not target assertions. If the reporter is incompatible, rerun the planned target with a supported reporter through the project's test command, capture that real command and result, then submit the rerun's record to the classifier below. Preserve other console output separately rather than editing the report to make it parse.
    - JUnit XML: capture the unchanged target report generated by the actual run. For Maven this is `target/surefire-reports/TEST-*.xml` or `target/failsafe-reports/TEST-*.xml`. Record the report path, run start, and modification time as `reportPath`, `runStartedAt`, and `reportModifiedAt`; require the report to be newer than the run start and verify the named target class or method executed in that run. Name the target as the method, the class (simple or package-qualified), or `<package.Class>#<method>`. Put one complete XML document in `output`, preserving console output alongside it. Missing, stale, or ambiguous reports require STOP and investigation.
+   - `go test`: capture the complete console output (`go test ./...` or `-v`; `-json` is not supported) including every package summary line (`FAIL\tpkg\t0.004s`). A failed test is its `--- FAIL: TestName` line; the same test name failing in two packages is ambiguous and needs the package-qualified target `import/path.TestName`. A package that does not compile (`FAIL\tpkg [build failed]`) or load (`[setup failed]`) asserted nothing — the usual cause is a test naming a symbol that does not exist yet — and the whole run is refused as `build_failure`, even if another package genuinely failed. Make the test compile and fail on its assertion, then record the run again.
    - swift-testing and `unittest`: capture the complete console output without color (`NO_COLOR=1`), including the final summary. swift-testing needs one `Test` result line (passed, failed, skipped, or cancelled) for every test its `Test run with N tests` summary counts; it names a test by its quoted display name or, without one, by its function name (`addsNumbers()`), and either name identifies the target; repeated swift-testing names are ambiguous and block GREEN. `unittest` needs one `FAIL:`/`ERROR:` header for every failure or error its `FAILED (...)` line counts; repeated headers from one test's failing subTests count as one failing test, a method name that repeats across classes needs its `module.Class.method` id, and a `unittest.loader._FailedTest` entry is a load failure, never RED.
-   - Pass the unchanged record to `gsd_run check tdd-red-evidence <record.json> --raw` and require `RED_EVIDENCE_OK` before GREEN. Every `INVALID_RED` reason (`unexpected_green`, `zero_tests_discovered`, `nonzero_exit_without_test_failure`, `fixture_or_load_failure`, `no_target_test_failure`, `invalid_record`, `unreadable_record`) trips the gate. `invalid_record` includes unsupported or malformed reports; inspect `evidence.report_errors`. An unsupported format requires a supported reporter or a parser adapter before GREEN. Classifier rejection never authorizes a fallback to self-attestation.
+   - Pass the unchanged record to `gsd_run check tdd-red-evidence <record.json> --raw` and require `RED_EVIDENCE_OK` before GREEN. Every `INVALID_RED` reason (`unexpected_green`, `zero_tests_discovered`, `nonzero_exit_without_test_failure`, `fixture_or_load_failure`, `no_target_test_failure`, `build_failure`, `invalid_record`, `unreadable_record`) trips the gate. `invalid_record` includes unsupported or malformed reports; inspect `evidence.report_errors`. An unsupported format requires a supported reporter or a parser adapter before GREEN. Classifier rejection never authorizes a fallback to self-attestation.
    - After machine validation, inspect whether the target actually executed and failed on the planned assertion for the intended reason. Zero tests, a missing, skipped, or cancelled target, setup, collection, import, syntax, or fixture faults, unrelated failures, unexpected green, and incomplete or ambiguous evidence block GREEN. Record this semantic assessment as `semanticAssessment` in the RED evidence and in the SUMMARY's RED entry; never fabricate reports, counters, or parser verdicts.
 5. If test passes: feature exists or test is wrong. Investigate.
 6. Commit: `test({phase}-{plan}): add failing test for [feature]`
@@ -341,7 +342,7 @@ TDD Plans: {count} | Gate violations: {count}
 
 ### What the Review Checks
 
-1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order
+1. **Gate sequence:** Each TDD plan has RED → GREEN commits in order. A plan is scored on its own `test(<plan>):` / `feat(<plan>):` commits, with one exception (#4867): a RED-only probe plan is satisfied by a `feat(...)` commit under a plan that declares it in `depends_on`, directly or through a chain. That is the gap-closure shape (probe plan, then the fix plan that depends on it). The plan's own RED is still required, a plan nothing depends on is scored alone, and the report names the plan that supplied the GREEN (`Plan {id} GREEN is supplied by dependent plan {id}.`).
 2. **Test quality:** RED phase tests fail for the right reason (not import errors or syntax)
 3. **Minimal GREEN:** Implementation is minimal — no premature optimization in GREEN phase
 4. **Refactor discipline:** If REFACTOR commit exists, tests still pass

package/gsd-core/references/verifier-phase-gates.md

@@ -39,7 +39,12 @@ fi
 ```
 
 The handler returns JSON `{ skipped, blocking: false, total, honored,
-not_honored: [...], message }`. A non-zero `DECISION_EXIT` (`69` `UNAVAILABLE`: the gate
+not_honored: [...], message }`, plus `reason` on a skip or a caller error. On a
+caller error about the phase directory (`reason` is `'phase directory not found'`,
+`'phase path is not a directory'`, `'phase directory unreadable'` or
+`'phase directory holds no plans'`), `total` and `honored` are `null` and
+`not_honored` is `[]`; nothing was checked, so there is no count to report.
+A non-zero `DECISION_EXIT` (`69` `UNAVAILABLE`: the gate
 could not read CONTEXT.md or the phase artifacts, #5170) is **not** "no decisions": record
 `Decision coverage: not evaluated (the gate could not read its evidence)` in VERIFICATION.md
 and do not report counts.
@@ -49,6 +54,8 @@ section) to VERIFICATION.md regardless of outcome — even when all
 decisions are honored, recording the count helps reviewers spot drift over
 time. Set `decision_coverage` in the verification result to
 `{honored, total, not_honored: [...]}` so downstream tooling can read it.
+On a caller error that is `{honored: null, total: null, not_honored: []}`;
+pass the nulls through rather than coercing them to `0`.
 
 **Status impact:** none. The decision gate does NOT influence the
 `gaps_found` / `human_needed` / `passed` decision tree in Step 9. Its

package/gsd-core/workflows/add-backlog.md

@@ -55,7 +55,11 @@ Plans:
 Apply the `project_code` prefix (if set in `.planning/config.json`) so the backlog directory name is consistent with all other phase-creation paths:
 
 ```bash
-SLUG=$(gsd_run query generate-slug "$ARGUMENTS" --raw)
+IFS= read -rd '' GSD_ARGS <<'GSD_ARGS_END' || true
+$ARGUMENTS
+GSD_ARGS_END
+GSD_ARGS=${GSD_ARGS%$'\n'}
+SLUG=$(gsd_run query generate-slug "$GSD_ARGS" --raw)
 PROJECT_CODE=$(gsd_run query config-get project_code --raw 2>/dev/null || echo "")
 PREFIX=$([ -n "$PROJECT_CODE" ] && echo "${PROJECT_CODE}-" || echo "")
 PHASE_DIR=".planning/phases/${PREFIX}${NEXT}-${SLUG}"
@@ -66,7 +70,11 @@ touch "${PHASE_DIR}/.gitkeep"
 ## Step 5: Commit
 
 ```bash
-gsd_run query commit "docs: add backlog item ${NEXT} — ${ARGUMENTS}" --files .planning/ROADMAP.md "${PHASE_DIR}/.gitkeep"
+IFS= read -rd '' GSD_ARGS <<'GSD_ARGS_END' || true
+$ARGUMENTS
+GSD_ARGS_END
+GSD_ARGS=${GSD_ARGS%$'\n'}
+gsd_run query commit "docs: add backlog item ${NEXT} — ${GSD_ARGS}" --files .planning/ROADMAP.md "${PHASE_DIR}/.gitkeep"
 ```
 
 ## Step 6: Report