oh-my-codex 0.16.3 → 0.17.0

package/dist/ultragoal/__tests__/docs-contract.test.js

@@ -27,5 +27,26 @@ describe('ultragoal docs contract', () => {
         assert.match(doc, /Active or incomplete wrong Codex goals remain strict mismatch errors/i);
         assert.match(doc, /must not be used to bypass active-goal mismatch protection/i);
     });
+    it('documents the mandatory final cleanup and review gate', () => {
+        const docs = [
+            loadDoc('docs/ultragoal.md'),
+            loadDoc('skills/ultragoal/SKILL.md'),
+            loadDoc('plugins/oh-my-codex/skills/ultragoal/SKILL.md'),
+        ];
+        for (const doc of docs) {
+            assert.match(doc, /Mandatory final cleanup and review gate/);
+            assert.match(doc, /ai-slop-cleaner/);
+            assert.match(doc, /passed\/no-op report/);
+            assert.match(doc, /post-cleaner verification/i);
+            assert.match(doc, /\$code-review/);
+            assert.match(doc, /record-review-blockers/);
+            assert.match(doc, /review_blocked/);
+            assert.match(doc, /quality-gate-json/);
+            assert.match(doc, /APPROVE/);
+            assert.match(doc, /CLEAR/);
+            assert.doesNotMatch(doc, /not_applicable/);
+            assert.doesNotMatch(doc, /On the final story only, call `update_goal/);
+        }
+    });
 });
 //# sourceMappingURL=docs-contract.test.js.map

package/dist/ultragoal/__tests__/docs-contract.test.js.map

@@ -1 +1 @@
-{"version":3,"file":"docs-contract.test.js","sourceRoot":"","sources":["../../../src/ultragoal/__tests__/docs-contract.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AAC1D,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,EAAE,WAAW,CAAC,CAAC;AAE9C,SAAS,OAAO,CAAC,IAAY;IAC3B,OAAO,YAAY,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,EAAE,OAAO,CAAC,CAAC;AACrD,CAAC;AAED,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,6DAA6D,EAAE,GAAG,EAAE;QACrE,MAAM,GAAG,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAEzC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,+CAA+C,CAAC,CAAC;QACnE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,uDAAuD,CAAC,CAAC;QAC3E,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,yBAAyB,CAAC,CAAC;QAC7C,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,sFAAsF,CAAC,CAAC;QAC1G,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,iFAAiF,CAAC,CAAC;IACvG,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,yEAAyE,EAAE,GAAG,EAAE;QACjF,MAAM,GAAG,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC;QAEzC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,oDAAoD,CAAC,CAAC;QACxE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,gBAAgB,CAAC,CAAC;QACpC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,6CAA6C,CAAC,CAAC;QACjE,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,qBAAqB,CAAC,CAAC;QACzC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,wBAAwB,CAAC,CAAC;QAC5C,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,uEAAuE,CAAC,CAAC;QAC3F,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,6DAA6D,CAAC,CAAC;IACnF,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}
+{"version":3,"file":"docs-contract.test.js","sourceRoot":"","sources":["../../../src/ultragoal/__tests__/docs-contract.test.ts"],"names":[],"mappings":"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"}

package/dist/ultragoal/artifacts.d.ts

@@ -2,7 +2,7 @@ export declare const ULTRAGOAL_DIR = ".omx/ultragoal";
 export declare const ULTRAGOAL_BRIEF = "brief.md";
 export declare const ULTRAGOAL_GOALS = "goals.json";
 export declare const ULTRAGOAL_LEDGER = "ledger.jsonl";
-export type UltragoalStatus = 'pending' | 'in_progress' | 'complete' | 'failed';
+export type UltragoalStatus = 'pending' | 'in_progress' | 'complete' | 'failed' | 'review_blocked';
 export type UltragoalCodexGoalMode = 'aggregate' | 'per_story';
 export interface UltragoalItem {
     id: string;
@@ -16,9 +16,16 @@ export interface UltragoalItem {
     startedAt?: string;
     completedAt?: string;
     failedAt?: string;
+    reviewBlockedAt?: string;
     evidence?: string;
     failureReason?: string;
 }
+export interface UltragoalAggregateCompletion {
+    status: 'complete';
+    completedAt: string;
+    evidence: string;
+    codexGoal?: unknown;
+}
 export interface UltragoalPlan {
     version: 1;
     createdAt: string;
@@ -28,17 +35,19 @@ export interface UltragoalPlan {
     ledgerPath: string;
     codexGoalMode?: UltragoalCodexGoalMode;
     codexObjective?: string;
+    aggregateCompletion?: UltragoalAggregateCompletion;
     activeGoalId?: string;
     goals: UltragoalItem[];
 }
 export interface UltragoalLedgerEntry {
     ts: string;
-    event: 'plan_created' | 'goal_started' | 'goal_resumed' | 'goal_completed' | 'goal_blocked' | 'goal_failed' | 'goal_retried';
+    event: 'plan_created' | 'goal_started' | 'goal_resumed' | 'goal_completed' | 'goal_blocked' | 'goal_failed' | 'goal_retried' | 'aggregate_completed' | 'goal_added' | 'final_review_failed' | 'goal_review_blocked';
     goalId?: string;
     status?: UltragoalStatus;
     message?: string;
     codexGoal?: unknown;
     evidence?: string;
+    qualityGate?: UltragoalQualityGate;
 }
 export interface CreateUltragoalOptions {
     brief: string;
@@ -60,14 +69,44 @@ export interface CheckpointOptions {
     status: Extract<UltragoalStatus, 'complete' | 'failed'> | 'blocked';
     evidence?: string;
     codexGoal?: unknown;
+    qualityGate?: unknown;
+    allowActiveFinalCodexGoal?: boolean;
+    now?: Date;
+}
+export interface AddUltragoalGoalOptions {
+    title: string;
+    objective: string;
+    evidence?: string;
     now?: Date;
 }
+export interface RecordFinalReviewBlockersOptions extends AddUltragoalGoalOptions {
+    goalId: string;
+    codexGoal?: unknown;
+}
+export interface UltragoalQualityGate {
+    aiSlopCleaner: {
+        status: 'passed';
+        evidence: string;
+    };
+    verification: {
+        status: 'passed';
+        commands: string[];
+        evidence: string;
+    };
+    codeReview: {
+        recommendation: 'APPROVE';
+        architectStatus: 'CLEAR';
+        evidence: string;
+    };
+}
 export declare class UltragoalError extends Error {
 }
 export declare function ultragoalDir(cwd: string): string;
 export declare function ultragoalBriefPath(cwd: string): string;
 export declare function ultragoalGoalsPath(cwd: string): string;
 export declare function ultragoalLedgerPath(cwd: string): string;
+export declare function isFinalRunCompletionCandidate(plan: UltragoalPlan, goal: UltragoalItem): boolean;
+export declare function isUltragoalDone(plan: UltragoalPlan): boolean;
 export declare function deriveGoalCandidates(brief: string): Array<{
     title: string;
     objective: string;
@@ -80,8 +119,14 @@ export declare function summarizeUltragoalPlan(plan: UltragoalPlan): {
     inProgress: number;
     complete: number;
     failed: number;
+    reviewBlocked: number;
+    aggregateComplete: boolean;
     activeGoalId?: string;
 };
+export declare function addUltragoalGoal(cwd: string, options: AddUltragoalGoalOptions): Promise<{
+    plan: UltragoalPlan;
+    goal: UltragoalItem;
+}>;
 export declare function startNextUltragoal(cwd: string, options?: StartNextOptions): Promise<{
     plan: UltragoalPlan;
     goal: UltragoalItem | null;
@@ -89,5 +134,10 @@ export declare function startNextUltragoal(cwd: string, options?: StartNextOptio
     done: boolean;
 }>;
 export declare function checkpointUltragoal(cwd: string, options: CheckpointOptions): Promise<UltragoalPlan>;
+export declare function recordFinalReviewBlockers(cwd: string, options: RecordFinalReviewBlockersOptions): Promise<{
+    plan: UltragoalPlan;
+    blockedGoal: UltragoalItem;
+    addedGoal: UltragoalItem;
+}>;
 export declare function buildCodexGoalInstruction(goal: UltragoalItem, plan: UltragoalPlan): string;
 //# sourceMappingURL=artifacts.d.ts.map

package/dist/ultragoal/artifacts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/ultragoal/artifacts.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../../src/ultragoal/artifacts.ts"],"names":[],"mappings":"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"}

package/dist/ultragoal/artifacts.js

@@ -32,9 +32,65 @@ function cleanLine(line) {
 function normalizeObjective(value) {
     return value.replace(/\s+/g, ' ').trim();
 }
+function textMentionsUltragoalPlanArtifact(value) {
+    const normalized = (value ?? '').toLowerCase();
+    return normalized.includes(ULTRAGOAL_DIR.toLowerCase())
+        || normalized.includes(ULTRAGOAL_GOALS.toLowerCase())
+        || normalized.includes(ULTRAGOAL_LEDGER.toLowerCase());
+}
+function textMentionsGoalId(value, goalId) {
+    return (value ?? '').toLowerCase().includes(goalId.toLowerCase());
+}
+function textHasCompletionValidationEvidence(value) {
+    const normalized = (value ?? '').toLowerCase();
+    const hasImplementationCompletion = /\b(?:planned work|implementation|deliverables?|scope|task|work)\b/.test(normalized)
+        && /\b(?:done|complete|completed|finished|shipped)\b/.test(normalized);
+    const hasValidation = /\b(?:validation|verification|tests?|build|lint|review|quality gate|code-review)\b/.test(normalized)
+        && /\b(?:passed|complete|completed|clean|green|approve|approved|clear)\b/.test(normalized);
+    return hasImplementationCompletion && hasValidation;
+}
+async function snapshotObjectiveMapsToUltragoalPlan(cwd, snapshotObjective) {
+    const actual = normalizeObjective(snapshotObjective).toLowerCase();
+    if (textMentionsUltragoalPlanArtifact(actual))
+        return true;
+    if (actual.length < 24)
+        return false;
+    try {
+        const brief = normalizeObjective(await readFile(ultragoalBriefPath(cwd), 'utf-8')).toLowerCase();
+        if (!brief || brief.length < 24)
+            return false;
+        return brief.includes(actual) || actual.includes(brief);
+    }
+    catch {
+        return false;
+    }
+}
+async function canReconcileCompletedTaskScopedAggregateSnapshot(cwd, plan, goal, snapshotObjective, evidence) {
+    if (codexGoalMode(plan) !== 'aggregate')
+        return false;
+    if (goal.status !== 'in_progress' || plan.activeGoalId !== goal.id)
+        return false;
+    if (!textMentionsUltragoalPlanArtifact(evidence))
+        return false;
+    if (!textMentionsGoalId(evidence, goal.id))
+        return false;
+    if (!textHasCompletionValidationEvidence(evidence))
+        return false;
+    return snapshotObjectiveMapsToUltragoalPlan(cwd, snapshotObjective);
+}
+function buildCompletedLegacyGoalRemediation(goal) {
+    return [
+        'If get_goal returns a different completed legacy/thread objective, do not repeat --status complete in this thread.',
+        `Record a non-terminal blocker with: omx ultragoal checkpoint --goal-id ${goal.id} --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json "<different completed get_goal JSON or path>".`,
+        'Then continue this ultragoal in a fresh Codex thread in the same repo/worktree and create the intended goal there.',
+    ].join(' ');
+}
 function codexGoalMode(plan) {
     return plan.codexGoalMode ?? 'per_story';
 }
+function isResolvedStatus(status) {
+    return status === 'complete' || status === 'review_blocked';
+}
 function aggregateCodexObjective(goals) {
     const prefix = `Complete all ultragoal stories in ${ULTRAGOAL_DIR}/${ULTRAGOAL_GOALS}: `;
     const suffix = goals.map((goal) => `${goal.id} ${goal.title}`).join('; ');
@@ -51,8 +107,20 @@ function expectedCodexObjective(plan, goal) {
         ? (plan.codexObjective ?? aggregateCodexObjective(plan.goals))
         : goal.objective;
 }
-function isFinalAggregateCheckpoint(plan, goal) {
-    return plan.goals.every((candidate) => candidate.id === goal.id || candidate.status === 'complete');
+export function isFinalRunCompletionCandidate(plan, goal) {
+    return plan.goals.every((candidate) => candidate.id === goal.id || isResolvedStatus(candidate.status));
+}
+export function isUltragoalDone(plan) {
+    if (plan.aggregateCompletion?.status === 'complete')
+        return true;
+    if (plan.goals.length === 0)
+        return true;
+    if (plan.goals.some((goal) => goal.status === 'pending' || goal.status === 'in_progress' || goal.status === 'failed'))
+        return false;
+    if (!plan.goals.every((goal) => isResolvedStatus(goal.status)))
+        return false;
+    const latestNonReviewBlocked = [...plan.goals].reverse().find((goal) => goal.status !== 'review_blocked');
+    return latestNonReviewBlocked?.status === 'complete';
 }
 function titleFromObjective(objective, fallback) {
     const firstLine = objective.split(/\r?\n/).map((line) => line.trim()).find(Boolean) ?? fallback;
@@ -156,12 +224,87 @@ export function summarizeUltragoalPlan(plan) {
         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,
+        aggregateComplete: plan.aggregateCompletion?.status === 'complete',
         activeGoalId: plan.activeGoalId,
     };
 }
+function assertNonEmpty(value, label) {
+    const trimmed = value?.trim();
+    if (!trimmed)
+        throw new UltragoalError(`Missing ${label}.`);
+    return trimmed;
+}
+function appendGoalToPlan(plan, options, now) {
+    const title = assertNonEmpty(options.title, '--title');
+    const objective = assertNonEmpty(options.objective, '--objective');
+    const goal = {
+        id: normalizeGoalId(title, plan.goals.length),
+        title,
+        objective,
+        status: 'pending',
+        attempt: 0,
+        createdAt: now,
+        updatedAt: now,
+        evidence: options.evidence,
+    };
+    plan.goals.push(goal);
+    plan.updatedAt = now;
+    return goal;
+}
+export async function addUltragoalGoal(cwd, options) {
+    const plan = await readUltragoalPlan(cwd);
+    const now = iso(options.now);
+    const goal = appendGoalToPlan(plan, options, now);
+    await writePlan(cwd, plan);
+    await appendLedger(cwd, {
+        ts: now,
+        event: 'goal_added',
+        goalId: goal.id,
+        status: goal.status,
+        evidence: options.evidence,
+        message: goal.title,
+    });
+    return { plan, goal };
+}
+function validateQualityGate(value) {
+    if (!value || typeof value !== 'object') {
+        throw new UltragoalError('Final ultragoal completion requires --quality-gate-json with ai-slop-cleaner, verification, and code-review evidence.');
+    }
+    const gate = value;
+    const cleaner = gate.aiSlopCleaner;
+    const verification = gate.verification;
+    const review = gate.codeReview;
+    if (!cleaner || typeof cleaner !== 'object')
+        throw new UltragoalError('Final quality gate is missing aiSlopCleaner evidence.');
+    if (cleaner.status !== 'passed') {
+        throw new UltragoalError('Final quality gate requires aiSlopCleaner.status="passed"; run ai-slop-cleaner even when it is a no-op.');
+    }
+    assertNonEmpty(cleaner.evidence, 'aiSlopCleaner.evidence');
+    if (!verification || typeof verification !== 'object')
+        throw new UltragoalError('Final quality gate is missing verification evidence.');
+    if (verification.status !== 'passed')
+        throw new UltragoalError('Final quality gate requires verification.status="passed".');
+    if (!Array.isArray(verification.commands) || verification.commands.length === 0 || verification.commands.some((command) => typeof command !== 'string' || command.trim() === '')) {
+        throw new UltragoalError('Final quality gate requires non-empty verification.commands.');
+    }
+    assertNonEmpty(verification.evidence, 'verification.evidence');
+    if (!review || typeof review !== 'object')
+        throw new UltragoalError('Final quality gate is missing codeReview evidence.');
+    if (review.recommendation !== 'APPROVE') {
+        throw new UltragoalError('Final code-review must be clean: codeReview.recommendation must be APPROVE; use record-review-blockers for COMMENT or REQUEST CHANGES.');
+    }
+    if (review.architectStatus !== 'CLEAR') {
+        throw new UltragoalError('Final code-review must be clean: codeReview.architectStatus must be CLEAR; use record-review-blockers for WATCH or BLOCK.');
+    }
+    assertNonEmpty(review.evidence, 'codeReview.evidence');
+    return gate;
+}
 export async function startNextUltragoal(cwd, options = {}) {
     const plan = await readUltragoalPlan(cwd);
     const now = iso(options.now);
+    if (plan.aggregateCompletion?.status === 'complete')
+        return { plan, goal: null, resumed: false, done: true };
     const existing = plan.goals.find((goal) => goal.status === 'in_progress');
     if (existing) {
         await appendLedger(cwd, { ts: now, event: 'goal_resumed', goalId: existing.id, status: existing.status, message: 'Resuming active ultragoal' });
@@ -174,7 +317,7 @@ export async function startNextUltragoal(cwd, options = {}) {
             await appendLedger(cwd, { ts: now, event: 'goal_retried', goalId: next.id, status: 'pending', message: next.failureReason });
     }
     if (!next)
-        return { plan, goal: null, resumed: false, done: plan.goals.every((goal) => goal.status === 'complete') };
+        return { plan, goal: null, resumed: false, done: isUltragoalDone(plan) };
     next.status = 'in_progress';
     next.attempt += 1;
     next.startedAt = now;
@@ -224,21 +367,70 @@ export async function checkpointUltragoal(cwd, options) {
         });
         return plan;
     }
+    let aggregateCompletion;
     if (options.status === 'complete') {
         const expectedObjective = expectedCodexObjective(plan, goal);
         const aggregateMode = codexGoalMode(plan) === 'aggregate';
-        const finalAggregateCheckpoint = aggregateMode && isFinalAggregateCheckpoint(plan, goal);
-        const reconciliation = reconcileCodexGoalSnapshot(options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal), {
+        const finalRunCheckpoint = isFinalRunCompletionCandidate(plan, goal);
+        const snapshot = options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal);
+        const reconciliation = reconcileCodexGoalSnapshot(snapshot, {
             expectedObjective,
             allowedStatuses: aggregateMode
-                ? (finalAggregateCheckpoint ? ['complete'] : ['active'])
+                ? (finalRunCheckpoint && !options.allowActiveFinalCodexGoal ? ['complete'] : ['active'])
                 : ['complete'],
             requireSnapshot: true,
-            requireComplete: !aggregateMode || finalAggregateCheckpoint,
+            requireComplete: !aggregateMode || (finalRunCheckpoint && !options.allowActiveFinalCodexGoal),
         });
         if (!reconciliation.ok) {
-            throw new UltragoalError(formatCodexGoalReconciliation(reconciliation));
+            const completedTaskScopedAggregateSnapshot = snapshot?.available
+                && snapshot.status === 'complete'
+                && Boolean(snapshot.objective)
+                && 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,
+                };
+            }
+            else {
+                const taskScopedRequirement = aggregateMode && snapshot?.status === 'complete' && Boolean(snapshot.objective)
+                    ? ' Completed task-scoped aggregate reconciliation requires the checkpoint goal to be the active in-progress OMX goal, evidence that names that active OMX goal id, names .omx/ultragoal/goals.json or ledger.jsonl, includes completed implementation plus validation/review evidence, and a get_goal objective that maps to the ultragoal brief/artifact.'
+                    : '';
+                const remediation = reconciliation.snapshot.available
+                    && reconciliation.snapshot.status === 'complete'
+                    && Boolean(reconciliation.snapshot.objective)
+                    && normalizeObjective(reconciliation.snapshot.objective ?? '') !== normalizeObjective(expectedObjective)
+                    ? ` ${buildCompletedLegacyGoalRemediation(goal)}`
+                    : '';
+                throw new UltragoalError(`${formatCodexGoalReconciliation(reconciliation)}${taskScopedRequirement}${remediation}`);
+            }
         }
+        if (finalRunCheckpoint && !options.allowActiveFinalCodexGoal)
+            goal.evidence = options.evidence;
+    }
+    const qualityGate = options.status === 'complete' && (aggregateCompletion !== undefined || (isFinalRunCompletionCandidate(plan, goal) && !options.allowActiveFinalCodexGoal))
+        ? validateQualityGate(options.qualityGate)
+        : undefined;
+    if (aggregateCompletion) {
+        plan.aggregateCompletion = aggregateCompletion;
+        if (plan.activeGoalId === goal.id)
+            delete plan.activeGoalId;
+        plan.updatedAt = now;
+        await writePlan(cwd, plan);
+        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 via task-scoped Codex goal snapshot; microgoal ledger progress remains independent.',
+        });
+        return plan;
     }
     goal.status = options.status;
     goal.updatedAt = now;
@@ -265,9 +457,75 @@ export async function checkpointUltragoal(cwd, options) {
         status: goal.status,
         evidence: options.evidence,
         codexGoal: options.codexGoal,
+        qualityGate,
     });
     return plan;
 }
+export async function recordFinalReviewBlockers(cwd, options) {
+    const plan = await readUltragoalPlan(cwd);
+    const goal = plan.goals.find((candidate) => candidate.id === options.goalId);
+    if (!goal)
+        throw new UltragoalError(`Unknown ultragoal id: ${options.goalId}`);
+    assertNonEmpty(options.evidence, '--evidence');
+    if (goal.status !== 'in_progress') {
+        throw new UltragoalError(`Cannot record final review blockers for ${goal.id} while it is ${goal.status}; start or resume the ultragoal first.`);
+    }
+    if (!isFinalRunCompletionCandidate(plan, goal)) {
+        throw new UltragoalError(`Cannot record final review blockers for ${goal.id}; it is not the only unresolved ultragoal story.`);
+    }
+    const now = iso(options.now);
+    const expectedObjective = expectedCodexObjective(plan, goal);
+    const aggregateMode = codexGoalMode(plan) === 'aggregate';
+    const reconciliation = reconcileCodexGoalSnapshot(options.codexGoal === undefined ? null : parseCodexGoalSnapshot(options.codexGoal), {
+        expectedObjective,
+        allowedStatuses: ['active'],
+        requireSnapshot: true,
+        requireComplete: false,
+    });
+    if (!reconciliation.ok) {
+        throw new UltragoalError(formatCodexGoalReconciliation(reconciliation));
+    }
+    const addedGoal = appendGoalToPlan(plan, options, now);
+    goal.status = 'review_blocked';
+    goal.reviewBlockedAt = now;
+    goal.updatedAt = now;
+    goal.completedAt = undefined;
+    goal.failedAt = undefined;
+    goal.failureReason = undefined;
+    goal.evidence = options.evidence;
+    if (plan.activeGoalId === goal.id)
+        delete plan.activeGoalId;
+    plan.updatedAt = now;
+    await writePlan(cwd, plan);
+    await appendLedger(cwd, {
+        ts: now,
+        event: 'final_review_failed',
+        goalId: goal.id,
+        status: goal.status,
+        evidence: options.evidence,
+        codexGoal: options.codexGoal,
+        message: aggregateMode
+            ? 'Final aggregate code-review was not clean; blocker story was appended while Codex goal remains active.'
+            : 'Final per-story code-review was not clean; blocker story was appended and may require a fresh/available Codex goal context.',
+    });
+    await appendLedger(cwd, {
+        ts: now,
+        event: 'goal_added',
+        goalId: addedGoal.id,
+        status: addedGoal.status,
+        evidence: options.evidence,
+        message: addedGoal.title,
+    });
+    await appendLedger(cwd, {
+        ts: now,
+        event: 'goal_review_blocked',
+        goalId: goal.id,
+        status: goal.status,
+        evidence: options.evidence,
+        codexGoal: options.codexGoal,
+    });
+    return { plan, blockedGoal: goal, addedGoal };
+}
 export function buildCodexGoalInstruction(goal, plan) {
     if (codexGoalMode(plan) === 'aggregate')
         return buildAggregateCodexGoalInstruction(goal, plan);
@@ -278,6 +536,7 @@ function buildPerStoryCodexGoalInstruction(goal, plan) {
         objective: goal.objective,
         ...(goal.tokenBudget ? { token_budget: goal.tokenBudget } : {}),
     };
+    const finalStory = isFinalRunCompletionCandidate(plan, goal);
     return [
         'Ultragoal active-goal handoff',
         `Plan: ${plan.goalsPath}`,
@@ -290,8 +549,24 @@ function buildPerStoryCodexGoalInstruction(goal, plan) {
         '- If get_goal returns a different completed legacy/thread goal and create_goal rejects because this thread already has a completed goal, continue this ultragoal in a fresh Codex thread (same repo/worktree) and create the payload there.',
         `- To preserve the durable ledger before switching threads, record the non-terminal blocker without failing this goal: omx ultragoal checkpoint --goal-id ${goal.id} --status blocked --evidence "<completed legacy Codex goal blocks create_goal in this thread>" --codex-goal-json "<get_goal JSON or path>"`,
         '- Work only this goal until its completion audit passes.',
-        '- After the goal is actually complete, call update_goal({status: "complete"}), call get_goal again for a fresh completion snapshot, then checkpoint the ledger with:',
-        `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh get_goal JSON or path>"`,
+        finalStory
+            ? '- Final mandatory quality gate: run ai-slop-cleaner on changed files even when it is a no-op, rerun verification, then run $code-review.'
+            : '- This is not the final ultragoal story; do not run the final ai-slop-cleaner/$code-review gate yet.',
+        finalStory
+            ? '- If final $code-review is not APPROVE with architect status CLEAR, do not call update_goal. Record blockers with:'
+            : '- After the goal is actually complete, call update_goal({status: "complete"}), call get_goal again for a fresh completion snapshot, then checkpoint the ledger with:',
+        finalStory
+            ? `  omx ultragoal record-review-blockers --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`
+            : `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh get_goal JSON or path>"`,
+        finalStory
+            ? '- In legacy per-story mode, the blocker story may require a fresh/available Codex goal context because this story remains an active incomplete Codex goal; do not claim it is complete.'
+            : null,
+        finalStory
+            ? '- If final $code-review is clean (APPROVE + CLEAR), call update_goal({status: "complete"}), call get_goal again, then checkpoint with --quality-gate-json:'
+            : null,
+        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,
         '- If blocked or failed, checkpoint with --status failed and the failure evidence; rerun complete-goals --retry-failed to resume.',
         '',
         'create_goal payload:',
@@ -299,11 +574,11 @@ function buildPerStoryCodexGoalInstruction(goal, plan) {
         '',
         'Objective:',
         goal.objective,
-    ].join('\n');
+    ].filter((line) => line !== null).join('\n');
 }
 function buildAggregateCodexGoalInstruction(goal, plan) {
     const objective = plan.codexObjective ?? aggregateCodexObjective(plan.goals);
-    const finalStory = isFinalAggregateCheckpoint(plan, goal);
+    const finalStory = isFinalRunCompletionCandidate(plan, goal);
     const createPayload = { objective };
     const checkpointStatus = finalStory ? 'complete' : 'active';
     return [
@@ -318,10 +593,21 @@ function buildAggregateCodexGoalInstruction(goal, plan) {
         '- If get_goal reports the same aggregate objective as active, continue this OMX story without creating a new Codex goal.',
         '- 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.',
         finalStory
-            ? '- This is the final pending story: after the story and whole-run audit pass, call update_goal({status: "complete"}), then call get_goal again for a fresh complete snapshot.'
+            ? '- This is the final pending story: run the mandatory final ai-slop-cleaner pass, rerun verification, and run $code-review before any update_goal call.'
             : '- This is not the final story: do not call update_goal yet; the aggregate Codex goal must remain active while later OMX stories remain.',
+        finalStory
+            ? '- If final $code-review is not APPROVE with architect status CLEAR, do not call update_goal. Record durable blocker work first:'
+            : null,
+        finalStory
+            ? `  omx ultragoal record-review-blockers --goal-id ${goal.id} --title "Resolve final code-review blockers" --objective "<blocker-resolution objective>" --evidence "<review findings>" --codex-goal-json "<active get_goal JSON or path>"`
+            : null,
+        finalStory
+            ? '- If final $code-review is clean (APPROVE + CLEAR), call update_goal({status: "complete"}), call get_goal again for a fresh complete snapshot, then checkpoint with --quality-gate-json.'
+            : null,
         `- Checkpoint this OMX story with a fresh get_goal snapshot whose objective matches the aggregate payload and whose status is ${checkpointStatus}:`,
-        `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh get_goal JSON or path>"`,
+        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>"`
+            : `  omx ultragoal checkpoint --goal-id ${goal.id} --status complete --evidence "<tests/files/PR evidence>" --codex-goal-json "<fresh get_goal JSON or path>"`,
         '- If blocked or failed, checkpoint with --status failed and the failure evidence; rerun complete-goals --retry-failed to resume.',
         '',
         'create_goal payload:',
@@ -332,6 +618,6 @@ function buildAggregateCodexGoalInstruction(goal, plan) {
         '',
         'Current OMX story objective:',
         goal.objective,
-    ].join('\n');
+    ].filter((line) => line !== null).join('\n');
 }
 //# sourceMappingURL=artifacts.js.map