oh-my-codex 0.18.13 → 0.18.15

package/dist/ultragoal/artifacts.js

@@ -1,7 +1,7 @@
 import { existsSync } from 'node:fs';
 import { appendFile, mkdir, open, readFile, rename, rm, writeFile } from 'node:fs/promises';
 import { join, relative } from 'node:path';
-import { formatCodexGoalReconciliation, parseCodexGoalSnapshot, reconcileCodexGoalSnapshot, } from '../goal-workflows/codex-goal-snapshot.js';
+import { formatCodexGoalReconciliation, buildCompletedCodexGoalRemediation, parseCodexGoalSnapshot, reconcileCodexGoalSnapshot, } from '../goal-workflows/codex-goal-snapshot.js';
 export const ULTRAGOAL_DIR = '.omx/ultragoal';
 export const ULTRAGOAL_BRIEF = 'brief.md';
 export const ULTRAGOAL_GOALS = 'goals.json';
@@ -207,6 +207,22 @@ async function snapshotObjectiveMapsToUltragoalPlan(cwd, snapshotObjective) {
         return false;
     }
 }
+function unresolvedReviewBlockedGoals(plan) {
+    return plan.goals.filter((candidate) => candidate.status === 'review_blocked' && !isReviewBlockedResolved(candidate, plan));
+}
+function isDesignatedReviewBlockerResolver(goal, parent) {
+    return parent?.status === 'review_blocked'
+        && goal.resolvesReviewBlockedGoalId === parent.id
+        && parent.reviewBlockerResolution?.resolverGoalId === goal.id;
+}
+function canUseCleanFinalResolverPathForReviewBlockedParent(plan, goal, finalRunCheckpoint, allowActiveFinalCodexGoal) {
+    const unresolvedReviewBlocked = unresolvedReviewBlockedGoals(plan);
+    if (unresolvedReviewBlocked.length !== 1)
+        return false;
+    return finalRunCheckpoint
+        && !allowActiveFinalCodexGoal
+        && isDesignatedReviewBlockerResolver(goal, unresolvedReviewBlocked[0]);
+}
 async function canReconcileCompletedTaskScopedAggregateSnapshot(cwd, plan, goal, snapshotObjective, evidence) {
     if (codexGoalMode(plan) !== 'aggregate')
         return false;
@@ -295,16 +311,29 @@ function isSupersededResolved(goal, plan) {
         return replacement !== undefined && isResolvedStatus(replacement.status);
     });
 }
+function isReviewBlockedResolved(goal, plan) {
+    if (goal.status !== 'review_blocked')
+        return false;
+    const resolverId = goal.reviewBlockerResolution?.resolverGoalId;
+    if (!resolverId || goal.reviewBlockerResolution?.status !== 'complete')
+        return false;
+    const resolver = plan.goals.find((candidate) => candidate.id === resolverId);
+    return resolver?.status === 'complete';
+}
 function isCompletionBlocking(goal, plan) {
     if (goal.steeringStatus === 'superseded')
         return !isSupersededResolved(goal, plan);
     if (goal.steeringStatus === 'blocked')
         return true;
+    if (goal.status === 'review_blocked')
+        return !isReviewBlockedResolved(goal, plan);
     return !isResolvedStatus(goal.status);
 }
 function isCompletionBlockingForFinalCandidate(candidate, finalCandidate, plan) {
     if (candidate.id === finalCandidate.id)
         return false;
+    if (candidate.status === 'review_blocked' && candidate.reviewBlockerResolution?.resolverGoalId === finalCandidate.id)
+        return false;
     if (candidate.steeringStatus === 'superseded') {
         const replacements = candidate.supersededBy ?? [];
         if (replacements.length === 0)
@@ -488,13 +517,15 @@ export async function createUltragoalPlan(cwd, options) {
     });
 }
 export function summarizeUltragoalPlan(plan) {
+    const activeReviewBlocked = plan.goals.filter((goal) => goal.status === 'review_blocked' && !isReviewBlockedResolved(goal, plan)).length;
     return {
         total: plan.goals.length,
         pending: plan.goals.filter((goal) => goal.status === 'pending').length,
         inProgress: plan.goals.filter((goal) => goal.status === 'in_progress').length,
         complete: plan.goals.filter((goal) => goal.status === 'complete').length,
         failed: plan.goals.filter((goal) => goal.status === 'failed').length,
-        reviewBlocked: plan.goals.filter((goal) => goal.status === 'review_blocked').length,
+        reviewBlocked: activeReviewBlocked,
+        historicalReviewBlocked: plan.goals.filter((goal) => goal.status === 'review_blocked').length - activeReviewBlocked,
         needsUserDecision: plan.goals.filter((goal) => goal.status === 'needs_user_decision').length,
         superseded: plan.goals.filter((goal) => goal.steeringStatus === 'superseded').length,
         steeringBlocked: plan.goals.filter((goal) => goal.steeringStatus === 'blocked').length,
@@ -548,6 +579,7 @@ function appendGoalToPlan(plan, options, nowOverride) {
         createdAt: now,
         updatedAt: now,
         evidence: options.evidence,
+        resolvesReviewBlockedGoalId: options.resolvesReviewBlockedGoalId,
     };
     plan.goals.push(goal);
     plan.updatedAt = now;
@@ -909,9 +941,160 @@ export async function steerUltragoal(cwd, proposal, options = {}) {
         return { plan, accepted: invariant.accepted, audit, rejectedReasons: invariant.rejectedReasons, deduped: false };
     });
 }
