@hongmaple0820/scale-engine 0.48.0 → 0.50.1

package/dist/cli/phaseCommands.js

@@ -18,7 +18,12 @@ import { WorkflowArtifactWriter } from '../workflow/WorkflowArtifactWriter.js';
 import { resolveVerificationTargets } from '../workflow/VerificationProfile.js';
 import { EvidenceStore } from '../workflow/EvidenceStore.js';
 import { ReviewStore } from '../workflow/ReviewStore.js';
+import { JudgePromptStore, LlmJudge } from '../review/LlmJudge.js';
+import { JsonLlmClient } from '../review/JsonLlmClient.js';
+import { FreshContextVerifier } from '../review/FreshContextVerifier.js';
 import { TaskMetricsStore } from '../workflow/TaskMetricsStore.js';
+import { ReleaseDeploymentLedger } from '../workflow/ReleaseDeploymentLedger.js';
+import { recordRuntimeInstinctApplications } from '../cortex/InstinctApplicationRecorder.js';
 import { appendVerificationArtifact, checkTaskArtifactCompleteness, scaffoldTaskArtifacts } from '../workflow/TaskArtifactScaffolder.js';
 import { createWorkflowGuidance, renderWorkflowGuidance } from '../workflow/WorkflowGuidance.js';
 import { blockingWorkflowOpenTasks, removeWorkflowOpenTask } from '../workflow/WorkflowOpenTasks.js';
@@ -33,6 +38,8 @@ import { loadToolPolicy } from '../tools/ToolPolicy.js';
 import { runSafeCommand } from '../tools/SafeCommandRunner.js';
 import { join } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { computeSurfaceCoverage, formatSurfaceCoverageWarnings } from '../workflow/SurfaceCoverage.js';
+import { evaluateBoundaries, evaluateConstraints, formatBoundaryWarnings, formatConstraintWarnings, isEnforcedBoundaryProfile, countBoundaryBlockers, } from '../workflow/BoundaryEnforcement.js';
 import { HTMLDocumentRenderer } from '../output/HTMLDocumentRenderer.js';
 import { SCALE_ENGINE_VERSION } from '../version.js';
 import { optimizeCodingPrompt } from '../prompts/PromptOptimizer.js';
