@opengsd/gsd-core 1.17.0 → 1.19.0

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/verification.cjs

@@ -47,6 +47,8 @@ const coreUtilsMod = require("./core-utils.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-scope.cjs is an export= CommonJS module
 const planningScopeMod = require("./planning-scope.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
+const text_lines_cjs_1 = require("./text-lines.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
 const security_cjs_1 = require("./security.cjs");
 const pattern_cjs_1 = require("./pattern.cjs");
@@ -607,17 +609,19 @@ function phaseArtifactPaths(phaseDir, projectRoot) {
  *                `.planning/<project>/workstreams/<ws>`), covering a
  *                per-project/per-workstream store symlink (amendment 1,
  *                revised R7).
+ *   v4 (#5351) — v3 with each CRLF byte pair hashed as LF. Every other
+ *                byte, including a lone CR and non-UTF-8 input, is preserved.
  *
  * A stored digest names its own version (`v<N>:sha256:…`), and
  * `readVerificationStatus` recomputes under the STORED version rather than
  * this constant — so bumping it does not flip every already-verified phase
- * to `stale` on upgrade. A legacy v1/v2 report keeps its own semantics
- * (shared documents included for v1; no report filter or artifact union for
- * either) until it is re-fingerprinted; only a version outside
+ * to `stale` on upgrade. A legacy v1/v2/v3 report keeps its own raw-byte
+ * semantics (shared documents included for v1; no report filter or artifact
+ * union for v1/v2) until it is re-fingerprinted; only a version outside
  * `KNOWN_FINGERPRINT_VERSIONS` is unrecomputable and fails closed.
  */
-const FINGERPRINT_VERSION = 3;
-const KNOWN_FINGERPRINT_VERSIONS = new Set([1, 2, 3]);
+const FINGERPRINT_VERSION = 4;
+const KNOWN_FINGERPRINT_VERSIONS = new Set([1, 2, 3, 4]);
 /**
  * #4623: the planning roots whose DIRECT children are repo-wide planning
  * documents, as project-root-relative posix paths. Always `.planning`; plus
@@ -815,7 +819,22 @@ function deriveCoveredDigest(projectRoot, coveredFiles, version = FINGERPRINT_VE
         catch {
             return { ok: true, digest: null, files: declared, mappedPhaseDir: artifactMappedPhaseDir };
         }
-        const fileHash = node_crypto_1.default.createHash('sha256').update(bytes).digest('hex');
+        const hash = node_crypto_1.default.createHash('sha256');
+        if (version >= 4) {
+            // #5351: drop only the CR in each CRLF pair without decoding the
+            // covered input — binary files and lone CR bytes keep their meaning.
+            // Hash Buffer slices directly, retaining the LF at each new start.
+            let start = 0;
+            for (let crlf = bytes.indexOf('\r\n'); crlf !== -1; crlf = bytes.indexOf('\r\n', start)) {
+                hash.update(bytes.subarray(start, crlf));
+                start = crlf + 1;
+            }
+            hash.update(bytes.subarray(start));
+        }
+        else {
+            hash.update(bytes);
+        }
+        const fileHash = hash.digest('hex');
         parts.push(`${rel}\n${fileHash}\n`);
         hashed++;
     }
@@ -1175,6 +1194,72 @@ function findVerificationStatusError(phaseDirs, deps = {}) {
     }
     return null;
 }
+/**
+ * #5291: legacy report statuses `validate health --repair` may rewrite, and the
+ * closed-set status each becomes. Deliberately minimal — only the value the
+ * maintainer ruled on (`pass_with_caveats` -> `passed`). Every other status
+ * outside the closed set (`pending`, `partial`, …) has NO mapping: it stays
+ * refused and its W030 stays advise-only (fail closed; only `passed` satisfies
+ * the gate). The original value is preserved in `legacy_status`.
+ */
+const LEGACY_STATUS_REPAIRS = Object.freeze({
+    pass_with_caveats: VERIFICATION_STATUS.PASSED,
+});
+/** The closed-set status a known legacy `raw` status repairs to, or `null` when it has no mapping. */
+function legacyStatusRepairTarget(raw) {
+    return typeof raw === 'string' && Object.prototype.hasOwnProperty.call(LEGACY_STATUS_REPAIRS, raw)
+        ? LEGACY_STATUS_REPAIRS[raw]
+        : null;
+}
+/**
+ * #5291: rewrite one report's frontmatter `status:` from a known legacy value
+ * to its closed-set equivalent and record the original as `legacy_status:`
+ * right after it. Touches only those lines — every other byte (body, other
+ * keys, line endings) is preserved — and never overwrites an existing
+ * `legacy_status`. Refuses (writes nothing) for a path that is not a report
+ * contained in its own phase directory, a report with no frontmatter `status`,
+ * and any status without a mapping.
+ */
+function repairLegacyVerificationStatus(filePath) {
+    if (!isReportContained(node_path_1.default.dirname(filePath), filePath)) {
+        return { ok: false, reason: 'the report is not contained in its phase directory' };
+    }
+    let content;
+    try {
+        content = node_fs_1.default.readFileSync(filePath, 'utf-8');
+    }
+    catch (err) {
+        return { ok: false, reason: err instanceof Error ? err.message : String(err) };
+    }
+    // The fence owner (`locateFrontmatterFence`) is the one place that knows where
+    // the frontmatter body starts and ends (BOM, CRLF, lenient closing fence).
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(content);
+    if (!fence || !fence.closed)
+        return { ok: false, reason: 'the report has no closed frontmatter' };
+    const lines = (0, text_lines_cjs_1.splitLines)(content.slice(fence.openEnd, fence.bodyEnd));
+    // The YAML reader keeps the LAST of duplicate keys, so the line the repair
+    // edits is the last `status:` line — the very value the refusal named. A
+    // trailing comment (`status: pass_with_caveats # x`) is not part of the value.
+    let statusAt = -1;
+    lines.forEach((l, i) => { if (/^status:/.test(l))
+        statusAt = i; });
+    if (statusAt === -1)
+        return { ok: false, reason: 'the report frontmatter has no status' };
+    const raw = lines[statusAt]
+        .replace(/^status:\s*/, '')
+        .replace(/\s+#.*$/, '')
+        .replace(/\s+$/, '')
+        .replace(/^(["'])(.*)\1$/, '$2');
+    const to = legacyStatusRepairTarget(raw);
+    if (to === null)
+        return { ok: false, reason: `${describeRawStatus(raw)} has no known repair` };
+    const legacyStatusKept = lines.some((l) => /^legacy_status:/.test(l));
+    lines[statusAt] = `status: ${to}`;
+    if (!legacyStatusKept)
+        lines.splice(statusAt + 1, 0, `legacy_status: ${raw}`);
+    (0, shell_command_projection_cjs_1.platformWriteSync)(filePath, content.slice(0, fence.openEnd) + (0, text_lines_cjs_1.joinLines)(lines, fence.eol) + content.slice(fence.bodyEnd), { verbatim: true });
+    return { ok: true, from: raw, to, legacyStatusKept };
+}
 /**
  * #3518: the shared phase-pinned artifact-selection core BOTH single-pick
  * resolvers (`resolveVerificationFile` for `*-VERIFICATION.md`,
@@ -1499,11 +1584,11 @@ function readVerificationStatus(phaseDir, opts = {}) {
             isStale = true;
         }
         else if (storedVersion >= 3) {
-            // #5095 (R1): v3's digest is computed over the declared set UNIONED
+            // #5095 (R1): the v3+ 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 (`uncoveredCurrentArtifacts`) is redundant
-            // for v3 and is not run.
+            // for v3+ and is not run.
             isStale =
                 computeCoveredDigest(projectRoot, coveredFilesVal, storedVersion, { phaseDir }) !== coveredDigestVal;
             if (isStale) {
@@ -1784,7 +1869,7 @@ function parseFingerprintFileArgs(tokens) {
  *                       directly assignable. #5095 (ADR-5057 Phase 2): `raw`
  *                       returning only the digest is safe even though the
  *                       emitted `covered_files` is a SUPERSET of the caller's
- *                       declared list — the v3 digest is computed over
+ *                       declared list — the v3+ digest is computed over
  *                       `canonicalize(declared ∪ phaseArtifactPaths)` on BOTH
  *                       the emit side (here) and the check side
  *                       (`readVerificationStatus`), so a `--raw` caller that
@@ -2134,6 +2219,8 @@ const verificationModule = {
     isReportContained,
     routeResult,
     findVerificationStatusError,
+    legacyStatusRepairTarget,
+    repairLegacyVerificationStatus,
     defaultPhaseCleanCommitTimesMs,
     resolvePhaseArtifactFile,
     resolveVerificationFile,

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);
@@ -1774,6 +1809,8 @@ function repairFixText(slash, action) {
             return `Run ${slash('health')} --repair to add key`;
         case REMEDY_ACTION.BACKFILL_MILESTONES:
             return `Run ${slash('health')} --backfill to synthesize missing entries from archive snapshots`;
+        case REMEDY_ACTION.REPAIR_VERIFICATION_STATUS:
+            return `Run ${slash('health')} --repair to rewrite the legacy status (original kept as legacy_status)`;
         default:
             return '';
     }

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -176,7 +176,28 @@ function resolveWorktreeContext(cwd, deps = {}) {
             reason: 'has_local_planning',
         };
     }
-    return resolveWorktreeLinkage(cwd, deps);
+    const linkage = resolveWorktreeLinkage(cwd, deps);
+    if (linkage.reason !== 'linked_worktree')
+        return linkage;
+    // #4885: from a SUBDIRECTORY of a LINKED worktree the cwd has no .planning of its own, but the
+    // worktree's own top-level may. That checkout is the project the caller means; remapping to the
+    // main checkout would make `commit` and every planning write land in the wrong repository. A linked
+    // worktree with no .planning anywhere still remaps to the main checkout, and the main checkout's own
+    // subdirectories are untouched.
+    const execGit = deps.execGit || execGitDefault;
+    const top = execGit(['rev-parse', '--show-toplevel'], { cwd });
+    const topText = String(top.stdout || '').trim();
+    if (!top.timedOut && top.exitCode === 0 && topText !== '') {
+        const topLevel = node_path_1.default.resolve(cwd, topText);
+        if (existsSync(node_path_1.default.join(topLevel, '.planning'))) {
+            return {
+                effectiveRoot: topLevel,
+                mode: 'current_directory',
+                reason: 'has_local_planning',
+            };
+        }
+    }
+    return linkage;
 }
 function planWorktreePrune(repoRoot, options = {}, deps = {}) {
     const parsePorcelain = deps.parseWorktreePorcelain || parseWorktreePorcelain;

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -22,6 +22,7 @@
   "git": {
     "branching_strategy": "none",
     "create_tag": true,
+    "repo_tagging": "single",
     "base_branch": null,
     "phase_branch_template": "gsd/phase-{phase}-{slug}",
     "milestone_branch_template": "gsd/{milestone}-{slug}",

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -51,6 +51,7 @@
     "git.protected_branches",
     "git.allow_default_branch_commits",
     "git.create_tag",
+    "git.repo_tagging",
     "git.phase_branch_template",
     "git.milestone_branch_template",
     "git.quick_branch_template",

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>
@@ -295,4 +295,15 @@ This stages `src/api/users.ts` and `src/types/user.ts` in the `backend/` repo, a
 
 Files that don't match any configured sub-repo are reported as unmatched.
 
+### Milestone Tagging Across Sub-Repos
+
+A GSD milestone version names planned work in `.planning/`; it is not any repository's release version. With `git.repo_tagging: "per_repo"` and a non-empty `sub_repos`, `/gsd:complete-milestone` records one release map entry per repository (status, release, reference, environment, tag choice) instead of creating one `v[X.Y]` tag in the current directory:
+
+1. `gsd_run query milestone release-tags --map <tags.json> --dry-run` checks every requested tag (repository listed in `sub_repos`, ref resolves, tag name valid, no tag at a different commit) before anything is written.
+2. After one consolidated confirmation, `gsd_run query milestone release-tags --map <tags.json>` creates the annotated tags, each with the target repository as its working directory. Re-running the same map is idempotent (`already_tagged`).
+3. `milestone complete <version> --release-map <file>` archives the map by recorded value.
+4. Nothing is pushed by default. Each repository's tag has its own confirmation naming the repository and its remote.
+
+With `git.create_tag: false` the map is still recorded and no tag is created. See [How to tag a multi-repository milestone](../../docs/how-to/tag-a-multi-repo-milestone.md).
+
 </sub_repos_support>

package/gsd-core/references/loop-hook-dispatch.md

@@ -91,12 +91,19 @@ not one shape of one.
 capability manifest, which may be third-party — and `gates[].check` is **not** one of the
 executable surfaces the install consent prompt discloses (`hooks`, command modules,
 `mcpServers`, reviewer lanes), so a capability can be consented to as declarative-only and
-still reach a shell through a gate. Check the query value you read from `activeHooks` against
-`^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$` yourself, IN-CONTEXT — **never** by pasting it into a
-shell command to be tested there, because a value carrying a quote, `;`, a `` ` ``, `$(`, or a
-newline would terminate the assignment and run as its own statement before any shell-side
-check could execute. A value that fails is a malformed manifest: record a warning, route it
-per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
+still reach a shell through a gate. Normalize first, then validate: the registry declares query
+ids in dotted form (`ui.plan-gate`, `verify.codebase-drift`) and `gsd_run check` accepts them by
+turning each `.` into `-`, so replace every `.` with `-` in the query value you read from
+`activeHooks`, then check that normalized value against
+`^[a-z][a-z0-9]*(-[a-z0-9]+)*( [a-z][a-z0-9]*(-[a-z0-9]+)*)*$` yourself, IN-CONTEXT — **never** by
+pasting it into a shell command to be tested there, because a value carrying a quote, `;`, a
+`` ` ``, `$(`, or a newline would terminate the assignment and run as its own statement before
+any shell-side check could execute. The normalized value is the one value you validate and the
+one value you pass: wherever a workflow shows `${hook.check.query}`, write the normalized value.
+A leading dot, a trailing dot or consecutive dots become a leading, trailing or doubled hyphen,
+which the pattern rejects. A value that fails — or that passes but names no known check, which
+`gsd_run check` rejects as an unknown check subcommand — is a malformed manifest: record a
+warning, route it per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
 element** for the same reason — never re-quote it into a shell string, where an apostrophe
 would close the literal. This is the identical requirement `step` → `ref.command` carries
 above; it was stated there and omitted here, which is the gap #3559 closed.

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/planning-config.md

@@ -35,6 +35,7 @@ Configuration options for `.planning/` directory behavior.
 | `git.base_branch` | `null` (auto-detect) | Target branch for PRs and merges (e.g. `"master"`, `"develop"`). When `null`, auto-detects from `git symbolic-ref refs/remotes/origin/HEAD`, falling back to `"main"`. |
 | `git.protected_branches` | (none) | Optional array of non-empty strings naming additional shared branches that should trigger protected-branch warnings |
 | `git.create_tag` | `true` | Create git tags on milestone completion |
+| `git.repo_tagging` | `"single"` | Milestone tagging mode: `"single"` (existing behavior) or `"per_repo"` (record one release per configured repository; each tag is pushed only after a per-repository confirmation) |
 | `git.phase_branch_template` | `"gsd/phase-{phase}-{slug}"` | Branch template for phase strategy |
 | `git.milestone_branch_template` | `"gsd/{milestone}-{slug}"` | Branch template for milestone strategy |
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
@@ -340,6 +341,7 @@ Set via `git.*` namespace (e.g., `"git": { "branching_strategy": "phase" }`).
 | `git.base_branch` | string\|null | `null` (auto-detect) | Any branch name | Target branch for PRs and merges; auto-detects from `origin/HEAD` when `null` |
 | `git.protected_branches` | array of non-empty strings | (none) | Non-empty branch names | Optional protected names added to the resolved base branch for execute-phase and ship warnings |
 | `git.create_tag` | boolean | `true` | `true`, `false` | Create git tags on milestone completion |
+| `git.repo_tagging` | string | `"single"` | `"single"`, `"per_repo"` | Milestone tagging mode; `"per_repo"` opts a multi-repo project into per-repository release records |
 | `git.phase_branch_template` | string | `"gsd/phase-{phase}-{slug}"` | Template with `{phase}`, `{slug}` | Branch naming template for `phase` strategy |
 | `git.milestone_branch_template` | string | `"gsd/{milestone}-{slug}"` | Template with `{milestone}`, `{slug}` | Branch naming template for `milestone` strategy |
 | `git.quick_branch_template` | string\|null | `null` | Template with `{slug}` | Optional branch template for quick-task runs |

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]`
@@ -315,7 +316,7 @@ git log --oneline -E --grep="^feat\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 git log --oneline -E --grep="^refactor\((0*${PHASE_N})-(0*${PLAN_N})\):" | head -1
 ```
 
-If RED or GREEN gate commits are missing, add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
+If RED or GREEN gate commits are missing, or no GREEN commit follows a RED commit (#5275), add a `## TDD Gate Compliance` section to SUMMARY.md with the violation details.
 </gate_enforcement>
 
 <end_of_phase_review>
@@ -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 (#5275). Order is commit ancestry, not log position or commit date: a GREEN counts only when it descends from a RED commit of the plan, so a history merged from worktree branches is judged by what each commit descends from. A plan with both commit kinds but no GREEN after a RED fails with `reason: green_before_red` and the line `Plan {id} GREEN precedes RED: no feat(...) commit descends from a test(...) commit.`, distinct from the `missing` row for a plan without a RED or GREEN commit. If git cannot answer the ancestry question, the GREEN keeps its credit rather than becoming a violation. 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