-function validateQualityGate(value) {
+function normalizeInvariantText(value) {
+    return value.replace(/[`*_~]/g, '').replace(/\s+/g, ' ').trim().toLowerCase();
+}
+function requiredInvariantSourceKey(invariant) {
+    return `${normalizeInvariantText(invariant.invariant)}\u0000${invariant.sourceArtifact}`;
+}
+function uniqueRequiredArchitectureInvariants(invariants) {
+    const seen = new Set();
+    const unique = [];
+    for (const invariant of invariants) {
+        const key = requiredInvariantSourceKey(invariant);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        unique.push(invariant);
+    }
+    return unique;
+}
+function architectureInvariantSectionSlug(label) {
+    return label
+        .replace(/[`*_~]/g, '')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '') || 'architecture-invariants';
+}
+function normalizeSourceArtifact(value) {
+    return value.trim().split('#', 1)[0]?.replace(/\\/g, '/') ?? '';
+}
+function sourceReferencesArtifact(source, artifact) {
+    return normalizeSourceArtifact(source) === normalizeSourceArtifact(artifact);
+}
+function sourceReferencesAnyArtifact(source, artifacts) {
+    return artifacts.some((artifact) => sourceReferencesArtifact(source, artifact));
+}
+function invariantFromInlineDeclaration(line) {
+    const trimmed = cleanLine(line).replace(/^['"]|['"]$/g, '').trim();
+    const match = /\b(?:(?:non-negotiable|required)\s+)?(?:architecture|architectural|domain)\s+(?:invariants?|constraints?|non-negotiables?)\s*:\s*(.+)$/i.exec(trimmed)
+        ?? /\bnon-negotiables?\s+(?:architecture|architectural|domain)\s+(?:invariants?|constraints?)\s*:\s*(.+)$/i.exec(trimmed);
+    const invariant = match?.[1]?.trim().replace(/[.;]\s*$/, '').trim();
+    return invariant || undefined;
+}
+function extractArchitectureInvariantsFromArtifact(text, sourceArtifact, sourcePrefix) {
+    const lines = text.split(/\r?\n/);
+    const invariants = [];
+    let inInvariantSection = false;
+    let sectionSlug = 'architecture-invariants';
+    for (const line of lines) {
+        const heading = line.match(/^\s{0,3}#{1,6}\s+(.+?)\s*#*\s*$/);
+        if (heading) {
+            const label = heading[1] ?? '';
+            const normalizedLabel = label.toLowerCase();
+            inInvariantSection = /\b(?:architecture|architectural|domain|non-negotiable)\b/.test(normalizedLabel) && /\binvariants?\b|\bconstraints?\b|\bnon-negotiables?\b/.test(normalizedLabel);
+            if (inInvariantSection)
+                sectionSlug = architectureInvariantSectionSlug(label);
+            continue;
+        }
+        const inline = invariantFromInlineDeclaration(line);
+        if (inline) {
+            invariants.push({ invariant: inline, sourceArtifact, source: `${sourceArtifact}#${sourcePrefix ?? 'inline-architecture-invariant'}` });
+            continue;
+        }
+        if (!inInvariantSection)
+            continue;
+        const item = cleanLine(line);
+        if (!item || item === line.trim())
+            continue;
+        invariants.push({ invariant: item, sourceArtifact, source: `${sourceArtifact}#${sourcePrefix ? `${sourcePrefix}-${sectionSlug}` : sectionSlug}` });
+    }
+    return uniqueRequiredArchitectureInvariants(invariants.map((item) => ({ ...item, invariant: item.invariant.trim() })).filter((item) => item.invariant));
+}
+function extractArchitectureInvariantsFromBrief(brief) {
+    return extractArchitectureInvariantsFromArtifact(brief, `${ULTRAGOAL_DIR}/${ULTRAGOAL_BRIEF}`);
+}
+function extractArchitectureInvariantsFromAcceptedSteering(entries) {
+    const invariants = [];
+    for (const [index, entry] of entries.entries()) {
+        if (entry.event !== 'steering_accepted' || !entry.steering?.invariant.accepted)
+            continue;
+        const sourcePrefix = `steering-${index + 1}`;
+        const steering = entry.steering;
+        const texts = [
+            entry.evidence,
+            entry.message,
+            steering.evidence,
+            steering.rationale,
+            steering.directiveText,
+        ].filter((value) => typeof value === 'string' && value.trim().length > 0);
+        for (const text of texts) {
+            invariants.push(...extractArchitectureInvariantsFromArtifact(text, `${ULTRAGOAL_DIR}/${ULTRAGOAL_LEDGER}`, sourcePrefix));
+        }
+    }
+    return uniqueRequiredArchitectureInvariants(invariants);
+}
+async function collectRequiredArchitectureInvariants(cwd) {
+    const briefInvariants = extractArchitectureInvariantsFromBrief(await readFile(ultragoalBriefPath(cwd), 'utf-8'));
+    const steeringInvariants = extractArchitectureInvariantsFromAcceptedSteering(await readSteeringLedgerEntries(cwd));
+    return uniqueRequiredArchitectureInvariants([...briefInvariants, ...steeringInvariants]);
+}
+function validateArchitectureInvariantGate(gate, requiredInvariants) {
+    const invariantGate = gate.architectureInvariantGate;
+    if (!invariantGate || typeof invariantGate !== 'object') {
+        throw new UltragoalError('Final quality gate is missing architectureInvariantGate evidence; include derived architecture/domain invariants, source artifacts, implementation/test/review evidence, or record final blockers for unproved invariants.');
+    }
+    if (invariantGate.status !== 'passed') {
+        throw new UltragoalError('Final architecture-invariant gate requires architectureInvariantGate.status="passed"; record blocker-resolution work for unproved invariants.');
+    }
+    if (!Array.isArray(invariantGate.sourceArtifacts)) {
+        throw new UltragoalError('Final architecture-invariant gate requires architectureInvariantGate.sourceArtifacts.');
+    }
+    const sourceArtifacts = invariantGate.sourceArtifacts.map((source) => assertNonEmpty(source, 'architectureInvariantGate.sourceArtifacts[]'));
+    for (const required of requiredInvariants) {
+        if (!sourceArtifacts.some((source) => sourceReferencesArtifact(source, required.sourceArtifact))) {
+            throw new UltragoalError(`Final architecture-invariant gate sourceArtifacts must include required invariant source artifact: ${required.sourceArtifact}`);
+        }
+    }
+    assertNonEmpty(invariantGate.evidence, 'architectureInvariantGate.evidence');
+    if (!Array.isArray(invariantGate.invariants)) {
+        throw new UltragoalError('Final architecture-invariant gate requires architectureInvariantGate.invariants.');
+    }
+    const provided = new Map();
+    for (const invariant of invariantGate.invariants) {
+        if (!invariant || typeof invariant !== 'object')
+            throw new UltragoalError('Final architecture-invariant gate invariants must be objects.');
+        const record = invariant;
+        const text = assertNonEmpty(record.invariant, 'architectureInvariantGate.invariants[].invariant');
+        const source = assertNonEmpty(record.source, 'architectureInvariantGate.invariants[].source');
+        if (!sourceReferencesAnyArtifact(source, sourceArtifacts)) {
+            throw new UltragoalError(`Final architecture invariant "${text}" source must reference one of architectureInvariantGate.sourceArtifacts; decorative provenance labels are not sufficient.`);
+        }
+        if (record.status !== 'proved')
+            throw new UltragoalError(`Final architecture invariant "${text}" is not proved; record blocker-resolution work before final completion.`);
+        if (record.blockers !== undefined)
+            throw new UltragoalError(`Final architecture invariant "${text}" has blockers; record blocker-resolution work before final completion.`);
+        assertNonEmpty(record.implementationEvidence, 'architectureInvariantGate.invariants[].implementationEvidence');
+        assertNonEmpty(record.testEvidence, 'architectureInvariantGate.invariants[].testEvidence');
+        assertNonEmpty(record.reviewEvidence, 'architectureInvariantGate.invariants[].reviewEvidence');
+        const key = normalizeInvariantText(text);
+        const records = provided.get(key) ?? [];
+        records.push(record);
+        provided.set(key, records);
+    }
+    for (const required of requiredInvariants) {
+        const matches = provided.get(normalizeInvariantText(required.invariant)) ?? [];
+        if (matches.length === 0) {
+            throw new UltragoalError(`Final architecture-invariant gate is missing proof for required invariant from ${required.sourceArtifact}: ${required.invariant}`);
+        }
+        if (!matches.some((record) => sourceReferencesArtifact(record.source, required.sourceArtifact))) {
+            throw new UltragoalError(`Final architecture-invariant gate proof for required invariant must reference ${required.sourceArtifact}: ${required.invariant}`);
+        }
+    }
+}
+function validateQualityGate(value, requiredInvariants = []) {
     if (!value || typeof value !== 'object') {
-        throw new UltragoalError('Final ultragoal completion requires --quality-gate-json with ai-slop-cleaner, verification, and code-review evidence.');
+        throw new UltragoalError('Final ultragoal completion requires --quality-gate-json with ai-slop-cleaner, verification, code-review, and architecture-invariant evidence.');
     }
     const gate = value;
     const cleaner = gate.aiSlopCleaner;
@@ -960,6 +1143,7 @@ function validateQualityGate(value) {
         throw new UltragoalError('Final code-review must use an independent architect subagent; self-review or default/authoring-lane review cannot approve the ultragoal gate.');
     }
     assertNonEmpty(architect.evidence, 'codeReview.independentReview.architect.evidence');
+    validateArchitectureInvariantGate(gate, requiredInvariants);
     return gate;
 }
 export async function startNextUltragoal(cwd, options = {}) {
@@ -1059,6 +1243,7 @@ export async function checkpointUltragoal(cwd, options) {
             return plan;
         }
         let aggregateCompletion;
+        let normalFinalAggregateCompletion;
         if (options.status === 'complete') {
             const expectedObjective = expectedCodexObjective(plan, goal);
             const aggregateMode = codexGoalMode(plan) === 'aggregate';
@@ -1080,12 +1265,19 @@ export async function checkpointUltragoal(cwd, options) {
                     && normalizeObjective(snapshot.objective ?? '') !== normalizeObjective(expectedObjective)
                     && await canReconcileCompletedTaskScopedAggregateSnapshot(cwd, plan, goal, snapshot.objective ?? '', options.evidence);
                 if (completedTaskScopedAggregateSnapshot) {
-                    aggregateCompletion = {
-                        status: 'complete',
-                        completedAt: now,
-                        evidence: assertNonEmpty(options.evidence, '--evidence'),
-                        codexGoal: options.codexGoal,
-                    };
+                    if (unresolvedReviewBlockedGoals(plan).length > 0) {
+                        if (!canUseCleanFinalResolverPathForReviewBlockedParent(plan, goal, finalRunCheckpoint, options.allowActiveFinalCodexGoal)) {
+                            throw new UltragoalError('Completed task-scoped aggregate reconciliation is not allowed while unresolved review_blocked parent goals exist; only the parent\'s designated resolver may continue through the clean final quality gate path.');
+                        }
+                    }
+                    else {
+                        aggregateCompletion = {
+                            status: 'complete',
+                            completedAt: now,
+                            evidence: assertNonEmpty(options.evidence, '--evidence'),
+                            codexGoal: options.codexGoal,
+                        };
+                    }
                 }
                 else {
                     const taskScopedRequirement = aggregateMode && snapshot?.status === 'complete' && Boolean(snapshot.objective)
@@ -1102,11 +1294,25 @@ export async function checkpointUltragoal(cwd, options) {
                     throw new UltragoalError(`${formatCodexGoalReconciliation(reconciliation)}${taskScopedRequirement}${remediation}`);
                 }
             }
+            const designatedReviewBlockerResolver = goal.resolvesReviewBlockedGoalId
+                ? isDesignatedReviewBlockerResolver(goal, plan.goals.find((candidate) => candidate.id === goal.resolvesReviewBlockedGoalId))
+                : false;
+            if (aggregateMode && finalRunCheckpoint && !options.allowActiveFinalCodexGoal && designatedReviewBlockerResolver) {
+                normalFinalAggregateCompletion = {
+                    status: 'complete',
+                    completedAt: now,
+                    evidence: assertNonEmpty(options.evidence, '--evidence'),
+                    codexGoal: options.codexGoal,
+                };
+            }
             if (finalRunCheckpoint && !options.allowActiveFinalCodexGoal)
                 goal.evidence = options.evidence;
         }
+        const requiredArchitectureInvariants = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal))
+            ? await collectRequiredArchitectureInvariants(cwd)
+            : [];
         const qualityGate = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal))
-            ? validateQualityGate(options.qualityGate)
+            ? validateQualityGate(options.qualityGate, requiredArchitectureInvariants)
             : undefined;
         if (aggregateCompletion) {
             plan.aggregateCompletion = aggregateCompletion;
@@ -1134,6 +1340,23 @@ export async function checkpointUltragoal(cwd, options) {
             goal.failureReason = undefined;
             goal.failedAt = undefined;
             clearGoalBlockerFields(goal);
+            if (normalFinalAggregateCompletion)
+                plan.aggregateCompletion = normalFinalAggregateCompletion;
+            const resolvedParent = goal.resolvesReviewBlockedGoalId
+                ? plan.goals.find((candidate) => candidate.id === goal.resolvesReviewBlockedGoalId)
+                : undefined;
+            if (resolvedParent?.status === 'review_blocked' && resolvedParent.reviewBlockerResolution?.resolverGoalId === goal.id && qualityGate) {
+                resolvedParent.status = 'complete';
+                resolvedParent.completedAt = now;
+                resolvedParent.updatedAt = now;
+                resolvedParent.reviewBlockerResolution = {
+                    resolverGoalId: goal.id,
+                    status: 'complete',
+                    resolvedAt: now,
+                    evidence: options.evidence,
+                };
+                clearGoalBlockerFields(resolvedParent);
+            }
             if (plan.activeGoalId === goal.id)
                 delete plan.activeGoalId;
         }
@@ -1173,6 +1396,33 @@ export async function checkpointUltragoal(cwd, options) {
                 ? `Blocked on repeated external authorization. Required decision: ${goal.requiredExternalDecision}.`
                 : undefined,
         });
+        if (options.status === 'complete' && goal.resolvesReviewBlockedGoalId) {
+            const resolvedParent = plan.goals.find((candidate) => candidate.id === goal.resolvesReviewBlockedGoalId);
+            if (resolvedParent?.reviewBlockerResolution?.status === 'complete' && resolvedParent.reviewBlockerResolution.resolverGoalId === goal.id) {
+                await appendLedger(cwd, {
+                    ts: now,
+                    event: 'goal_completed',
+                    goalId: resolvedParent.id,
+                    status: resolvedParent.status,
+                    evidence: options.evidence,
+                    codexGoal: options.codexGoal,
+                    qualityGate,
+                    message: `Review-blocked final story resolved by ${goal.id}; original failed review remains in prior final_review_failed/goal_review_blocked ledger entries.`,
+                });
+            }
+        }
+        if (normalFinalAggregateCompletion) {
+            await appendLedger(cwd, {
+                ts: now,
+                event: 'aggregate_completed',
+                goalId: goal.id,
+                status: goal.status,
+                evidence: options.evidence,
+                codexGoal: options.codexGoal,
+                qualityGate,
+                message: 'Aggregate ultragoal plan completed with a clean final quality gate.',
+            });
+        }
         return plan;
     });
 }
