@opengsd/gsd-core 1.15.0 → 1.16.0

package/gsd-core/bin/lib/workstream-inventory-builder.cjs

@@ -17,11 +17,16 @@ exports.isCompletedInventory = isCompletedInventory;
 exports.buildWorkstreamInventory = buildWorkstreamInventory;
 const node_path_1 = __importDefault(require("node:path"));
 const phase_lifecycle_cjs_1 = require("./phase-lifecycle.cjs");
+// #5060: `phase-status.cjs` is a load-time leaf (no top-level requires) — its
+// `phaseStatusFromFacts`/`toWireStatus` are pure functions of facts, so
+// importing them here does not violate this module's "No I/O. No async."
+// contract.
+const phase_status_cjs_1 = require("./phase-status.cjs");
 // Internal helpers
 function toPosixPath(p) {
     return p.split('\\').join('/');
 }
-// #2562/#2645's FAILING_VERIFICATION_STATUSES set (the verdicts that used to
+// #2562/#2645's former failing-verdict set (the verdicts that used to
 // disqualify a phase from `complete` when combined with a local
 // summary-count-meets-plan-count check) was removed by ADR-3180 §7.4
 // (#3186): `complete` is now the single canonical owner's verdict
@@ -133,11 +138,14 @@ function buildWorkstreamInventory(inputs) {
         // read `pending` instead of `complete`. `complete` defaults to `false`
         // when absent so a caller that has not been updated to pass it never
         // silently reads as complete.
-        const status = (counts?.complete ?? false)
-            ? 'complete'
-            : planCount > 0
-                ? 'in_progress'
-                : 'pending';
+        // #5060: routed through the Phase Status Module's owner ladder rather
+        // than a local re-derivation of the same complete/planCount branches.
+        const status = (0, phase_status_cjs_1.toWireStatus)((0, phase_status_cjs_1.phaseStatusFromFacts)({
+            planCount,
+            summaryCount,
+            complete: counts?.complete ?? false,
+            verificationStatus: counts?.verificationStatus ?? null,
+        }));
         // #2562: only current-milestone phases feed the rollup when scoping is on,
         // and only one directory per phase key (see rollupDirs above).
         const countsTowardMilestone = (!scoped || counts?.inMilestone !== false) && rollupDirs.has(dir);

package/gsd-core/bin/lib/workstream-inventory.cjs

@@ -33,7 +33,7 @@ const { extractFrontmatter, stripFrontmatter } = frontmatterMod;
 const markdown_table_cjs_1 = require("./markdown-table.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- verification.cjs is an export= CommonJS module
 const verificationMod = require("./verification.cjs");
-const { isPhaseComplete } = verificationMod;
+const { isPhaseComplete, isVerificationStatus, VERIFICATION_STATUS } = verificationMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- phase-id.cjs is an export= CommonJS module
 const phaseIdMod = require("./phase-id.cjs");
 const { phaseKeyFromDir, phaseKeyFromProse, parentPhaseKey } = phaseIdMod;
@@ -269,7 +269,10 @@ function readVerificationLedger(wsDir) {
     }
     const out = {};
     for (const [key, value] of Object.entries(parsed)) {
-        if (typeof value === 'string')
+        // #5118: an entry outside the closed enum (a stored `unknown` from an
+        // older run) reads as absent — the phase then fails CLOSED to
+        // `unrecorded`, the same posture as a corrupt ledger.
+        if (isVerificationStatus(value))
             out[key] = value;
     }
     return { state: 'ok', entries: out };
@@ -555,7 +558,7 @@ function inspectWorkstream(cwd, name, options = {}) {
         // unverified-fallback diagnostic (#3057 B4) — the closest existing idiom,
         // since `WorkstreamInventory`'s aggregate return shape carries no
         // per-phase verification detail for this to attach to.
-        if (verificationResult.staleCheckIndeterminate) {
+        if ('staleCheckIndeterminate' in verificationResult && verificationResult.staleCheckIndeterminate) {
             writeDiagnostic(`⚠ workstream-inventory: verification staleness check could not complete for phase directory '${dir}' in workstream '${name}' — routed as not-stale, but this was not actually verified. See #3057.\n`, { phaseDir: dir, reason: 'staleCheckIndeterminate' });
         }
         return {
@@ -566,14 +569,24 @@ function inspectWorkstream(cwd, name, options = {}) {
             summaryCount: counts.summaryCount,
             inMilestone: isDirInCurrentMilestone(dir),
             liveVerificationStatus: verificationResult.status,
+            // #5118: the owner's out-of-set report error, carried to the check below.
+            statusError: completionResult.value.statusError,
             // ADR-3180 §7.4 (#3186): the owner's verdict, read live off disk — never
             // ledger-adjusted (see the phaseFilesCounts map below; the ledger only
             // ever substitutes a 'missing' status with a remembered one, and under
-            // disk-strict neither 'missing' nor 'unrecorded' is ever complete, so
-            // there is nothing for the ledger to override here).
+            // disk-strict 'missing' is never complete, so there is nothing for the
+            // ledger to override here).
             complete: completionResult.value.complete,
         };
     });
+    // #5118 (no write before the error): this inspection WRITES the ledger
+    // below, so a report whose `status` is outside the closed set fails it
+    // first — the owner's own error thrown as-is (like `init *`, `phase *` and
+    // `state *`), which the CLI entry seam projects once into its reason and
+    // message; nothing persisted.
+    const firstStatusError = rawPhaseEntries.find((entry) => entry.statusError)?.statusError;
+    if (firstStatusError)
+        throw firstStatusError;
     // #2645: only the directory Bug #2445's de-dup rollup would actually pick
     // for a phase key may read or write that key's ledger entry. Letting every
     // same-keyed directory (including a stale leftover) write would let a
@@ -604,10 +617,11 @@ function inspectWorkstream(cwd, name, options = {}) {
     const verificationLedger = ledgerRead.entries;
     let ledgerDirty = false;
     for (const winner of ledgerWinnerByKey.values()) {
-        if (winner.liveVerificationStatus === 'missing')
+        const live = winner.liveVerificationStatus;
+        if (live === null || live === VERIFICATION_STATUS.MISSING)
             continue;
-        if (verificationLedger[winner.phaseKey] !== winner.liveVerificationStatus) {
-            verificationLedger[winner.phaseKey] = winner.liveVerificationStatus;
+        if (verificationLedger[winner.phaseKey] !== live) {
+            verificationLedger[winner.phaseKey] = live;
             ledgerDirty = true;
         }
     }
@@ -620,20 +634,16 @@ function inspectWorkstream(cwd, name, options = {}) {
         writeVerificationLedger(wsDir, verificationLedger);
     const phaseFilesCounts = rawPhaseEntries.map(entry => {
         const isLedgerWinner = ledgerWinnerByKey.get(entry.phaseKey) === entry;
+        // A live `missing` on the ledger winner reads the remembered verdict when
+        // there is one. #5118: the former `unrecorded` state ("adopted, never
+        // recorded") is deleted — its only reader, phaseStatusFromFacts, treats it
+        // exactly like `missing` (only `human_needed` changes the ladder, and under
+        // disk-strict neither is ever complete), so it was a dead distinction.
         let verificationStatus = entry.liveVerificationStatus;
-        if (entry.liveVerificationStatus === 'missing' && isLedgerWinner) {
-            if (ledgerRead.state === 'absent') {
-                // State 1: pre-adoption. Exactly today's behavior — 'missing' is
-                // NOT in FAILING_VERIFICATION_STATUSES, so this does not gate.
-                verificationStatus = 'missing';
-            }
-            else {
-                // States 2/3 ('corrupt' or 'ok'): this workstream has adopted the
-                // ledger. A remembered entry wins; no entry fails CLOSED to the
-                // 'unrecorded' sentinel rather than falling open to 'missing'.
-                const remembered = verificationLedger[entry.phaseKey];
-                verificationStatus = remembered !== undefined ? remembered : 'unrecorded';
-            }
+        if (entry.liveVerificationStatus === VERIFICATION_STATUS.MISSING && isLedgerWinner) {
+            const remembered = verificationLedger[entry.phaseKey];
+            if (remembered !== undefined)
+                verificationStatus = remembered;
         }
         return {
             directory: entry.directory,

package/gsd-core/bin/lib/workstream-name-policy.cjs

@@ -26,7 +26,9 @@
  * phase-id.cts's toDir/getPhaseDirFromPhaseId.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = void 0;
+exports.RESERVED_WORKSTREAM_NAMES = exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = void 0;
+exports.isReservedWorkstreamName = isReservedWorkstreamName;
+exports.reservedWorkstreamNameMessage = reservedWorkstreamNameMessage;
 exports.normalizeWorkstreamNameInput = normalizeWorkstreamNameInput;
 exports.hasInvalidPathSegment = hasInvalidPathSegment;
 exports.validateActiveWorkstreamName = validateActiveWorkstreamName;
@@ -36,6 +38,34 @@ exports.isValidActiveWorkstreamName = isValidActiveWorkstreamName;
 exports.assertValidActiveWorkstreamName = assertValidActiveWorkstreamName;
 exports.INVALID_ACTIVE_WORKSTREAM_NAME_MESSAGE = 'Invalid workstream name: must be alphanumeric, hyphens, underscores, or dots';
 const ACTIVE_WORKSTREAM_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/;
+/**
+ * Names that pass the charset check but can never name a workstream (#4772).
+ * `none` reads as "no workstream" to every caller that types it, yet the path
+ * layer treated it as a literal directory, so `--ws none` silently resolved
+ * `.planning/workstreams/none/...` (and fell back to the root config). Single
+ * owner: resolveActiveWorkstream and workstream create/set all consume this list.
+ */
+exports.RESERVED_WORKSTREAM_NAMES = Object.freeze(['none']);
+/** True when `name` (trimmed, case-insensitive) is a reserved workstream name. */
+function isReservedWorkstreamName(name) {
+    const value = normalizeWorkstreamNameInput(name);
+    return value !== null && exports.RESERVED_WORKSTREAM_NAMES.includes(value.toLowerCase());
+}
+/**
+ * The error text shared by every site that rejects a reserved name. `source`
+ * (where the name came from: 'cli' | 'env' | 'store') picks a remedy that can
+ * actually be carried out: the rejection happens in the gsd-tools bootstrap
+ * before any verb runs, so advising `workstream set --clear` would fail too.
+ */
+function reservedWorkstreamNameMessage(name, source = null) {
+    const value = normalizeWorkstreamNameInput(name) ?? '';
+    const remedy = source === 'env'
+        ? 'unset GSD_WORKSTREAM for flat mode'
+        : source === 'store'
+            ? 'delete the stale active-workstream pointer for flat mode'
+            : 'omit --ws for flat mode';
+    return `Workstream name '${value}' is reserved and cannot name a workstream; ${remedy}`;
+}
 function normalizeWorkstreamNameInput(name) {
     const value = String(name ?? '').trim();
     return value || null;

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

@@ -50,6 +50,9 @@ function migrateToWorkstreams(cwd, workstreamName) {
     catch {
         throw new Error('Invalid workstream name for migration');
     }
+    if ((0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(workstreamName)) {
+        throw new Error((0, workstream_name_policy_cjs_1.reservedWorkstreamNameMessage)(workstreamName));
+    }
     const baseDir = planningRoot(cwd);
     const wsDir = node_path_1.default.join(baseDir, 'workstreams', workstreamName);
     if (node_fs_1.default.existsSync(node_path_1.default.join(baseDir, 'workstreams'))) {
@@ -101,6 +104,9 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
     if (!slug) {
         error('Invalid workstream name — must contain at least one alphanumeric character');
     }
+    if ((0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(slug)) {
+        error((0, workstream_name_policy_cjs_1.reservedWorkstreamNameMessage)(slug));
+    }
     const baseDir = planningRoot(cwd);
     if (!node_fs_1.default.existsSync(baseDir)) {
         error(`.planning/ directory not found — run ${(0, runtime_slash_cjs_1.formatGsdSlash)('new-project', (0, runtime_slash_cjs_1.resolveRuntime)(cwd))} first`);
@@ -331,8 +337,11 @@ function cmdWorkstreamSet(cwd, name, raw) {
         output({ active: null, cleared: true, previous: previous || null }, raw, undefined);
         return;
     }
-    if (!(0, workstream_name_policy_cjs_1.isValidActiveWorkstreamName)(name)) {
-        output({ active: null, error: 'invalid_name', message: 'Workstream name must be alphanumeric, hyphens, underscores, or dots' }, raw, undefined);
+    if (!(0, workstream_name_policy_cjs_1.isValidActiveWorkstreamName)(name) || (0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(name)) {
+        const message = (0, workstream_name_policy_cjs_1.isReservedWorkstreamName)(name)
+            ? (0, workstream_name_policy_cjs_1.reservedWorkstreamNameMessage)(name)
+            : 'Workstream name must be alphanumeric, hyphens, underscores, or dots';
+        output({ active: null, error: 'invalid_name', message }, raw, undefined);
         return;
     }
     const wsDir = node_path_1.default.join(planningRoot(cwd), 'workstreams', name);

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

@@ -14,6 +14,11 @@
   "phase_id_convention": null,
   "mode": "interactive",
   "claude_md_path": "./.claude/CLAUDE.md",
+  "gates": {
+    "execute_next_plan": true,
+    "confirm_transition": true,
+    "confirm_milestone_scope": true
+  },
   "git": {
     "branching_strategy": "none",
     "create_tag": true,

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

@@ -2,6 +2,9 @@
   "_comment": "Canonical schema manifest for valid config key paths. This manifest is the single CJS source of truth for valid config keys; dynamicKeyPatterns source strings are recompiled to RegExp at runtime by config-schema.cjs. runtimeStateKeys mirrors RUNTIME_STATE_KEYS.",
   "validKeys": [
     "mode",
+    "gates.execute_next_plan",
+    "gates.confirm_transition",
+    "gates.confirm_milestone_scope",
     "granularity",
     "parallelization",
     "commit_docs",
@@ -111,6 +114,7 @@
     "resolve_model_ids",
     "effort.default",
     "fast_mode.enabled",
+    "audit.enabled",
     "plan_review.source_grounding",
     "plan_review.source_grounding_authority",
     "model_policy.provider",

package/gsd-core/references/autonomous-smart-discuss.md

@@ -5,7 +5,8 @@ Smart discuss is the autonomous-optimized variant of `gsd-discuss-phase`. It pro
 **Inputs:** `PHASE_NUM` from execute_phase. Run init to get phase paths:
 
 ```bash
-PHASE_STATE=$(gsd_run query init.phase-op ${PHASE_NUM})
+GSD_WS=$(echo " $ARGUMENTS" | sed -nE 's/.* --ws +([A-Za-z0-9][A-Za-z0-9._-]*).*/--ws \1/p' | head -n 1)
+PHASE_STATE=$(gsd_run query init.phase-op ${GSD_WS:+--ws=${GSD_WS##* }} ${PHASE_NUM})
 ```
 
 Parse from JSON: `phase_dir`, `phase_slug`, `padded_phase`, `phase_name`.

package/gsd-core/references/autonomous-ui-design-contract.md

@@ -1,6 +1,6 @@
 # UI Design Contract (Frontend Phases) — Autonomous Mode
 
-Step 3a.5 of `/gsd:autonomous`: resolve whether the current phase needs a UI-SPEC.md generated before planning, and generate one via active `plan:pre` step hooks if so. Always non-blocking — proceeds to step 3b (Plan) regardless of outcome.
+Step 3a.5 of `/gsd:autonomous`: resolve whether the current phase needs a UI-SPEC.md generated before planning, and generate one via active `plan:pre` step hooks if so. Non-blocking for every answer it gets — proceeds to step 3b (Plan) — except a gate that could not look (below), which is surfaced and stops.
 
 **Inputs:** `PHASE_NUM`, `PHASE_DIR` from execute_phase.
 
@@ -16,10 +16,10 @@ Read the `activeHooks` array directly from `HOOKS_JSON` (in-context — do NOT i
 (At least one active step hook ⇒ `workflow.ui_phase` is on.) Run the UI-SPEC gate:
 
 ```bash
-GATE=$(gsd_run check ui-plan-gate "${PHASE_NUM}" --raw)
+GATE=$(gsd_run check ui-plan-gate "${PHASE_NUM}" --raw) && GATE_RC=0 || GATE_RC=$?
 ```
 
-Read `frontend` and `hasUiSpec` from `GATE` (in-context).
+A non-zero `GATE_RC` is a command failure, including `69` (`UNAVAILABLE`: the gate could not read its evidence, so its `frontend: false` is not an answer): surface it and stop — never skip silently to 3b as if the phase had no frontend. Otherwise read `frontend` and `hasUiSpec` from `GATE` (in-context).
 
 **If `frontend` is false:** Skip silently to 3b.
 

package/gsd-core/references/execute-mvp-tdd.md

@@ -15,15 +15,10 @@ If any of these is false, the gate is inactive — execution proceeds normally.
 For each task gated by TDD, the executor MUST verify (before running the implementation step):
 
 1. **A failing-test commit exists.** Search git log on the current branch for a commit matching `test({phase}-{plan})` whose subject mentions the same plan as the current task. The commit must touch a test file (`*.test.*`, `*.spec.*`, `tests/**`).
-2. **The test was actually red — INTENTIONALLY (#3770).** A nonzero exit is not RED by itself: syntax errors, zero-test discovery, fixture crashes, parser errors, and unrelated assertions are INVALID_RED. The executor must persist the RED evidence record (command, exit code, failing test, expected result from `<behavior>`, actual result) and verify it:
-   ```bash
-   gsd_run check tdd-red-evidence <record.json> --raw
-   ```
-   - `RED_EVIDENCE_OK` (reason `target_test_failed`): the TARGET test named by the plan failed on a real assertion — the ONLY verdict that authorizes GREEN.
-   - `INVALID_RED` (reasons `unexpected_green`, `zero_tests_discovered`, `nonzero_exit_without_test_failure`, `fixture_or_load_failure`, `no_target_test_failure`, `invalid_record`, `unreadable_record`): the gate trips — halt, fix the RED phase (test identity, fixture, discovery), and re-verify before any implementation step. A `RED:` prefix or `(RED)` tag in the commit message is NOT sufficient evidence on its own.
+2. **The test was actually red — INTENTIONALLY (#3770).** Read `gsd-core/references/tdd.md`, "Red-Green-Refactor Cycle", RED step 4, and follow its complete evidence contract before GREEN. That section owns format selection (TAP, including Node/Vitest; JUnit XML, including Surefire/Failsafe; swift-testing console; or Python `unittest` text), reporter reruns, report freshness, the classifier invocation, and semantic inspection. Require `RED_EVIDENCE_OK` for the actual run and verify the planned target assertion failed for the intended reason. An `INVALID_RED` verdict, unsupported format, or failed semantic assessment trips this gate; self-attestation cannot substitute for machine validation. A `RED:` prefix or `(RED)` tag in the commit message is not evidence.
 3. **No implementation commit yet.** No `feat({phase}-{plan})` commit may exist for the same plan ID before the failing-test commit.
 
-If any check fails, the gate trips. For check 2, an INVALID_RED verdict (`check tdd-red-evidence`) trips the gate — the executor MUST halt and block the implementation step.
+If any check fails, the gate trips. A non-zero exit from `gsd_run check tdd-red-evidence` (`69` `UNAVAILABLE`: the record could not be read, #5170) is a command failure that has NOT authorized GREEN — the gate trips. For check 2, an `INVALID_RED` classifier verdict or a failed semantic assessment trips the gate (halt reason `invalid_red`) — the executor MUST halt and block the implementation step.
 
 ## What "behavior-adding task" means
 
@@ -52,7 +47,7 @@ The executor MUST:
    Required next step:
    1. Write a failing test for the behavior above.
    2. Commit it as: test({phase}-{plan}): {short description}
-   3. Re-run /gsd execute-phase
+   3. Re-run /gsd:execute-phase
    ```
 
 3. Exit the current execution wave cleanly. Do NOT roll back any prior commits in the same wave.
@@ -65,7 +60,7 @@ The existing end-of-phase TDD review (in `workflows/execute-phase.md`'s `tdd_rev
 Under TDD mode, escalate this to **blocking**:
 - If any TDD plan is missing a RED or GREEN commit, the executor MUST refuse to mark the phase complete.
 - The user is shown the same review table, but the verdict line reads:
-  > "Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under TDD. Resolve and re-run /gsd execute-phase, or override with `/gsd execute-phase {phase} --force-mvp-gate` to ship anyway."
+  > "Phase blocked: {N} TDD plan(s) violate the RED→GREEN gate sequence under TDD. Resolve and re-run /gsd:execute-phase, or override with `/gsd:execute-phase {phase} --force-mvp-gate` to ship anyway."
 
 The `--force-mvp-gate` flag is documented but not introduced by this plan — it is the escape hatch the spec mentions; if the user later builds it, the workflow already references the contract.
 
@@ -73,7 +68,7 @@ The `--force-mvp-gate` flag is documented but not introduced by this plan — it
 
 - It does not enforce REFACTOR commits. REFACTOR remains optional (per `gsd-core/references/tdd.md`).
 - It does not check test quality (the test could be trivially weak). That's the planner's job. It DOES check that the RED failure was intentional — the target test failing an assertion (#3770).
-- It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
+- It does not start implementation by running tests. During RED, the executor runs the planned test and captures its result, rerunning the planned target with a supported reporter when the first report is unsupported (`tdd.md` RED step 4); before GREEN, this gate inspects that persisted evidence, git history, and test assertion. The implementation step starts only after the RED gate passes.
 - It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
 
 ## Compatibility with existing TDD discipline

package/gsd-core/references/execute-phase-between-wave-reset.md

@@ -4,6 +4,9 @@
     - `## Cross-Plan Wiring Gap` with plan/link/from/pattern rows
     - Options: investigate+fix before continue, or continue with cascade risk
     Skip key-links that reference files in the CURRENT (upcoming) wave.
+    Exit status (#5170): `0` all verified; `1` a link failed (read the JSON); `66` the plan declares no
+    key_links (nothing to check); `69` the plan is missing/unreadable (could not look — surface it, never
+    treat the plan as wired).
 
 7c. **Between-wave manifest reset and worktree base refresh (waves 2+ only — #1369):**
 

package/gsd-core/references/execute-phase-response-language.md

@@ -2,7 +2,7 @@
 
 **If `response_language` is set:** User-facing orchestrator output (questions, narration, report-template prose) in `{response_language}`; technical terms, code, file paths, and subagent prompts stay in English. Pass `response_language: {value}` into every spawned subagent prompt so any user-facing output they produce stays in the configured language.
 
-**The `gsd-verifier` subagent has no workflow file of its own (#2529):** the `verify_phase_goal` step reaches it by dispatch, not by reading a workflow, so there is no file in which to place a directive — the dispatch prompt is the only place its coverage can live. That prompt MUST carry this line verbatim, immediately after `Create VERIFICATION.md.`:
+**The `gsd-verifier` subagent has no workflow file of its own (#2529):** the shared verification step (`workflows/execute-phase/steps/verify-phase-goal.md`, included by execute-phase's `verify_phase_goal` and by verify-work, #5118) reaches it by dispatch, not by reading a workflow, so there is no file in which to place a directive — the dispatch prompt is the only place its coverage can live. That prompt MUST carry this line verbatim, immediately after `Create VERIFICATION.md.` (the shared step's prompt carries it inline, so both callers inject it):
 
 `Use response_language {response_language} for all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code and paths.`
 

package/gsd-core/references/gsd-run-resolver.md

@@ -4,5 +4,5 @@ Use this bootstrap block when a workflow must call `gsd-tools` from the active w
 Keep this resolver centralized; workflows should reference this file instead of copying the shell probe.
 
 ```bash
-_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; _gsd_id_ok() { case "$("$1" runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') return 0;; *) return 1;; esac; }; _gsd_homes() { set -- "${CLAUDE_CONFIG_DIR:-$HOME/.claude}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}" "$HOME/.gemini/antigravity-ide" "$HOME/.gemini/antigravity-cli" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}" "${CLINE_CONFIG_DIR:-$HOME/.cline}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}" "${CODEX_HOME:-$HOME/.codex}" "${COPILOT_CONFIG_DIR:-${COPILOT_HOME:-$HOME/.copilot}}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}" "${HERMES_HOME:-$HOME/.hermes}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}" "${KIMI_CONFIG_DIR:-$HOME/.config/agents}" "$HOME/.agents" "${KIMI_CODE_HOME:-$HOME/.kimi-code}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}" "${PI_CODING_AGENT_DIR:-$HOME/.pi/agent}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}" "${TRAE_CONFIG_DIR:-$HOME/.trae}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}" "${ZCODE_CONFIG_DIR:-$HOME/.zcode}" "${GROK_AGENTS_HOME:-$HOME/.agents}"; for _h; do _gsd_at "$_h/gsd-core/bin/${_GSD_SHIM_NAME}" && return 0; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif _gsd_homes; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; [ -n "$_G" ] && _gsd_id_ok "$_G"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and no identity-proving gsd_run is on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; _gsd_id_ok gsd_run && GSD_IDENTITY_STATUS=ok; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
 ```

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

@@ -108,7 +108,13 @@ Evaluate `check` (one of `query`, `predicate`, or `agentVerdict`). Then honor `b
 - `blocking: false` → advisory only; surface the message but continue regardless of outcome.
 
 Honor `onError` if the check itself errors: `skip` means treat as non-blocking and continue;
-`halt` means surface the error and stop.
+`halt` means surface the error and stop. "Errors" means a non-zero exit from `gsd_run check ...`,
+and that includes `69` (`UNAVAILABLE`, #5170): a gate verb exits `69` when it **could not look** at
+its evidence, still printing the gate's usual JSON (its own fields name what could not be read, such
+as `status: "unresolvable"`, `readError`, or `unreadable`). That JSON is not a verdict — do not act
+on its `block`; route it by `onError` as a step-1 command failure. Exit `0` always means a
+delivered verdict, a blocking one included (`block: true`): a gate verb never exits non-zero to say
+"blocked".
 
 ## Empty / absent `activeHooks`
 

package/gsd-core/references/offer-next.md

@@ -34,7 +34,7 @@ STOP. Do not proceed to auto-advance or transition.
 1. Parse `--auto` flag from $ARGUMENTS
 2. Read consolidated auto-mode (`active` = chain flag OR user preference; chain flag already synced in init step):
    ```bash
-   AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null || echo "false")
+   AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null) || AUTO_MODE="false"
    ```
 
 **If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**

package/gsd-core/references/planning-config.md

@@ -432,7 +432,7 @@ Several config fields affect each other or trigger special behavior:
 
 4. **`parallelization` polymorphism** -- Accepts both a simple boolean and an object with an `enabled` field. `loadConfig()` normalizes either form to a boolean. `{ "enabled": true }` is equivalent to `true`.
 
-5. **Search API keys and flags** -- `brave_search`, `firecrawl`, and `exa_search` are auto-set to `true` during project creation if the corresponding API key is detected (environment variable or `~/.gsd/<name>_api_key` file). Setting them to `true` without the API key has no effect.
+5. **Search API keys and flags** -- `brave_search`, `firecrawl`, and `exa_search` are auto-set to `true` during project creation if the corresponding API key is detected (environment variable or `$GSD_HOME/.gsd/<name>_api_key` file; `GSD_HOME` defaults to the home directory). Setting them to `true` without the API key has no effect.
 
 6. **`planning.*` and top-level equivalence** -- `planning.commit_docs` and `commit_docs` are equivalent; `planning.search_gitignored` and `search_gitignored` are equivalent. If both are set, the top-level value takes precedence.
 

package/gsd-core/references/spidr-splitting.md

@@ -55,7 +55,7 @@ When SPIDR triggers, the workflow:
 2. Asks "Which SPIDR axis fits best?" with the five options above.
 3. Walks through the chosen axis interactively (one focused question), produces a split proposal: "Phase N (this one): X. Phase N+1: Y. Phase N+2: Z."
 4. Confirms the split with the user.
-5. On accept: writes the FIRST phase's story to the current ROADMAP entry; defers creating new phases for the splits to a follow-up step (the workflow surfaces a list of `/gsd add-phase` invocations the user can run after `mvp-phase` completes — but does not run them automatically, to preserve user control over phase numbering).
+5. On accept: writes the FIRST phase's story to the current ROADMAP entry; defers creating new phases for the splits to a follow-up step (the workflow surfaces a list of `/gsd:phase` invocations the user can run after `mvp-phase` completes — but does not run them automatically, to preserve user control over phase numbering).
 6. On reject: proceeds with the original story unchanged.
 
 ## Anti-patterns to reject

package/gsd-core/references/tdd.md

@@ -78,7 +78,7 @@ Output: [Working, tested feature]
 
 <output>
 After completion, create SUMMARY.md with:
-- RED: What test was written, why it failed
+- RED: What test was written, why it failed, and the semantic assessment of its RED evidence
 - GREEN: What implementation made it pass
 - REFACTOR: What cleanup was done (if any)
 - Commits: List of commits produced
@@ -95,7 +95,13 @@ After completion, create SUMMARY.md with:
 1. Create test file following project conventions
 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 record (command, exit code, failing test, expected result, actual result) and verify it: `gsd_run check tdd-red-evidence <record.json>`. Only verdict `RED_EVIDENCE_OK` satisfies the RED gate; `INVALID_RED` blocks GREEN until the RED phase is fixed.
+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.
+   - 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.
+   - 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.
+   - 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]`
 
@@ -279,14 +285,14 @@ When `workflow.tdd_mode` is enabled in config, the RED/GREEN/REFACTOR gate seque
 
 | Gate | Required | Commit Pattern | Validation |
 |------|----------|---------------|------------|
-| RED | Yes | `test({phase}-{plan}): ...` | Test exists AND fails before implementation — intentionally: `check tdd-red-evidence` returns `RED_EVIDENCE_OK` (target test failed on an assertion for the behavior; anything else is INVALID_RED) |
+| RED | Yes | `test({phase}-{plan}): ...` | Target test exists AND fails before implementation: a complete report in a supported format (RED step 4) from the current run must return `RED_EVIDENCE_OK`, followed by semantic inspection of the planned assertion (RED step 4) |
 | GREEN | Yes | `feat({phase}-{plan}): ...` | Test passes after implementation |
 | REFACTOR | No | `refactor({phase}-{plan}): ...` | Tests still pass after cleanup |
 
 ### Fail-Fast Rules
 
 1. **Unexpected GREEN in RED phase:** If the test passes before any implementation code is written, STOP. The feature may already exist or the test is wrong. Investigate before proceeding.
-2. **INVALID_RED in RED phase (#3770):** A nonzero exit is not RED by itself. Zero-test discovery, fixture/load crashes, nonzero exits with no failing test, unrelated failing tests, and unexpected greens all classify as INVALID_RED (`gsd_run check tdd-red-evidence`). STOP and fix the RED phase — do NOT proceed to GREEN.
+2. **INVALID_RED in RED phase (#3770):** A nonzero exit is not RED by itself. Follow the format-based evidence contract in RED step 4, including reporter reruns and report freshness. An `INVALID_RED` verdict or failed semantic assessment halts GREEN. Unsupported, incomplete, ambiguous, or contradictory evidence cannot authorize implementation.
 3. **Missing RED commit:** If no `test(...)` commit precedes the `feat(...)` commit, the TDD discipline was violated. Flag in SUMMARY.md.
 4. **REFACTOR breaks tests:** Undo the refactor immediately. Commit was premature — refactor in smaller steps.
 

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

@@ -34,12 +34,15 @@ no `<decisions>` block.
 GATE_CFG=$(gsd_run query config-get workflow.context_coverage_gate 2>/dev/null || echo "true")
 if [ "$GATE_CFG" != "false" ]; then
   CONTEXT_PATH=$(ls "${PHASE_DIR}"/*-CONTEXT.md 2>/dev/null | head -1)  # #2962: not a for-glob (zsh aborts)
-  DECISION_RESULT=$(gsd_run query check.decision-coverage-verify "${PHASE_DIR}" "${CONTEXT_PATH}")
+  DECISION_RESULT=$(gsd_run query check.decision-coverage-verify "${PHASE_DIR}" "${CONTEXT_PATH}") && DECISION_EXIT=0 || DECISION_EXIT=$?
 fi
 ```
 
 The handler returns JSON `{ skipped, blocking: false, total, honored,
-not_honored: [...], message }`.
+not_honored: [...], message }`. 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.
 
 **Reporting:** Append the handler's `message` (a `### Decision Coverage`
 section) to VERIFICATION.md regardless of outcome — even when all

package/gsd-core/references/verify-mvp-mode.md

@@ -15,9 +15,9 @@ The user-flow form mirrors what a real user does: open, fill, click, see. No HTT
 
 The framing fires when:
 - The phase under verification has `**Mode:** mvp` in ROADMAP.md (parsed via `gsd_run query roadmap.get-phase --pick mode`).
-- AND the phase has a user-story-formatted goal (set by `/gsd mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
+- AND the phase has a user-story-formatted goal (set by `/gsd:mvp-phase` per Phase 2): "As a [user role], I want to [capability], so that [outcome]."
 
-If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `gsd-core/references/planner-mvp-mode.md`).
+If the phase has `mode: mvp` but the goal is NOT in user-story format, the verifier surfaces this as a discrepancy and asks the user to run `/gsd:mvp-phase` to reformat the goal — same pattern as the planner agent under MVP_MODE (per `gsd-core/references/planner-mvp-mode.md`).
 
 ## Generated UAT script structure under MVP mode
 

package/gsd-core/references/workstream-flag.md

@@ -77,13 +77,43 @@ and broader temp hygiene is left to OS temp cleanup or future maintenance work.
 
 ## Routing Propagation
 
-All workflow routing commands include `${GSD_WS}` which:
-- Expands to `--ws <name>` when a workstream is active
-- Expands to empty string in flat mode (backward compatible)
+Every workstream-scoped workflow parses the `--ws <name>` it was started with out of
+`$ARGUMENTS` in each shell fence that needs it (fences are separate shells, so nothing is
+carried over between them) and sets `GSD_WS`:
+- `GSD_WS` is `--ws <name>` when the command was started with `--ws`, and empty otherwise
+  (flat mode, backward compatible). It is always re-assigned, so a stale value never leaks in.
+- Every `gsd_run query agent-skills <agent>` and `gsd_run query init.*` call in those
+  workflows forwards it as the single token `${GSD_WS:+--ws=${GSD_WS##* }}`. The explicit
+  flag has the highest priority above, so the workstream a command was started for wins over
+  the session pointer and the shared marker. The single-token form is required because zsh
+  does not word-split an unquoted `$GSD_WS`.
+- Workflows recognize the documented spelling `--ws <name>`; `--ws=<name>` is accepted by the
+  CLI itself but is not parsed out of `$ARGUMENTS` by workflows.
+- Routing suggestions (`/gsd:plan-phase {X} ${GSD_WS}`) carry the same value to the next command.
+- Project and workspace lifecycle workflows (`new-project`, `new-workspace`,
+  `list-workspaces`, `remove-workspace`, `update`) are root-scoped and do not forward it.
+
+`tests/agent-skills.test.cjs` scans every fenced call in `gsd-core/workflows/` so a new call
+that omits the flag fails CI.
 
 This ensures workstream scope chains automatically through the workflow:
 `new-milestone → discuss-phase → plan-phase → execute-phase → transition`
 
+## Reserved names
+
+`none` (case-insensitive) cannot name a workstream. `--ws none`, `--ws=none`, `GSD_WORKSTREAM=none`
+and a pointer of `none` are all rejected with a "reserved" error, and `workstream create` and
+`workstream set` refuse it unconditionally. The one exception on the read side is a
+`.planning/workstreams/none/` directory that already exists: it stays addressable with `--ws none`
+so projects that used the name before it was reserved keep working (the directory name must match
+exactly; `NONE` is still rejected). Such a grandfathered directory is reachable through `--ws` and
+`GSD_WORKSTREAM` only, because `workstream set none` refuses unconditionally. To force flat mode,
+omit `--ws`, unset `GSD_WORKSTREAM`, or clear the pointer (`workstream set --clear`). The rejection
+happens before any command runs, so a stale `GSD_WORKSTREAM=none` in the environment must be unset
+first. The reserved list has a single owner
+(`RESERVED_WORKSTREAM_NAMES` in `src/workstream-name-policy.cts`); near-misses such as `none1` or
+`nonexistent` are ordinary names.
+
 ## Directory Structure
 
 ```

package/gsd-core/templates/README.md

@@ -17,7 +17,7 @@ These files live directly at `.planning/` — not inside phase subdirectories.
 | `STATE.md` | `state.md` | `/gsd:new-project`, `/gsd:health --repair` | Current session state, active phase, last activity |
 | `REQUIREMENTS.md` | `requirements.md` | `/gsd:new-milestone` | Functional requirements with traceability |
 | `MILESTONES.md` | `milestone.md` | `/gsd:complete-milestone` | Log of completed milestones with accomplishments |
-| `BACKLOG.md` | *(inline)* | `/gsd-add-backlog` | Pending ideas and deferred work |
+| `BACKLOG.md` | *(inline)* | `/gsd:capture --backlog` | Pending ideas and deferred work |
 | `LEARNINGS.md` | *(inline)* | `/gsd:extract-learnings`, `/gsd:execute-phase` (gated: `features.global_learnings`) | Phase retrospective learnings for future plans |
 | `THREADS.md` | *(inline)* | `/gsd:thread` | Persistent discussion threads |
 | `config.json` | `config.json` | `/gsd:new-project`, `/gsd:health --repair` | Project-specific GSD configuration |

package/gsd-core/templates/UAT.md

@@ -66,7 +66,7 @@ blocked: [N]
 
 <!-- YAML format for plan-phase --gaps consumption -->
 - truth: "[expected behavior from test]"
-  status: failed
+  status: failed | resolved
   reason: "User reported: [verbatim response]"
   severity: blocker | major | minor | cosmetic
   test: [N]
@@ -74,6 +74,10 @@ blocked: [N]
   artifacts: []      # Filled by diagnosis
   missing: []        # Filled by diagnosis
   debug_session: ""  # Filled by diagnosis
+  resolved_by: ""    # Written by verify-work's reconcile_gaps (#1921) when
+                      # an executed gap-closure plan resolves this gap —
+                      # never author this directly. Plan basename.
+  resolved_at: ""     # Written alongside resolved_by (#1921).
 ```
 
 ---
@@ -107,6 +111,18 @@ blocked: [N]
 - APPEND only when issue found (YAML format)
 - After diagnosis: fill `root_cause`, `artifacts`, `missing`, `debug_session`
 - This section feeds directly into /gsd:plan-phase --gaps
+- `status: resolved` (#1921, #4983): when `/gsd:verify-work`'s `reconcile_gaps`
+  step finds an executed gap-closure plan (a `*-PLAN.md` naming this entry's
+  `gap_id` with a matching `*-SUMMARY.md`), it updates the entry IN PLACE —
+  `status: failed` → `status: resolved` — and adds `resolved_by` (the
+  resolving plan's basename) and `resolved_at` (the date). A resolved entry
+  is no longer surfaced as an open gap, and its matching `### N.` test's
+  `result: issue` no longer blocks `phase uat-passed` — but only when
+  `resolved_by` names a plan that actually exists in the phase directory with
+  a matching SUMMARY; a hand-written `status: resolved` with no valid
+  `resolved_by` still blocks (src/uat-predicate.cts's `isTestGapResolved`).
+  A later regression against the same test gets a fresh `gap_id`, never a
+  reopened resolved one.
 
 </section_rules>