@opengsd/gsd-core 1.13.0 → 1.15.0

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

@@ -61,6 +61,13 @@ const planDependencyGraphMod = require("./plan-dependency-graph.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verificationMod = require("./verification.cjs");
 const { isPhaseComplete } = verificationMod;
+// #4129: the single owner of "count the ROADMAP's milestone Complete rows"
+// (phase-lifecycle.cts) — reused for the completed-phases numerator floor so
+// this scan cannot grow a second ROADMAP parser. Pure computation module (no
+// I/O), so it introduces no cycle on this path.
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseLifecycleMod = require("./phase-lifecycle.cjs");
+const { deriveProgressFromRoadmap } = phaseLifecycleMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const planningScopeMod = require("./planning-scope.cjs");
 const { SCOPE } = planningScopeMod;
@@ -286,7 +293,7 @@ function cmdStateGet(cwd, section, raw) {
         // Try to find markdown section or field
         const fieldEscaped = (0, pattern_cjs_1.escapeRegex)(section);
         // Check for **field:** value (bold format)
-        const boldPattern = new RegExp(`\\*\\*${fieldEscaped}:\\*\\*\\s*(.*)`, 'i');
+        const boldPattern = new RegExp(`^[ \\t]*\\*\\*${fieldEscaped}:\\*\\*[ \\t]*(.*)`, 'im');
         const boldMatch = content.match(boldPattern);
         if (boldMatch) {
             output({ [section]: boldMatch[1].trim() }, raw, boldMatch[1].trim());
@@ -314,13 +321,10 @@ function readTextArgOrFile(cwd, value, filePath, label) {
         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 { validatePath } = require('./security.cjs');
-    const pathCheck = validatePath(filePath, cwd, { allowAbsolute: true });
-    if (!pathCheck.safe) {
-        throw new Error(`${label} path rejected: ${pathCheck.error}`);
-    }
+    const { assertWithinRoot, PathAcceptance } = require('./security.cjs');
+    const contained = assertWithinRoot(filePath, cwd, `${label} path`, PathAcceptance.AbsoluteInsideRoot);
     try {
-        return node_fs_1.default.readFileSync(pathCheck.resolved, 'utf-8').trimEnd();
+        return node_fs_1.default.readFileSync(contained, 'utf-8').trimEnd();
     }
     catch {
         throw new Error(`${label} file not found: ${filePath}`);
@@ -489,7 +493,31 @@ function cmdStateUpdate(cwd, field, value) {
         // (#3345's direction) — reported separately from `updated` because this
         // command's contract is a single-field boolean, not a per-field array.
         const reconciled = reconcileReportedFields(statePath, preWriteState, updated ? [field] : [], divergedFields);
-        updated = reconciled.includes(field);
+        // #4488: `updateCore` itself already told us whether it matched the field
+        // (`updated`, captured above `readModifyWriteStateMd` runs it) — that is a
+        // real signal, not a guess. `reconcileReportedFields` answers a DIFFERENT
+        // question ("what changed on disk") and, per its own docstring, reports
+        // `[]` whenever `preWriteState.fm` is `undefined`. That happens in two
+        // known cases, both of which mean "no snapshot was ever captured", not
+        // "nothing happened": (a) `readModifyWriteStateMd`'s #948 no-op guard
+        // fires because the transform's output was byte-identical to the input —
+        // the requested value already equals what's on disk, so the field WAS
+        // found and there was simply nothing left to change; (b)
+        // `applyPostSyncPreservation`'s `isUnparseableFrontmatter` early return —
+        // the ORIGINAL frontmatter block was malformed, so preservation never
+        // runs, yet `readModifyWriteStateMd` still persists the transform's raw
+        // output via `platformWriteSync`. In neither case did preservation
+        // discard or rewrite what the transform wrote, so trusting the
+        // transform's own `updated` signal here is never a false positive.
+        // Collapsing either case into the same `false` as "field not found" is
+        // the #4488 bug — `explainUpdateFailure` then reports a message that is
+        // actively false (it tells the caller to add a line that is already
+        // there). Every other `false` origin (case-D fallback did not apply, or
+        // the transform genuinely found nothing) is unaffected: there
+        // `preWriteState.fm` is defined (a normal sync ran) or `updated` was
+        // already false before this line.
+        const noopBecauseAlreadyCorrect = updated && preWriteState.fm === undefined;
+        updated = reconciled.includes(field) || noopBecauseAlreadyCorrect;
         const preserved = reconciled.filter((f) => f !== field);
         if (updated) {
             // #3699 case D: surfaced so a caller can tell "wrote the body source" from
@@ -1560,6 +1588,18 @@ function cmdStateResolveBlocker(cwd, text, raw) {
     }
 }
 function cmdStateRecordSession(cwd, options, raw) {
+    // #4186: a bare invocation is a usage error, not a heartbeat write. The
+    // pre-#4186 handler accepted zero arguments and still refreshed
+    // `Last session` / `Last Date` / `last_updated` — a caller probing the
+    // command's signature (the way other subcommands encourage) silently
+    // mutated STATE.md. Mirrors `state update`'s required-arg guard
+    // (cmdStateUpdate: `error('field and value required for state update')`),
+    // including its ordering: validation precedes the STATE.md existence
+    // check. Either flag suffices — `--resume-file` alone carries an explicit
+    // value the handler must persist.
+    if (!options.stopped_at && (options.resume_file === undefined || options.resume_file === null)) {
+        error('stopped-at or resume-file required for state record-session');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -1569,10 +1609,31 @@ function cmdStateRecordSession(cwd, options, raw) {
     const updated = [];
     let sessionCreated = false;
     const divergedFields = [];
+    // #4763 (1): last-writer-wins stays (the recorded single-slot handoff design),
+    // but a displaced record is no longer silent. The pre-write session record is
+    // captured below and surfaced in the payload under `replacedRecord` whenever a
+    // replacement actually changes a non-empty prior value.
+    const priorRecord = {};
     // ADR-3473 §8.7 (#3872): caller-allocated out-param, filled with the
     // transaction's own pre-write snapshot + body by `applyPostSyncPreservation`.
     const preWriteState = {};
     readModifyWriteStateMd(statePath, (content) => {
+        // #4763 (1): read the pre-write session record. The capture mirrors the
+        // WRITER, not the snapshot reader: stateReplaceField replaces the FIRST
+        // case-insensitive label match anywhere in the document, so the capture is
+        // document-wide too — scoping it to ## Session would miss an archive-section
+        // line the writer actually displaced. Continuation lines join via
+        // stateFieldContinuation (the sanctioned joiner — stateExtractField alone is
+        // first-line-only), so a wrapped multi-line handoff is surfaced whole.
+        const capturePrior = (fieldName) => {
+            const first = (0, state_document_cjs_1.stateExtractField)(content, fieldName);
+            if (first === null)
+                return undefined;
+            const cont = (0, state_document_cjs_1.stateFieldContinuation)(content, fieldName);
+            return cont ? `${first}\n${cont}` : first;
+        };
+        priorRecord.stoppedAt = capturePrior('Stopped At');
+        priorRecord.resumeFile = capturePrior('Resume File');
         // Update Last session / Last Date
         let result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last session', now);
         if (result) {
@@ -1796,6 +1857,27 @@ function cmdStateRecordSession(cwd, options, raw) {
         const result = { recorded: true, updated: reconciledUpdated };
         if (sessionCreated)
             result['created'] = true;
+        // #4763 (1): surface any non-empty prior record the write displaced. Gated
+        // on reconciledUpdated (the fields that actually persisted, post-#3957
+        // reconcile) rather than the pre-reconciliation updated[]. Only fields with
+        // real prior content differing from the caller's value count — same-value
+        // rewrites, the insert path (no prior label), and the #944 template-default
+        // DWIM (defaults match case-insensitively, so a case-variant 'none' →
+        // 'None' rewrite is normalization, not displacement) are excluded.
+        const isResumeTemplateDefault = priorRecord.resumeFile !== undefined
+            && state_document_cjs_1.KNOWN_TEMPLATE_DEFAULTS['Resume File'].some((d) => d.toLowerCase() === priorRecord.resumeFile?.toLowerCase());
+        const replacedRecord = {};
+        if (reconciledUpdated.includes('Stopped At') && priorRecord.stoppedAt
+            && priorRecord.stoppedAt !== options.stopped_at) {
+            replacedRecord['Stopped At'] = priorRecord.stoppedAt;
+        }
+        if (reconciledUpdated.includes('Resume File') && priorRecord.resumeFile
+            && !isResumeTemplateDefault
+            && priorRecord.resumeFile !== (options.resume_file ?? undefined)) {
+            replacedRecord['Resume File'] = priorRecord.resumeFile;
+        }
+        if (Object.keys(replacedRecord).length > 0)
+            result['replacedRecord'] = replacedRecord;
         output(result, raw, 'true');
     }
     else if (updated.length === 0) {
@@ -2512,7 +2594,10 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // own comment on that field). Folding this consumer onto the raw
                         // summaries-met flag was the exact "consolidate two of three and
                         // leave the third" gap §7.4's forcing function rules out.
-                        if (isPhaseComplete(phaseDir).value.complete)
+                        // #612: `phaseConvention` threaded so a bracket phase dir resolves
+                        // and scopes its verification report like its legacy twin — the
+                        // read-side half of the same thread cmdStateSync gets below.
+                        if (isPhaseComplete(phaseDir, { convention: phaseConvention }).value.complete)
                             diskCompletedPhases++;
                     }
                     // Count phase headings from ROADMAP — single source of truth for
@@ -2619,6 +2704,34 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                         // write silently clobbered the three stored siblings with the
                         // under-scoped disk numbers.
                         const diskCountsWithheld = milestonedButUnbounded || roadmapAbsentWithAssertedMilestone;
+                        // #4129: floor the completed-phases numerator at the ROADMAP's own
+                        // milestone Complete-row count. The disk numerator counts ONLY
+                        // phase dirs whose *-VERIFICATION.md routes `passed` (isPhaseComplete,
+                        // #2957 disk-strict — the gate stays untouched), so a completed
+                        // phase whose verification reads `stale` (a SUMMARY committed or
+                        // edited after it, #2348 clean-commit-time clock) or `missing`
+                        // (pre-verification era, hand-flipped ROADMAP row) drops out of the
+                        // count forever — while every other surface (the ROADMAP row
+                        // `phase complete` just flipped, the body `Completed Phases` field
+                        // completePhaseCore derives from deriveProgressFromRoadmap) still
+                        // asserts the phase complete. max(disk, ROADMAP) keeps the disk
+                        // signal for gap detection (a verification-passed phase whose ROADMAP
+                        // row is not yet flipped still counts) while never UNDER-counting
+                        // what the ROADMAP asserts. Scoped exactly like the denominator:
+                        // the same milestone window (roadmapScope), the same
+                        // safeToUseRoadmapCount gate, and never under the #3354/#3573
+                        // withhold — a whole-document Complete-row count must not leak
+                        // through an untrustworthy scope. Reuses deriveProgressFromRoadmap
+                        // (phase-lifecycle.cts, the one owner of "read the Progress table")
+                        // — no second ROADMAP parser here. A ROADMAP without a canonical
+                        // `## Progress` table resolves no table → floor inert (disk count
+                        // stands), the owner's own answer to "what is countable".
+                        const roadmapCompletedPhases = roadmapScope !== null && safeToUseRoadmapCount && !diskCountsWithheld
+                            ? deriveProgressFromRoadmap(roadmapScope).completedPhases
+                            : null;
+                        const flooredCompletedPhases = roadmapCompletedPhases !== null
+                            ? Math.max(diskCompletedPhases, roadmapCompletedPhases)
+                            : diskCompletedPhases;
                         return {
                             // The two WITHHOLD shapes (#3354 milestoned-but-unbounded, #3573
                             // roadmap-absent-with-asserted-milestone) must be evaluated BEFORE
@@ -2629,7 +2742,7 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
                                 ? null
                                 : (safeToUseRoadmapCount ? Math.max(phaseDirs.length, roadmapPhaseCount) : phaseDirs.length),
                             milestoneBounded,
-                            completedPhases: diskCountsWithheld ? null : diskCompletedPhases,
+                            completedPhases: diskCountsWithheld ? null : flooredCompletedPhases,
                             totalPlans: diskCountsWithheld ? null : diskTotalPlans,
                             completedPlans: diskCountsWithheld ? null : diskTotalSummaries,
                             phaseDirScope,
@@ -2722,19 +2835,19 @@ storedCompletedPhases, storedTotalPlans, storedCompletedPlans) {
             progressPercent = parseInt(pctMatch[1], 10);
     }
     let normalizedStatus = (0, state_document_cjs_1.normalizeStateStatus)(status, pausedAt);
-    // #3578: normalizeStateStatus matches 'complete' as a case-insensitive
-    // SUBSTRING, so the phase-completion prose cmdStateCompletePhase writes to
-    // the body (`Phase ${N} complete`) collapses to the milestone-level
-    // 'completed' status even when other phases remain open. Phase-level
-    // prose must never decide milestone-level status — completedPhases /
-    // totalPhases / diskScope, already derived above from a disk scan, are
-    // the authority on whether the MILESTONE is actually done. Only override
-    // when: (a) normalizeStateStatus actually landed on 'completed'; (b) the
-    // raw prose is UNAMBIGUOUSLY phase-completion prose — the anchored
-    // pattern below deliberately excludes "All phases complete" (no `\S+`
-    // phase token) and milestone-close prose like "v1.0 milestone complete"
-    // (no leading "phase"); and (c) the counters are trustworthy (a COMPLETE
-    // disk scope, both counts are finite numbers, and a positive
+    // #3578: the declared status vocabulary (#4186) recognizes
+    // `Phase ${N} complete` (state.cts's own phase-completion write) and maps
+    // it to `completed`, so the phase-completion prose still collapses to the
+    // milestone-level status even when other phases remain open — this guard
+    // demotes it back. Phase-level prose must never decide milestone-level
+    // status — completedPhases / totalPhases / diskScope, already derived above
+    // from a disk scan, are the authority on whether the MILESTONE is actually
+    // done. Only override when: (a) normalizeStateStatus actually landed on
+    // 'completed'; (b) the raw prose is UNAMBIGUOUSLY phase-completion prose —
+    // the anchored pattern below deliberately excludes "All phases complete"
+    // (no `\S+` phase token) and milestone-close prose like "v1.0 milestone
+    // complete" (no leading "phase"); and (c) the counters are trustworthy (a
+    // COMPLETE disk scope, both counts are finite numbers, and a positive
     // denominator) and affirmatively disagree with 'completed'. In every
     // other case normalizedStatus is left exactly as normalizeStateStatus
     // returned it.
@@ -2996,6 +3109,75 @@ function readStoredTotalPlans(existingFm) {
 function readStoredCompletedPlans(existingFm) {
     return readStoredProgressCounter(existingFm, 'completed_plans');
 }
+/**
+ * #4129: is this authoritativeFm value a PARTIAL progress intent? The #2736
+ * seam was string-only (names); #4129 extends it with one object direction —
+ * the `progress` key carrying the sub-keys a transition resolved
+ * authoritatively (completePhase's ROADMAP-derived completed_phases/percent).
+ * Anything else keeps the seam's existing contract untouched.
+ */
+function isPartialProgressIntent(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/**
+ * #4129: merge a PARTIAL progress intent (see isPartialProgressIntent) into a
+ * frontmatter object's `progress` block. Sub-keys are accepted only when they
+ * are a declared `progress.*` row in FIELD_CLASSIFICATION — the single policy
+ * source (ADR-3408 §8.5) decides which leaves exist; an intent may not invent
+ * one. Returns whether anything changed.
+ *
+ * `completedOnlyRaise` (both application sites use it): completed counters
+ * apply only when strictly greater than what is already in the block, so no
+ * intent can LOWER a count another trustworthy signal already established —
+ * at the pre-preservation site the disk derivation's own count (a
+ * verification-passed phase whose ROADMAP row drifted behind), at the
+ * post-preservation re-assert the #2969 monotonic property preservation just
+ * enforced. `percent` follows its sibling: it is applied when a completed
+ * counter moved this call (the intent percent was computed from the intent
+ * counters and is coherent with them) or when the block has no percent to
+ * lose (a repair, never a regression of an upstream withhold — the withhold
+ * nulled percent upstream precisely so no write would re-assert one over
+ * untrustworthy counts; here the intent's own counts ARE the trustworthy
+ * source, the post-completion ROADMAP).
+ */
+function applyAuthoritativeProgressSubkeys(fm, intent, opts) {
+    const current = fm['progress'];
+    const base = isPartialProgressIntent(current)
+        ? { ...current }
+        : {};
+    let changed = false;
+    let completedMoved = false;
+    for (const [subkey, value] of Object.entries(intent)) {
+        if (typeof value !== 'number' || !Number.isFinite(value))
+            continue;
+        if (!getFieldClassification(`progress.${subkey}`))
+            continue;
+        const isCompletedCounter = subkey === 'completed_phases' || subkey === 'completed_plans';
+        if (isCompletedCounter && opts.completedOnlyRaise) {
+            const currentNum = (0, state_document_cjs_1.toFiniteNumber)(base[subkey]);
+            if (currentNum !== null && currentNum >= value)
+                continue;
+        }
+        if (isCompletedCounter && !Object.is(base[subkey], value))
+            completedMoved = true;
+        if (!Object.is(base[subkey], value)) {
+            base[subkey] = value;
+            changed = true;
+        }
+    }
+    // percent: applied only when a completed counter moved (coherent with the
+    // counters that just landed) or when no percent exists to contradict.
+    const intentPercent = intent['percent'];
+    if (typeof intentPercent === 'number' && Number.isFinite(intentPercent) && (completedMoved || (0, state_document_cjs_1.toFiniteNumber)(base['percent']) === null)) {
+        if (!Object.is(base['percent'], intentPercent)) {
+            base['percent'] = intentPercent;
+            changed = true;
+        }
+    }
+    if (changed)
+        fm['progress'] = base;
+    return changed;
+}
 function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanentEmptyFallback) {
     // Read existing frontmatter BEFORE stripping — it may contain values
     // that the body no longer has (e.g., Status field removed by an agent).
@@ -3201,11 +3383,22 @@ function syncStateFrontmatter(content, cwd, authoritativeFm, sanctionedPermanent
     // parenthetical (`Closer-ruling measurement (D1a)` → `D1a`) — never runs
     // the final word on a field the transition just resolved. The prose parser
     // remains the fallback for genuinely unknown prose only.
+    // #4129: the `progress` key carries a PARTIAL block (the object direction of
+    // this seam — see applyAuthoritativeProgressSubkeys) for the same reason:
+    // completePhase holds the POST-completion ROADMAP, and the disk scan this
+    // function drives reads the PRE-completion one. The intent is applied as a
+    // FLOOR here too (completedOnlyRaise): a derivation that already counted
+    // MORE completed phases than the ROADMAP table asserts (verification-passed
+    // phases whose table rows drifted behind) must not be lowered by the intent
+    // — the two signals agree on direction (up), never on subtraction.
     if (authoritativeFm) {
         for (const [key, value] of Object.entries(authoritativeFm)) {
             if (typeof value === 'string' && value.trim().length > 0) {
                 derivedFm[key] = value;
             }
+            else if (key === 'progress' && isPartialProgressIntent(value)) {
+                applyAuthoritativeProgressSubkeys(derivedFm, value, { completedOnlyRaise: true });
+            }
         }
     }
     // #3257: propagate full-line frontmatter comments from the extracted source onto the
@@ -3782,6 +3975,10 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
     // (equal), so the #1695 restore fires and would put the stale pre-transition
     // name back over the authoritative one. Intent beats both the prose
     // re-derivation and the curated restore — the transition just resolved it.
+    // #4129: for the `progress` key the re-assert is a FLOOR, not an override —
+    // the #2969 monotonic property preservation just enforced (completed
+    // counters never move down) must not be undone by the intent, so completed
+    // sub-keys apply only-raise here (see applyAuthoritativeProgressSubkeys).
     let authoritativeReasserted = false;
     if (authoritativeFm) {
         for (const [key, value] of Object.entries(authoritativeFm)) {
@@ -3789,6 +3986,11 @@ function applyPostSyncPreservation(originalContent, transformedContent, syncedCo
                 preservation.postFm[key] = value;
                 authoritativeReasserted = true;
             }
+            else if (key === 'progress' && isPartialProgressIntent(value)) {
+                if (applyAuthoritativeProgressSubkeys(preservation.postFm, value, { completedOnlyRaise: true })) {
+                    authoritativeReasserted = true;
+                }
+            }
         }
     }
     let finalContent = syncedContent;
@@ -4454,6 +4656,26 @@ function cmdStateJson(cwd, raw) {
  * Fixes: #1102 (plan counts), #1103 (status/last_activity), #1104 (body text).
  */
 function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
+    // #4138: `--phase` is this verb's one required argument, and an invocation
+    // that names no phase must fail closed BEFORE any read-modify-write runs —
+    // previously the missing flag flowed through as null and the transition
+    // serialised `String(null)` into the body (`Phase: null — EXECUTING`,
+    // `Status: Executing Phase null`, `last_activity_desc: Phase null execution
+    // started`) while the post-sync frontmatter rebuild dropped current_phase /
+    // current_phase_name entirely, so a single argument-less call un-set the
+    // phase identity. The guard mirrors the sibling usage errors that already
+    // exit non-zero (`state update`'s "field and value required", the router's
+    // "unexpected positional argument" / "Invalid --plans value"), NOT
+    // `cmdStateMilestoneSwitch`'s `output({error})` form, which exits 0 — the
+    // issue's Expected is explicit: "Exit non-zero with a usage message and
+    // write nothing." Empty and whitespace-only values are the same missing
+    // argument (CONTRIBUTING.md CLI matrix); a flag-shaped `--phase --name x`
+    // resolves to null in parseNamedArgs and lands here too. Runs before the
+    // STATE.md existence check so argument validation always precedes I/O, and
+    // before claimMilestonePhase so no phase-"null" milestone claim is taken.
+    if (phaseNumber == null || String(phaseNumber).trim() === '') {
+        error('phase required (--phase <N>)');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -4467,7 +4689,11 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     // #1230 post-sync preservation, and the no-op write guard.
     const intent = {
         kind: 'beginPhase',
-        phaseNumber,
+        // The guard above made this non-null/non-empty; `error` is never-returning
+        // at runtime but this module's destructured io binding does not narrow CFA,
+        // so the narrowed fact is restated once (cmdStateUpdate's `field as string`
+        // idiom, state.cts:782).
+        phaseNumber: phaseNumber,
         phaseName: phaseName ?? null,
         planCount: planCount ?? null,
     };
@@ -4763,6 +4989,12 @@ function updatePerformanceMetricsSection(content, cwd, phaseNum, planCount, summ
  * Updates Status to "Ready to execute", Total Plans, Last Activity.
  */
 function cmdStatePlannedPhase(cwd, phaseNumber, phaseName, planCount, raw) {
+    // #4383: mirror begin-phase's command-boundary guard. A missing phase must
+    // fail before even looking up STATE.md so no invalid invocation can enter
+    // the read-modify-write path and serialize a null/blank phase identity.
+    if (phaseNumber == null || String(phaseNumber).trim() === '') {
+        error('phase required (--phase <N>)');
+    }
     const statePath = planningPaths(cwd).state;
     if (!node_fs_1.default.existsSync(statePath)) {
         output({ error: 'STATE.md not found' }, raw, undefined);
@@ -4778,7 +5010,7 @@ function cmdStatePlannedPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     // still owns the lock, the #1230 preservation, and the no-op write guard.
     const intent = {
         kind: 'plannedPhase',
-        phaseNumber,
+        phaseNumber: phaseNumber,
         phaseName: phaseName ?? null,
         planCount: planCount ?? null,
     };
@@ -5134,7 +5366,10 @@ function cmdStateValidate(cwd, raw, opts = {}) {
         // ("verification passed" drift), not a false S007.
         const files = node_fs_1.default.readdirSync(phaseDirPath);
         const phaseDirBaseName = node_path_1.default.basename(phaseDirPath);
-        const verificationFiles = scopeToPhase(files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md')), phaseDirBaseName);
+        // #612: `validateConvention` threaded (already resolved above for
+        // `phaseKeyFromDir`) so the S006/S007 scan scopes bracket dirs by
+        // their real token instead of the include-everything fail-safe.
+        const verificationFiles = scopeToPhase(files.filter(f => f.includes('VERIFICATION') && f.endsWith('.md')), phaseDirBaseName, validateConvention);
         for (const vf of verificationFiles) {
             try {
                 const vContent = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDirPath, vf), 'utf-8');
@@ -5325,7 +5560,10 @@ function cmdStateSync(cwd, options, raw) {
         // was a second, independent consumer of the same raw field the initial
         // migration missed — without it, `state sync` and `state json` disagreed
         // on completed_phases for the identical disk state.
-        if (isPhaseComplete(dirPath).value.complete)
+        // #612: `syncConvention` threaded — the write-side half of
+        // buildStateFrontmatter's thread above, so `state sync` and `state json`
+        // keep agreeing on completed_phases under the bracket convention.
+        if (isPhaseComplete(dirPath, { convention: syncConvention }).value.complete)
             diskCompletedPhases++;
         // Track the highest phase with incomplete plans (or any plans)
         const phaseMatch = dir.match(new RegExp(`^(${PHASE_NUMBER_TOKEN_SOURCE})`, 'i'));

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

@@ -61,6 +61,18 @@ const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs"
 const retiredArtifactCleanup = require("./retired-artifact-cleanup.cjs");
 const { assertDestWithinConfigHome } = runtimeArtifactInstallPlan;
 const SURFACE_FILE_NAME = '.gsd-surface.json';
+const INSTALL_MANIFEST_FILE_NAME = 'gsd-file-manifest.json';
+/** Read only the installer-owned relative-include style, failing closed. */
+function readRelativeIncludePrefix(runtimeConfigDir) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(runtimeConfigDir, INSTALL_MANIFEST_FILE_NAME), 'utf8'));
+        const prefix = parsed?.['relativeIncludePrefix'];
+        return typeof prefix === 'string' ? prefix : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
 /**
  * Read the surface state from a runtime config directory.
  *
@@ -341,7 +353,11 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     const _isGlobal = (0, install_scope_cjs_1.isGlobalScope)(layout.scope ?? 'global');
     const _isOpencode = layout.runtime === 'opencode';
     const _isWindowsHost = (opts?.platform ?? process.platform) === 'win32';
-    const _pathPrefix = runtimeArtifactConversion._computePathPrefix({ isGlobal: _isGlobal, isOpencode: _isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget: _resolvedTarget, homeDir: _homeDir });
+    // #4377: style is an install-time fact, not a process environment setting.
+    // A later gsd-tools surface apply runs in another process, so it must reuse
+    // the persisted, root-relative prefix the installer actually emitted.
+    const _relativeIncludePrefix = readRelativeIncludePrefix(runtimeConfigDir);
+    const _pathPrefix = runtimeArtifactConversion._computePathPrefix({ isGlobal: _isGlobal, isOpencode: _isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget: _resolvedTarget, homeDir: _homeDir, projectRelative: !_isGlobal && typeof _relativeIncludePrefix === 'string', projectRelativePath: _relativeIncludePrefix, localDirName: runtimeArtifactConversion._localIncludeDirName(layout.runtime) });
     const _attribution = opts?.resolveAttribution ? opts.resolveAttribution(layout.runtime) : undefined;
     // #2875 Part 2 (row I1): layout.configDir is this call's install root.
     const agentCtx = { runtime: layout.runtime, pathPrefix: _pathPrefix, attribution: _attribution, targetDir: layout.configDir };
@@ -364,14 +380,25 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     try {
         for (const kind of layout.kinds) {
             let staged;
-            if (kind.kind === 'agents') {
+            // #4211: kimi-agents is an AGENT kind — kimiAgentsKind.stage() forwards
+            // agentCtx into stageAgentsForRuntimeWithConverter exactly as agentsKind
+            // does, and createRuntimeArtifactInstallPlan hands every kind the
+            // context. Staging it bare here dropped the path-prefix rewrites and the
+            // attribution trailer from Kimi's generated subagents, and (under an
+            // unmodified `full` profile) staged only the skill-referenced subset the
+            // install path stages with `skills: '*'`.
+            if (kind.kind === 'agents' || kind.kind === 'kimi-agents') {
                 const agentProfile = _isUnmodifiedFull ? { ...resolved, skills: '*' } : resolved;
                 staged = kind.stage(agentProfile, agentCtx);
             }
             else {
                 staged = kind.stage(resolved);
             }
-            if (kind.kind === 'skills') {
+            // #4211: kimi-agents takes the skill-body rewrite too —
+            // createRuntimeArtifactInstallPlan routes `skills` and `kimi-agents`
+            // through rewriteStagedSkillBodies together, so omitting it here left
+            // Kimi's surface-materialized prompts with unrewritten paths.
+            if (kind.kind === 'skills' || kind.kind === 'kimi-agents') {
                 runtimeArtifactConversion.rewriteStagedSkillBodies(staged, {
                     runtime: layout.runtime,
                     configDir: layout.configDir,
@@ -572,6 +599,53 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest, runtime) {
     // (no agentFileExtension declared) keep the staged filename verbatim.
     const _agentExt = runtime ? runtimeArtifactConversion.agentFileExtensionFor(runtime) : undefined;
     const isRenamedAgents = !!_agentExt && kindName === 'agents';
+    if (kindName === 'kimi-agents') {
+        // #4211: Kimi's managed tree is `gsd.yaml` + `gsd.md` + `subagents/gsd-*.{yaml,md}`
+        // (runtime-artifact-layout.cts kimiAgentsKind), and install copies it
+        // RECURSIVELY (_copyStaged in src/install-engine.cts). Surface apply fell
+        // through to the flat command/agent branch below, which reads only `*.md`
+        // at the top level: the YAML half and the whole subagents/ subtree were
+        // dropped, and `gsd.md` was written as `gsdgsd.md` (the flat branch
+        // re-applies kind.prefix to a name that already carries it). A surface
+        // change could therefore corrupt Kimi's installed artifacts while still
+        // reporting success.
+        node_fs_1.default.cpSync(stagedDir, destDir, { recursive: true });
+        // Prune GSD-owned files the new surface no longer stages, with exactly the
+        // ownership rule install's _removeGsdEntries applies to this kind: the two
+        // root files, and `gsd-`-prefixed .yaml/.md under subagents/. Everything
+        // else in the directory is user-owned and is preserved.
+        const _rootStaged = new Set(node_fs_1.default.readdirSync(stagedDir));
+        for (const fileName of ['gsd.yaml', 'gsd.md']) {
+            if (!_rootStaged.has(fileName)) {
+                try {
+                    node_fs_1.default.rmSync(node_path_1.default.join(destDir, fileName), { force: true });
+                }
+                catch { /* ignore */ }
+            }
+        }
+        const _stagedSubagentsDir = node_path_1.default.join(stagedDir, 'subagents');
+        const _destSubagentsDir = node_path_1.default.join(destDir, 'subagents');
+        const _stagedSubagents = node_fs_1.default.existsSync(_stagedSubagentsDir)
+            ? new Set(node_fs_1.default.readdirSync(_stagedSubagentsDir))
+            : new Set();
+        if (node_fs_1.default.existsSync(_destSubagentsDir)) {
+            for (const entry of node_fs_1.default.readdirSync(_destSubagentsDir, { withFileTypes: true })) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.startsWith('gsd-'))
+                    continue;
+                if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.md'))
+                    continue;
+                if (_stagedSubagents.has(entry.name))
+                    continue;
+                try {
+                    node_fs_1.default.rmSync(node_path_1.default.join(_destSubagentsDir, entry.name), { force: true });
+                }
+                catch { /* ignore */ }
+            }
+        }
+        return;
+    }
     if (kindName === 'skills') {
         // Skills kind: work with directories, not files.
         // Each staged entry is a directory named ${prefix}${stem}.

package/gsd-core/bin/lib/task-command-router.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 security_cjs_1 = require("./security.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const ioMod = require("./io.cjs");
 const { output, error, ERROR_REASON } = ioMod;
@@ -108,12 +109,14 @@ function routeResolveContent({ args, cwd, raw }, deps = {}) {
         return;
     }
     const projectRoot = node_path_1.default.resolve(cwd || process.cwd());
-    const resolvedPlanPath = node_path_1.default.resolve(projectRoot, plan);
-    const rel = node_path_1.default.relative(projectRoot, resolvedPlanPath);
-    if (rel === '..' || rel.startsWith(`..${node_path_1.default.sep}`)) {
+    // Lexical containment (ADR-4650): this path is validated before existence is
+    // checked below, so realpath resolution is neither available nor required.
+    const contained = (0, security_cjs_1.tryWithinRootLexical)(plan, projectRoot);
+    if (contained === null) {
         error(`Plan file is outside project scope: ${plan}`, ERROR_REASON.USAGE);
         return;
     }
+    const resolvedPlanPath = contained;
     if (!node_fs_1.default.existsSync(resolvedPlanPath)) {
         error(`Plan file not found: ${plan}`, ERROR_REASON.USAGE);
         return;
@@ -173,11 +176,14 @@ function routeTaskCommand({ args, cwd, raw }) {
     else if (args[2]) {
         const projectRoot = node_path_1.default.resolve(cwd || process.cwd());
         const requestedPath = args[2];
-        const resolvedTaskPath = node_path_1.default.resolve(projectRoot, requestedPath);
-        const rel = node_path_1.default.relative(projectRoot, resolvedTaskPath);
-        if (rel === '..' || rel.startsWith(`..${node_path_1.default.sep}`)) {
+        // Lexical containment (ADR-4650): validated before existence is checked below.
+        // `error()` here does not return/throw (preserved from before this migration),
+        // so resolvedTaskPath must still be computed identically on the rejected path.
+        const contained = (0, security_cjs_1.tryWithinRootLexical)(requestedPath, projectRoot);
+        if (contained === null) {
             error(`Task file is outside project scope: ${requestedPath}`, ERROR_REASON.USAGE);
         }
+        const resolvedTaskPath = contained ?? node_path_1.default.resolve(projectRoot, requestedPath);
         if (!node_fs_1.default.existsSync(resolvedTaskPath)) {
             error(`Task file not found: ${requestedPath}`, ERROR_REASON.USAGE);
         }