@@ -1202,7 +1452,7 @@ export async function recordFinalReviewBlockers(cwd, options) {
         if (!reconciliation.ok) {
             throw new UltragoalError(formatCodexGoalReconciliation(reconciliation));
         }
-        const addedGoal = appendGoalToPlan(plan, { ...options, now: options.now });
+        const addedGoal = appendGoalToPlan(plan, { ...options, now: options.now, resolvesReviewBlockedGoalId: goal.id });
         goal.status = 'review_blocked';
         goal.reviewBlockedAt = now;
         goal.updatedAt = now;
@@ -1210,6 +1460,11 @@ export async function recordFinalReviewBlockers(cwd, options) {
         goal.failedAt = undefined;
         goal.failureReason = undefined;
         goal.evidence = options.evidence;
+        goal.reviewBlockerResolution = {
+            resolverGoalId: addedGoal.id,
+            status: 'pending',
+            evidence: options.evidence,
+        };
         if (plan.activeGoalId === goal.id)
             delete plan.activeGoalId;
         plan.updatedAt = now;
@@ -1263,6 +1518,7 @@ function buildPerStoryCodexGoalInstruction(goal, plan) {
         '',
         'Codex goal integration constraints:',
         '- First call get_goal. If no active goal exists, call create_goal with the payload below.',
+        `- If get_goal reports status complete before create_goal, do not call create_goal over it. ${buildCompletedCodexGoalRemediation('Ultragoal preflight')}`,
         '- If a different active Codex goal exists, finish/checkpoint that goal before starting this ultragoal.',
         '- Ultragoal cannot call /goal clear from the model/shell tool surface. For another per-story goal in the same session/thread after a completed Codex goal, manually run /goal clear in the Codex UI before creating the next goal.',
         '- If get_goal returns a different completed legacy/thread goal and create_goal rejects because this thread already has a completed goal, continue only from a Codex goal context with no active/completed conflicting goal in the same repo/worktree and create the payload there.',
@@ -1289,6 +1545,9 @@ function buildPerStoryCodexGoalInstruction(goal, plan) {
         finalStory
             ? `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`
             : null,
+        finalStory
+            ? '- After the final checkpoint command succeeds, treat `/goal clear` as the explicit terminal cleanup step before another same-thread goal.'
+            : null,
         '- If blocked or failed, checkpoint with --status failed and the failure evidence; rerun complete-goals --retry-failed to resume.',
         '',
         'create_goal payload:',
@@ -1313,6 +1572,7 @@ function buildAggregateCodexGoalInstruction(goal, plan) {
         '- Codex goal = the whole ultragoal run; OMX G001/G002/etc. = ledger stories.',
         '- First call get_goal. If no active goal exists, call create_goal with the aggregate payload below.',
         '- If get_goal reports the same aggregate objective as active, continue this OMX story without creating a new Codex goal.',
+        `- If get_goal reports status complete before create_goal, do not call create_goal over it. ${buildCompletedCodexGoalRemediation('Ultragoal preflight')}`,
         '- If a different active or incomplete Codex goal exists, finish/checkpoint that goal before starting this ultragoal; do not replace hidden Codex state from the shell.',
         '- Ultragoal does not call /goal clear. After a completed aggregate run, manually run /goal clear in the Codex UI before starting another ultragoal run in the same session/thread.',
         finalStory
@@ -1330,6 +1590,9 @@ function buildAggregateCodexGoalInstruction(goal, plan) {
         finalStory
             ? '- If final $code-review is clean (APPROVE + CLEAR + independent code-reviewer and architect subagent evidence), call update_goal({status: "complete"}), call get_goal again for a fresh complete snapshot, then checkpoint with --quality-gate-json.'
             : null,
+        finalStory
+            ? '- After the final checkpoint command succeeds, treat `/goal clear` as the explicit terminal cleanup step before another same-thread goal.'
+            : null,
         `- Checkpoint this OMX story with a fresh get_goal snapshot whose objective matches the aggregate payload and whose status is ${checkpointStatus}:`,
         finalStory
             ? `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh complete get_goal JSON or path>" --quality-gate-json "<quality gate JSON or path>"`