@hongmaple0820/scale-engine 0.12.3 → 0.13.0

package/dist/cli/phaseCommands.js

@@ -9,13 +9,22 @@ import { FSM } from '../artifact/fsm.js';
 import { registerAllFSMs } from '../artifact/fsmDefinitions.js';
 import { CapabilityRegistry } from '../capabilities/CapabilityRegistry.js';
 import { SkillRegistry } from '../skills/SkillRegistry.js';
+import { registerCoreSkills } from '../skills/coreSkills.js';
+import { registerExternalSkills } from '../skills/ExternalSkills.js';
+import { createSkillPlan, evaluateSkillGate, loadSkillRoutingPolicy } from '../skills/routing/index.js';
 import { WorkflowEngine } from '../workflow/WorkflowEngine.js';
+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 { TaskMetricsStore } from '../workflow/TaskMetricsStore.js';
+import { appendVerificationArtifact, checkTaskArtifactCompleteness, scaffoldTaskArtifacts } from '../workflow/TaskArtifactScaffolder.js';
 import { analyzeReview, parseChangedFiles, shouldReviewFile, summarizeFindings } from '../workflow/ReviewAnalyzer.js';
 import { join } from 'node:path';
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { HTMLDocumentRenderer } from '../output/HTMLDocumentRenderer.js';
 const SCALE_DIR = process.env.SCALE_DIR ?? '.scale';
