@opengsd/gsd-core 1.16.0 → 1.17.0

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

@@ -417,7 +417,41 @@ function createStateWriteIntent(transaction, init = {}) {
         err.code = 'STATE_WRITE_INTENT_TRANSACTION_REQUIRED';
         throw err;
     }
-    const assertions = Object.freeze((init.assertions ?? []).map((a) => Object.freeze({ field: a.field, requirement: a.requirement })));
+    // C2 (ADR-4629 §8.2): an unknown `requirement` is a construction error. §8.2
+    // judges only `'required'` assertions, so a mistyped value (`'Required'`)
+    // would otherwise be silently skipped: a fail-open verifier.
+    for (const a of init.assertions ?? []) {
+        if (a.requirement !== 'required' && a.requirement !== 'best-effort') {
+            const err = new Error(`createStateWriteIntent: assertion ${JSON.stringify(a.field)} has unknown requirement ` +
+                `${JSON.stringify(a.requirement)}; expected 'required' or 'best-effort' (ADR-4629 §8.1).`);
+            err.code = 'STATE_WRITE_INTENT_REQUIREMENT_INVALID';
+            throw err;
+        }
+    }
+    if (init.scope !== undefined && init.scope !== 'narrow' && init.scope !== 'broad') {
+        const err = new Error(`createStateWriteIntent: unknown scope ${JSON.stringify(init.scope)}; expected 'narrow' or 'broad' ` +
+            '(ADR-4629 §8.1).');
+        err.code = 'STATE_WRITE_INTENT_SCOPE_INVALID';
+        throw err;
+    }
+    // C2 (ADR-4629 §8.2): an unknown `target` is a construction error, never a
+    // silent fall-back to field semantics (a JS caller passing `'sections'`).
+    for (const a of init.assertions ?? []) {
+        if (a.target !== undefined && a.target !== 'field' && a.target !== 'section') {
+            const err = new Error(`createStateWriteIntent: assertion ${JSON.stringify(a.field)} has unknown target ` +
+                `${JSON.stringify(a.target)}; expected 'field' or 'section' (ADR-4629 §8.2).`);
+            err.code = 'STATE_WRITE_INTENT_TARGET_INVALID';
+            throw err;
+        }
+    }
+    // C2 (ADR-4629 §8.2): `target` / `value` are copied only when the caller set
+    // them, so a C1-shaped assertion stays exactly `{ field, requirement }`.
+    const assertions = Object.freeze((init.assertions ?? []).map((a) => Object.freeze({
+        field: a.field,
+        requirement: a.requirement,
+        ...(a.target !== undefined ? { target: a.target } : {}),
+        ...(a.value !== undefined ? { value: a.value } : {}),
+    })));
     return Object.freeze({
         ...transaction,
         assertions,
@@ -1575,9 +1609,30 @@ function advancePlanCore(content, deps) {
         data: { advanced: true, previous_plan: currentPlan, current_plan: newPlan, total_plans: totalPlans },
     };
 }
-// ----------------------------------------------------------------------------
-// completePhase — intent implementation (Phase 3)
-// ----------------------------------------------------------------------------
+/**
+ * #4824: Status / Current Plan / Stopped-at wording for the phase a
+ * completion hands off to. The historical `Ready to plan` is only true for a
+ * phase with no plans; a phase that already has PLANs routes to execution,
+ * and one whose plans all have SUMMARYs awaits verification — never back to
+ * `/gsd-plan-phase`. Which phase is selected stays #4078's rule.
+ */
+function nextPhaseWording(disk) {
+    switch (disk?.status) {
+        case 'PLANNED':
+            return { status: 'Ready to execute', currentPlan: 'Not started', stoppedAt: 'ready to execute' };
+        case 'IN_PROGRESS':
+            return { status: 'Ready to execute', currentPlan: String(disk.summaryCount + 1), stoppedAt: 'ready to execute' };
+        case 'EXECUTED':
+        case 'NEEDS_REVIEW':
+            return {
+                status: 'Phase complete — ready for verification',
+                currentPlan: String(disk.planCount),
+                stoppedAt: 'ready to verify',
+            };
+        default:
+            return { status: 'Ready to plan', currentPlan: 'Not started', stoppedAt: 'ready to plan' };
+    }
+}
 /**
  * Apply a `completePhase` transition to STATE.md content.
  *
@@ -1585,7 +1640,9 @@ function advancePlanCore(content, deps) {
  * (phase.cts) onto the substrate. Owns the field-classification-governed body
  * mutations: Current Phase (preserving the `of total` shape and phase name),
  * Current Phase Name, Status (`All phases complete` on the last phase, else
- * `Ready to plan` per ADR-2207), Current Plan (`Not started`), Last Activity + Description,
+ * `Ready to plan` per ADR-2207 — or, #4824, the next phase's disk-derived
+ * wording when it is already planned or executed), Current Plan (`Not started`
+ * unless the next phase is in flight), Last Activity + Description,
  * and the Completed/Total Phases + Progress percent block (re-derived from the
  * roadmap via the injected `roadmapProvider`).
  *
@@ -1602,6 +1659,7 @@ function advancePlanCore(content, deps) {
 function completePhaseCore(content, intent, deps) {
     const updated = [];
     const today = deps.clock.localToday();
+    const nextWording = nextPhaseWording(intent.isLastPhase ? null : intent.nextPhaseDisk ?? null);
     // Consult the field-classification table for the frontmatter keys this
     // transition touches (same guard beginPhaseCore applies). A missing row is a
     // substrate defect — fail loudly rather than silently re-encoding policy.
@@ -1665,7 +1723,7 @@ function completePhaseCore(content, intent, deps) {
     // Status — `All phases complete` on the final phase (ADR-2207), otherwise
     // `Ready to plan`. Milestone termination (`<version> milestone complete`) is
     // owned solely by the milestone-close verb (milestoneCompleteCore).
-    const statusValue = intent.isLastPhase ? 'All phases complete' : 'Ready to plan';
+    const statusValue = intent.isLastPhase ? 'All phases complete' : nextWording.status;
     const statusAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Status', null, statusValue);
     if (statusAfter !== body) {
         body = statusAfter;
@@ -1682,10 +1740,10 @@ function completePhaseCore(content, intent, deps) {
     let planAfter;
     const positionScope = (0, state_document_cjs_1.stateCurrentPositionSlice)(body);
     if (positionScope !== null) {
-        planAfter = (0, markdown_sectionizer_cjs_1.withSection)(body, (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position', (sectionBody) => (0, state_document_cjs_1.stateReplaceFieldWithFallback)(sectionBody, 'Current Plan', 'Plan', 'Not started'), { levelBounded: true });
+        planAfter = (0, markdown_sectionizer_cjs_1.withSection)(body, (h) => (h.level === 2 || h.level === 3) && h.text.trim().toLowerCase() === 'current position', (sectionBody) => (0, state_document_cjs_1.stateReplaceFieldWithFallback)(sectionBody, 'Current Plan', 'Plan', nextWording.currentPlan), { levelBounded: true });
     }
     else {
-        planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', 'Not started');
+        planAfter = (0, state_document_cjs_1.stateReplaceFieldWithFallback)(body, 'Current Plan', 'Plan', nextWording.currentPlan);
     }
     if (planAfter !== body) {
         body = planAfter;
@@ -1729,7 +1787,7 @@ function completePhaseCore(content, intent, deps) {
     // milestone termination wording stays owned by milestoneCompleteCore.
     const stoppedAtLine = intent.isLastPhase
         ? `Phase ${intent.phaseNum} complete — all phases complete`
-        : `Phase ${intent.phaseNum} complete${intent.nextPhaseNum ? `, ready to plan Phase ${intent.nextPhaseNum}` : ''}`;
+        : `Phase ${intent.phaseNum} complete${intent.nextPhaseNum ? `, ${nextWording.stoppedAt} Phase ${intent.nextPhaseNum}` : ''}`;
     const stoppedAfter = (0, state_document_cjs_1.stateReplaceFieldInSession)(body, 'Stopped At', 'Stopped at', stoppedAtLine);
     if (stoppedAfter !== body) {
         body = stoppedAfter;