@hongmaple0820/scale-engine 0.16.0 → 0.18.0

package/dist/api/cli.js

@@ -30,24 +30,30 @@ import { EvidenceStore } from '../workflow/EvidenceStore.js';
 import { OutOfScopeStore } from '../workflow/OutOfScopeStore.js';
 import { ReviewStore } from '../workflow/ReviewStore.js';
 import { WorkflowEngine } from '../workflow/WorkflowEngine.js';
-import { resolveVerificationTargets } from '../workflow/VerificationProfile.js';
+import { resolveVerificationTargets, } from '../workflow/VerificationProfile.js';
 import { writeGovernanceTemplates } from '../workflow/GovernanceTemplates.js';
 import { computeGovernanceDrift } from '../workflow/GovernanceLock.js';
 import { baselineEngineeringStandards, doctorEngineeringStandards, scanEngineeringStandards, settleEngineeringStandards, } from '../workflow/EngineeringStandards.js';
 import { doctorResourceAssets, scanResourceAssets, settleResourceAssets } from '../workflow/ResourceGovernance.js';
+import { analyzeContextGovernance, renderContextGrillPrompt, writeContextGovernanceTemplates, } from '../workflow/ContextGovernance.js';
+import { createDiagnosticLoop, renderDiagnosticLoopMarkdown, validateDiagnosticLoop, } from '../workflow/DiagnosticLoop.js';
+import { createTddSlice, evaluateTddSlice, renderTddSliceMarkdown, } from '../workflow/TddLoop.js';
+import { nextWorkflowOpenTask, removeWorkflowOpenTask, toolEvidenceRunCompletesOpenTask } from '../workflow/WorkflowOpenTasks.js';
 import { TaskMetricsStore } from '../workflow/TaskMetricsStore.js';
-import { checkTaskArtifactCompleteness } from '../workflow/TaskArtifactScaffolder.js';
+import { appendContextGrillArtifact, appendDiagnosticLoopArtifact, appendTddSliceArtifact, checkTaskArtifactCompleteness, } from '../workflow/TaskArtifactScaffolder.js';
 import { WorkflowArtifactWriter } from '../workflow/WorkflowArtifactWriter.js';
 import { inspectToolCapabilities } from '../tools/ToolCapabilityRegistry.js';
 import { evaluateToolEvidenceGate } from '../tools/ToolEvidenceGate.js';
 import { ToolEvidenceStore } from '../tools/ToolEvidenceStore.js';
 import { ToolOrchestrator } from '../tools/ToolOrchestrator.js';
 import { loadToolPolicy, toolPolicyTemplate } from '../tools/ToolPolicy.js';
+import { doctorHtmlArtifacts, renderHtmlArtifact, resolveHtmlArtifactForOpen, settleHtmlArtifacts, } from '../output/HTMLArtifactLayer.js';
 import { cleanupWorkspaceLifecycle, inspectWorkspaceLifecycle, } from '../workflow/WorkspaceLifecycle.js';
 import { resolveWorkspaceTopology, workspaceTopologyPath, workspaceTopologyTemplate, } from '../workflow/WorkspaceTopology.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
 import { SCALE_ENGINE_VERSION } from '../version.js';
 // ============================================================================
 // Engine bootstrap (单例 + lazy init)
