@opengsd/gsd-core 1.7.0-rc.6 → 1.7.0

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

@@ -305,8 +305,8 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     // surface-path agents lack path-prefix rewrites and Co-Authored-By trailers,
     // diverging from a fresh install.
     const _homedirFn = opts?.homedir ?? (() => node_os_1.default.homedir());
-    const _resolvedTarget = node_path_1.default.resolve(layout.configDir).replace(/\\/g, '/');
-    const _homeDir = _homedirFn().replace(/\\/g, '/');
+    const _resolvedTarget = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(layout.configDir));
+    const _homeDir = (0, shell_command_projection_cjs_1.posixNormalize)(_homedirFn());
     const _isGlobal = (layout.scope ?? 'global') === 'global';
     const _isOpencode = layout.runtime === 'opencode';
     const _isWindowsHost = (opts?.platform ?? process.platform) === 'win32';

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

@@ -11,6 +11,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error } = ioMod;
@@ -85,7 +86,7 @@ function cmdTemplateFill(cwd, templateType, options, raw) {
         return;
     }
     const padded = normalizePhaseName(options.phase);
-    const today = new Date().toISOString().split('T')[0];
+    const today = clock_cjs_1.realClock.localToday();
     const phaseName = options.name || phaseInfo.phase_name || 'Unnamed';
     const phaseSlug = phaseInfo.phase_slug || generateSlugInternal(phaseName);
     const phaseId = `${padded}-${phaseSlug}`;

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

@@ -21,6 +21,9 @@ const { output, error } = io;
 const markdownSectionizer = require("./markdown-sectionizer.cjs");
 const { collectSection, tokenizeHeadings } = markdownSectionizer;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const markdownTable = require("./markdown-table.cjs");
