@opengsd/gsd-core 1.17.0 → 1.18.0

package/gsd-core/bin/lib/state-document.cjs

@@ -14,6 +14,7 @@ exports.isUnfilledFieldValue = isUnfilledFieldValue;
 exports.leadingCalendarDate = leadingCalendarDate;
 exports.isRealCalendarDate = isRealCalendarDate;
 exports.stateFieldContinuation = stateFieldContinuation;
+exports.fieldContinuationEnd = fieldContinuationEnd;
 exports.stateExtractField = stateExtractField;
 exports.stateFieldValue = stateFieldValue;
 exports.stateCurrentPositionSlice = stateCurrentPositionSlice;
@@ -378,7 +379,16 @@ function stateFieldContinuation(content, fieldName) {
     if (!rest.startsWith('\n'))
         return null; // end of file: nothing follows
     const lines = rest.slice(1).split('\n').map((line) => line.replace(/\r$/, ''));
-    const continuation = [];
+    const continuation = lines.slice(0, continuationLineCount(lines)).map((line) => line.trim());
+    return continuation.length ? continuation.join(' ') : null;
+}
+/**
+ * How many of the lines directly below a single-line field belong to its value: the scan
+ * `stateFieldContinuation` reports on, shared so a writer that replaces the value removes exactly
+ * the lines a validator would call its continuation (#4945). `lines` are CR-free.
+ */
+function continuationLineCount(lines) {
+    let count = 0;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
         if (!line.trim())
@@ -391,9 +401,33 @@ function stateFieldContinuation(content, fieldName) {
         // title, so stop before consuming it rather than after.
         if (i + 1 < lines.length && SETEXT_UNDERLINE_RE.test(lines[i + 1]))
             break;
-        continuation.push(line.trim());
+        count++;
     }
-    return continuation.length ? continuation.join(' ') : null;
+    return count;
+}
+/**
+ * The index just past a single-line field's value AND the continuation lines that wrap it
+ * (#4945). `valueEnd` is where the field's own line ends (before its line terminator). Replacing
+ * `content.slice(valueEnd, result)` with nothing removes every continuation line and the
+ * terminator in front of each, so the terminator after the last one stays. Returns `valueEnd`
+ * when nothing continues the value.
+ */
+function fieldContinuationEnd(content, valueEnd) {
+    const tail = content.slice(valueEnd);
+    const first = /^\r?\n/.exec(tail);
+    if (!first)
+        return valueEnd;
+    const rawLines = tail.slice(first[0].length).split('\n');
+    const count = continuationLineCount(rawLines.map((line) => line.replace(/\r$/, '')));
+    if (count === 0)
+        return valueEnd;
+    let removed = first[0].length + (count - 1);
+    for (let i = 0; i < count; i++)
+        removed += rawLines[i].length;
+    // The terminator after the last continuation line stays; on a CRLF document that includes its CR.
+    if (rawLines[count - 1].endsWith('\r'))
+        removed -= 1;
+    return valueEnd + removed;
 }
 function stateExtractField(content, fieldName) {
     const escaped = (0, pattern_cjs_1.escapeRegex)(fieldName);

package/gsd-core/bin/lib/state-transition.cjs

@@ -922,6 +922,8 @@ function transitionCore(content, intent, deps) {
  */
 function beginPhaseCore(content, intent, deps) {
     const updated = [];
+    // #4945: a re-entry whose earlier plans already have summaries starts at the first plan still to run.
+    const startPlan = intent.startPlan && intent.startPlan > 0 ? Math.floor(intent.startPlan) : 1;
     // #1255: body-field replacements operate on body only (frontmatter stripped),
     // not on the full content. The YAML `status:` key matches `^Status:\s*`
     // before the body pipe-table row if full content is passed.
@@ -977,7 +979,7 @@ function beginPhaseCore(content, intent, deps) {
         if (intent.phaseName) {
             tryField('Current Phase Name', intent.phaseName);
         }
-        tryField('Current Plan', '1');
+        tryField('Current Plan', String(startPlan));
         if (intent.planCount) {
             tryField('Total Plans in Phase', String(intent.planCount));
         }
@@ -996,14 +998,21 @@ function beginPhaseCore(content, intent, deps) {
         // end-of-line (inert here since `.` never crosses line terminators
         // without `/s`, which is not set).
         const focusPattern = /^([ \t]*\*\*Current focus:\*\*[ \t]*)(.*)$/im;
-        if (focusPattern.test(body)) {
-            body = body.replace(focusPattern, (_match, prefix) => `${prefix}${focusLabel}`);
+        const focusMatch = focusPattern.exec(body);
+        if (focusMatch) {
+            // #4945: a value an author wrapped onto further lines is replaced whole, so its tail is not
+            // left behind under the new value. The lines that count are the ones `state validate` already
+            // reports as a field's continuation (stops at a blank line, a heading, a list item, a table
+            // row, a fence or a sibling field). An empty first line has no value to continue.
+            const valueEnd = focusMatch.index + focusMatch[0].length;
+            const end = focusMatch[2].trim() === '' ? valueEnd : (0, state_document_cjs_2.fieldContinuationEnd)(body, valueEnd);
+            body = body.slice(0, focusMatch.index) + focusMatch[1] + focusLabel + body.slice(end);
             updated.push('Current focus');
         }
         // ## Current Position section mutation (#1104, #1365).
         // `locateCurrentPosition` (fence-aware, tokenizeHeadings-based) locates
         // the section; mirrors state.cts:2261-2324 byte-for-behaviour.
-        body = mutateCurrentPositionFirstTime(body, intent, today, updated);
+        body = mutateCurrentPositionFirstTime(body, { ...intent, startPlan }, today, updated);
     }
     else {
         // Resume path: only update Last activity timestamp in Current Position
@@ -1107,7 +1116,7 @@ function mutateCurrentPositionFirstTime(body, intent, today, updated) {
             sectionBody = replaced;
     }
     // Plan line.
-    const planValue = `1 of ${intent.planCount || '?'}`;
+    const planValue = `${intent.startPlan} of ${intent.planCount || '?'}`;
     if (/^Plan:/m.test(sectionBody)) {
         sectionBody = sectionBody.replace(/^Plan:.*$/m, `Plan: ${planValue}`);
     }
@@ -1798,15 +1807,27 @@ function completePhaseCore(content, intent, deps) {
     // Only runs when a Completed Phases field exists (the existing guard).
     const completedRaw = (0, state_document_cjs_1.stateExtractField)(body, 'Completed Phases');
     if (completedRaw !== null) {
-        let newCompleted = parseInt(completedRaw, 10);
+        const recordedCompleted = parseInt(completedRaw, 10);
+        let newCompleted = recordedCompleted;
         let derivedTotalPhases = null;
         const roadmapContent = deps.roadmapProvider ? deps.roadmapProvider() : null;
         if (roadmapContent) {
             const derived = (0, phase_lifecycle_cjs_1.deriveProgressFromRoadmap)(roadmapContent);
-            if (derived.completedPhases !== null)
-                newCompleted = derived.completedPhases;
-            if (derived.totalPhases !== null)
-                derivedTotalPhases = derived.totalPhases;
+            // #4901: completed counters only ratchet up, like the frontmatter twin
+            // (applyAuthoritativeProgressSubkeys, completedOnlyRaise). A derivation
+            // that lands BELOW the recorded counter read a narrower scope than the
+            // counter spans (e.g. the first `## Progress` section of a multi-milestone
+            // roadmap), so its total is just as suspect: keep the recorded counter and
+            // fall back to the recorded Total Phases for the percent below.
+            const derivedLowered = derived.completedPhases !== null
+                && Number.isFinite(recordedCompleted)
+                && derived.completedPhases < recordedCompleted;
+            if (!derivedLowered) {
+                if (derived.completedPhases !== null)
+                    newCompleted = derived.completedPhases;
+                if (derived.totalPhases !== null)
+                    derivedTotalPhases = derived.totalPhases;
+            }
         }
         // #3057 B9: only mark 'Completed Phases' updated when the text actually
         // changed. `stateReplaceField` returns the full (re-)substituted content

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

@@ -14,11 +14,14 @@ const node_path_1 = __importDefault(require("node:path"));
 const pattern_cjs_1 = require("./pattern.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
-const { output, error, declineNoOp, formatDiagnosticToken } = ioMod;
+const { output, error, declineNoOp, formatDiagnosticToken, ERROR_REASON } = ioMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const cliExitModule = require("./cli-exit.cjs");
 const { ExitError } = cliExitModule;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
+const capabilityLedgerMod = require("./capability-ledger.cjs");
+const { readSmallRegularFile } = capabilityLedgerMod;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
 const stateContract = require("./state-contract.cjs");
 const { publishStateContract } = stateContract;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -316,19 +319,51 @@ function cmdStateGet(cwd, section, raw) {
         output({ error: `Section or field "${section}" not found` }, raw, '');
     }
 }
-function readTextArgOrFile(cwd, value, filePath, label) {
+/**
+ * #4926: cap on a `--<flag>-file` text input. Twice the 128 KiB one argv string
+ * can carry on Linux, so the file form never takes less than the inline form,
+ * and the entry echoed back on stdout stays small.
+ */
+const TEXT_FILE_MAX_BYTES = 256 * 1024;
+/**
+ * Resolve a text argument that may instead be supplied as a file (`--<flag>`
+ * or `--<flag>-file`).
+ *
+ * #4926: the file is a read-once INPUT — its contents are copied into
+ * STATE.md and the path itself is never written, recorded, or resolved
+ * again — so it is not a project-write resource and is not confined to the
+ * project root. A scratch file from an agent's temp directory is accepted.
+ * A relative path still resolves against the project root.
+ *
+ * A file that cannot be read is a caller error and goes through the fault
+ * path — stderr, non-zero exit (USAGE), `--json-errors` envelope — rather than
+ * an `{ added: false }` payload at exit 0 that a shell caller gating on `$?`
+ * reads as success while nothing was written.
+ *
+ * An unconfined path is hostile input, so the read goes through
+ * `readSmallRegularFile`: a FIFO, a device (`/dev/zero`, a piped `/dev/stdin`)
+ * or a directory is refused without blocking, and a file over
+ * TEXT_FILE_MAX_BYTES is refused without being read.
+ */
+function readTextArgOrFile(cwd, value, filePath, flag) {
     if (!filePath)
         return value;
-    // Path traversal guard: ensure file resolves within project directory
-    // eslint-disable-next-line @typescript-eslint/no-require-imports, @typescript-eslint/unbound-method
-    const { assertWithinRoot, PathAcceptance } = require('./security.cjs');
-    const contained = assertWithinRoot(filePath, cwd, `${label} path`, PathAcceptance.AbsoluteInsideRoot);
+    const refuse = (why) => error(`--${flag}-file could not be read: ${formatDiagnosticToken(filePath)}${why ? ` (${why})` : ''}`, ERROR_REASON.USAGE);
+    let content;
     try {
-        return node_fs_1.default.readFileSync(contained, 'utf-8').trimEnd();
-    }
-    catch {
-        throw new Error(`${label} file not found: ${filePath}`);
+        content = readSmallRegularFile(node_path_1.default.resolve(cwd, filePath), TEXT_FILE_MAX_BYTES);
     }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EFBIG')
+            return refuse(`larger than ${TEXT_FILE_MAX_BYTES} bytes`);
+        if (code === 'EISDIR' || code === 'ENXIO')
+            return refuse('not a regular file');
+        return refuse(code);
+    }
+    if (content === null)
+        return refuse('ENOENT');
+    return content.trimEnd();
 }
 function cmdStatePatch(cwd, patches, raw) {
     // Validate all field names before processing
@@ -1224,25 +1259,19 @@ function cmdStateUpdateProgress(cwd, raw) {
 }
 function cmdStateAddDecision(cwd, options, raw) {
     const statePath = planningPaths(cwd).state;
-    if (!node_fs_1.default.existsSync(statePath)) {
-        output({ error: 'STATE.md not found' }, raw, undefined);
-        return;
-    }
+    // #4926: every refusal from this verb goes through the fault path (non-zero
+    // exit), so a caller gating on `$?` never reads success while nothing was written.
+    if (!node_fs_1.default.existsSync(statePath))
+        return error('STATE.md not found', ERROR_REASON.USAGE);
     const { phase, summary, summary_file, rationale, rationale_file } = options;
-    let summaryText = undefined;
-    let rationaleText = '';
-    try {
-        summaryText = readTextArgOrFile(cwd, summary, summary_file, 'summary');
-        rationaleText = readTextArgOrFile(cwd, rationale || '', rationale_file, 'rationale') || '';
-    }
-    catch (err) {
-        output({ added: false, reason: err.message }, raw, 'false');
-        return;
-    }
-    if (!summaryText) {
-        output({ error: 'summary required' }, raw, undefined);
-        return;
-    }
+    const summaryText = readTextArgOrFile(cwd, summary, summary_file, 'summary');
+    // The rationale is optional: blank, inline or file, means "no rationale".
+    const rationaleInput = readTextArgOrFile(cwd, rationale || '', rationale_file, 'rationale') || '';
+    const rationaleText = rationaleInput.trim() ? rationaleInput : '';
+    // A blank inline value is refused the same as a blank file (the file form is
+    // trimEnd()ed by readTextArgOrFile, the inline form is not).
+    if (!summaryText || !summaryText.trim())
+        return error('summary required — pass a non-blank --summary or --summary-file', ERROR_REASON.USAGE);
     // #3231/#3481: `--phase` omitted → resolve from the STATE.md being written, via
     // the canonical ladder `state prune` uses. A decision entry is a permanent
     // record, so a literal `[Phase ?]` written while `current_phase` sat three
@@ -1310,23 +1339,14 @@ function cmdStateAddDecision(cwd, options, raw) {
 }
 function cmdStateAddBlocker(cwd, text, raw) {
     const statePath = planningPaths(cwd).state;
-    if (!node_fs_1.default.existsSync(statePath)) {
-        output({ error: 'STATE.md not found' }, raw, undefined);
-        return;
-    }
+    // #4926: every refusal from this verb goes through the fault path (non-zero
+    // exit), so a caller gating on `$?` never reads success while nothing was written.
+    if (!node_fs_1.default.existsSync(statePath))
+        return error('STATE.md not found', ERROR_REASON.USAGE);
     const blockerOptions = typeof text === 'object' && text !== null ? text : { text: text };
-    let blockerText = undefined;
-    try {
-        blockerText = readTextArgOrFile(cwd, blockerOptions.text, blockerOptions.text_file, 'blocker');
-    }
-    catch (err) {
-        output({ added: false, reason: err.message }, raw, 'false');
-        return;
-    }
-    if (!blockerText) {
-        output({ error: 'text required' }, raw, undefined);
-        return;
-    }
+    const blockerText = readTextArgOrFile(cwd, blockerOptions.text, blockerOptions.text_file, 'text');
+    if (!blockerText || !blockerText.trim())
+        return error('text required — pass a non-blank --text or --text-file', ERROR_REASON.USAGE);
     const entry = `- ${blockerText}`;
     let _added = false;
     let created = false;
@@ -1379,25 +1399,16 @@ function cmdStateAddBlocker(cwd, text, raw) {
 }
 function cmdStateAddRoadmapEvolution(cwd, options, raw) {
     const statePath = planningPaths(cwd).state;
-    if (!node_fs_1.default.existsSync(statePath)) {
-        output({ error: 'STATE.md not found' }, raw, undefined);
-        return;
-    }
+    // #4926: every refusal from this verb goes through the fault path (non-zero
+    // exit), so a caller gating on `$?` never reads success while nothing was written.
+    if (!node_fs_1.default.existsSync(statePath))
+        return error('STATE.md not found', ERROR_REASON.USAGE);
     const { phase, action, after, note, note_file, urgent } = options;
-    let noteText = undefined;
-    try {
-        noteText = readTextArgOrFile(cwd, note, note_file, 'note');
-    }
-    catch (err) {
-        output({ added: false, reason: err.message }, raw, 'false');
-        return;
-    }
+    const noteText = readTextArgOrFile(cwd, note, note_file, 'note');
     // Reject missing / empty / whitespace-only notes — an evolution entry with no
     // narrative is meaningless and would corrupt the section with a dangling bullet.
-    if (!noteText || !noteText.trim()) {
-        output({ error: 'note required' }, raw, undefined);
-        return;
-    }
+    if (!noteText || !noteText.trim())
+        return error('note required — pass a non-blank --note or --note-file', ERROR_REASON.USAGE);
     // Flatten line breaks so the entry is always a single Markdown bullet. The
     // dedupe + rendering contract is line-oriented; a multiline --note-file would
     // otherwise spill continuation lines outside the bullet and defeat dedupe.
@@ -5097,6 +5108,23 @@ function cmdStateJson(cwd, raw) {
     preferNewerLastActivity(existingFm, built);
     output(built, raw, JSON.stringify(built, null, 2));
 }
+/**
+ * 1-based position of the first plan with no summary, when SOME of the phase's plans already have
+ * one (a gap-closure re-entry: plans 1..17 are done and 18 and 19 are the gap plans, #4945).
+ * `null` when no plan is summarized yet, when every plan is, or when the phase directory cannot be
+ * found: the phase then starts at plan 1, exactly as before. Plans and summaries are paired by the
+ * phase locator's own rule, so this agrees with `init` and `phase-plan-index`.
+ */
+function firstPlanToRun(cwd, phaseNumber) {
+    const located = phaseLocatorMod.findPhaseInternal(cwd, String(phaseNumber));
+    if (!located || !located.found)
+        return null;
+    const { plans, incomplete_plans: incomplete } = located;
+    if (incomplete.length === 0 || incomplete.length === plans.length)
+        return null;
+    const index = plans.indexOf(incomplete[0]);
+    return index === -1 ? null : index + 1;
+}
 /**
  * Update STATE.md when a new phase begins execution.
  * Updates body text fields (Current focus, Status, Last Activity, Current Position)
@@ -5144,6 +5172,8 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
         phaseNumber: phaseNumber,
         phaseName: phaseName ?? null,
         planCount: planCount ?? null,
+        // #4945: a gap-closure re-entry starts at the first plan still to run, not at plan 1.
+        startPlan: firstPlanToRun(cwd, phaseNumber),
     };
     const deps = {
         clock: clock_cjs_1.realClock,

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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