+const PROJECT_DIR = process.env.SCALE_PROJECT_DIR ?? process.cwd();
 function validateVerificationEvidence(ids) {
     const evidenceStore = new EvidenceStore(SCALE_DIR);
     const missing = [];
@@ -72,11 +81,14 @@ function getEngine() {
     const capabilityRegistry = new CapabilityRegistry(eventBus);
     // Initialize skill registry
     const skillRegistry = new SkillRegistry(eventBus);
+    registerCoreSkills(skillRegistry);
+    registerExternalSkills(skillRegistry, eventBus);
     // Initialize workflow engine with cognitive scaffolding and quality gates.
     const workflowEngine = new WorkflowEngine({
         eventBus,
         capabilityRegistry,
-        skillRegistry
+        skillRegistry,
+        scaleDir: SCALE_DIR,
     });
     return { eventBus, store, fsm, workflowEngine, skillRegistry };
 }
@@ -93,6 +105,127 @@ function shouldSkipCommit(value) {
 function normalizeGitPath(path) {
     return path.replace(/\\/g, '/');
 }
+function normalizeWorkflowLevel(value) {
+    const normalized = String(value ?? 'M').trim().toUpperCase();
+    if (normalized === 'S' || normalized === 'M' || normalized === 'L' || normalized === 'CRITICAL') {
+        return normalized;
+    }
+    throw new Error(`Invalid workflow level "${String(value)}"; expected S, M, L, or CRITICAL.`);
+}
+function metricLevelFromPayload(payload) {
+    const level = normalizeWorkflowLevel(payload.workflowLevel ?? 'M');
+    return level === 'S' ? null : level;
+}
+function normalizeServices(value) {
+    if (!value)
+        return [];
+    return String(value)
+        .split(',')
+        .map(service => service.trim())
+        .filter(Boolean);
+}
+function isWorkflowGeneratedArtifact(path) {
+    return path.replace(/\\/g, '/').startsWith('docs/worklog/tasks/');
+}
+function checkCurrentTaskArtifacts(level) {
+    const state = new WorkflowArtifactWriter(SCALE_DIR).readCurrentState();
+    return checkTaskArtifactCompleteness({
+        projectDir: PROJECT_DIR,
+        artifactsDir: state?.artifactsDir,
+        level,
+        skillRequiredArtifacts: state?.requiredSkillArtifacts,
+    });
+}
+function planSkillsForTask(options) {
+    return createSkillPlan({
+        taskId: options.taskId,
+        taskName: options.taskName,
+        description: options.description,
+        level: options.level,
+        services: options.services ?? [],
+        files: options.files ?? [],
+        policy: loadSkillRoutingPolicy(PROJECT_DIR, SCALE_DIR),
+    });
+}
+function normalizeArtifactGateMode(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const normalized = String(value).trim().toLowerCase();
+    if (normalized === 'off' || normalized === 'warn' || normalized === 'block')
+        return normalized;
+    throw new Error(`Invalid artifact gate mode "${String(value)}"; expected off, warn, or block.`);
+}
+function artifactGateLevels(policy) {
+    return policy.artifactGateLevels?.length ? policy.artifactGateLevels : ['M', 'L', 'CRITICAL'];
+}
+function assumeVerificationArtifactWillBeWritten(check) {
+    if (!check.artifactsDir)
+        return check;
+    const missing = check.missing.filter(file => file !== 'verification.md');
+    const incomplete = check.incomplete.filter(item => item.file !== 'verification.md');
+    return {
+        ...check,
+        missing,
+        incomplete,
+        complete: missing.length === 0 && incomplete.length === 0,
+    };
+}
+function evaluateArtifactGate(options) {
+    const mode = isTruthyFlag(options.requireArtifacts)
+        ? 'block'
+        : normalizeArtifactGateMode(options.cliMode) ?? options.policy.artifactGate ?? 'warn';
+    const levels = artifactGateLevels(options.policy);
+    const applies = Boolean(options.level && levels.includes(options.level));
+    const checked = applies && mode !== 'off' && Boolean(options.check);
+    const complete = checked ? options.check?.complete : undefined;
+    return {
+        mode,
+        levels,
+        applies,
+        checked,
+        complete,
+        blocked: mode === 'block' && checked && complete === false,
+    };
+}
+async function countChangedFiles(taskPayload) {
+    if (taskPayload.filesInvolved.length > 0)
+        return new Set(taskPayload.filesInvolved.map(normalizeGitPath)).size;
+    try {
+        const status = await runGit(['status', '--short']);
+        const untracked = await runGit(['ls-files', '--others', '--exclude-standard']);
+        const statusOutput = mergeUntrackedFilesIntoStatus(status.stdout, untracked.stdout);
+        return parseChangedFiles(statusOutput)
+            .filter(file => shouldReviewFile(file.path))
+            .filter(file => !isWorkflowGeneratedArtifact(file.path))
+            .length;
+    }
+    catch {
+        return 0;
+    }
+}
+async function recordVerificationMetric(options) {
+    const level = metricLevelFromPayload(options.taskPayload);
+    if (!level)
+        return null;
+    const services = options.taskPayload.servicesTouched?.length
+        ? options.taskPayload.servicesTouched
+        : options.serviceNames ?? [];
+    const metricsStore = new TaskMetricsStore(SCALE_DIR);
+    const artifactCheck = options.artifactCheck ?? checkCurrentTaskArtifacts(level);
+    const record = metricsStore.recordVerification({
+        taskId: options.taskId,
+        taskName: options.taskName,
+        level,
+        services,
+        filesChanged: await countChangedFiles(options.taskPayload),
+        passed: options.passed,
+        artifactComplete: artifactCheck.complete,
+        residualRisk: options.taskPayload.residualRisk,
+        finalGateStatus: options.finalGateStatus,
+    });
+    metricsStore.writeMarkdownReport(PROJECT_DIR);
+    return record;
+}
 // Helper: Generate spec markdown file
 function generateSpecMarkdown(id, title, payload) {
     return `# Spec: ${title}
@@ -146,6 +279,8 @@ export const phaseDefine = defineCommand({
         'context': { type: 'string', description: 'Context answer for Socratic refinement' },
         'risk': { type: 'string', description: 'Risk answer for Socratic refinement' },
         'priority': { type: 'string', description: 'Priority answer for Socratic refinement' },
+        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)' },
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
@@ -157,7 +292,7 @@ export const phaseDefine = defineCommand({
             : ['Feature works as described', 'No regression in existing functionality'];
         // === WorkflowEngine Integration ===
         // Step 1: Explore with AmbiguityScorer + SocraticQuestioner
-        const exploreResult = await workflowEngine.explore(desc);
+        const exploreResult = await workflowEngine.explore(desc, { persistArtifact: false, runGate: false });
         const ambiguityResult = workflowEngine.getAmbiguityScorer().analyzeRequirement(desc);
         // Step 2: Check if requirement needs refinement.
         if (ambiguityResult.blocked) {
@@ -251,6 +386,29 @@ export const phaseDefine = defineCommand({
         ensureDir(specsDir);
         const specPath = join(specsDir, `${spec.id}.md`);
         writeFileSync(specPath, generateSpecMarkdown(spec.id, args.title, specPayload));
+        // Generate spec HTML file (default format: html)
+        const outputFormat = args.format ?? 'md';
+        let specHtmlPath;
+        if (outputFormat === 'html') {
+            const renderer = new HTMLDocumentRenderer({
+                title: args.title,
+                brand: args.brand,
+                version: '0.13.0',
+                status: 'FROZEN',
+            });
+            const html = renderer.renderSpec({
+                id: spec.id,
+                title: args.title,
+                what: refinedRequirement,
+                successCriteria,
+                outOfScope: specPayload.outOfScope,
+                edgeCases: specPayload.edgeCases,
+                northStar: specPayload.northStar,
+                ambiguityScore,
+            });
+            specHtmlPath = join(specsDir, `${spec.id}.html`);
+            renderer.writeToFile(html, specHtmlPath);
+        }
         // FSM transitions: DRAFT -> REVIEWING -> FROZEN
         // Phase 1: refine (DRAFT -> REVIEWING) - no guards
         const refineResult = await fsm.canTransition(spec.id, 'refine');
@@ -277,12 +435,24 @@ export const phaseDefine = defineCommand({
         if (!args.json) {
             console.log('   FSM: DRAFT -> REVIEWING -> FROZEN ✓');
         }
-        const result = { phase: 'DEFINE', spec, specPath, ambiguityScore, successCriteria };
+        const result = { phase: 'DEFINE', spec, specPath, specHtmlPath, ambiguityScore, successCriteria, format: outputFormat };
+        // Write explore artifact for Gate G1 verification
+        const artifactWriter = new WorkflowArtifactWriter(SCALE_DIR);
+        artifactWriter.writeExploreResult({
+            timestamp: new Date().toISOString(),
+            files: [specPath],
+            fileCount: 1,
+            mainContradiction: refinedRequirement !== desc ? 'requirement ambiguity resolved via Socratic refinement' : '',
+            ambiguityScore,
+            socraticCompleted: !ambiguityResult.requiresQuestioning || (ambiguityResult.requiresQuestioning && !exploreResult.socraticSession),
+        });
         if (args.json)
             console.log(JSON.stringify(result, null, 2));
         else {
             console.log(`\nDEFINE: ${spec.id}`);
             console.log(`   Spec file: ${specPath}`);
+            if (specHtmlPath)
+                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`);
@@ -322,6 +492,8 @@ export const phasePlan = defineCommand({
         'spec-id': { type: 'positional', required: true },
         approach: { type: 'string', alias: 'a', description: 'Implementation approach' },
         'rollback': { type: 'string', alias: 'r', description: 'Rollback strategy (required for FSM)' },
+        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)' },
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
@@ -335,7 +507,7 @@ export const phasePlan = defineCommand({
         // === WorkflowEngine Integration ===
         // Step 1: Run ConsensusPlanner (Planner -> Architect -> Critic).
         const specDesc = spec.payload.what;
-        const consensusResult = await workflowEngine.plan(specDesc);
+        const consensusResult = await workflowEngine.plan(specDesc, { persistArtifact: false, runGate: false });
         // Step 2: Display RALPLAN-DR output
         if (!args.json) {
             console.log('\nConsensus Planning Result:');
@@ -364,6 +536,41 @@ export const phasePlan = defineCommand({
         ensureDir(plansDir);
         const planPath = join(plansDir, `${plan.id}.md`);
         writeFileSync(planPath, generatePlanMarkdown(plan.id, args['spec-id'], planPayload));
+        // Generate plan HTML file (default format: html)
+        const planOutputFormat = args.format ?? 'md';
+        let planHtmlPath;
+        if (planOutputFormat === 'html') {
+            const planRenderer = new HTMLDocumentRenderer({
+                title: `Plan ${plan.id}`,
+                brand: args.brand,
+                version: '0.13.0',
+                status: 'APPROVED',
+            });
+            const planHtml = planRenderer.renderPlan({
+                id: plan.id,
+                specId: args['spec-id'],
+                approach: planPayload.approach,
+                techChoices: planPayload.techChoices,
+                modules: planPayload.modules,
+                rollbackStrategy: planPayload.rollbackStrategy,
+                estimatedComplexity: planPayload.estimatedComplexity,
+            });
+            planHtmlPath = join(plansDir, `${plan.id}.html`);
+            planRenderer.writeToFile(planHtml, planHtmlPath);
+        }
+        // Write plan artifact for Gate G2 verification
+        const artifactWriter = new WorkflowArtifactWriter(SCALE_DIR);
+        artifactWriter.writePlanResult({
+            timestamp: new Date().toISOString(),
+            planId: plan.id,
+            specId: args['spec-id'],
+            hasBoundaryAnalysis: consensusResult.viableOptions.length > 1,
+            hasExceptionHandling: consensusResult.preMortem.rootCauses.length > 0,
+            hasRollbackStrategy: !!rollbackStrategy,
+            modules: planPayload.modules.map(m => m.path),
+            consensusRounds: consensusResult.iterationCount,
+            verdict: consensusResult.verdict,
+        });
         // FSM transition: DRAFT -> APPROVED (requires rollbackStrategy guard)
         const reviewResult = await fsm.canTransition(plan.id, 'review');
         if (!reviewResult.allowed) {
@@ -379,12 +586,14 @@ export const phasePlan = defineCommand({
         if (!args.json) {
             console.log('   FSM: DRAFT -> APPROVED ✓');
         }
-        const result = { phase: 'PLAN', plan, planPath, rollbackStrategy };
+        const result = { phase: 'PLAN', plan, planPath, planHtmlPath, rollbackStrategy, format: planOutputFormat };
         if (args.json)
             console.log(JSON.stringify(result, null, 2));
         else {
             console.log(`\nPLAN: ${plan.id}`);
             console.log(`   Plan file: ${planPath}`);
+            if (planHtmlPath)
+                console.log(`   HTML file: ${planHtmlPath}`);
             console.log(`   Rollback: ${rollbackStrategy}`);
             console.log(`\n   Next: scale build ${plan.id}\n`);
         }
@@ -396,6 +605,9 @@ export const phaseBuild = defineCommand({
     args: {
         'plan-id': { type: 'positional', required: true },
         description: { type: 'string', alias: 'd', description: 'Task description' },
+        level: { type: 'string', default: 'M', description: 'Workflow task level: S, M, L, or CRITICAL' },
+        service: { type: 'string', description: 'Comma-separated service names touched by this task' },
+        'residual-risk': { type: 'string', description: 'Known residual risk statement for metrics' },
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
@@ -406,9 +618,20 @@ export const phaseBuild = defineCommand({
             console.error(`\nPlan not found: ${args['plan-id']}\n`);
             process.exit(1);
         }
+        let workflowLevel;
+        try {
+            workflowLevel = normalizeWorkflowLevel(args.level);
+        }
+        catch (e) {
+            console.error(`\n${e.message}\n`);
+            process.exit(1);
+        }
         // Create TaskPayload
         const taskPayload = {
             description: args.description ?? `Implement ${plan.title}`,
+            workflowLevel,
+            servicesTouched: normalizeServices(args.service),
+            residualRisk: args['residual-risk'],
             filesInvolved: [],
             dependsOn: [],
             requiredRole: 'implementer',
@@ -428,13 +651,60 @@ export const phaseBuild = defineCommand({
                 outOfScope: [],
             },
         };
+        const taskTitle = `Task for ${plan.title}`;
         const task = await store.create({
-            type: 'Task', title: `Task for ${plan.title}`,
+            type: 'Task', title: taskTitle,
             payload: taskPayload,
             parents: [args['plan-id']],
             initialStatus: 'PENDING',
             createdBy: { kind: 'human', userId: 'cli' },
         });
+        const skillPlan = planSkillsForTask({
+            taskId: task.id,
+            taskName: taskTitle,
+            description: taskPayload.description,
+            level: workflowLevel,
+            services: taskPayload.servicesTouched,
+            files: taskPayload.filesInvolved,
+        });
+        const taskPayloadWithSkills = {
+            ...taskPayload,
+            skillIntents: skillPlan.intents.map(intent => intent.domain),
+            skillRoutingMode: skillPlan.mode,
+            skillPlanRequired: skillPlan.required,
+            requiredSkills: skillPlan.requiredSkills,
+            recommendedSkills: skillPlan.recommendedSkills,
+            requiredSkillArtifacts: skillPlan.requiredArtifacts,
+            requiredSkillVerification: skillPlan.requiredVerification,
+        };
+        await store.update(task.id, { payload: taskPayloadWithSkills });
+        let taskArtifacts;
+        if (workflowLevel !== 'S') {
+            taskArtifacts = scaffoldTaskArtifacts({
+                projectDir: PROJECT_DIR,
+                taskId: task.id,
+                taskName: task.title,
+                description: taskPayloadWithSkills.description,
+                level: workflowLevel,
+                services: taskPayloadWithSkills.servicesTouched,
+                skillPlan,
+            });
+        }
+        new WorkflowArtifactWriter(SCALE_DIR).updateCurrentState({
+            taskId: task.id,
+            level: workflowLevel,
+            phase: 'build',
+            lastTaskId: task.id,
+            artifactsDir: taskArtifacts?.relativeDir,
+            skillIntents: skillPlan.intents.map(intent => intent.domain),
+            skillRoutingMode: skillPlan.mode,
+            skillPlanRequired: skillPlan.required,
+            skillPlanPath: taskArtifacts?.relativeDir ? `${taskArtifacts.relativeDir}/skill-plan.md` : undefined,
+            requiredSkills: skillPlan.requiredSkills,
+            recommendedSkills: skillPlan.recommendedSkills,
+            requiredSkillArtifacts: skillPlan.requiredArtifacts,
+            requiredSkillVerification: skillPlan.requiredVerification,
+        });
         // FSM transitions: PENDING -> READY -> RUNNING
         // Phase 1: schedule (PENDING -> READY) - no guards
         const scheduleResult = await fsm.canTransition(task.id, 'schedule');
@@ -456,13 +726,21 @@ export const phaseBuild = defineCommand({
         if (implResult.allowed) {
             await fsm.transition(args['plan-id'], 'implement', { actor: { kind: 'system', component: 'phase-build' } });
         }
-        const result = { phase: 'BUILD', task, status: 'RUNNING' };
+        const result = { phase: 'BUILD', task: { ...task, payload: taskPayloadWithSkills }, status: 'RUNNING', artifactDir: taskArtifacts?.relativeDir, artifactFiles: taskArtifacts?.created ?? [], skillPlan };
         if (args.json)
             console.log(JSON.stringify(result, null, 2));
         else {
             console.log(`\nBUILD: ${task.id}`);
             console.log(`   Status: RUNNING (ready to implement)`);
-            console.log(`   Description: ${taskPayload.description}`);
+            console.log(`   Description: ${taskPayloadWithSkills.description}`);
+            if (skillPlan.intents.length)
+                console.log(`   Skill intents: ${skillPlan.intents.map(intent => intent.domain).join(', ')}`);
+            if (skillPlan.requiredSkills.length)
+                console.log(`   Required skills: ${skillPlan.requiredSkills.join(', ')}`);
+            if (skillPlan.recommendedSkills.length)
+                console.log(`   Recommended skills: ${skillPlan.recommendedSkills.join(', ')}`);
+            if (taskArtifacts?.relativeDir)
+                console.log(`   Artifacts: ${taskArtifacts.relativeDir}`);
             console.log(`\n   Implement now, then run: scale verify ${task.id}\n`);
         }
     },
@@ -487,8 +765,13 @@ export const phaseVerify = defineCommand({
         'lint-cmd': { type: 'string', description: 'Override lint command' },
         'test-cmd': { type: 'string', description: 'Override test command' },
         'coverage-cmd': { type: 'string', description: 'Override coverage command' },
+        profile: { type: 'string', description: 'Verification profile from .scale/verification.json' },
+        service: { type: 'string', description: 'Service name from .scale/verification.json' },
+        'artifact-gate': { type: 'string', description: 'Task artifact policy override: off, warn, or block' },
+        'require-artifacts': { type: 'boolean', default: false, description: 'Fail verification when required M/L/CRITICAL artifacts are incomplete' },
         'tdd-evidence': { type: 'string', description: 'Path to JSON TDD evidence with red/green/refactor/testFirst=true' },
         'tdd-strict': { type: 'boolean', default: false, description: 'Require TDD evidence before other gates' },
+        'residual-risk': { type: 'string', description: 'Residual risk statement to record in task metrics' },
         'skip-build': { type: 'boolean', default: false },
         'skip-lint': { type: 'boolean', default: false },
         'skip-test': { type: 'boolean', default: false },
@@ -506,14 +789,38 @@ export const phaseVerify = defineCommand({
         // Step 1: Run GateSystem G3-G7
         if (!args.json)
             console.log('\nRunning Quality Gates...');
-        const gateResults = await workflowEngine.verify({
-            build: args['build-cmd'],
-            lint: args['lint-cmd'],
-            test: args['test-cmd'],
-            coverage: args['coverage-cmd'],
-            tddEvidence: args['tdd-evidence'],
-            tddStrict: isTruthyFlag(args['tdd-strict']),
+        const resolvedVerification = resolveVerificationTargets({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            profile: args.profile,
+            service: args.service,
         });
+        if (!args.json) {
+            for (const warning of resolvedVerification.warnings)
+                console.log(`   [WARN] ${warning}`);
+            for (const target of resolvedVerification.targets) {
+                if (target.service) {
+                    console.log(`   Service: ${target.service.name} (${target.service.path})`);
+                }
+            }
+            console.log(`   Profile: ${resolvedVerification.profileName}`);
+        }
+        const gateResults = [];
+        for (const target of resolvedVerification.targets) {
+            if (!args.json && resolvedVerification.targets.length > 1) {
+                console.log(`\n   Target: ${target.service?.name ?? 'root'}`);
+            }
+            const targetResults = await workflowEngine.verify({
+                cwd: target.config.cwd,
+                build: args['build-cmd'] ?? target.config.build,
+                lint: args['lint-cmd'] ?? target.config.lint,
+                test: args['test-cmd'] ?? target.config.test,
+                coverage: args['coverage-cmd'] ?? target.config.coverage,
+                tddEvidence: args['tdd-evidence'],
+                tddStrict: isTruthyFlag(args['tdd-strict']),
+            });
+            gateResults.push(...targetResults);
+        }
         // Step 2: Display gate results
         if (!args.json) {
             console.log('\nGate Results:');
@@ -525,28 +832,51 @@ export const phaseVerify = defineCommand({
             }
         }
         // Extract results from gateResults
-        const g0Result = gateResults.find(g => g.gate === 'G0');
-        const g4Result = gateResults.find(g => g.gate === 'G4');
-        const g5Result = gateResults.find(g => g.gate === 'G5');
-        const g6Result = gateResults.find(g => g.gate === 'G6');
-        const g7Result = gateResults.find(g => g.gate === 'G7');
+        const g0Results = gateResults.filter(g => g.gate === 'G0');
+        const g4Results = gateResults.filter(g => g.gate === 'G4');
+        const g5Results = gateResults.filter(g => g.gate === 'G5');
+        const g6Results = gateResults.filter(g => g.gate === 'G6');
+        const g7Results = gateResults.filter(g => g.gate === 'G7');
+        const gatePassed = (results) => results.length > 0 && results.every(result => result.passed);
+        const buildExitCodes = g0Results
+            .flatMap(result => result.evidenceItems ?? [])
+            .filter(item => item.kind === 'command')
+            .map(item => item.exitCode)
+            .filter((code) => typeof code === 'number');
         const results = {
-            buildStatus: g0Result?.passed ? 'success' : 'failed',
-            buildExitCode: g0Result?.evidenceItems?.find(item => item.kind === 'command')?.exitCode,
-            lintStatus: g4Result?.passed ? 'success' : 'failed',
-            testPassed: g5Result?.passed,
+            buildStatus: gatePassed(g0Results) ? 'success' : 'failed',
+            buildExitCode: buildExitCodes.find(code => code !== 0) ?? (buildExitCodes.length > 0 ? 0 : undefined),
+            lintStatus: gatePassed(g4Results) ? 'success' : 'failed',
+            testPassed: gatePassed(g5Results),
             testCoverage: undefined,
-            securityPassed: g7Result?.passed,
+            securityPassed: gatePassed(g7Results),
         };
         const verificationEvidenceIds = gateResults
             .map(g => g.evidenceRecordId)
             .filter((id) => Boolean(id));
         // Extract coverage from G6 evidence
-        const coverageMatch = g6Result?.evidence.match(/Coverage: (\d+\.?\d*)%/);
-        if (coverageMatch)
-            results.testCoverage = parseFloat(coverageMatch[1]);
+        const coverageValues = g6Results
+            .map(result => result.evidence.match(/Coverage: (\d+\.?\d*)%/))
+            .filter((match) => Boolean(match))
+            .map(match => parseFloat(match[1]));
+        if (coverageValues.length > 0)
+            results.testCoverage = Math.min(...coverageValues);
         // Update Task payload with verification results
         const currentPayload = task.payload;
+        const taskLevel = normalizeWorkflowLevel(currentPayload.workflowLevel ?? 'M');
+        const verificationSkillPlan = taskLevel === 'S'
+            ? undefined
+            : planSkillsForTask({
+                taskId: args['task-id'],
+                taskName: task.title,
+                description: currentPayload.description,
+                level: taskLevel,
+                services: currentPayload.servicesTouched,
+                files: currentPayload.filesInvolved,
+            });
+        const verifiedServices = resolvedVerification.targets
+            .map(target => target.service?.name)
+            .filter((service) => Boolean(service));
         const updatedPayload = {
             ...currentPayload,
             buildStatus: results.buildStatus,
@@ -554,20 +884,64 @@ export const phaseVerify = defineCommand({
             lintStatus: results.lintStatus,
             testPassed: results.testPassed,
             testCoverage: results.testCoverage,
+            servicesTouched: currentPayload.servicesTouched?.length
+                ? currentPayload.servicesTouched
+                : verifiedServices.length > 0 ? verifiedServices : currentPayload.servicesTouched,
+            residualRisk: args['residual-risk'] ?? currentPayload.residualRisk,
             verificationEvidenceIds,
+            skillIntents: verificationSkillPlan?.intents.map(intent => intent.domain) ?? currentPayload.skillIntents,
+            skillRoutingMode: verificationSkillPlan?.mode ?? currentPayload.skillRoutingMode,
+            skillPlanRequired: verificationSkillPlan?.required ?? currentPayload.skillPlanRequired,
+            requiredSkills: verificationSkillPlan?.requiredSkills ?? currentPayload.requiredSkills,
+            recommendedSkills: verificationSkillPlan?.recommendedSkills ?? currentPayload.recommendedSkills,
+            requiredSkillArtifacts: verificationSkillPlan?.requiredArtifacts ?? currentPayload.requiredSkillArtifacts,
+            requiredSkillVerification: verificationSkillPlan?.requiredVerification ?? currentPayload.requiredSkillVerification,
             verifiedAt: Date.now(),
         };
         await store.update(args['task-id'], { payload: updatedPayload });
+        const workflowState = new WorkflowArtifactWriter(SCALE_DIR).updateCurrentState({
+            taskId: args['task-id'],
+            phase: 'verify',
+            lastTaskId: args['task-id'],
+            filesModified: updatedPayload.filesInvolved,
+            skillIntents: updatedPayload.skillIntents,
+            skillRoutingMode: updatedPayload.skillRoutingMode,
+            skillPlanRequired: updatedPayload.skillPlanRequired,
+            requiredSkills: updatedPayload.requiredSkills,
+            recommendedSkills: updatedPayload.recommendedSkills,
+            requiredSkillArtifacts: updatedPayload.requiredSkillArtifacts,
+            requiredSkillVerification: updatedPayload.requiredSkillVerification,
+        });
+        const metricLevel = metricLevelFromPayload(updatedPayload);
+        const preArtifactCheck = metricLevel ? checkCurrentTaskArtifacts(metricLevel) : undefined;
+        const artifactGate = evaluateArtifactGate({
+            policy: resolvedVerification.policy,
+            level: metricLevel,
+            check: preArtifactCheck ? assumeVerificationArtifactWillBeWritten(preArtifactCheck) : undefined,
+            cliMode: args['artifact-gate'],
+            requireArtifacts: args['require-artifacts'],
+        });
+        const skillPolicy = loadSkillRoutingPolicy(PROJECT_DIR, SCALE_DIR);
+        const skillGate = metricLevel && verificationSkillPlan
+            ? evaluateSkillGate({
+                projectDir: PROJECT_DIR,
+                artifactsDir: workflowState.artifactsDir,
+                level: metricLevel,
+                plan: verificationSkillPlan,
+                enforceLevels: skillPolicy.policy.enforceLevels,
+            })
+            : undefined;
         // Attempt FSM transition to COMPLETED
-        // Guards: build_passed, lint_passed, tests_passed
-        const allPassed = results.buildStatus === 'success' &&
+        // Guards: build_passed, lint_passed, tests_passed, and optional artifact policy.
+        const codePassed = results.buildStatus === 'success' &&
             (results.buildExitCode ?? 1) === 0 &&
             results.lintStatus === 'success' &&
             results.testPassed === true &&
             (results.testCoverage ?? 0) >= 80 &&
             results.securityPassed === true;
+        const completionEligible = codePassed && !artifactGate.blocked && !(skillGate?.blocked ?? false);
         let transitionResult = null;
-        if (allPassed) {
+        if (completionEligible) {
             const completeResult = await fsm.canTransition(args['task-id'], 'complete');
             if (!completeResult.allowed) {
                 if (!args.json) {
@@ -582,18 +956,92 @@ export const phaseVerify = defineCommand({
                     actor: { kind: 'human', userId: 'cli' }
                 });
                 if (!args.json)
-                    console.log('\n   FSM: RUNNING -> COMPLETED ✓');
+                    console.log('\n   FSM: RUNNING -> COMPLETED');
             }
         }
-        else if (!args.json) {
+        else if (!args.json && !codePassed) {
             console.log('\n   Verification requirements not met - cannot complete Task');
         }
-        const passed = allPassed && (transitionResult?.success ?? false);
-        const result = { phase: 'VERIFY', taskId: args['task-id'], results, evidenceIds: verificationEvidenceIds, passed };
+        else if (!args.json && artifactGate.blocked) {
+            console.log('\n   Artifact gate blocked completion - required task artifacts are incomplete');
+        }
+        else if (!args.json && skillGate?.blocked) {
+            console.log('\n   Skill gate blocked completion - required skill evidence artifacts are incomplete');
+        }
+        const passed = completionEligible && (transitionResult?.success ?? false);
+        const verificationArtifactPath = appendVerificationArtifact({
+            projectDir: PROJECT_DIR,
+            artifactsDir: workflowState.artifactsDir,
+            taskId: args['task-id'],
+            profile: resolvedVerification.profileName,
+            services: verifiedServices,
+            gateResults,
+            passed,
+        });
+        const artifactCheck = metricLevel ? checkCurrentTaskArtifacts(metricLevel) : undefined;
+        const finalArtifactGate = artifactCheck
+            ? evaluateArtifactGate({
+                policy: resolvedVerification.policy,
+                level: metricLevel,
+                check: artifactCheck,
+                cliMode: args['artifact-gate'],
+                requireArtifacts: args['require-artifacts'],
+            })
+            : artifactGate;
+        const finalSkillGate = metricLevel && verificationSkillPlan
+            ? evaluateSkillGate({
+                projectDir: PROJECT_DIR,
+                artifactsDir: workflowState.artifactsDir,
+                level: metricLevel,
+                plan: verificationSkillPlan,
+                enforceLevels: skillPolicy.policy.enforceLevels,
+            })
+            : skillGate;
+        const finalPayload = {
+            ...updatedPayload,
+            artifactGateMode: finalArtifactGate.mode,
+            artifactGatePassed: !finalArtifactGate.blocked,
+            artifactComplete: artifactCheck?.complete,
+            skillGatePassed: finalSkillGate ? !finalSkillGate.blocked : undefined,
+        };
+        await store.update(args['task-id'], { payload: finalPayload });
+        const metricGateStatus = codePassed && (finalArtifactGate.blocked || finalSkillGate?.blocked) ? 'blocked' : undefined;
+        const metricRecord = await recordVerificationMetric({
+            taskId: args['task-id'],
+            taskName: task.title,
+            taskPayload: finalPayload,
+            passed,
+            serviceNames: verifiedServices,
+            artifactCheck,
+            finalGateStatus: metricGateStatus,
+        });
+        const result = {
+            phase: 'VERIFY',
+            taskId: args['task-id'],
+            profile: resolvedVerification.profileName,
+            service: verifiedServices.length === 1 ? verifiedServices[0] : undefined,
+            services: verifiedServices,
+            results,
+            evidenceIds: verificationEvidenceIds,
+            verificationArtifactPath,
+            artifactCheck,
+            artifactGate: finalArtifactGate,
+            skillGate: finalSkillGate,
+            metric: metricRecord,
+            passed
+        };
         if (args.json)
             console.log(JSON.stringify(result, null, 2));
         else {
             console.log(`\nVERIFY: ${passed ? 'PASSED' : 'FAILED'}`);
+            if (metricRecord)
+                console.log(`   Metrics: ${metricRecord.taskId} ${metricRecord.finalGateStatus} (fix iterations: ${metricRecord.fixIterations})`);
+            if (artifactCheck && !artifactCheck.complete) {
+                console.log(`   Artifact gaps: ${artifactCheck.missing.length} missing, ${artifactCheck.incomplete.length} incomplete`);
+            }
+            if (finalSkillGate && !finalSkillGate.complete) {
+                console.log(`   Skill evidence gaps: ${finalSkillGate.missing.length} missing, ${finalSkillGate.incomplete.length} incomplete`);
+            }
             if (passed)
                 console.log(`\n   Next: scale review\n`);
             else
@@ -612,12 +1060,14 @@ async function runGit(args) {
 }
 function mergeUntrackedFilesIntoStatus(statusOutput, untrackedOutput) {
     const existing = new Set(parseChangedFiles(statusOutput).map(file => file.path.replace(/\\/g, '/')));
+    // Add '??' status marker for untracked files so parseChangedFiles can recognize them
     const additions = untrackedOutput
         .split('\n')
         .map(line => line.trim())
         .filter(Boolean)
         .filter(path => shouldReviewFile(path))
-        .filter(path => !existing.has(path.replace(/\\/g, '/')));
+        .filter(path => !existing.has(path.replace(/\\/g, '/')))
+        .map(path => `?? ${path}`); // Add status marker
     return [statusOutput.trim(), ...additions].filter(Boolean).join('\n');
 }
 function readUntrackedFileAsDiff(path) {
@@ -641,7 +1091,23 @@ function readUntrackedFileAsDiff(path) {
 async function reviewGitChanges(taskPayload) {
     const status = await runGit(['status', '--short']);
     const untracked = await runGit(['ls-files', '--others', '--exclude-standard']);
-    const statusOutput = mergeUntrackedFilesIntoStatus(status.stdout, untracked.stdout);
+    let statusOutput = mergeUntrackedFilesIntoStatus(status.stdout, untracked.stdout);
+    // Scope review to task-relevant files only.
+    // When filesInvolved is set, only analyze those files.
+    // When empty, only analyze untracked (new) files to avoid picking up
+    // unrelated modifications from a dirty working tree.
+    if (taskPayload?.filesInvolved?.length) {
+        const involved = new Set(taskPayload.filesInvolved.map(f => f.replace(/\\/g, '/')));
+        statusOutput = statusOutput.split('\n').filter(line => {
+            const parsed = parseChangedFiles(line);
+            return parsed.length > 0 && involved.has(parsed[0].path.replace(/\\/g, '/'));
+        }).join('\n');
+    }
+    else {
+        // Only include untracked files (status '??') — skip tracked modifications
+        // that may be unrelated to the task under review.
+        statusOutput = statusOutput.split('\n').filter(line => line.startsWith('??')).join('\n');
+    }
     const verificationEvidence = getVerificationEvidenceSummary(taskPayload?.verificationEvidenceIds);
     const changedFiles = analyzeReview({ statusOutput, diffs: [], taskPayload, verificationEvidence }).changedFiles;
     const diffs = [];
@@ -679,6 +1145,12 @@ async function stageReviewedFiles(reviewRecords) {
     const currentChanges = await getReviewableGitChanges();
     const stagedFiles = [];
     const unreviewedFiles = [];
+    // Edge case: if currentChanges is empty but reviewedFiles has files that should be staged,
+    // this indicates files were deleted or moved. Treat reviewed but missing files as unreviewed.
+    if (currentChanges.length === 0 && reviewedFiles.size > 0) {
+        // No changes to stage, but we have review records - this is a pass (nothing to commit)
+        return { stagedFiles: [], unreviewedFiles: [] };
+    }
     for (const file of currentChanges) {
         const normalizedPath = normalizeGitPath(file.path);
         if (reviewedFiles.has(normalizedPath)) {
@@ -688,6 +1160,7 @@ async function stageReviewedFiles(reviewRecords) {
             unreviewedFiles.push(file.path);
         }
     }
+    // Only block if there are actual unreviewed changes
     if (unreviewedFiles.length > 0) {
         return { stagedFiles: [], unreviewedFiles };
     }
@@ -706,6 +1179,8 @@ export const phaseReview = defineCommand({
         'task-id': { type: 'positional', required: false },
         'check-security': { type: 'boolean', default: true },
         '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)' },
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
@@ -742,7 +1217,7 @@ export const phaseReview = defineCommand({
             taskId: args['task-id'],
             passed,
             findings,
-            changedFiles: review.changedFiles.map(file => file.path),
+            changedFiles: review.changedFiles.map(file => normalizeGitPath(file.path)),
             summary,
         });
         if (task && taskPayload) {
@@ -754,14 +1229,44 @@ export const phaseReview = defineCommand({
             };
             await store.update(task.id, { payload: updatedPayload });
         }
+        // Generate review HTML file (default format: html)
+        const reviewOutputFormat = args.format ?? 'md';
+        let reviewHtmlPath;
+        if (reviewOutputFormat === 'html') {
+            const reviewRenderer = new HTMLDocumentRenderer({
+                title: `Review ${record.id}`,
+                brand: args.brand,
+                version: '0.13.0',
+                status: passed ? 'PASS' : 'FAIL',
+            });
+            const reviewHtml = reviewRenderer.renderReview({
+                id: record.id,
+                title: `Code Review — ${record.id}`,
+                timestamp: new Date().toISOString(),
+                findings: findings.map(f => ({
+                    severity: f.severity,
+                    file: f.file ?? '',
+                    message: f.description,
+                })),
+                passed,
+                specCoverage: undefined,
+                specFindings: undefined,
+            });
+            const reviewsDir = join(SCALE_DIR, 'reviews');
+            ensureDir(reviewsDir);
+            reviewHtmlPath = join(reviewsDir, `${record.id}.html`);
+            reviewRenderer.writeToFile(reviewHtml, reviewHtmlPath);
+        }
         const result = {
             phase: 'REVIEW',
             taskId: args['task-id'],
             reviewId: record.id,
+            reviewHtmlPath,
             findings,
-            changedFiles: review.changedFiles.map(file => file.path),
+            changedFiles: review.changedFiles.map(file => normalizeGitPath(file.path)),
             summary,
             passed,
+            format: reviewOutputFormat,
             recommendation: passed ? 'Ready to ship' : 'Fix CRITICAL issues before shipping'
         };
         if (args.json)
@@ -769,6 +1274,8 @@ export const phaseReview = defineCommand({
         else {
             console.log('\nREVIEW Phase');
             console.log(`\nReview evidence: ${record.id}`);
+            if (reviewHtmlPath)
+                console.log(`HTML report: ${reviewHtmlPath}`);
             console.log('\nReview Findings:');
             console.log('----------------------------------------');
             console.log(`CRITICAL: ${summary.critical} issues ${summary.critical > 0 ? 'BLOCKED' : 'OK'}`);
@@ -817,6 +1324,19 @@ export const phaseShip = defineCommand({
             (payload.testCoverage ?? 0) >= 80 &&
             evidenceValidation.ok;
         const reviewPassed = payload.reviewPassed === true && reviewValidation.ok;
+        const artifactGatePassed = payload.artifactGateMode !== 'block' || payload.artifactGatePassed !== false;
+        const skillGatePassed = payload.skillGatePassed !== false;
+        if (!artifactGatePassed) {
+            console.error('\nTask artifact gate did not pass. Complete required task artifacts and re-run: scale verify ' + args['task-id'] + ' --artifact-gate block\n');
+            if (payload.artifactComplete === false) {
+                console.error('Required task artifacts are incomplete.');
+            }
+            process.exit(1);
+        }
+        if (!skillGatePassed) {
+            console.error('\nTask skill gate did not pass. Complete required skill evidence artifacts and re-run: scale verify ' + args['task-id'] + '\n');
+            process.exit(1);
+        }
         if (task.status !== 'COMPLETED') {
             if (!verificationPassed) {
                 console.error('\nTask not verified with persisted evidence. Run: scale verify ' + args['task-id'] + '\n');