+const { splitTableRow } = markdownTable;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const roadmapParser = require("./roadmap-parser.cjs");
 const { getMilestonePhaseFilter } = roadmapParser;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -292,24 +295,67 @@ function parseVerificationItems(content, status) {
         // Use the seam to locate the ## Human Verification section (ADR-1372 T5).
         const hvSection = collectSection(content, (h) => /^human\s+verification/i.test(h.text) && h.level === 2, { levelBounded: true });
         if (hvSection) {
+            // #2245 review Fix 3: reverted to the pre-Phase-4 (HEAD 2cbf18642)
+            // implementation. The live Human Verification section is NOT a strict
+            // GFM table — the planner/verifier templates mix table rows, numbered
+            // items, and bullet items in the same section (and a `### N.` heading
+            // format is common too), so a table-XOR-list read (parse a table, and
+            // if it parses, suppress numbered/bullet items entirely) silently
+            // dropped items on any mixed or malformed section: a malformed
+            // `| N | … |` table with no valid header/delimiter yielded ZERO items
+            // instead of reading the rows positionally. This per-line scan reads
+            // table rows AND numbered items AND bullet items as a UNION (whichever
+            // pattern a given line matches), exactly like OLD, and reads
+            // `| N | desc |` rows even without a valid table header/delimiter.
+            //
+            // #2245 audit: the table-row branch's CELL SPLIT is name/position-
+            // addressed via `splitTableRow` (escape-aware, canonical) instead of a
+            // hand-rolled pipe regex — candidacy itself is decided WITHOUT a table
+            // regex (a leading `|` plus a purely-numeric first cell), so this no
+            // longer needs an allow-adhoc-markdown suppression at all.
             const lines = hvSection.body.split('\n');
             for (const line of lines) {
-                // Match table rows: | N | description | ... |
-                const tableMatch = line.match(/\|\s*(\d+)\s*\|\s*([^|]+)/);
+                const trimmedLine = line.trim();
+                // Match table rows: | N | description | ... — candidacy requires a
+                // leading pipe and a purely-numeric first cell (mirrors what the old
+                // regex effectively required: a "|digit|" cell immediately followed
+                // by more content), with at least 2 physical cells so a bare "| N |"
+                // with nothing after it is NOT treated as a row.
+                //
+                // #2245 review Fix 9: this is NOT the same as OLD for a row whose
+                // ONLY content past the digit cell is trailing whitespace (e.g.
+                // "| N | ", no second delimiting `|`). OLD's `([^|]+)` regex ran
+                // against the RAW (untrimmed) line and its `\s*` would backtrack to
+                // let `[^|]+` swallow that trailing whitespace, so OLD matched and
+                // pushed an item with an EMPTY (`.trim()`-collapsed) name. Here,
+                // `trimmedLine = line.trim()` strips that trailing whitespace BEFORE
+                // `splitTableRow` ever sees it, collapsing the line to a single cell
+                // (`candidateCells.length === 1`), which fails the `>= 2` check —
+                // the item is silently dropped instead. A real, acceptable behaviour
+                // change (an empty-named UAT item is not useful either way), but the
+                // two implementations are NOT equivalent on this input.
+                let tableCells = null;
+                if (trimmedLine.startsWith('|')) {
+                    const candidateCells = splitTableRow(trimmedLine);
+                    if (candidateCells.length >= 2 && /^\d+$/.test(candidateCells[0])) {
+                        tableCells = candidateCells;
+                    }
+                }
                 // Match bullet items: - description
                 const bulletMatch = line.match(/^[-*]\s+(.+)/);
                 // Match numbered items: 1. description
                 const numberedMatch = line.match(/^(\d+)\.\s+(.+)/);
-                if (tableMatch) {
+                if (tableCells) {
                     // Skip rows that already have a passing result (PASS, pass, resolved, etc.)
-                    const rowRemainder = line.slice(tableMatch.index + tableMatch[0].length);
-                    const cellValues = rowRemainder.split('|').map(c => c.trim());
-                    const hasPassResult = cellValues.some(c => /^pass$/i.test(c) || /^resolved$/i.test(c));
+                    // — checked over every cell AFTER the description column, mirroring
+                    // OLD's rowRemainder scan (which only ever saw cells past the
+                    // description, the description itself having already been consumed).
+                    const hasPassResult = tableCells.slice(2).some(c => /^pass$/i.test(c) || /^resolved$/i.test(c));
                     if (hasPassResult)
                         continue;
                     items.push({
-                        test: parseInt(tableMatch[1], 10),
-                        name: tableMatch[2].trim(),
+                        test: parseInt(tableCells[0], 10),
+                        name: tableCells[1] ?? '',
                         result: 'human_needed',
                         category: 'human_uat',
                     });

package/gsd-core/bin/lib/ui-safety-gate.cjs

@@ -67,14 +67,36 @@ function checkUiPresence(text) {
     }
     // Normalise CRLF so the pattern sees consistent line boundaries.
     const normalised = text.replace(/\r\n/g, '\n');
+    // #2150: an explicit `**UI hint**: yes|no` metadata line is the author's
+    // authoritative declaration of whether the phase has a UI surface — progress.md
+    // and new-project.md already parse this line (`UI hint.*yes`). The bare token
+    // `UI` in the line itself must not count as a UI indicator, and the declaration
+    // overrides token-sniffing. Line-anchored (`m`) so a mid-line prose mention is
+    // not treated as the metadata line; word-boundary on the value so `nope`/`not`
+    // do not match `no`.
+    const hintMatch = normalised.match(/^\s*\*\*UI hint\*\*\s*:\s*(yes|no)\b/im);
+    const hint = hintMatch ? hintMatch[1].toLowerCase() : null;
+    // Strip ANY `**UI hint**:` line before token-sniffing so a hint without a
+    // recognised yes/no (or one we did not short-circuit on) cannot false-positive
+    // on the bare `UI` token.
+    const sniffable = normalised
+        .split('\n')
+        .filter((line) => !/^\s*\*\*UI hint\*\*\s*:/i.test(line))
+        .join('\n');
     const found = new Set();
-    for (const line of normalised.split('\n')) {
+    for (const line of sniffable.split('\n')) {
         // Reset lastIndex before each line so the global pattern restarts from 0.
         UI_GATE_PATTERN_GLOBAL.lastIndex = 0;
         for (const m of line.matchAll(UI_GATE_PATTERN_GLOBAL)) {
             found.add(m[2].toLowerCase());
         }
     }
+    if (hint === 'no') {
+        return { hasUI: false, tokens: [] };
+    }
+    if (hint === 'yes') {
+        return { hasUI: true, tokens: [...found] };
+    }
     return { hasUI: found.size > 0, tokens: [...found] };
 }
 // ── CLI entry point ─────────────────────────────────────────────────────────

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

@@ -13,6 +13,7 @@ const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
 const validate_cjs_1 = require("./validate.cjs");
+const clock_cjs_1 = require("./clock.cjs");
 const validate_cjs_2 = require("./validate.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- planning-workspace.cjs is an export= CommonJS module
 const planningWorkspace = require("./planning-workspace.cjs");
@@ -1049,7 +1050,7 @@ function cmdValidateConsistency(cwd, raw) {
                 .sort();
             for (const dir of dirs) {
                 const phasePath = node_path_1.default.join(phaseRoot, dir);
-                const phaseLabel = node_path_1.default.relative(planBase, phasePath).replace(/\\/g, '/');
+                const phaseLabel = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.relative(planBase, phasePath));
                 const phaseFiles = node_fs_1.default.readdirSync(phasePath);
                 const plans = phaseFiles.filter((f) => f.endsWith('-PLAN.md')).sort();
                 const planNums = plans
@@ -1591,7 +1592,7 @@ function cmdValidateHealth(cwd, options, raw) {
                         stateContent += `**Current phase:** (determining...)\n`;
                         stateContent += `**Status:** Resuming\n\n`;
                         stateContent += `## Session Log\n\n`;
-                        stateContent += `- ${new Date().toISOString().split('T')[0]}: STATE.md regenerated by ${slash('health')} --repair\n`;
+                        stateContent += `- ${clock_cjs_1.realClock.localToday()}: STATE.md regenerated by ${slash('health')} --repair\n`;
                         writeStateMd(statePath, stateContent, cwd);
                         repairActions.push({ action: repair, success: true, path: 'STATE.md' });
                         break;
@@ -1647,7 +1648,7 @@ function cmdValidateHealth(cwd, options, raw) {
                     case 'backfillMilestones': {
                         if (!options['backfill'] && !options['repair'])
                             break;
-                        const today = new Date().toISOString().split('T')[0];
+                        const today = clock_cjs_1.realClock.localToday();
                         let backfilled = 0;
                         for (const ver of missingFromRegistry) {
                             try {

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

@@ -17,6 +17,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
+const clock_cjs_1 = require("./clock.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const io = require("./io.cjs");
 const { output, error } = io;
@@ -154,7 +155,7 @@ function cmdWorkstreamCreate(cwd, name, options, raw) {
     }
     (0, shell_command_projection_cjs_1.platformEnsureDir)(wsDir);
     (0, shell_command_projection_cjs_1.platformEnsureDir)(node_path_1.default.join(wsDir, 'phases'));
-    const today = new Date().toISOString().split('T')[0];
+    const today = clock_cjs_1.realClock.localToday();
     const stateContent = [
         '---',
         `workstream: ${slug}`,
@@ -264,7 +265,7 @@ function cmdWorkstreamComplete(cwd, name, options, raw) {
     if (active === name)
         setActiveWorkstream(cwd, null);
     const archiveDir = node_path_1.default.join(root, 'milestones');
-    const today = new Date().toISOString().split('T')[0];
+    const today = clock_cjs_1.realClock.localToday();
     let archivePath = node_path_1.default.join(archiveDir, `ws-${name}-${today}`);
     let suffix = 1;
     while (node_fs_1.default.existsSync(archivePath)) {

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

@@ -440,7 +440,7 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
         // relPath is the path relative to the worktree root (e.g. ".planning/q1-SUMMARY.md")
         // Normalize to forward slashes so the Set comparison against `git status --porcelain`
         // output works on Windows too (git always emits forward slashes in porcelain output).
-        const relPath = absPath.slice(worktreePath.length).replace(/^[/\\]/, '').replace(/\\/g, '/');
+        const relPath = (0, shell_command_projection_cjs_1.posixNormalize)(absPath.slice(worktreePath.length).replace(/^[/\\]/, ''));
         // #706: skip rescue when the SUMMARY is already committed on the branch.
         // Use `git cat-file -e HEAD:<relPath>` (not `ls-files --error-unmatch`) so
         // the check is against the committed tree, not the index.  ls-files also

package/gsd-core/bin/lib/write-set.cjs

@@ -0,0 +1,38 @@
+"use strict";
+/**
+ * Write-Set — shared fail-loud parse `Result` and per-surface write-set
+ * contracts (ADR-2143, epic #2143). Pure, Node built-ins only, no I/O.
+ * Compiled by tsc to gsd-core/bin/lib/write-set.cjs.
+ *
+ * ADR-2143 §5 (fail-loud parsing, no null-swallow): seam parse operations
+ * and document-model accessors return a typed `Result<T>` — never a bare
+ * `null` a caller can mistake for "empty but fine." This is the same
+ * `{ ok: true; value: T } | { ok: false; reason: string }` shape
+ * `markdown-table.cts` already defined for `parseMarkdownTable` /
+ * `appendQuickTaskRow`; this module is now the single source of truth for
+ * it and `markdown-table.cjs` re-exports the type so existing importers of
+ * `Result` from that module keep working unchanged.
+ *
+ * NOTE: deliberately distinct from command-routing-hub's dispatch `Result`
+ * (`{ok,data}|{ok:false,kind}`) — the two never mix (different modules,
+ * different shapes, different purposes).
+ *
+ * ADR-2143 §6 (write-set results for multi-surface commands, no
+ * OR-into-one-flag): a command that mutates more than one surface returns
+ * an explicit per-surface write-set — `{ surface, applied }` outcomes — and
+ * its top-level "did this fully succeed" signal is true only if EVERY
+ * surface in the set applied. ORing independent surfaces into a single
+ * boolean is the direct anti-pattern that let a checkbox-only partial
+ * write (#2140) report full success.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeSetComplete = writeSetComplete;
+/**
+ * True only if the write-set is non-empty AND every surface in it applied.
+ * An empty write-set is never "complete" — there is nothing to be complete
+ * about, so treating it as vacuously true would let a no-op masquerade as
+ * a full success (the same OR-into-one-flag class ADR-2143 §6 prohibits).
+ */
+function writeSetComplete(ws) {
+    return ws.length > 0 && ws.every((o) => o.applied);
+}

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

@@ -71,6 +71,8 @@
     "workflow.context_coverage_gate",
     "statusline.show_last_command",
     "statusline.context_position",
+    "statusline.show_context_tokens",
+    "statusline.show_git",
     "workflow.max_discuss_passes",
     "features.thinking_partner",
     "context",

package/gsd-core/references/checkpoints.md

@@ -9,6 +9,18 @@ Plans execute autonomously. Checkpoints formalize interaction points where human
 3. **User only does what requires human judgment** - Visual checks, UX evaluation, "does this feel right?"
 4. **Secrets come from user, automation comes from Claude** - Ask for API keys, then Claude uses them via CLI
 5. **Auto-mode bypasses verification/decision checkpoints** — When `workflow._auto_chain_active` or `workflow.auto_advance` is true in config: human-verify auto-approves, decision auto-selects first option, human-action still stops (auth gates cannot be automated)
+6. **`gate="blocking-human"` is never auto-approved** — a checkpoint carrying this gate stops for a human in *every* mode, including auto-mode, regardless of its type. Rule 5 does not apply to it.
+
+**The `gate` attribute:**
+
+| Value | Auto-mode behavior | Use for |
+|-------|--------------------|---------|
+| `gate="blocking"` | Bypassed per rule 5 (human-verify auto-approves, decision auto-selects) | The default. Post-hoc verification and implementation choices that are safe to take the recommended path on when unattended. |
+| `gate="blocking-human"` | **Never bypassed.** Stops for a human in auto-mode too. | Irreversible or trust-establishing steps a human must actually see: package-legitimacy verification before install, and any decision whose default answer would be wrong to assume. |
+
+Reach for `gate="blocking-human"` whenever auto-approving the checkpoint would defeat its purpose. If the checkpoint exists because a human must *decide* something, `blocking` is the wrong gate — auto-mode will decide it for them.
+
+The gate spans two layers, and both must honor it. `gsd-executor` refuses to auto-approve a `gate="blocking-human"` checkpoint and escalates it via `checkpoint_return_format` precisely so a human sees it; `execute-phase`'s `checkpoint_handling` step then decides what the user is actually shown. An orchestrator that dispatches on checkpoint *type* alone would auto-approve the very checkpoint the executor just refused to auto-approve, nullifying that refusal one layer up and letting an unattended `--auto` / `--chain` run install a package no human ever vetted.
 </overview>
 
 <checkpoint_types>

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

@@ -308,7 +308,7 @@ If there are passing tests to commit:
 
 ```bash
 git add {test files}
-git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command"
+git commit -m "test(phase-${phase_number}): add unit and E2E tests from add-tests command" -- {test files}
 ```
 
 Present next steps:

package/gsd-core/workflows/debug.md

@@ -190,6 +190,8 @@ Create `.planning/debug/{slug}.md` with initial state using the Write tool (neve
 
 After initial context setup, spawn the session manager to handle the full checkpoint/continuation loop. The session manager handles specialist_hint dispatch internally: when gsd-debugger returns ROOT CAUSE FOUND it extracts the specialist_hint field and invokes the matching skill (e.g. typescript-expert, swift-concurrency) before offering fix options.
 
+> **Foreground, blocking spawn — #2196.** The `Agent(subagent_type="gsd-debug-session-manager", …)` call below is FOREGROUND and BLOCKING — it returns the compact session summary directly. Wait for it; do not background it, and do not poll for it. Never pass an agent or session identifier to `TaskOutput` — an agent ID is NOT a task ID, so `TaskOutput <agent-id>` always returns `No task found with ID`. If the spawn returns no usable result (the handoff is lost), do NOT claim the session is still running: preserve the checkpoint at `.planning/debug/{slug}.md`, report the failed handoff plainly, and resume by re-spawning the session manager or via `/gsd:debug continue {slug}`.
+
 Print before spawning (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze):
 ```
 [debug] Delegating loop to session manager...

package/gsd-core/workflows/execute-phase.md

@@ -1056,11 +1056,13 @@ AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null || echo "fal
 ```
 
 When executor returns a checkpoint AND `AUTO_MODE` is `true`:
-- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`.
-- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`.
+- **human-verify** → Auto-spawn continuation agent with `{user_response}` = `"approved"`. Log `⚡ Auto-approved checkpoint`. **Except `blocking-human`.**
+- **decision** → Auto-spawn continuation agent with `{user_response}` = first option from checkpoint details. Log `⚡ Auto-selected: [option]`. **Except `blocking-human`.**
 - **human-action** → Present to user (existing behavior below). Auth gates cannot be automated.
 
-**Standard flow (not auto-mode, or human-action type):**
+**Carve-out — overrides all branches above.** If the returned `Gate:` is `blocking-human`, or its `<what-built>` mentions `Package verification required before install` or `Package install failed — human verification required`, never auto-approve or auto-select, regardless of type. Present to user (standard flow below). Log `⛔ blocking-human gate — auto-mode suspended`.
+
+**Standard flow (not auto-mode, human-action, or blocking-human):**
 
 1. Spawn agent for checkpoint plan
 2. Agent runs until checkpoint task or auth gate → returns structured state

package/gsd-core/workflows/fast.md

@@ -64,32 +64,18 @@ Use conventional commit format: `fix:`, `feat:`, `docs:`, `chore:`, `refactor:`
 
 <step name="log_to_state">
 If `.planning/STATE.md` exists and has a "Quick Tasks Completed" table, append a row
-that matches the existing table's schema. If no table exists, skip silently.
-If the table's schema is unrecognized, skip with a brief log rather than append a
-malformed row.
+that matches the existing table's schema via the schema-backed `gsd-tools
+quick-tasks-append` helper (`markdown-table.cjs`'s `appendQuickTaskRow`; #2133,
+ADR-2143 §3/§7). If no table exists, skip silently. If the table's schema is
+unrecognized, the helper fails loud (non-zero exit) instead of silently guessing
+a column count — this replaces the prior inline `awk NF-2` arithmetic that was
+the root cause of #2133.
 
 ```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}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; 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
 # Detect whether STATE.md has a Quick Tasks Completed table
 if grep -q "Quick Tasks Completed" .planning/STATE.md 2>/dev/null; then
-  # Read the table header line to determine the column schema.
-  # quick.md Step 7 creates a 5-column table:
-  #   | # | Description | Date | Commit | Directory |
-  # Count pipe characters in the header to determine column count.
-  HEADER_LINE=$(grep -A2 "Quick Tasks Completed" .planning/STATE.md 2>/dev/null | grep "^|" | head -1)
-  # Count columns: number of | separators minus 1 gives column count
-  COL_COUNT=$(echo "$HEADER_LINE" | awk -F'|' '{print NF-1}')
-
-  if [ "$COL_COUNT" -eq 5 ] && echo "$HEADER_LINE" | grep -qi "Description" && echo "$HEADER_LINE" | grep -qi "Commit" && echo "$HEADER_LINE" | grep -qi "Directory"; then
-    # 5-column schema from quick.md Step 7: | # | Description | Date | Commit | Directory |
-    # Determine the next row number by counting existing data rows (non-separator, non-header).
-    NEXT_NUM=$(awk '/Quick Tasks Completed/{found=1} found && /^\|/ && !/^[|][-: |]*[|]$/ && !/Description/{count++} END{print count+1}' .planning/STATE.md 2>/dev/null || echo "1")
-    # Get the latest commit hash (short)
-    COMMIT_HASH=$(git rev-parse --short HEAD 2>/dev/null || echo "—")
-    echo "| $NEXT_NUM | $TASK | $(date +%Y-%m-%d) | $COMMIT_HASH | — |" >> .planning/STATE.md
-  else
-    # Unrecognized table schema — skip to avoid appending a malformed row.
-    echo "⚠ fast.md log_to_state: Quick Tasks Completed table has unrecognized schema (${COL_COUNT} columns); skipping STATE.md update."
-  fi
+  gsd_run quick-tasks-append --task "$TASK" || echo "⚠ fast.md log_to_state: could not append Quick Tasks row (see message above); continuing."
 fi
 ```
 </step>

package/gsd-core/workflows/progress.md

@@ -536,7 +536,7 @@ State: "Current phase is {X}. Milestone has {N} phases (highest: {Y})."
 | Condition | Meaning | Action |
 |-----------|---------|--------|
 | current phase < highest phase | More phases remain | Go to **Route C** |
-| current phase = highest phase | Milestone complete | Go to **Route D** |
+| current phase = highest phase | All phases complete | Go to **Route D** |
 
 ---
 
@@ -602,7 +602,7 @@ NEXT_HAS_UI=$(echo "$NEXT_PHASE_SECTION" | grep -qi "UI hint.*yes" && echo "true
 
 ---
 
-**Route D: Milestone complete**
+**Route D: All phases complete (milestone ready to close)**
 
 ```
 ---

package/gsd-core/workflows/quick.md

@@ -971,6 +971,8 @@ Use `date` from init:
 | ${quick_id} | ${DESCRIPTION} | ${date} | ${commit_hash} | [${quick_id}-${slug}](./quick/${quick_id}-${slug}/) |
 ```
 
+For a schema-safe append outside this workflow (e.g. from fast.md), `gsd-tools quick-tasks-append --task <text>` performs the equivalent write via the shared, schema-backed `appendQuickTaskRow` helper (#2133, ADR-2143 §3/§7).
+
 **7d. Update "Last activity" line:**
 
 Use `date` from init:

package/gsd-core/workflows/review.md

@@ -255,6 +255,8 @@ shell-interpolated). Exact invocation in `gsd-core/references/reviewer-instances
 
 For each selected CLI, invoke in sequence (not parallel — avoid rate limits):
 
+**Timeout guidance (#2194):** prompt-fed source-grounded reviews are slow — measured ~570s for Codex at `xhigh` effort and ~525s for headless Claude on a large plan set. Each of the Gemini / Claude / Codex blocks below MUST be invoked with a high Bash `timeout:` — at least `900000` (15 min), and `1200000` (20 min) for Codex `xhigh` or headless Claude — so a lane is not killed mid-review. On Claude Code, raise the host cap via `BASH_MAX_TIMEOUT_MS` if a review can exceed it. A silent empty output after a long run is a **timeout kill, not a crash** — the Codex `0xc0000142` misdiagnosis persisted because the empty-output branches below cannot distinguish the two; treat an empty result on a slow lane as a dropped lane and re-run with more time rather than diagnosing a CLI/sandbox failure. A cross-AI review that silently drops a lane is blind in one eye.
+
 **Gemini:**
 ```bash
 if [ -n "$GEMINI_MODEL" ] && [ "$GEMINI_MODEL" != "null" ]; then
@@ -364,7 +366,12 @@ fi
 # prompt as an ARGUMENT, not stdin. A full review prompt can exceed the OS argument limit, so
 # reference the prompt file by path rather than inlining it. Capture stderr so a failure is
 # diagnosable instead of a silent empty result.
-CURSOR_PROMPT_ARG="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. Output only the resulting markdown review. Do not edit any files."
+# #2176: same absolute-root anchor as the Antigravity block — cursor-agent runs
+# in the repo cwd, but repo-relative references in the assembled prompt still
+# need an explicit root to resolve against. rev-parse (not bare pwd) so the
+# anchor is correct even when /gsd:review is invoked from a repo subdirectory.
+_CURSOR_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+CURSOR_PROMPT_ARG="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. The repository under review is at $_CURSOR_ROOT — resolve every relative file path in the review request against that absolute root. Output only the resulting markdown review. Do not edit any files."
 cursor-agent -p --mode ask --trust --output-format text "$CURSOR_PROMPT_ARG" 2>/tmp/gsd-review-cursor-{phase}.err > /tmp/gsd-review-cursor-{phase}.md
 if [ ! -s /tmp/gsd-review-cursor-{phase}.md ]; then
   echo "Cursor review failed or returned empty output. stderr:" > /tmp/gsd-review-cursor-{phase}.md
@@ -456,7 +463,19 @@ if [ -n "$AGY_MODEL" ] && [ "$AGY_MODEL" != "null" ]; then
 else
   set --
 fi
-_AGY_PROMPT="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. Output only the resulting markdown review. Do not edit any files."
+# #2176: grant the reviewer the repo under review. Without --add-dir, agy's
+# permission context never receives the cwd repo — the agent anchors on its own
+# ~/.gemini/antigravity-cli/scratch dir and reviews the plan text in isolation
+# (the exact failure the Review Instructions forbid). Capability-probed like the
+# Codex bypass flag so an older agy without --add-dir still runs; the prompt
+# anchor below keeps absolute-path reads possible on that fallback.
+if agy --help 2>/dev/null | grep -q -- '--add-dir'; then
+  set -- "$@" --add-dir "$_AGY_WS"
+fi
+# #2176: anchor the prompt to the absolute repo root so repo-relative references
+# in the assembled review prompt resolve even on the no---add-dir fallback, and
+# require an explicit self-report if the reviewer still cannot read the repo.
+_AGY_PROMPT="Read the file at /tmp/gsd-review-prompt-{phase}.md in full and carry out the review request it contains. The repository under review is at $_AGY_WS — resolve every relative file path in the review request against that absolute root and verify claims against those files. If you cannot read files under $_AGY_WS, begin your output with the exact line REVIEWED-WITHOUT-REPO-ACCESS before the review. Output only the resulting markdown review. Do not edit any files."
 # Capability-probe an external wall-clock killer (GNU coreutils `timeout` or the
 # macOS Homebrew `gtimeout`). Stock macOS ships NEITHER — a bare `timeout …` would
 # fail with rc 127 ("command not found") and silently lose the reviewer, so fall
@@ -523,6 +542,26 @@ if [ ! -s /tmp/gsd-review-antigravity-{phase}.md ]; then
     echo "If no agy run started, that is the pre-session-stall case: check whether a new ~/.gemini/antigravity-cli/brain/<conv-id>/ dir appeared within ~30s of launch."
   } > /tmp/gsd-review-antigravity-{phase}.md
 fi
+
+# #2176: blind-review marker. Two tells that the reviewer ran without repo
+# access: the prompt's mandated REVIEWED-WITHOUT-REPO-ACCESS self-report in the
+# first lines of output, or the agent DECLARING the scratch dir as its
+# workspace. Both patterns are anchored — the self-report to the head of the
+# file, the scratch tell to a workspace-declaration phrasing — so a grounded
+# review that merely QUOTES these strings (e.g. reviewing this very file) is
+# never mis-stamped. Stamp a machine-readable marker so the Consensus Summary
+# down-weights the review instead of counting an ungrounded verdict at full
+# weight. (Temp file + mv, no in-place sed — BSD/GNU safe.)
+if [ -s /tmp/gsd-review-antigravity-{phase}.md ] && \
+   { head -5 /tmp/gsd-review-antigravity-{phase}.md | grep -q 'REVIEWED-WITHOUT-REPO-ACCESS' || \
+     grep -qiE '(workspace|working) (directory|dir).{0,40}antigravity-cli/scratch' /tmp/gsd-review-antigravity-{phase}.md; }; then
+  {
+    echo "> [reviewed-without-repo-access] This reviewer ran without visibility into the repo under review — down-weight its verdict in the Consensus Summary."
+    echo ""
+    cat /tmp/gsd-review-antigravity-{phase}.md
+  } > /tmp/gsd-review-antigravity-{phase}.md.tmp && \
+  mv /tmp/gsd-review-antigravity-{phase}.md.tmp /tmp/gsd-review-antigravity-{phase}.md
+fi
 ```
 
 **Ollama (local, OpenAI-compatible):**
@@ -835,7 +874,7 @@ trimmed_reviewers:        # only present if at least one reviewer was trimmed
 
 ## Consensus Summary
 
-{synthesize common concerns across all reviewers. CodeRabbit is a diff-only reviewer (it never received the source-grounding prompt), so do not weight its verdict as a grounded plan review — fold in its diff findings, but base plan-level consensus on the prompt-fed reviewers.}
+{synthesize common concerns across all reviewers. CodeRabbit is a diff-only reviewer (it never received the source-grounding prompt), so do not weight its verdict as a grounded plan review — fold in its diff findings, but base plan-level consensus on the prompt-fed reviewers. A reviewer output carrying the `[reviewed-without-repo-access]` marker (or beginning with `REVIEWED-WITHOUT-REPO-ACCESS`) ran without repo access (#2176) — treat it the same way: note its concerns, but do not count its verdict at full consensus weight.}
 
 ### Agreed Strengths
 {strengths mentioned by 2+ reviewers}

package/gsd-core/workflows/secure-phase.md

@@ -108,7 +108,7 @@ Agent(
     "<files_to_read>{PLAN, SUMMARY, impl files, SECURITY.md}</files_to_read>" +
     "<threat_register>{threat register}</threat_register>" +
     "<config>asvs_level: {SECURITY_ASVS}, block_on: {SECURITY_BLOCK_ON}</config>" +
-    "<constraints>Never modify implementation files. Verify mitigations exist — do not scan for new threats. Escalate implementation gaps.</constraints>" +
+    "<constraints>Never modify implementation files. Verify mitigations exist — do not scan for new threats. Escalate implementation gaps. Return a structured verdict only — do NOT write SECURITY.md (the orchestrator owns the file write).</constraints>" +
     "${AGENT_SKILLS_AUDITOR}",
   subagent_type="gsd-security-auditor",
   model="{AUDITOR_MODEL}",

package/gsd-core/workflows/ship.md

@@ -394,9 +394,15 @@ gsd_run query state.update "Last Activity" "$(date +%Y-%m-%d)"
 gsd_run query state.update "Status" "Phase ${PHASE_NUMBER} shipped — PR #${PR_NUMBER}"
 ```
 
-If `commit_docs` is true:
+If `commit_docs` is true, commit the ship-note AND push it onto the PR branch so
+it reaches the default branch when the PR merges. Without this push the ship-note
+commit stays local-only and is silently discarded when the branch is deleted on
+merge (#2138). The `[ci skip]` trailer suppresses the redundant pipeline the push
+would otherwise trigger (GitHub honors `[ci skip]` / `[skip ci]`):
+
 ```bash
-gsd_run query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER}" --files .planning/STATE.md
+gsd_run query commit "docs(${padded_phase}): ship phase ${PHASE_NUMBER} — PR #${PR_NUMBER} [ci skip]" --files .planning/STATE.md
+git push origin ${CURRENT_BRANCH} 2>&1 || echo "⚠ track_shipping: ship-note push failed — it is local-only; rerun: git push origin ${CURRENT_BRANCH}"
 ```
 </step>
 

package/gsd-core/workflows/spec-phase.md

@@ -456,7 +456,7 @@ Write to: `{phase_dir}/{padded_phase}-SPEC.md`
 
 ```bash
 git add "${phase_dir}/${padded_phase}-SPEC.md"
-git commit -m "spec(phase-${phase_number}): add SPEC.md for ${phase_name} — ${requirement_count} requirements (#2213)"
+git commit -m "spec(phase-${phase_number}): add SPEC.md for ${phase_name} — ${requirement_count} requirements (#2213)" -- "${phase_dir}/${padded_phase}-SPEC.md"
 ```
 
 If `commit_docs` is false: Skip commit. Note that SPEC.md was written but not committed.

package/gsd-core/workflows/transition.md

@@ -597,7 +597,7 @@ Do NOT auto-invoke any further slash commands.
 
 ---
 
-**Route B: Milestone complete (all phases done)**
+**Route B: All phases complete (milestone ready to close)**
 
 **This route is only reached when:**
 - `is_last_phase: true` AND no other active workstreams exist (or flat mode)