@@ -57,6 +64,7 @@ function validateReviewEvidence(ids) {
     const reviewStore = new ReviewStore(SCALE_DIR);
     const missing = [];
     const failed = [];
+    const records = [];
     for (const id of ids ?? []) {
         const record = reviewStore.getReview(id);
         if (!record) {
@@ -64,9 +72,14 @@ function validateReviewEvidence(ids) {
         }
         else if (!record.passed) {
             failed.push(id);
+            records.push(record);
+        }
+        else {
+            records.push(record);
         }
     }
-    return { ok: (ids?.length ?? 0) > 0 && missing.length === 0 && failed.length === 0, missing, failed };
+    const latest = records.sort((a, b) => b.createdAt - a.createdAt)[0];
+    return { ok: (ids?.length ?? 0) > 0 && missing.length === 0 && latest?.passed === true, missing, failed };
 }
 function getValidatedReviewRecords(ids) {
     const reviewStore = new ReviewStore(SCALE_DIR);
@@ -321,12 +334,56 @@ async function recordVerificationMetric(options) {
     metricsStore.writeMarkdownReport(PROJECT_DIR);
     return record;
 }
+async function recordShipDeployment(options) {
+    const version = optionalString(options.args['deploy-version']) ?? readPackageVersion(PROJECT_DIR);
+    const completedAt = optionalString(options.args['deployed-at']);
+    const commitTimestamp = await resolveCommitTimestamp(options.commitHash);
+    const notes = [
+        `task=${options.taskId}`,
+        options.taskTitle ? `title=${options.taskTitle}` : undefined,
+        options.taskPayload.verificationEvidenceIds?.length ? `verificationEvidence=${options.taskPayload.verificationEvidenceIds.join(',')}` : undefined,
+        options.taskPayload.reviewEvidenceIds?.length ? `reviewEvidence=${options.taskPayload.reviewEvidenceIds.join(',')}` : undefined,
+    ].filter((value) => Boolean(value)).join('; ');
+    return new ReleaseDeploymentLedger(SCALE_DIR).record({
+        service: optionalString(options.args['deploy-service']) ?? 'scale-engine',
+        environment: optionalString(options.args['deploy-environment']) ?? 'production',
+        status: 'succeeded',
+        version,
+        commitSha: options.commitHash,
+        commitTimestamp,
+        completedAt,
+        source: 'ship',
+        notes,
+    });
+}
+function optionalString(value) {
+    const normalized = typeof value === 'string' ? value.trim() : '';
+    return normalized ? normalized : undefined;
+}
+function readPackageVersion(projectDir) {
+    const pkgPath = join(projectDir, 'package.json');
+    if (!existsSync(pkgPath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+        return optionalString(pkg.version);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function resolveCommitTimestamp(commitHash) {
+    const result = await runGit(['show', '-s', '--format=%cI', commitHash]);
+    if (result.exitCode !== 0)
+        return undefined;
+    return optionalString(result.stdout);
+}
 // Helper: Generate spec markdown file
-function generateSpecMarkdown(id, title, payload) {
+function generateSpecMarkdown(id, title, payload, status = 'FROZEN') {
     return `# Spec: ${title}
 
 **ID**: ${id}
-**Status**: FROZEN
+**Status**: ${status}
 **Ambiguity Score**: ${payload.ambiguityScore ?? 0.15}
 
 ## What
@@ -343,11 +400,34 @@ ${payload.edgeCases.map(e => `- ${e}`).join('\n') || '(none defined)'}
 
 ## North Star
 ${payload.northStar || 'User value delivered'}
-
+${renderSpecContractSections(payload)}
 ---
 *Generated by SCALE Engine DEFINE phase*
 `;
 }
+// Helper: Render the optional P0 six-element contract sections.
+// Each section is omitted when its field is unset, keeping legacy specs unchanged.
+function renderSpecContractSections(payload) {
+    const sections = [];
+    if (payload.verificationSurface?.length) {
+        sections.push(`\n## Verification Surface\n${payload.verificationSurface.map(s => `- ${s}`).join('\n')}`);
+    }
+    if (payload.constraints?.length) {
+        sections.push(`\n## Constraints\n${payload.constraints.map(c => `- ${c}`).join('\n')}`);
+    }
+    if (payload.boundaries) {
+        const b = payload.boundaries;
+        const line = (label, items) => `- ${label}: ${items.length ? items.join(', ') : '(none)'}`;
+        sections.push(`\n## Boundaries\n${line('Files', b.files)}\n${line('Tools', b.tools)}\n${line('Forbidden', b.forbidden)}`);
+    }
+    if (payload.iterationStrategy) {
+        sections.push(`\n## Iteration Strategy\n${payload.iterationStrategy}`);
+    }
+    if (payload.blockedStopCondition) {
+        sections.push(`\n## Blocked Stop Condition\n${payload.blockedStopCondition}`);
+    }
+    return sections.length ? `\n${sections.join('\n')}\n` : '\n';
+}
 // Helper: Calculate ambiguity score
 function calculateAmbiguityScore(description, successCriteria) {
     let score = 0.2; // Base score (maximum threshold)
@@ -364,9 +444,20 @@ function calculateAmbiguityScore(description, successCriteria) {
 export const phaseDefine = defineCommand({
     meta: { name: 'define', description: 'DEFINE: Create Spec with AmbiguityScorer + SocraticQuestioner (/spec)' },
     args: {
-        title: { type: 'positional', required: true },
+        title: { type: 'positional', required: false },
         description: { type: 'string', alias: 'd' },
         'success-criteria': { type: 'string', alias: 'c', description: 'Comma-separated criteria' },
+        // P0 draft/confirm two-step lifecycle (backward compatible: bare `define` still auto-freezes)
+        draft: { type: 'boolean', default: false, description: 'Stop the new Spec at REVIEWING (requires `define --confirm <id>` to FROZEN)' },
+        confirm: { type: 'string', description: 'Confirm and freeze an existing draft Spec id (REVIEWING -> FROZEN)' },
+        // P0 six-element contract inputs (optional, comma-separated where plural)
+        'verification-surface': { type: 'string', description: 'Comma-separated evidence sources: test names / benchmark commands / artifact paths' },
+        'constraints': { type: 'string', description: 'Comma-separated invariants that must not regress (perf/security/compat)' },
+        'boundary-files': { type: 'string', description: 'Comma-separated files allowed to change' },
+        'boundary-tools': { type: 'string', description: 'Comma-separated tools allowed to use' },
+        'boundary-forbidden': { type: 'string', description: 'Comma-separated scope that must not be touched' },
+        'iteration-strategy': { type: 'string', description: 'How each build iteration decides the next step' },
+        'blocked-stop': { type: 'string', description: 'What to report / what is needed to unblock when no path is viable' },
         // Socratic refinement answers (optional)
         'goal': { type: 'string', description: 'Goal answer for Socratic refinement' },
         'constraint': { type: 'string', description: 'Constraint answer for Socratic refinement' },
@@ -380,6 +471,15 @@ export const phaseDefine = defineCommand({
     },
     async run({ args }) {
         const { store, fsm, workflowEngine } = getEngine();
+        // P0: --confirm freezes an existing draft Spec (REVIEWING -> FROZEN) without re-creating it.
+        if (args.confirm) {
+            await confirmDraftSpec(store, fsm, String(args.confirm), Boolean(args.json));
+            return;
+        }
+        if (!args.title) {
+            console.error('\nMissing required argument: title (or pass --confirm <spec-id> to freeze a draft)\n');
+            process.exit(1);
+        }
         const rawDesc = String(args.description ?? args.title);
         // Parse success criteria
         const successCriteria = args['success-criteria']
@@ -467,6 +567,17 @@ export const phaseDefine = defineCommand({
             initialStatus: 'DRAFT',
             createdBy: { kind: 'human', userId: 'cli' },
         });
+        // P0 six-element contract inputs (optional; omitted fields stay undefined)
+        const csv = (v) => {
+            const items = typeof v === 'string' ? v.split(',').map(s => s.trim()).filter(Boolean) : [];
+            return items.length ? items : undefined;
+        };
+        const boundaryFiles = csv(args['boundary-files']);
+        const boundaryTools = csv(args['boundary-tools']);
+        const boundaryForbidden = csv(args['boundary-forbidden']);
+        const boundaries = (boundaryFiles || boundaryTools || boundaryForbidden)
+            ? { files: boundaryFiles ?? [], tools: boundaryTools ?? [], forbidden: boundaryForbidden ?? [] }
+            : undefined;
         // Create Spec artifact with proper payload (use refined requirement if available)
         const specPayload = {
             what: refinedRequirement,
@@ -475,6 +586,11 @@ export const phaseDefine = defineCommand({
             edgeCases: [],
             northStar: 'Deliver user value',
             ambiguityScore,
+            verificationSurface: csv(args['verification-surface']),
+            constraints: csv(args['constraints']),
+            boundaries,
+            iterationStrategy: typeof args['iteration-strategy'] === 'string' && args['iteration-strategy'] ? String(args['iteration-strategy']) : undefined,
+            blockedStopCondition: typeof args['blocked-stop'] === 'string' && args['blocked-stop'] ? String(args['blocked-stop']) : undefined,
         };
         const spec = await store.create({
             type: 'Spec', title: args.title,
@@ -483,11 +599,14 @@ export const phaseDefine = defineCommand({
             initialStatus: 'DRAFT',
             createdBy: { kind: 'human', userId: 'cli' },
         });
+        // Draft mode stops at REVIEWING; default mode auto-freezes (FROZEN).
+        const isDraft = Boolean(args.draft);
+        const finalStatus = isDraft ? 'REVIEWING' : 'FROZEN';
         // Generate spec markdown file
         const specsDir = join(SCALE_DIR, 'specs');
         ensureDir(specsDir);
         const specPath = join(specsDir, `${spec.id}.md`);
-        writeFileSync(specPath, generateSpecMarkdown(spec.id, args.title, specPayload));
+        writeFileSync(specPath, generateSpecMarkdown(spec.id, args.title, specPayload, finalStatus));
         // Generate spec HTML file (default format: html)
         const outputFormat = args.format ?? 'md';
         let specHtmlPath;
@@ -496,7 +615,7 @@ export const phaseDefine = defineCommand({
                 title: args.title,
                 brand: args.brand,
                 version: SCALE_ENGINE_VERSION,
-                status: 'FROZEN',
+                status: finalStatus,
             });
             const html = renderer.renderSpec({
                 id: spec.id,
@@ -507,11 +626,16 @@ export const phaseDefine = defineCommand({
                 edgeCases: specPayload.edgeCases,
                 northStar: specPayload.northStar,
                 ambiguityScore,
+                verificationSurface: specPayload.verificationSurface,
+                constraints: specPayload.constraints,
+                boundaries: specPayload.boundaries,
+                iterationStrategy: specPayload.iterationStrategy,
+                blockedStopCondition: specPayload.blockedStopCondition,
             });
             specHtmlPath = join(specsDir, `${spec.id}.html`);
             renderer.writeToFile(html, specHtmlPath);
         }
-        // FSM transitions: DRAFT -> REVIEWING -> FROZEN
+        // FSM transitions: DRAFT -> REVIEWING (-> FROZEN unless --draft)
         // Phase 1: refine (DRAFT -> REVIEWING) - no guards
         const refineResult = await fsm.canTransition(spec.id, 'refine');
         if (!refineResult.allowed) {
@@ -522,22 +646,30 @@ export const phaseDefine = defineCommand({
             process.exit(1);
         }
         await fsm.transition(spec.id, 'refine', { actor: { kind: 'system', component: 'phase-define' } });
-        // Phase 2: approve (REVIEWING -> FROZEN) - guards: ambiguityScore <= 0.2, has successCriteria
-        const approveResult = await fsm.canTransition(spec.id, 'approve');
-        if (!approveResult.allowed) {
+        // Phase 2: approve (REVIEWING -> FROZEN) - guards: ambiguityScore <= 0.2, has successCriteria.
+        // Skipped in --draft mode: the draft waits for `scale define --confirm <id>`.
+        if (!isDraft) {
+            const approveResult = await fsm.canTransition(spec.id, 'approve');
+            if (!approveResult.allowed) {
+                if (!args.json) {
+                    console.error('\nFSM transition blocked: REVIEWING -> FROZEN');
+                    console.error('   Spec cannot be frozen due to:');
+                    approveResult.blockedBy?.forEach(b => console.error(`   [GUARD] ${b.guard}: ${b.message}`));
+                    console.error('\n   Resolve issues before proceeding.');
+                }
+                process.exit(1);
+            }
+            await fsm.transition(spec.id, 'approve', { actor: { kind: 'system', component: 'phase-define' } });
             if (!args.json) {
-                console.error('\nFSM transition blocked: REVIEWING -> FROZEN');
-                console.error('   Spec cannot be frozen due to:');
-                approveResult.blockedBy?.forEach(b => console.error(`   [GUARD] ${b.guard}: ${b.message}`));
-                console.error('\n   Resolve issues before proceeding.');
+                console.log('   FSM: DRAFT -> REVIEWING -> FROZEN ✓');
             }
-            process.exit(1);
         }
-        await fsm.transition(spec.id, 'approve', { actor: { kind: 'system', component: 'phase-define' } });
-        if (!args.json) {
-            console.log('   FSM: DRAFT -> REVIEWING -> FROZEN ✓');
+        else if (!args.json) {
+            console.log('   FSM: DRAFT -> REVIEWING (draft; not yet FROZEN)');
         }
-        const result = { phase: 'DEFINE', spec, specPath, specHtmlPath, ambiguityScore, successCriteria, format: outputFormat, promptOptimization };
+        // Refresh the spec so the reported status reflects the post-transition state.
+        const finalSpec = (await store.get(spec.id)) ?? spec;
+        const result = { phase: 'DEFINE', spec: finalSpec, specPath, specHtmlPath, ambiguityScore, successCriteria, format: outputFormat, promptOptimization, status: finalStatus, draft: isDraft };
         // Write explore artifact for Gate G1 verification
         const artifactWriter = new WorkflowArtifactWriter(SCALE_DIR);
         artifactWriter.writeExploreResult({
@@ -557,10 +689,94 @@ export const phaseDefine = defineCommand({
                 console.log(`   HTML file: ${specHtmlPath}`);
             console.log(`   Ambiguity score: ${ambiguityScore.toFixed(2)}`);
             console.log(`   Success criteria: ${successCriteria.length}`);
-            console.log(`\n   Next: scale plan ${spec.id}\n`);
+            if (isDraft) {
+                console.log(`\n   Draft created (REVIEWING). Review, then confirm:`);
+                console.log(`   Next: scale define --confirm ${spec.id}\n`);
+            }
+            else {
+                console.log(`\n   Next: scale plan ${spec.id}\n`);
+            }
         }
     },
 });
+// Helper: Confirm a draft Spec (REVIEWING -> FROZEN) for the `define --confirm <id>` flow.
+async function confirmDraftSpec(store, fsm, specId, json) {
+    const spec = await store.get(specId);
+    if (!spec || spec.type !== 'Spec') {
+        console.error(`\nSpec not found: ${specId}\n`);
+        process.exit(1);
+    }
+    if (spec.status === 'FROZEN') {
+        if (!json)
+            console.log(`\nSpec ${specId} is already FROZEN.\n`);
+        else
+            console.log(JSON.stringify({ phase: 'DEFINE', confirm: true, spec, status: 'FROZEN', alreadyFrozen: true }, null, 2));
+        return;
+    }
+    const approveResult = await fsm.canTransition(specId, 'approve');
+    if (!approveResult.allowed) {
+        if (!json) {
+            console.error('\nFSM transition blocked: REVIEWING -> FROZEN');
+            console.error('   Spec cannot be confirmed due to:');
+            approveResult.blockedBy?.forEach(b => console.error(`   [GUARD] ${b.guard}: ${b.message}`));
+            console.error('\n   Resolve issues before confirming.');
+        }
+        process.exit(1);
+    }
+    await fsm.transition(specId, 'approve', { actor: { kind: 'human', userId: 'cli' } });
+    // Refresh persisted markdown status (draft was written as REVIEWING).
+    const specPath = join(SCALE_DIR, 'specs', `${specId}.md`);
+    if (existsSync(specPath)) {
+        writeFileSync(specPath, generateSpecMarkdown(specId, spec.title, spec.payload, 'FROZEN'));
+    }
+    const confirmed = await store.get(specId);
+    if (json) {
+        console.log(JSON.stringify({ phase: 'DEFINE', confirm: true, spec: confirmed, status: 'FROZEN' }, null, 2));
+    }
+    else {
+        console.log(`\nCONFIRM: ${specId}`);
+        console.log('   FSM: REVIEWING -> FROZEN ✓');
+        console.log(`\n   Next: scale plan ${specId}\n`);
+    }
+}
+// Helper: Resolve the originating Spec for a Task by walking Task -> Plan -> Spec.
+async function resolveSpecForTask(store, task) {
+    const planId = task?.parents?.[0];
+    if (!planId)
+        return undefined;
+    const plan = await store.get(planId);
+    const specId = plan?.parents?.[0];
+    if (!specId)
+        return undefined;
+    const spec = await store.get(specId);
+    if (!spec || spec.type !== 'Spec')
+        return undefined;
+    return { id: spec.id, payload: spec.payload };
+}
+// Helper: Collect free-form evidence signals (commands run, files, evidence refs/artifacts)
+// used to soft-map a Spec's verificationSurface during verify/ship (P0 Decision C1).
+async function gatherVerificationSignals(store, options) {
+    const signals = [];
+    for (const command of options.commands ?? [])
+        if (command)
+            signals.push(command);
+    for (const file of options.files ?? [])
+        if (file)
+            signals.push(file);
+    for (const id of options.evidenceIds ?? []) {
+        const record = await store.get(id);
+        if (!record || record.type !== 'Evidence')
+            continue;
+        const payload = record.payload;
+        if (payload.verificationSurfaceRef)
+            signals.push(payload.verificationSurfaceRef);
+        if (payload.toolUsed)
+            signals.push(payload.toolUsed);
+        if (payload.artifacts?.length)
+            signals.push(...payload.artifacts);
+    }
+    return signals;
+}
 // Helper: Generate plan markdown file
 function generatePlanMarkdown(id, specId, payload) {
     return `# Plan: ${id}
@@ -906,10 +1122,15 @@ export const phaseVerify = defineCommand({
         'skip-build': { type: 'boolean', default: false },
         'skip-lint': { type: 'boolean', default: false },
         'skip-test': { type: 'boolean', default: false },
+        progress: { type: 'boolean', default: false, description: 'Emit coarse verify progress events to stderr without changing JSON output' },
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
         const { store, fsm, workflowEngine } = getEngine();
+        const emitProgress = (event, detail) => {
+            if (isTruthyFlag(args.progress))
+                console.error(`[progress] ${event}: ${detail}`);
+        };
         // Validate task exists
         const task = await store.get(args['task-id']);
         if (!task || task.type !== 'Task') {
@@ -932,6 +1153,7 @@ export const phaseVerify = defineCommand({
             service: args.service,
             services: args.service ? undefined : taskServices,
         });
+        emitProgress('verify:start', `task=${args['task-id']} profile=${resolvedVerification.profileName} targets=${resolvedVerification.targets.length}`);
         if (!args.json) {
             for (const warning of resolvedVerification.warnings)
                 console.log(`   [WARN] ${warning}`);
@@ -947,6 +1169,7 @@ export const phaseVerify = defineCommand({
             if (!args.json && resolvedVerification.targets.length > 1) {
                 console.log(`\n   Target: ${target.service?.name ?? 'root'}`);
             }
+            emitProgress('target:start', target.service?.name ?? 'root');
             const targetResults = await workflowEngine.verify({
                 cwd: target.config.cwd,
                 build: args['build-cmd'] ?? target.config.build,
@@ -964,7 +1187,9 @@ export const phaseVerify = defineCommand({
                 tddStrict: isTruthyFlag(args['tdd-strict']),
             });
             gateResults.push(...targetResults);
+            emitProgress('target:done', `${target.service?.name ?? 'root'} gates=${targetResults.length}`);
         }
+        emitProgress('verify:gates-complete', `gates=${gateResults.length}`);
         // Step 2: Display gate results
         if (!args.json) {
             console.log('\nGate Results:');
@@ -1095,6 +1320,16 @@ export const phaseVerify = defineCommand({
         });
         const workflowOpenTaskBlockers = blockingWorkflowOpenTasks(workflowState.openTasks, args['task-id']);
         const workflowOpenTasksBlocked = workflowOpenTaskBlockers.length > 0;
+        // P0+ (decision E1): resolve the originating Spec up-front so the executional
+        // boundary / constraint checks can gate Task completion. Both reports are
+        // advisory under default/auto and blocking under full/ci/strict; the
+        // detection logic is identical, only the report mode and gating differ.
+        const spec = await resolveSpecForTask(store, task);
+        const boundaryEnforced = isEnforcedBoundaryProfile(resolvedVerification.profileName);
+        const boundaryEnforcement = evaluateBoundaries(taskFiles, spec?.payload.boundaries, boundaryEnforced);
+        const constraintCoverage = evaluateConstraints(spec?.payload.constraints, spec?.payload.verificationSurface, boundaryEnforced);
+        const boundaryBlocked = boundaryEnforced &&
+            countBoundaryBlockers(boundaryEnforcement, constraintCoverage) > 0;
         // Attempt FSM transition to COMPLETED
         // Guards: build_passed, lint_passed, tests_passed, open workflow tasks, and optional artifact policy.
         const codePassed = results.buildStatus === 'success' &&
@@ -1109,9 +1344,15 @@ export const phaseVerify = defineCommand({
             !skillInstallationBlocked &&
             !engineeringStandards.blocked &&
             !(toolEvidenceGate?.blocked ?? false) &&
+            !boundaryBlocked &&
             !workflowOpenTasksBlocked;
         let transitionResult = null;
-        if (completionEligible) {
+        const alreadyCompleted = task.status === 'COMPLETED';
+        if (completionEligible && alreadyCompleted) {
+            if (!args.json)
+                console.log('\n   FSM: already COMPLETED');
+        }
+        else if (completionEligible) {
             const completeResult = await fsm.canTransition(args['task-id'], 'complete');
             if (!completeResult.allowed) {
                 if (!args.json) {
@@ -1147,10 +1388,13 @@ export const phaseVerify = defineCommand({
         else if (!args.json && toolEvidenceGate?.blocked) {
             console.log('\n   Tool evidence gate blocked completion - required tools need passed execution evidence');
         }
+        else if (!args.json && boundaryBlocked) {
+            console.log('\n   Boundary enforcement blocked completion - keep edits inside Spec boundaries and guard every constraint (enforced profile)');
+        }
         else if (!args.json && workflowOpenTasksBlocked) {
             console.log('\n   Workflow open tasks blocked completion - finish required workflow commands first');
         }
-        const passed = completionEligible && (transitionResult?.success ?? false);
+        const passed = completionEligible && (alreadyCompleted || (transitionResult?.success ?? false));
         if (passed) {
             workflowState = workflowWriter.updateCurrentState({
                 openTasks: removeWorkflowOpenTask(workflowState.openTasks, 'verification'),
@@ -1203,7 +1447,7 @@ export const phaseVerify = defineCommand({
             toolEvidenceGatePassed: finalToolEvidenceGate ? !finalToolEvidenceGate.blocked : true,
         };
         await store.update(args['task-id'], { payload: finalPayload });
-        const metricGateStatus = (finalArtifactGate.blocked || finalSkillGate?.blocked || skillInstallationBlocked || engineeringStandards.blocked || finalToolEvidenceGate?.blocked || workflowOpenTasksBlocked)
+        const metricGateStatus = (finalArtifactGate.blocked || finalSkillGate?.blocked || skillInstallationBlocked || engineeringStandards.blocked || finalToolEvidenceGate?.blocked || boundaryBlocked || workflowOpenTasksBlocked)
             ? 'blocked'
             : undefined;
         const metricRecord = await recordVerificationMetric({
@@ -1215,6 +1459,30 @@ export const phaseVerify = defineCommand({
             artifactCheck,
             finalGateStatus: metricGateStatus,
         });
+        const cortexInstinctApplications = recordRuntimeInstinctApplications({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            phase: 'verify',
+            success: passed,
+        });
+        // P0 (Decision C1): soft-map the Spec's verificationSurface against evidence.
+        // Unmapped items are reported as warnings only — never blocking in P0.
+        // (`spec`, `boundaryEnforcement` and `constraintCoverage` were resolved
+        // above so the boundary checks could gate completion under enforced profiles.)
+        const verificationCommands = resolvedVerification.targets.flatMap(target => [
+            target.config.build, target.config.lint, target.config.test, target.config.coverage,
+        ]);
+        const surfaceSignals = await gatherVerificationSignals(store, {
+            evidenceIds: verificationEvidenceIds,
+            commands: [
+                ...verificationCommands,
+                args['build-cmd'], args['lint-cmd'], args['test-cmd'], args['coverage-cmd'],
+            ],
+            files: taskFiles,
+        });
+        const surfaceCoverage = spec?.payload.verificationSurface?.length
+            ? computeSurfaceCoverage(spec.payload.verificationSurface, surfaceSignals)
+            : undefined;
         const result = {
             phase: 'VERIFY',
             taskId: args['task-id'],
@@ -1240,14 +1508,29 @@ export const phaseVerify = defineCommand({
                 blocked: skillInstallationBlocked,
             },
             metric: metricRecord,
+            cortexInstinctApplications,
+            verificationSurfaceCoverage: surfaceCoverage,
+            boundaryEnforcement,
+            constraintCoverage,
             passed
         };
         if (args.json)
             console.log(JSON.stringify(result, null, 2));
         else {
             console.log(`\nVERIFY: ${passed ? 'PASSED' : 'FAILED'}`);
+            if (surfaceCoverage) {
+                for (const line of formatSurfaceCoverageWarnings(surfaceCoverage))
+                    console.log(`   ${line}`);
+            }
+            for (const line of formatBoundaryWarnings(boundaryEnforcement))
+                console.log(`   ${line}`);
+            for (const line of formatConstraintWarnings(constraintCoverage))
+                console.log(`   ${line}`);
             if (metricRecord)
                 console.log(`   Metrics: ${metricRecord.taskId} ${metricRecord.finalGateStatus} (fix iterations: ${metricRecord.fixIterations})`);
+            if (cortexInstinctApplications.recorded.length > 0) {
+                console.log(`   Cortex instincts: ${cortexInstinctApplications.recorded.length} outcome(s) recorded`);
+            }
             if (artifactCheck && !artifactCheck.complete) {
                 console.log(`   Artifact gaps: ${artifactCheck.missing.length} missing, ${artifactCheck.incomplete.length} incomplete`);
             }
@@ -1309,7 +1592,13 @@ function readUntrackedFileAsDiff(path) {
         return '';
     }
 }
-async function reviewGitChanges(taskPayload) {
+function normalizeMaxDiffFiles(value) {
+    const parsed = Number.parseInt(String(value ?? ''), 10);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return 200;
+    return Math.min(parsed, 1000);
+}
+async function reviewGitChanges(taskPayload, maxDiffFiles = 200) {
     const status = await runGit(['status', '--short']);
     const untracked = await runGit(['ls-files', '--others', '--exclude-standard']);
     let statusOutput = mergeUntrackedFilesIntoStatus(status.stdout, untracked.stdout);
@@ -1332,7 +1621,7 @@ async function reviewGitChanges(taskPayload) {
     const verificationEvidence = getVerificationEvidenceSummary(taskPayload?.verificationEvidenceIds);
     const changedFiles = analyzeReview({ statusOutput, diffs: [], taskPayload, verificationEvidence }).changedFiles;
     const diffs = [];
-    for (const file of changedFiles.slice(0, 50)) {
+    for (const file of changedFiles.slice(0, maxDiffFiles)) {
         if (file.status === '??') {
             diffs.push({ file: file.path, text: readUntrackedFileAsDiff(file.path) });
         }
@@ -1341,7 +1630,23 @@ async function reviewGitChanges(taskPayload) {
             diffs.push({ file: file.path, text: diff.stdout });
         }
     }
-    return analyzeReview({ statusOutput, diffs, taskPayload, verificationEvidence });
+    return { ...analyzeReview({ statusOutput, diffs, taskPayload, verificationEvidence }), diffs };
+}
+function normalizeReviewMode(value) {
+    return value === 'fresh-subagent' || value === 'hybrid' ? value : 'ai-self';
+}
+// Build a compact diff summary (file headers + added lines) for the advisory
+// LLM-as-Judge (P1.4). Capped so it never blows the model/context budget.
+function buildJudgeDiffSummary(diffs) {
+    const parts = [];
+    for (const diff of diffs) {
+        const added = diff.text
+            .split('\n')
+            .filter(line => line.startsWith('+') && !line.startsWith('+++'))
+            .map(line => line.slice(1));
+        parts.push(`# ${diff.file}\n${added.join('\n')}`);
+    }
+    return parts.join('\n\n').slice(0, 6000);
 }
 function collectReviewedFiles(records) {
     const reviewed = new Set();
@@ -1553,6 +1858,9 @@ export const phaseReview = defineCommand({
         'check-style': { type: 'boolean', default: true },
         format: { type: 'string', alias: 'f', description: 'Output format: html or md (default: html)' },
         brand: { type: 'string', description: 'Brand theme for HTML output (vercel/stripe/notion/linear/github)' },
+        judge: { type: 'boolean', default: true, description: 'Run the advisory LLM-as-Judge spec-conformance check (P1.4)' },
+        mode: { type: 'string', default: 'ai-self', description: 'Review mode: ai-self (default) | fresh-subagent | hybrid (P2.2)' },
+        'max-diff-files': { type: 'string', default: '200', description: 'Maximum changed files whose diffs are scanned during deterministic review' },
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
@@ -1569,7 +1877,7 @@ export const phaseReview = defineCommand({
             }
             taskPayload = task.payload;
         }
-        const review = await reviewGitChanges(taskPayload);
+        const review = await reviewGitChanges(taskPayload, normalizeMaxDiffFiles(args['max-diff-files']));
         const karpathyContext = deriveReviewKarpathyContext(review, taskPayload);
         const karpathyResult = workflowEngine.checkKarpathy(karpathyContext);
         const karpathyReport = {
@@ -1586,12 +1894,44 @@ export const phaseReview = defineCommand({
         const findings = review.findings;
         const summary = summarizeFindings(findings);
         const passed = summary.critical === 0 && summary.high === 0;
+        const reviewMode = normalizeReviewMode(args.mode);
+        // Resolve the originating Spec once; both the advisory judge (P1.4) and the
+        // fresh-context verifier (P2.2) read its outcome / verificationSurface.
+        const needsSpec = args.judge || reviewMode !== 'ai-self';
+        const spec = needsSpec ? await resolveSpecForTask(store, task) : undefined;
+        const diffSummary = needsSpec ? buildJudgeDiffSummary(review.diffs) : '';
+        // P1.4 (decision K1): advisory LLM-as-Judge. Never part of `passed`.
+        let judgeVerdict;
+        if (args.judge) {
+            const judge = new LlmJudge(new JsonLlmClient(), new JudgePromptStore(SCALE_DIR));
+            judgeVerdict = await judge.judge({
+                outcome: spec?.payload.what,
+                verificationSurface: spec?.payload.verificationSurface ?? [],
+                diffSummary,
+                reviewFindings: summary,
+            });
+        }
+        // P2.2 (decisions M1/N1/O1): fresh-context verifier runs only for
+        // fresh-subagent / hybrid modes, on isolated input (surface + diff + gate
+        // summary, no build-agent history). Advisory only — never blocks ship.
+        let freshVerifyVerdict;
+        if (reviewMode !== 'ai-self') {
+            freshVerifyVerdict = await new FreshContextVerifier(new JsonLlmClient()).verify({
+                outcome: spec?.payload.what,
+                verificationSurface: spec?.payload.verificationSurface ?? [],
+                diffSummary,
+                gateSummary: `critical=${summary.critical} high=${summary.high} medium=${summary.medium} low=${summary.low}`,
+            });
+        }
         const record = reviewStore.saveReview({
             taskId: args['task-id'],
             passed,
             findings,
             changedFiles: review.changedFiles.map(file => normalizeGitPath(file.path)),
             summary,
+            judge: judgeVerdict,
+            reviewMode,
+            freshVerify: freshVerifyVerdict,
         });
         if (task && taskPayload) {
             const updatedPayload = {
@@ -1638,6 +1978,9 @@ export const phaseReview = defineCommand({
             findings,
             changedFiles: review.changedFiles.map(file => normalizeGitPath(file.path)),
             summary,
+            judge: judgeVerdict,
+            reviewMode,
+            freshVerify: freshVerifyVerdict,
             karpathy: karpathyReport,
             passed,
             format: reviewOutputFormat,
@@ -1660,6 +2003,18 @@ export const phaseReview = defineCommand({
             console.log(`LOW:      ${summary.low} issues`);
             console.log('----------------------------------------');
             findings.slice(0, 10).forEach(f => console.log(`  [${f.severity}] ${f.file ? `${f.file}: ` : ''}${f.description}`));
+            if (judgeVerdict) {
+                console.log(`\nJudge (advisory, ${judgeVerdict.modelUsed}): ${judgeVerdict.decision.toUpperCase()} (confidence ${judgeVerdict.confidence.toFixed(2)})`);
+                console.log(`  ${judgeVerdict.rationale}`);
+                if (judgeVerdict.unmetSurfaces.length)
+                    console.log(`  Unmet surfaces: ${judgeVerdict.unmetSurfaces.join('; ')}`);
+            }
+            if (freshVerifyVerdict) {
+                console.log(`\nFresh-context verifier (advisory, ${freshVerifyVerdict.modelUsed}): ${freshVerifyVerdict.decision.toUpperCase()} (confidence ${freshVerifyVerdict.confidence.toFixed(2)})`);
+                console.log(`  ${freshVerifyVerdict.rationale}`);
+                if (freshVerifyVerdict.unmetSurfaces.length)
+                    console.log(`  Unmet surfaces: ${freshVerifyVerdict.unmetSurfaces.join('; ')}`);
+            }
             if (passed) {
                 console.log('\nReview passed (no CRITICAL issues)');
                 console.log('\n   Next: scale ship ' + (args['task-id'] ?? '<task-id>') + '\n');
@@ -1679,6 +2034,11 @@ export const phaseShip = defineCommand({
         message: { type: 'string', alias: 'm', description: 'Commit message' },
         'no-commit': { type: 'boolean', default: false, description: 'Skip git commit' },
         'skip-commit': { type: 'boolean', default: false, description: 'Skip git commit' },
+        'record-deployment': { type: 'boolean', default: false, description: 'Record a deployment event after a successful ship commit' },
+        'deploy-service': { type: 'string', default: 'scale-engine', description: 'Deployment service name' },
+        'deploy-environment': { type: 'string', default: 'production', description: 'Deployment environment name' },
+        'deploy-version': { type: 'string', description: 'Deployment version override' },
+        'deployed-at': { type: 'string', description: 'Deployment completion timestamp override' },
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
@@ -1755,10 +2115,12 @@ export const phaseShip = defineCommand({
             process.exit(1);
         }
         // Git operations
+        const skipCommit = shouldSkipCommit(args['skip-commit']);
         let commitHash = null;
         let stagedFiles = [];
         let workspaceBoundary = null;
-        if (!shouldSkipCommit(args['skip-commit'])) {
+        let deploymentRecord = null;
+        if (!skipCommit) {
             const commitMessage = args.message ?? `feat: ${task.title ?? args['task-id']}`;
             try {
                 workspaceBoundary = await validateWorkspaceShipBoundary();
@@ -1789,7 +2151,11 @@ export const phaseShip = defineCommand({
                     }
                 }
                 else {
-                    commitHash = result.stdout.split('\n')[0]; // First line contains hash
+                    const head = await runGit(['rev-parse', 'HEAD']);
+                    if (head.exitCode !== 0 || !head.stdout.trim()) {
+                        throw new Error(head.stderr || 'git rev-parse HEAD failed after commit');
+                    }
+                    commitHash = head.stdout.trim();
                 }
             }
             catch (e) {
@@ -1802,12 +2168,64 @@ export const phaseShip = defineCommand({
         if (task.parents.length > 0) {
             const planId = task.parents[0];
             try {
-                await fsm.transition(planId, 'complete', { actor: { kind: 'system', component: 'phase-ship' } });
+                const plan = await store.get(planId);
+                if (plan?.status !== 'DONE') {
+                    await fsm.transition(planId, 'complete', { actor: { kind: 'system', component: 'phase-ship' } });
+                }
             }
             catch (e) {
                 console.error("Warning: Plan completion transition failed:", e.message);
             }
         }
+        // P0 (Decision C1): soft-map the Spec's verificationSurface at ship time too.
+        const shipSpec = await resolveSpecForTask(store, task);
+        const shipSignals = await gatherVerificationSignals(store, {
+            evidenceIds: payload.verificationEvidenceIds,
+            files: payload.filesInvolved,
+        });
+        const shipSurfaceCoverage = shipSpec?.payload.verificationSurface?.length
+            ? computeSurfaceCoverage(shipSpec.payload.verificationSurface, shipSignals)
+            : undefined;
+        if (isTruthyFlag(args['record-deployment'])) {
+            if (!commitHash) {
+                process.stderr.write('\nDeployment recording requires a new ship commit. Re-run without --no-commit/--skip-commit, or record a real deployment explicitly with scale workflow deploy record.\n\n');
+                process.exit(1);
+            }
+            try {
+                deploymentRecord = await recordShipDeployment({
+                    taskId: args['task-id'],
+                    taskTitle: task.title,
+                    taskPayload: payload,
+                    commitHash,
+                    args,
+                });
+            }
+            catch (error) {
+                process.stderr.write(`\nDeployment record failed: ${error.message}\n`);
+                process.exit(1);
+            }
+        }
+        const cortexInstinctApplications = recordRuntimeInstinctApplications({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            phase: 'ship',
+            success: true,
+        });
+        const shippedAt = Date.now();
+        const shipMode = skipCommit
+            ? 'no-commit'
+            : commitHash
+                ? 'commit'
+                : 'commit-skipped';
+        const shippedPayload = {
+            ...payload,
+            shipPassed: true,
+            shippedAt,
+            shipMode,
+            shipCommitHash: commitHash ?? undefined,
+            shipDeploymentRecordId: deploymentRecord?.id,
+        };
+        await store.update(task.id, { payload: shippedPayload });
         // === WorkflowEngine Integration ===
         // Generate HonestDelivery report
         if (!args.json) {
@@ -1818,6 +2236,11 @@ export const phaseShip = defineCommand({
             console.log(`  - Status: COMPLETED`);
             if (commitHash)
                 console.log(`  - Commit: ${commitHash}`);
+            if (deploymentRecord)
+                process.stdout.write(`  - Deployment evidence: ${deploymentRecord.id}\n`);
+            if (cortexInstinctApplications.recorded.length > 0) {
+                console.log(`  - Cortex instinct outcomes: ${cortexInstinctApplications.recorded.length}`);
+            }
             if (stagedFiles.length)
                 console.log(`  - Files committed: ${stagedFiles.length}`);
             console.log('');
@@ -1844,6 +2267,10 @@ export const phaseShip = defineCommand({
                 unverifiedItems.forEach(item => console.log(`  [UNVERIFIED] ${item}`));
                 console.log('');
             }
+            if (shipSurfaceCoverage) {
+                for (const line of formatSurfaceCoverageWarnings(shipSurfaceCoverage))
+                    console.log(line);
+            }
         }
         const result = {
             phase: 'SHIP',
@@ -1854,7 +2281,10 @@ export const phaseShip = defineCommand({
             reviewEvidenceIds: payload.reviewEvidenceIds ?? [],
             reviewValidation,
             commitHash,
+            deploymentRecord,
             stagedFiles,
+            shippedAt,
+            shipMode,
             workspaceBoundary: workspaceBoundary ? {
                 topology: workspaceBoundary.report?.topology.topology ?? null,
                 configured: workspaceBoundary.report?.topology.configured ?? false,
@@ -1863,6 +2293,8 @@ export const phaseShip = defineCommand({
                 blockers: workspaceBoundary.blockers,
                 warnings: workspaceBoundary.warnings,
             } : null,
+            cortexInstinctApplications,
+            verificationSurfaceCoverage: shipSurfaceCoverage,
         };
         if (args.json)
             console.log(JSON.stringify(result, null, 2));
@@ -1871,6 +2303,8 @@ export const phaseShip = defineCommand({
             console.log('\nTask COMPLETED: ' + args['task-id']);
             if (commitHash)
                 console.log('   Commit: ' + commitHash);
+            if (deploymentRecord)
+                process.stdout.write('   Deployment evidence: ' + deploymentRecord.id + '\n');
             console.log('\nDone. Feature shipped.\n');
         }
     },