@@ -69,6 +75,18 @@ function ensureDir(dir) {
 function isTruthyFlag(value) {
     return value === true || value === '' || value === 'true' || value === '1';
 }
+function commandEvidence(command, exitCode, summary) {
+    if (exitCode === undefined || exitCode === null || exitCode === '')
+        return undefined;
+    const parsed = Number.parseInt(String(exitCode), 10);
+    if (Number.isNaN(parsed))
+        return undefined;
+    return {
+        command,
+        exitCode: parsed,
+        outputSummary: summary ? String(summary) : `Command exited ${parsed}`,
+    };
+}
 function normalizePreflightProfile(value) {
     const normalized = String(value ?? 'quick').trim().toLowerCase();
     if (normalized === 'full' || normalized === 'ci')
@@ -80,6 +98,26 @@ function gatesForPreflightProfile(profile) {
         return ['G3', 'G0', 'G4', 'G5'];
     return ['G3', 'G0', 'G4', 'G5', 'G6', 'G7'];
 }
+function shouldSkipPreflightCommandTargets(resolved, args) {
+    if (!resolved.matrix)
+        return false;
+    const requestedService = String(args.service ?? '').trim();
+    if (requestedService && requestedService !== 'all')
+        return false;
+    const hasCommandOverrides = [
+        args['build-cmd'],
+        args['lint-cmd'],
+        args['test-cmd'],
+        args['coverage-cmd'],
+    ].some(value => typeof value === 'string' && value.trim().length > 0);
+    if (hasCommandOverrides)
+        return false;
+    const profile = resolved.matrix.profiles?.[resolved.profileName];
+    const hasProfileCommands = Object.values(profile?.commands ?? {})
+        .some(value => typeof value === 'string' && value.trim().length > 0);
+    const hasServices = (resolved.matrix.services ?? []).length > 0;
+    return !hasServices && !hasProfileCommands;
+}
 function evaluateEngineeringStandardsGate(options) {
     const mode = normalizeEngineeringStandardsGateMode(options.policy.engineeringStandardsGate);
     if (mode === 'off') {
@@ -776,9 +814,239 @@ const contextGlossary = defineCommand({
         }
     },
 });
+const contextInit = defineCommand({
+    meta: { name: 'init', description: 'Create CONTEXT.md and CONTEXT-MAP.md starter templates' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        name: { type: 'string', description: 'Project display name' },
+        force: { type: 'boolean', default: false, description: 'Overwrite existing templates' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const result = writeContextGovernanceTemplates({
+            projectDir: resolve(String(args.dir ?? PROJECT_DIR)),
+            projectName: args.name ? String(args.name) : undefined,
+            force: isTruthyFlag(args.force),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log('\nSCALE Context Templates');
+        for (const file of result.created)
+            console.log(`  [CREATED] ${file}`);
+        for (const file of result.skipped)
+            console.log(`  [SKIPPED] ${file}`);
+    },
+});
+const contextGrill = defineCommand({
+    meta: { name: 'grill', description: 'Check project context docs and generate request-specific grill questions' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        'task-id': { type: 'string', description: 'Task id for workflow state and artifact linkage' },
+        task: { type: 'string', required: true, description: 'Task or requirement description' },
+        files: { type: 'string', description: 'Comma-separated changed or target files' },
+        'artifact-dir': { type: 'string', description: 'Task artifact directory where explore.md should be updated' },
+        write: { type: 'boolean', default: false, description: 'Append context grill output to the task explore artifact' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const taskId = String(args['task-id'] ?? `context-${Date.now()}`);
+        const changedFiles = parseCommaList(args.files);
+        const report = analyzeContextGovernance({
+            projectDir,
+            request: String(args.task ?? ''),
+            changedFiles,
+        });
+        const artifactPath = isTruthyFlag(args.write)
+            ? appendContextGrillArtifact({
+                projectDir,
+                artifactsDir: args['artifact-dir'] ? String(args['artifact-dir']) : undefined,
+                report,
+            }) ?? undefined
+            : undefined;
+        if (args['task-id'] || artifactPath) {
+            const writer = new WorkflowArtifactWriter(SCALE_DIR);
+            const current = writer.readCurrentState();
+            const currentOpenTasks = current?.taskId === taskId ? current.openTasks : [];
+            writer.updateCurrentState({
+                taskId,
+                phase: 'explore',
+                artifactsDir: args['artifact-dir'] ? String(args['artifact-dir']).replace(/\\/g, '/') : undefined,
+                exploredFiles: changedFiles,
+                fileCount: changedFiles.length,
+                mainContradiction: report.findings[0]?.message ?? 'context governance ready',
+                openTasks: removeWorkflowOpenTask(currentOpenTasks, 'context-grill'),
+            });
+        }
+        if (args.json) {
+            console.log(JSON.stringify({ ...report, artifactPath }, null, 2));
+            return;
+        }
+        console.log(renderContextGrillPrompt(report));
+        if (artifactPath)
+            console.log(`\nArtifact: ${artifactPath}`);
+    },
+});
 const context = defineCommand({
     meta: { name: 'context', description: 'Context assembly' },
-    subCommands: { build: contextBuild, status: contextStatus, inject: contextInject, glossary: contextGlossary },
+    subCommands: { build: contextBuild, status: contextStatus, inject: contextInject, glossary: contextGlossary, init: contextInit, grill: contextGrill },
+});
+// ============================================================================
+// diagnose command - evidence-first debugging loop
+// ============================================================================
+const diagnosePlanCommand = defineCommand({
+    meta: { name: 'plan', description: 'Create a reproducible diagnostic loop before fixing a bug' },
+    args: {
+        'task-id': { type: 'string', required: true },
+        symptom: { type: 'string', required: true },
+        repro: { type: 'string', description: 'Command that reproduces the current failure' },
+        'expected-failure': { type: 'string', description: 'Expected failing behavior or assertion' },
+        files: { type: 'string', description: 'Comma-separated changed or suspicious files' },
+        verify: { type: 'string', description: 'Comma-separated verification commands after the fix' },
+        'artifact-dir': { type: 'string', description: 'Task artifact directory where plan.md should be updated' },
+        write: { type: 'boolean', default: false, description: 'Append diagnostic loop output to the task plan artifact' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const changedFiles = parseCommaList(args.files);
+        const loop = createDiagnosticLoop({
+            taskId: String(args['task-id']),
+            symptom: String(args.symptom),
+            reproductionCommand: args.repro ? String(args.repro) : undefined,
+            expectedFailure: args['expected-failure'] ? String(args['expected-failure']) : undefined,
+            changedFiles,
+            verificationCommands: parseCommaList(args.verify),
+        });
+        const validation = validateDiagnosticLoop(loop);
+        const artifactPath = isTruthyFlag(args.write)
+            ? appendDiagnosticLoopArtifact({
+                projectDir: PROJECT_DIR,
+                artifactsDir: args['artifact-dir'] ? String(args['artifact-dir']) : undefined,
+                loop,
+                validation,
+            }) ?? undefined
+            : undefined;
+        if (artifactPath || args['artifact-dir']) {
+            const writer = new WorkflowArtifactWriter(SCALE_DIR);
+            const current = writer.readCurrentState();
+            const currentOpenTasks = current?.taskId === loop.taskId ? current.openTasks : [];
+            writer.updateCurrentState({
+                taskId: loop.taskId,
+                phase: 'plan',
+                artifactsDir: args['artifact-dir'] ? String(args['artifact-dir']).replace(/\\/g, '/') : undefined,
+                filesModified: changedFiles,
+                openTasks: validation.ready
+                    ? removeWorkflowOpenTask(currentOpenTasks.filter(task => task.trim().startsWith('scale ')), 'diagnostic-loop')
+                    : uniqueStrings([
+                        ...currentOpenTasks,
+                        ...validation.blockers,
+                    ]),
+            });
+        }
+        if (args.json) {
+            console.log(JSON.stringify({ loop, validation, artifactPath }, null, 2));
+            return;
+        }
+        console.log(renderDiagnosticLoopMarkdown(loop));
+        if (!validation.ready) {
+            console.log('\nBlockers:');
+            for (const blocker of validation.blockers)
+                console.log(`  - ${blocker}`);
+        }
+        if (artifactPath)
+            console.log(`\nArtifact: ${artifactPath}`);
+    },
+});
+const diagnose = defineCommand({
+    meta: { name: 'diagnose', description: 'Evidence-first debugging workflows' },
+    subCommands: { plan: diagnosePlanCommand },
+});
+// ============================================================================
+// tdd command - vertical slice RED/GREEN/REFACTOR loop
+// ============================================================================
+const tddSliceCommand = defineCommand({
+    meta: { name: 'slice', description: 'Create and evaluate a TDD vertical slice' },
+    args: {
+        'task-id': { type: 'string', required: true },
+        behavior: { type: 'string', required: true },
+        'public-interface': { type: 'string', required: true },
+        'failing-test': { type: 'string', required: true },
+        'test-file': { type: 'string', required: true },
+        'impl-files': { type: 'string', required: true },
+        'red-exit-code': { type: 'string', description: 'Exit code from the RED command' },
+        'red-summary': { type: 'string', description: 'Short RED output summary' },
+        'green-exit-code': { type: 'string', description: 'Exit code from the GREEN command' },
+        'green-summary': { type: 'string', description: 'Short GREEN output summary' },
+        'refactor-exit-code': { type: 'string', description: 'Exit code from the REFACTOR command' },
+        'refactor-summary': { type: 'string', description: 'Short REFACTOR output summary' },
+        'artifact-dir': { type: 'string', description: 'Task artifact directory where verification.md should be updated' },
+        write: { type: 'boolean', default: false, description: 'Append TDD slice output to the task verification artifact' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const failingTest = String(args['failing-test']);
+        const slice = createTddSlice({
+            taskId: String(args['task-id']),
+            behavior: String(args.behavior),
+            publicInterface: String(args['public-interface']),
+            failingTestCommand: failingTest,
+            testFile: String(args['test-file']),
+            implementationFiles: parseCommaList(args['impl-files']),
+            redEvidence: commandEvidence(failingTest, args['red-exit-code'], args['red-summary']),
+            greenEvidence: commandEvidence(failingTest, args['green-exit-code'], args['green-summary']),
+            refactorEvidence: commandEvidence(failingTest, args['refactor-exit-code'], args['refactor-summary']),
+        });
+        const evaluation = evaluateTddSlice(slice);
+        const artifactPath = isTruthyFlag(args.write)
+            ? appendTddSliceArtifact({
+                projectDir: PROJECT_DIR,
+                artifactsDir: args['artifact-dir'] ? String(args['artifact-dir']) : undefined,
+                slice,
+            }) ?? undefined
+            : undefined;
+        let tddStatePath;
+        if (slice.redEvidence && slice.greenEvidence && slice.refactorEvidence) {
+            const writer = new WorkflowArtifactWriter(SCALE_DIR);
+            writer.writeTDDEvidence({
+                timestamp: new Date().toISOString(),
+                taskId: slice.taskId,
+                red: slice.redEvidence.exitCode !== 0,
+                green: slice.greenEvidence.exitCode === 0,
+                refactor: slice.refactorEvidence.exitCode === 0,
+                testFirst: slice.redEvidence.exitCode !== 0,
+                testFile: slice.testFile,
+                implFile: slice.implementationFiles[0] ?? '',
+            });
+            writer.updateCurrentState({
+                taskId: slice.taskId,
+                phase: 'verify',
+                artifactsDir: args['artifact-dir'] ? String(args['artifact-dir']).replace(/\\/g, '/') : undefined,
+                filesModified: slice.implementationFiles,
+                openTasks: removeWorkflowOpenTask(writer.readCurrentState()?.openTasks, 'tdd-slice'),
+            });
+            tddStatePath = join(writer.getStateDir(), `tdd-${slice.taskId}.json`);
+        }
+        if (args.json) {
+            console.log(JSON.stringify({ slice, evaluation, artifactPath, tddStatePath }, null, 2));
+            return;
+        }
+        console.log(renderTddSliceMarkdown(slice));
+        if (evaluation.blockers.length > 0) {
+            console.log('\nBlockers:');
+            for (const blocker of evaluation.blockers)
+                console.log(`  - ${blocker}`);
+        }
+        if (artifactPath)
+            console.log(`\nArtifact: ${artifactPath}`);
+        if (tddStatePath)
+            console.log(`TDD state: ${tddStatePath}`);
+    },
+});
+const tdd = defineCommand({
+    meta: { name: 'tdd', description: 'TDD vertical slice workflows' },
+    subCommands: { slice: tddSliceCommand },
 });
 // ============================================================================
 // stats
@@ -1132,6 +1400,10 @@ const preflight = defineCommand({
             profile: args.profile,
             service: args.service,
         });
+        const commandTargetsSkipped = shouldSkipPreflightCommandTargets(resolved, args);
+        if (commandTargetsSkipped) {
+            resolved.warnings.push('No verification services or profile commands configured; command gates skipped for this governance-only project.');
+        }
         const engineeringStandards = evaluateEngineeringStandardsGate({
             policy: resolved.policy,
         });
@@ -1151,7 +1423,7 @@ const preflight = defineCommand({
                 console.log('  Engineering standards: skipped');
             }
         }
-        for (const target of resolved.targets) {
+        for (const target of commandTargetsSkipped ? [] : resolved.targets) {
             if (!args.json) {
                 const label = target.service ? `${target.service.name} (${target.service.path})` : 'root';
                 console.log(`\n  Target: ${label}`);
@@ -1181,8 +1453,7 @@ const preflight = defineCommand({
                 }
             }
         }
-        const passed = targetResults.length > 0 &&
-            targetResults.every(target => target.passed) &&
+        const passed = (targetResults.length === 0 || targetResults.every(target => target.passed)) &&
             !engineeringStandards.blocked;
         const result = {
             phase: 'PREFLIGHT',
@@ -1193,6 +1464,7 @@ const preflight = defineCommand({
             policy: resolved.policy,
             engineeringStandards,
             targets: targetResults,
+            commandTargetsSkipped,
             passed,
         };
         if (args.json) {
@@ -1224,6 +1496,9 @@ const status = defineCommand({
         const latestReviews = reviewStore.listReviews(5);
         const latestTask = tasks[0];
         const taskPayload = latestTask?.payload;
+        const workflowState = new WorkflowArtifactWriter(SCALE_DIR).readCurrentState();
+        const currentOpenTasks = workflowState?.taskId === latestTask?.id ? workflowState.openTasks ?? [] : [];
+        const nextOpenTask = nextWorkflowOpenTask(currentOpenTasks);
         const blockers = [];
         const latestBlockingEvidence = latestEvidence.find(record => !record.passed);
         const latestBlockingReview = latestReviews.find(record => !record.passed);
@@ -1244,6 +1519,10 @@ const status = defineCommand({
                 return `scale plan ${specs[0].id}`;
             if (!latestTask)
                 return `scale build ${plans[0].id}`;
+            if (nextOpenTask?.kind === 'command')
+                return nextOpenTask.value;
+            if (nextOpenTask?.kind === 'blocker')
+                return `Resolve workflow blocker: ${nextOpenTask.value}`;
             if (!taskPayload?.verificationEvidenceIds?.length)
                 return `scale verify ${latestTask.id}`;
             if (latestTask.status !== 'COMPLETED')
@@ -1285,6 +1564,14 @@ const status = defineCommand({
                 summary: record.summary,
                 createdAt: record.createdAt,
             })),
+            workflowState: workflowState ? {
+                taskId: workflowState.taskId,
+                level: workflowState.level,
+                phase: workflowState.phase,
+                artifactsDir: workflowState.artifactsDir,
+                openTasks: workflowState.openTasks,
+                skillIntents: workflowState.skillIntents,
+            } : null,
             blockers,
             nextCommand,
         };
@@ -1314,6 +1601,11 @@ const status = defineCommand({
             for (const blocker of blockers)
                 console.log(`  - ${blocker}`);
         }
+        if (result.workflowState?.openTasks.length) {
+            console.log('\nOpen Tasks:');
+            for (const task of result.workflowState.openTasks)
+                console.log(`  - ${task}`);
+        }
         console.log(`\nNext: ${nextCommand}`);
     },
 });
@@ -1423,7 +1715,7 @@ const init = defineCommand({
                 const detection = qsResult.success ? undefined : detectPlatform(args.dir);
                 console.log(JSON.stringify({
                     ok: qsResult.success,
-                    mode: 'quick',
+                    mode: qsResult.success && !qsResult.platform ? 'governance-only' : 'quick',
                     platform: qsResult.platform,
                     created: qsResult.created,
                     skipped: qsResult.skipped,
@@ -1435,8 +1727,11 @@ const init = defineCommand({
                 }, null, 2));
                 return;
             }
-            if (qsResult.success && qsResult.platform) {
-                console.log(`\n✅ SCALE Engine Quick Start completed for ${qsResult.platform}`);
+            if (qsResult.success) {
+                if (!qsResult.platform)
+                    console.log(`\nSCALE governance templates initialized`);
+                else
+                    console.log(`\n✅ SCALE Engine Quick Start completed for ${qsResult.platform}`);
                 console.log(`\n📁 Created (${qsResult.created.length}):`);
                 for (const f of qsResult.created)
                     console.log(`   + ${f}`);
@@ -1790,6 +2085,182 @@ const standards = defineCommand({
     subCommands: { scan: standardsScan, doctor: standardsDoctor, settle: standardsSettle, baseline: standardsBaseline },
 });
 // ============================================================================
+// artifact command - Derived HTML artifacts for human review
+// ============================================================================
+const artifactRender = defineCommand({
+    meta: { name: 'render', description: 'Render a task Markdown source set into a governed HTML artifact' },
+    args: {
+        dir: { type: 'string', default: '.', description: 'Project directory' },
+        'task-id': { type: 'string', description: 'Task id under docs/worklog/tasks' },
+        'artifact-dir': { type: 'string', description: 'Task artifact directory override' },
+        type: { type: 'string', default: 'release-report', description: 'HTML artifact type' },
+        source: { type: 'string', description: 'Comma or newline separated source Markdown files relative to the task directory' },
+        theme: { type: 'string', default: 'auto', description: 'Theme mode: dark/light/auto' },
+        lang: { type: 'string', default: 'zh', description: 'HTML language: zh/en' },
+        title: { type: 'string', description: 'HTML document title override' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const result = renderHtmlArtifact({
+            projectDir: args.dir,
+            taskId: args['task-id'],
+            artifactDir: args['artifact-dir'],
+            type: String(args.type ?? 'release-report'),
+            sourcePaths: splitChangedFiles(typeof args.source === 'string' ? args.source : undefined),
+            theme: normalizeThemeArg(args.theme),
+            lang: normalizeLangArg(args.lang),
+            title: typeof args.title === 'string' ? args.title : undefined,
+        });
+        if (args.json) {
+            console.log(JSON.stringify(result, null, 2));
+            return;
+        }
+        console.log('SCALE HTML Artifact Render');
+        console.log(`  Type: ${result.type}`);
+        console.log(`  HTML: ${result.outputPath}`);
+        console.log(`  Index: ${result.indexPath}`);
+        console.log(`  Manifest: ${result.manifestPath}`);
+        if (result.missingSources.length > 0) {
+            console.log(`  Missing sources: ${result.missingSources.join(', ')}`);
+        }
+    },
+});
+const artifactDoctor = defineCommand({
+    meta: { name: 'doctor', description: 'Check HTML artifacts for traceability, stale sources, remote assets, and secret-like content' },
+    args: {
+        dir: { type: 'string', default: '.', description: 'Project directory' },
+        'task-id': { type: 'string', description: 'Task id under docs/worklog/tasks' },
+        'artifact-dir': { type: 'string', description: 'Task artifact directory override' },
+        type: { type: 'string', description: 'Optional HTML artifact type to check' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const report = doctorHtmlArtifacts({
+            projectDir: args.dir,
+            taskId: args['task-id'],
+            artifactDir: args['artifact-dir'],
+            type: typeof args.type === 'string' ? args.type : undefined,
+        });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
+        console.log(`SCALE HTML Artifact Doctor: ${report.ok ? 'OK' : 'FAILED'}`);
+        console.log(`  Manifest: ${report.manifestPath}`);
+        console.log(`  Artifacts: ${report.artifacts.length}`);
+        if (report.findings.length === 0) {
+            console.log('  No HTML artifact findings.');
+        }
+        else {
+            for (const finding of report.findings) {
+                const path = finding.path ? ` ${finding.path}` : '';
+                console.log(`  [${finding.severity.toUpperCase()}] ${finding.code}${path}: ${finding.message}`);
+                if (finding.fix)
+                    console.log(`    fix: ${finding.fix}`);
+            }
+        }
+        if (!report.ok)
+            process.exitCode = 1;
+    },
+});
+const artifactSettle = defineCommand({
+    meta: { name: 'settle', description: 'Record HTML artifact settlement evidence for a task' },
+    args: {
+        dir: { type: 'string', default: '.', description: 'Project directory' },
+        'task-id': { type: 'string', description: 'Task id under docs/worklog/tasks' },
+        'artifact-dir': { type: 'string', description: 'Task artifact directory override' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const report = settleHtmlArtifacts({
+            projectDir: args.dir,
+            taskId: args['task-id'],
+            artifactDir: args['artifact-dir'],
+        });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
+        console.log(`SCALE HTML Artifact Settlement: ${report.ok ? 'OK' : 'FAILED'}`);
+        console.log(`  HTML impact: ${report.htmlImpactPath}`);
+        for (const finding of report.doctor.findings) {
+            const path = finding.path ? ` ${finding.path}` : '';
+            console.log(`  [${finding.severity.toUpperCase()}] ${finding.code}${path}: ${finding.message}`);
+        }
+        if (!report.ok)
+            process.exitCode = 1;
+    },
+});
+const artifactOpen = defineCommand({
+    meta: { name: 'open', description: 'Open or print the local file URL for a rendered HTML artifact' },
+    args: {
+        dir: { type: 'string', default: '.', description: 'Project directory' },
+        'task-id': { type: 'string', description: 'Task id under docs/worklog/tasks' },
+        'artifact-dir': { type: 'string', description: 'Task artifact directory override' },
+        type: { type: 'string', description: 'Optional HTML artifact type to open' },
+        'print-only': { type: 'boolean', default: false, description: 'Only print the file URL without launching a browser' },
+        json: { type: 'boolean', default: false, description: 'Print JSON output' },
+    },
+    run({ args }) {
+        const path = resolveHtmlArtifactForOpen({
+            projectDir: args.dir,
+            taskId: args['task-id'],
+            artifactDir: args['artifact-dir'],
+            type: typeof args.type === 'string' ? args.type : undefined,
+        });
+        const url = pathToFileURL(path).toString();
+        const exists = existsSync(path);
+        if (!args['print-only'] && exists)
+            launchLocalFile(path);
+        const output = { ok: exists, path, url, launched: Boolean(!args['print-only'] && exists) };
+        if (args.json) {
+            console.log(JSON.stringify(output, null, 2));
+            if (!exists)
+                process.exitCode = 1;
+            return;
+        }
+        if (!exists) {
+            console.log(`HTML artifact not found: ${path}`);
+            process.exitCode = 1;
+            return;
+        }
+        console.log(url);
+    },
+});
+const artifact = defineCommand({
+    meta: { name: 'artifact', description: 'Derived HTML artifact rendering and safety checks' },
+    subCommands: { render: artifactRender, doctor: artifactDoctor, settle: artifactSettle, open: artifactOpen },
+});
+function normalizeThemeArg(value) {
+    const normalized = String(value ?? 'auto').trim().toLowerCase();
+    if (normalized === 'dark' || normalized === 'light' || normalized === 'auto')
+        return normalized;
+    return 'auto';
+}
+function normalizeLangArg(value) {
+    return String(value ?? 'zh').trim().toLowerCase() === 'en' ? 'en' : 'zh';
+}
+function launchLocalFile(path) {
+    try {
+        if (process.platform === 'win32') {
+            execFileSync('cmd', ['/c', 'start', '', path], { stdio: 'ignore' });
+        }
+        else if (process.platform === 'darwin') {
+            execFileSync('open', [path], { stdio: 'ignore' });
+        }
+        else {
+            execFileSync('xdg-open', [path], { stdio: 'ignore' });
+        }
+    }
+    catch {
+        // Opening is convenience-only; artifact doctor/render remains the source of truth.
+    }
+}
+// ============================================================================
 // evolve command
 // ============================================================================
 const evolve = defineCommand({
@@ -2187,6 +2658,7 @@ const skillCheckCommand = defineCommand({
             artifactsDir: args.dir ?? state?.artifactsDir,
             level,
             requiredArtifacts: state?.requiredSkillArtifacts,
+            requiredSkills: state?.requiredSkills,
             mode: state?.skillRoutingMode ?? policy.policy.mode,
             enforceLevels: policy.policy.enforceLevels,
         });
@@ -2480,6 +2952,16 @@ const toolRunCommand = defineCommand({
         const report = await result.orchestrator.run(result.plan, {
             dryRun: isTruthyFlag(args['dry-run']),
         });
+        if (toolEvidenceRunCompletesOpenTask(report)) {
+            const writer = new WorkflowArtifactWriter(SCALE_DIR);
+            const current = writer.readCurrentState();
+            if (current?.taskId === report.taskId) {
+                writer.updateCurrentState({
+                    taskId: report.taskId,
+                    openTasks: removeWorkflowOpenTask(current.openTasks, 'tool-evidence'),
+                });
+            }
+        }
         if (args.json) {
             console.log(JSON.stringify(report, null, 2));
         }
@@ -2729,6 +3211,7 @@ const main = defineCommand({
         stats,
         preflight,
         governance,
+        artifact,
         assets,
         standards,
         metrics,
@@ -2737,6 +3220,8 @@ const main = defineCommand({
         status,
         workflow,
         evidence,
+        diagnose,
+        tdd,
         tool,
         skill,
         skills: skill,