@opengsd/gsd-core 1.5.0-rc.3 → 1.5.0-rc.4

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

@@ -1327,6 +1327,19 @@ function acquireStateLock(statePath, clock) {
     const staleThresholdMs = 10000;
     const maxWaitMs = 30000;
     const startedAt = clock.now();
+    // Shared helper: check the time budget then back off with jitter before the
+    // next retry.  Both the EEXIST contention path and the recoverable-errno path
+    // must go through this so neither can busy-spin (#1217).
+    const checkBudgetAndSleep = (context) => {
+        if (clock.now() - startedAt >= maxWaitMs) {
+            const e = new Error('acquireStateLock: ' + lockPath + ' ' + context + ' for ' +
+                (clock.now() - startedAt) + 'ms (exceeded ' + maxWaitMs + 'ms budget)');
+            e.lockBudgetExceeded = true;
+            throw e;
+        }
+        const jitter = Math.floor(Math.random() * 50);
+        clock.sleep(retryDelay + jitter);
+    };
     while (true) {
         try {
             const fd = node_fs_1.default.openSync(lockPath, node_fs_1.default.constants.O_CREAT | node_fs_1.default.constants.O_EXCL | node_fs_1.default.constants.O_WRONLY);
@@ -1338,9 +1351,11 @@ function acquireStateLock(statePath, clock) {
         }
         catch (err) {
             // Transient filesystem errors (Docker overlay-fs, NFS, OS signals, AV scanners)
-            // are recoverable — retry the acquisition loop rather than propagating.
+            // are recoverable — retry with the same budget + backoff as the EEXIST path so
+            // a permanently-failing errno cannot busy-spin at 100% CPU (#1217).
             // See ACQUIRE_LOCK_RETRY_ERRNOS for the full list and rationale.
             if (ACQUIRE_LOCK_RETRY_ERRNOS.has(err.code)) {
+                checkBudgetAndSleep(err.code + ' persisted');
                 continue;
             }
             if (err.code !== 'EEXIST')
@@ -1351,22 +1366,39 @@ function acquireStateLock(statePath, clock) {
             try {
                 const stat = node_fs_1.default.statSync(lockPath);
                 if ((clock).now() - stat.mtimeMs > staleThresholdMs) {
+                    let removed = false;
                     try {
                         node_fs_1.default.unlinkSync(lockPath);
+                        removed = true;
+                    }
+                    catch { /* swallow: bounded below */ }
+                    if (removed) {
+                        // Successful steal — retry immediately to grab the just-freed lock.
+                        // Must NOT call checkBudgetAndSleep here: a throw-after-delete would
+                        // corrupt the filesystem state, and the budget is already bounded on
+                        // the next iteration's EEXIST or open attempt (#1217 regression fix).
+                        continue;
                     }
-                    catch { /* already gone */ }
+                    // Persistent unlinkSync failure — apply budget + backoff so it cannot
+                    // busy-spin (#1217).
+                    checkBudgetAndSleep('stale lock removal failed');
                     continue;
                 }
             }
-            catch {
-                continue; /* released between EEXIST and stat */
-            }
-            if ((clock).now() - startedAt >= maxWaitMs) {
-                throw new Error('acquireStateLock: ' + lockPath + ' held by live process for ' +
-                    ((clock).now() - startedAt) + 'ms (exceeded ' + maxWaitMs + 'ms budget)');
+            catch (err) {
+                // Re-throw a budget-exceeded error from the unlinkSync failure path above
+                // unchanged — its message already names the real cause ("stale lock removal
+                // failed") and double-wrapping it would replace that with the misleading
+                // "statSync failed after EEXIST" context string (#1217 diagnostic fix).
+                if (err?.lockBudgetExceeded)
+                    throw err;
+                // statSync failed — lock was likely released between our EEXIST and this
+                // stat call.  Apply budget + backoff so a persistent statSync failure
+                // cannot busy-spin (#1217).
+                checkBudgetAndSleep('statSync failed after EEXIST');
+                continue;
             }
-            const jitter = Math.floor(Math.random() * 50);
-            (clock).sleep(retryDelay + jitter);
+            checkBudgetAndSleep('held by live process');
         }
     }
 }
@@ -1441,6 +1473,26 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
         // Snapshot the existing progress block BEFORE the transform so we can
         // restore it when resync is false.
         const preFm = resync ? null : extractFrontmatter(content);
+        // Bug #1230: delta heuristic — snapshot pre-transform body source fields so
+        // we can detect whether THIS write changed them. syncStateFrontmatter
+        // re-derives frontmatter status/stopped_at from the body on every write;
+        // when the body's source field was NOT changed by the transform, the
+        // existing frontmatter value (e.g. a hand-set 'completed') must win over
+        // the body-derived value (e.g. 'verifying' from a stale "Status: Verifying
+        // Phase 3" line that an earlier tool wrote). We do NOT disturb `preFm`
+        // above (null when resync:true) — these are independent snapshots.
+        // Strip frontmatter before calling stateExtractField so the YAML `status:`
+        // key in the frontmatter block cannot shadow the body field we are tracking.
+        const preBody = stripFrontmatter(content);
+        const preFmSnapshot = extractFrontmatter(content);
+        const preBodyStatus = (0, state_document_cjs_1.stateExtractField)(preBody, 'Status');
+        // Bug #1230 / Change B: scope stopped_at delta to the ## Session section,
+        // mirroring buildStateFrontmatter's sessionBodyScope logic (line ~1172).
+        // A stale "Stopped at:" in a non-Session section (e.g. Session Continuity
+        // Archive prose) must not interfere with the delta comparison.
+        const preSessionMatch = matchSessionSection(preBody);
+        const preSessionScope = preSessionMatch ? preSessionMatch[1] : preBody;
+        const preBodyStoppedAt = (0, state_document_cjs_1.stateExtractField)(preSessionScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(preSessionScope, 'Stopped at');
         const modified = transformFn(content);
         // Bug #948: no-op guard — if the transform produced no change, do NOT write
         // the file. An unconditional write would bump `last_updated`, reset
@@ -1453,14 +1505,53 @@ function readModifyWriteStateMd(statePath, transformFn, cwd, options, clock) {
             return;
         }
         let synced = syncStateFrontmatter(modified, cwd);
-        if (!resync && preFm && preFm['progress']) {
+        // Compute postFm once and apply BOTH the progress-restore (when !resync)
+        // AND the status/stopped_at preservation (#1230) before reconstructing.
+        // This avoids double-wrapping the frontmatter block.
+        const needsProgressRestore = !resync && preFm && preFm['progress'];
+        // Post-transform body source fields used for the delta comparison (#1230).
+        // Use `modified` (not `synced`): syncStateFrontmatter only rewrites the frontmatter block, so the body is identical in both — and we need the body the transform produced.
+        // Strip frontmatter so the YAML status key cannot shadow the body field.
+        const postBody = stripFrontmatter(modified);
+        const postBodyStatus = (0, state_document_cjs_1.stateExtractField)(postBody, 'Status');
+        // Bug #1230 / Change B: scope stopped_at delta to the ## Session section,
+        // consistent with the pre-transform snapshot above and buildStateFrontmatter.
+        const postSessionMatch = matchSessionSection(postBody);
+        const postSessionScope = postSessionMatch ? postSessionMatch[1] : postBody;
+        const postBodyStoppedAt = (0, state_document_cjs_1.stateExtractField)(postSessionScope, 'Stopped At') || (0, state_document_cjs_1.stateExtractField)(postSessionScope, 'Stopped at');
+        let mutated = false;
+        const postFm = extractFrontmatter(synced);
+        if (needsProgressRestore) {
             // Re-apply the curated progress block that syncStateFrontmatter just
             // overwrote with disk-derived values.  Only restore keys that were present
             // in the snapshot — this preserves any new non-progress frontmatter fields
             // (e.g., status, current_phase) that syncStateFrontmatter legitimately
             // derived from the updated body.
-            const postFm = extractFrontmatter(synced);
             postFm['progress'] = preFm['progress'];
+            mutated = true;
+        }
+        // Bug #1230: preserve existing frontmatter status when this write did NOT
+        // change the body's Status field. A write that doesn't touch Status must
+        // not silently revert a hand-set frontmatter status (e.g. 'completed') to
+        // whatever the stale body Status happens to derive (e.g. 'verifying').
+        // Only apply when the existing frontmatter held a real, non-unknown status.
+        if (postBodyStatus === preBodyStatus &&
+            typeof preFmSnapshot['status'] === 'string' &&
+            preFmSnapshot['status'].length > 0 &&
+            preFmSnapshot['status'] !== 'unknown' &&
+            postFm['status'] !== preFmSnapshot['status']) {
+            postFm['status'] = preFmSnapshot['status'];
+            mutated = true;
+        }
+        // Bug #1230: same delta heuristic for stopped_at.
+        if (postBodyStoppedAt === preBodyStoppedAt &&
+            typeof preFmSnapshot['stopped_at'] === 'string' &&
+            preFmSnapshot['stopped_at'].length > 0 &&
+            postFm['stopped_at'] !== preFmSnapshot['stopped_at']) {
+            postFm['stopped_at'] = preFmSnapshot['stopped_at'];
+            mutated = true;
+        }
+        if (mutated) {
             const yamlStr = reconstructFrontmatter(postFm);
             const body = stripFrontmatter(synced);
             synced = `---\n${yamlStr}\n---\n\n${body}`;
@@ -1529,74 +1620,89 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
     const today = clock_cjs_1.realClock.today();
     const updated = [];
     readModifyWriteStateMd(statePath, (content) => {
+        // Bug #1255: all body-field replacements must operate on the body only
+        // (frontmatter stripped), not on the full content.  When the full content is
+        // passed to stateReplaceField the YAML `status: planning` key matches the
+        // plain-text pattern (`^Status:\s*`) before the body pipe-table row, so the
+        // pipe-table `| Status | Planning |` is never updated and syncStateFrontmatter
+        // re-derives 'planning' from the unchanged body — the status never advances.
+        const existingFm = extractFrontmatter(content);
+        const hasFrontmatter = Object.keys(existingFm).length > 0;
+        let body = stripFrontmatter(content);
+        // Helper to reassemble content for field-replacement checks; callers that
+        // only need to test/replace body fields use `body` directly, and the final
+        // return reassembles the frontmatter block with the updated body.
+        const reassemble = (b) => hasFrontmatter ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}` : b;
         // Idempotency guard (#3127): if the phase is already mid-flight, do NOT
         // overwrite execution-progress fields (Current Plan, plan body line,
         // Last Activity Description). Only update fields that are safe to
         // refresh on resume (Last Activity date, Status if inconsistent).
         // A phase is considered mid-flight when Status contains 'Executing Phase N'
         // for the current phase number.
-        const currentStatus = (0, state_document_cjs_1.stateExtractField)(content, 'Status') || '';
+        // #1255: extract from body (not full content) so the YAML `status:` key
+        // cannot shadow the body Status field.
+        const currentStatus = (0, state_document_cjs_1.stateExtractField)(body, 'Status') || '';
         const isAlreadyExecuting = new RegExp(`Executing Phase\\s+${escapeRegex(String(phaseNumber))}\\b`, 'i').test(currentStatus);
-        // Update Status field
+        // Update Status field (body only — #1255)
         const statusValue = `Executing Phase ${phaseNumber}`;
-        let result = (0, state_document_cjs_1.stateReplaceField)(content, 'Status', statusValue);
+        let result = (0, state_document_cjs_1.stateReplaceField)(body, 'Status', statusValue);
         if (result) {
-            content = result;
+            body = result;
             updated.push('Status');
         }
         // Update Last Activity (safe to update on resume — tracks when execute-phase ran)
-        result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last Activity', today);
+        result = (0, state_document_cjs_1.stateReplaceField)(body, 'Last Activity', today);
         if (result) {
-            content = result;
+            body = result;
             updated.push('Last Activity');
         }
         if (!isAlreadyExecuting) {
             // First-time execution: set all progress fields
             // Update Last Activity Description
             const activityDesc = `Phase ${phaseNumber} execution started`;
-            result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last Activity Description', activityDesc);
+            result = (0, state_document_cjs_1.stateReplaceField)(body, 'Last Activity Description', activityDesc);
             if (result) {
-                content = result;
+                body = result;
                 updated.push('Last Activity Description');
             }
             // Update Current Phase
-            result = (0, state_document_cjs_1.stateReplaceField)(content, 'Current Phase', String(phaseNumber));
+            result = (0, state_document_cjs_1.stateReplaceField)(body, 'Current Phase', String(phaseNumber));
             if (result) {
-                content = result;
+                body = result;
                 updated.push('Current Phase');
             }
             // Update Current Phase Name
             if (phaseName) {
-                result = (0, state_document_cjs_1.stateReplaceField)(content, 'Current Phase Name', phaseName);
+                result = (0, state_document_cjs_1.stateReplaceField)(body, 'Current Phase Name', phaseName);
                 if (result) {
-                    content = result;
+                    body = result;
                     updated.push('Current Phase Name');
                 }
             }
             // Update Current Plan to 1 (starting from the first plan)
-            result = (0, state_document_cjs_1.stateReplaceField)(content, 'Current Plan', '1');
+            result = (0, state_document_cjs_1.stateReplaceField)(body, 'Current Plan', '1');
             if (result) {
-                content = result;
+                body = result;
                 updated.push('Current Plan');
             }
             // Update Total Plans in Phase
             if (planCount) {
-                result = (0, state_document_cjs_1.stateReplaceField)(content, 'Total Plans in Phase', String(planCount));
+                result = (0, state_document_cjs_1.stateReplaceField)(body, 'Total Plans in Phase', String(planCount));
                 if (result) {
-                    content = result;
+                    body = result;
                     updated.push('Total Plans in Phase');
                 }
             }
             // Update **Current focus:** body text line (#1104)
             const focusLabel = phaseName ? `Phase ${phaseNumber} — ${phaseName}` : `Phase ${phaseNumber}`;
             const focusPattern = /(\*\*Current focus:\*\*\s*).*/i;
-            if (focusPattern.test(content)) {
-                content = content.replace(focusPattern, (_match, prefix) => `${prefix}${focusLabel}`);
+            if (focusPattern.test(body)) {
+                body = body.replace(focusPattern, (_match, prefix) => `${prefix}${focusLabel}`);
                 updated.push('Current focus');
             }
             // Update ## Current Position section (#1104, #1365)
             const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-            const positionMatch = content.match(positionPattern);
+            const positionMatch = body.match(positionPattern);
             if (positionMatch) {
                 const header = positionMatch[1];
                 let posBody = positionMatch[2];
@@ -1606,7 +1712,13 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
                     posBody = posBody.replace(/^Phase:.*$/m, newPhase);
                 }
                 else {
-                    posBody = newPhase + '\n' + posBody;
+                    // Pipe-table format in Current Position (#1257): update the | Phase | … |
+                    // cell rather than prepending a spurious inline `Phase:` line (which left
+                    // the table cell stale). Mirrors the Status/Last-activity table branches.
+                    const phaseValue = `${phaseNumber}${phaseName ? ` (${phaseName})` : ''} — EXECUTING`;
+                    const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Phase', phaseValue);
+                    if (replaced !== null)
+                        posBody = replaced;
                 }
                 // Update or insert Plan line
                 const newPlan = `Plan: 1 of ${planCount || '?'}`;
@@ -1614,19 +1726,39 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
                     posBody = posBody.replace(/^Plan:.*$/m, newPlan);
                 }
                 else {
-                    posBody = posBody.replace(/^(Phase:.*$)/m, `$1\n${newPlan}`);
+                    // Pipe-table format in Current Position (#1257): update the | Plan | … |
+                    // cell rather than appending after a prepended inline line.
+                    const planValue = `1 of ${planCount || '?'}`;
+                    const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Plan', planValue);
+                    if (replaced !== null)
+                        posBody = replaced;
                 }
                 // Update Status line if present
                 const newStatus = `Status: Executing Phase ${phaseNumber}`;
                 if (/^Status:/m.test(posBody)) {
                     posBody = posBody.replace(/^Status:.*$/m, newStatus);
                 }
+                else {
+                    // Pipe-table format in Current Position (#1255)
+                    const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Status', `Executing Phase ${phaseNumber}`);
+                    if (replaced !== null)
+                        posBody = replaced;
+                }
                 // Update Last activity line if present
                 const newActivity = `Last activity: ${today} -- Phase ${phaseNumber} execution started`;
                 if (/^Last activity:/im.test(posBody)) {
                     posBody = posBody.replace(/^Last activity:.*$/im, newActivity);
                 }
-                content = content.replace(positionPattern, () => `${header}${posBody}`);
+                else {
+                    // Pipe-table format in Current Position (#1255)
+                    // Value must match the inline branch (date + narrative), not bare date.
+                    const activityValue = `${today} -- Phase ${phaseNumber} execution started`;
+                    const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last Activity', activityValue)
+                        ?? (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last activity', activityValue);
+                    if (replaced !== null)
+                        posBody = replaced;
+                }
+                body = body.replace(positionPattern, () => `${header}${posBody}`);
                 updated.push('Current Position');
             }
         }
@@ -1634,19 +1766,29 @@ function cmdStateBeginPhase(cwd, phaseNumber, phaseName, planCount, raw) {
             // Resume path: only update Last activity timestamp in Current Position
             // (do not touch Plan:, stopped_at, progress.percent, or plan counter)
             const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-            const positionMatch = content.match(positionPattern);
+            const positionMatch = body.match(positionPattern);
             if (positionMatch) {
                 const header = positionMatch[1];
                 let posBody = positionMatch[2];
                 const resumeActivity = `Last activity: ${today} -- Phase ${phaseNumber} execution resumed (wave continue)`;
                 if (/^Last activity:/im.test(posBody)) {
                     posBody = posBody.replace(/^Last activity:.*$/im, resumeActivity);
-                    content = content.replace(positionPattern, () => `${header}${posBody}`);
+                    body = body.replace(positionPattern, () => `${header}${posBody}`);
                     updated.push('Last activity (resume)');
                 }
+                else {
+                    // Pipe-table format in Current Position (#1255)
+                    const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last Activity', resumeActivity)
+                        ?? (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last activity', resumeActivity);
+                    if (replaced !== null) {
+                        posBody = replaced;
+                        body = body.replace(positionPattern, () => `${header}${posBody}`);
+                        updated.push('Last activity (resume)');
+                    }
+                }
             }
         }
-        return content;
+        return reassemble(body);
     }, cwd);
     output({ updated, phase: phaseNumber, phase_name: phaseName || null, plan_count: planCount || null }, raw, updated.length > 0 ? 'true' : 'false');
 }
@@ -1746,43 +1888,54 @@ function cmdStatePlannedPhase(cwd, phaseNumber, planCount, raw) {
     // doing so tramples curated/known-good counters. Route through the body-only
     // write contract (resync:false), the same guard state.update uses. (#500 RC1)
     readModifyWriteStateMd(statePath, (content) => {
+        // Bug #1257: all body-field replacements must operate on the body only
+        // (frontmatter stripped), not on the full content. When the full content is
+        // passed to stateReplaceFieldIfTemplate the YAML `status: planning` key matches
+        // the plain-text pattern (`^Status:\s*`) before the body pipe-table row, so the
+        // pipe-table `| Status | Planning |` cell is never updated and syncStateFrontmatter
+        // re-derives 'planning' from the unchanged body — the status never advances.
+        // (Mirrors the begin/complete-phase fix from #1255/#1256.)
+        const existingFm = extractFrontmatter(content);
+        const hasFrontmatter = Object.keys(existingFm).length > 0;
+        let body = stripFrontmatter(content);
+        const reassemble = (b) => hasFrontmatter ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}` : b;
         // Update Status — only when the existing value is a known template default
         // (Knuth invariant: preserve executor-authored values).
-        const newContent = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(content, 'Status', statusDefaults, 'Ready to execute');
-        if (newContent !== content) {
-            content = newContent;
+        const newBody = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(body, 'Status', statusDefaults, 'Ready to execute');
+        if (newBody !== body) {
+            body = newBody;
             updated.push('Status');
         }
         // Update Total Plans in Phase
         if (planCount !== null && planCount !== undefined) {
-            const result = (0, state_document_cjs_1.stateReplaceField)(content, 'Total Plans in Phase', String(planCount));
+            const result = (0, state_document_cjs_1.stateReplaceField)(body, 'Total Plans in Phase', String(planCount));
             if (result) {
-                content = result;
+                body = result;
                 updated.push('Total Plans in Phase');
             }
         }
         // Update Last Activity — only when the existing value is a known template default
         {
-            const after = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(content, 'Last Activity', lastActivityDefaults, today);
-            if (after !== content) {
-                content = after;
+            const after = (0, state_document_cjs_1.stateReplaceFieldIfTemplate)(body, 'Last Activity', lastActivityDefaults, today);
+            if (after !== body) {
+                body = after;
                 updated.push('Last Activity');
             }
         }
         // Update Last Activity Description
         {
-            const result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last Activity Description', `Phase ${phaseNumber} planning complete — ${planCount || '?'} plans ready`);
+            const result = (0, state_document_cjs_1.stateReplaceField)(body, 'Last Activity Description', `Phase ${phaseNumber} planning complete — ${planCount || '?'} plans ready`);
             if (result) {
-                content = result;
+                body = result;
                 updated.push('Last Activity Description');
             }
         }
         // Update Current Position section
-        content = updateCurrentPositionFields(content, {
+        body = updateCurrentPositionFields(body, {
             status: 'Ready to execute',
             lastActivity: `${today} -- Phase ${phaseNumber} planning complete`,
         });
-        return content;
+        return reassemble(body);
     }, cwd, { resync: false });
     output({ updated, phase: phaseNumber, plan_count: planCount }, raw, updated.length > 0 ? 'true' : 'false');
 }
@@ -2263,29 +2416,35 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
     const updated = [];
     readModifyWriteStateMd(statePath, (content) => {
         const currentPhase = resolvedPhase;
-        // Update Status field
+        // Bug #1255: operate on body only so the YAML frontmatter `status:` key
+        // cannot shadow the body Status field (pipe-table or inline).
+        const existingFm = extractFrontmatter(content);
+        const hasFrontmatter = Object.keys(existingFm).length > 0;
+        let body = stripFrontmatter(content);
+        const reassemble = (b) => hasFrontmatter ? `---\n${reconstructFrontmatter(existingFm)}\n---\n\n${b}` : b;
+        // Update Status field (body only — #1255)
         const statusValue = `Phase ${currentPhase} complete`;
-        let result = (0, state_document_cjs_1.stateReplaceField)(content, 'Status', statusValue);
+        let result = (0, state_document_cjs_1.stateReplaceField)(body, 'Status', statusValue);
         if (result) {
-            content = result;
+            body = result;
             updated.push('Status');
         }
         // Update Last Activity date
-        result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last Activity', today);
+        result = (0, state_document_cjs_1.stateReplaceField)(body, 'Last Activity', today);
         if (result) {
-            content = result;
+            body = result;
             updated.push('Last Activity');
         }
         // Update Last Activity Description
         const activityDesc = `Phase ${currentPhase} marked complete`;
-        result = (0, state_document_cjs_1.stateReplaceField)(content, 'Last Activity Description', activityDesc);
+        result = (0, state_document_cjs_1.stateReplaceField)(body, 'Last Activity Description', activityDesc);
         if (result) {
-            content = result;
+            body = result;
             updated.push('Last Activity Description');
         }
         // Update ## Current Position section
         const positionPattern = /(##\s*Current Position\s*\n)([\s\S]*?)(?=\n##|$)/i;
-        const positionMatch = content.match(positionPattern);
+        const positionMatch = body.match(positionPattern);
         if (positionMatch) {
             const header = positionMatch[1];
             let posBody = positionMatch[2];
@@ -2294,20 +2453,42 @@ function cmdStateCompletePhase(cwd, raw, overridePhase) {
             if (/^Phase:/m.test(posBody)) {
                 posBody = posBody.replace(/^Phase:.*$/m, newPhase);
             }
+            else {
+                // Pipe-table format in Current Position (#1255)
+                // Value cell must be bare (no "Phase:" label prefix) — the column header already provides the label.
+                const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Phase', `${currentPhase} — COMPLETE`);
+                if (replaced !== null)
+                    posBody = replaced;
+            }
             // Update Status line if present
             const newStatus = `Status: Phase ${currentPhase} complete`;
             if (/^Status:/m.test(posBody)) {
                 posBody = posBody.replace(/^Status:.*$/m, newStatus);
             }
+            else {
+                // Pipe-table format in Current Position (#1255)
+                const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Status', `Phase ${currentPhase} complete`);
+                if (replaced !== null)
+                    posBody = replaced;
+            }
             // Update Last activity line if present
             const newActivity = `Last activity: ${today} -- Phase ${currentPhase} marked complete`;
             if (/^Last activity:/im.test(posBody)) {
                 posBody = posBody.replace(/^Last activity:.*$/im, newActivity);
             }
-            content = content.replace(positionPattern, () => `${header}${posBody}`);
+            else {
+                // Pipe-table format in Current Position (#1255)
+                // Value must match the inline branch (date + narrative), not bare date.
+                const activityValue = `${today} -- Phase ${currentPhase} marked complete`;
+                const replaced = (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last Activity', activityValue)
+                    ?? (0, state_document_cjs_1.stateReplaceField)(posBody, 'Last activity', activityValue);
+                if (replaced !== null)
+                    posBody = replaced;
+            }
+            body = body.replace(positionPattern, () => `${header}${posBody}`);
             updated.push('Current Position');
         }
-        return content;
+        return reassemble(body);
     }, cwd);
     output({ updated, phase: resolvedPhase }, raw, updated.length > 0 ? 'true' : 'false');
 }

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

@@ -24,6 +24,8 @@ const frontmatterMod = require("./frontmatter.cjs");
 const stateMod = require("./state.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports -- model-profiles.cjs is an export= CommonJS module
 const modelProfilesMod = require("./model-profiles.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports -- plan-scan.cjs is an export= CommonJS module
+const planScanMod = require("./plan-scan.cjs");
 const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs");
 const package_identity_cjs_1 = require("./package-identity.cjs");
 const runtime_slash_cjs_1 = require("./runtime-slash.cjs");
@@ -450,6 +452,39 @@ function cmdVerifyArtifacts(cwd, planFilePath, raw) {
         artifacts: results,
     }, raw, passed === results.length ? 'valid' : 'invalid');
 }
+/**
+ * Returns a Set of file paths (relative to cwd) that are promised by plans in
+ * the same phase directory at a wave number >= minWave.
+ *
+ * Used by cmdVerifyKeyLinks to avoid hard-failing a missing `from:` file that
+ * is a planned future artifact (fix #1202).
+ */
+function collectPromisedFilesAtOrAfterWave(phaseDir, minWave) {
+    const promised = new Set();
+    const { planFiles } = planScanMod.scanPhasePlans(phaseDir);
+    for (const planFile of planFiles) {
+        const planFullPath = node_path_1.default.join(phaseDir, planFile);
+        const planContent = (0, shell_command_projection_cjs_1.platformReadSync)(planFullPath);
+        if (!planContent)
+            continue;
+        const fm = extractFrontmatter(planContent);
+        const waveRaw = fm['wave'];
+        const wave = typeof waveRaw === 'string' ? parseInt(waveRaw, 10) : (typeof waveRaw === 'number' ? waveRaw : NaN);
+        if (isNaN(wave) || wave < minWave)
+            continue;
+        const filesModified = fm['files_modified'];
+        if (!filesModified)
+            continue;
+        const files = Array.isArray(filesModified)
+            ? filesModified
+            : (typeof filesModified === 'string' ? [filesModified] : []);
+        for (const f of files) {
+            if (typeof f === 'string' && f.trim())
+                promised.add(f.trim());
+        }
+    }
+    return promised;
+}
 function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
     if (!planFilePath) {
         error('plan file path required');
@@ -465,7 +500,25 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
         output({ error: 'No must_haves.key_links found in frontmatter', path: planFilePath }, raw);
         return;
     }
+    // Derive the current plan's wave number and phase directory for wave-aware
+    // missing-file handling (fix #1202).
+    const currentFm = extractFrontmatter(content);
+    const currentWaveRaw = currentFm['wave'];
+    const currentWave = typeof currentWaveRaw === 'string'
+        ? parseInt(currentWaveRaw, 10)
+        : (typeof currentWaveRaw === 'number' ? currentWaveRaw : 1);
+    const phaseDir = node_path_1.default.dirname(fullPath);
+    // Collect files promised by plans at wave >= currentWave (lazy: computed once
+    // the first time a missing source is encountered).
+    let promisedFiles = null;
+    function getPromisedFiles() {
+        if (promisedFiles === null) {
+            promisedFiles = collectPromisedFilesAtOrAfterWave(phaseDir, isNaN(currentWave) ? 1 : currentWave);
+        }
+        return promisedFiles;
+    }
     const results = [];
+    let pendingCount = 0;
     for (const link of keyLinks) {
         if (typeof link === 'string')
             continue;
@@ -476,9 +529,20 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
             verified: false,
             detail: '',
         };
-        const sourceContent = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, link['from'] || ''));
+        const fromPath = link['from'] || '';
+        const sourceContent = (0, shell_command_projection_cjs_1.platformReadSync)(node_path_1.default.join(cwd, fromPath));
         if (!sourceContent) {
-            check['detail'] = 'Source file not found (from: must be a relative file path; describe components/endpoints in via:)';
+            // Check if the missing file is promised by a plan at the same or later wave.
+            const promised = getPromisedFiles();
+            const isPromised = fromPath.trim() !== '' && promised.has(fromPath.trim());
+            if (isPromised) {
+                check['pending'] = true;
+                check['detail'] = 'Source file not yet created — declared in files_modified of a same-or-later-wave plan';
+                pendingCount++;
+            }
+            else {
+                check['detail'] = 'Source file not found (from: must be a relative file path; describe components/endpoints in via:)';
+            }
         }
         else if (link['pattern']) {
             try {
@@ -514,12 +578,17 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
         results.push(check);
     }
     const verified = results.filter((r) => r['verified']).length;
+    // A pending link (from: file promised by a same-or-later-wave plan) is not a
+    // hard failure — it should not count against the all_verified gate (#1202).
+    const hardFailed = results.filter((r) => !r['verified'] && !r['pending']).length;
+    const allVerified = hardFailed === 0;
     output({
-        all_verified: verified === results.length,
+        all_verified: allVerified,
         verified,
+        pending: pendingCount,
         total: results.length,
         links: results,
-    }, raw, verified === results.length ? 'valid' : 'invalid');
+    }, raw, allVerified ? 'valid' : 'invalid');
 }
 function listMilestoneArchiveDirs(planBase) {
     const milestonesDir = node_path_1.default.join(planBase, 'milestones');