@hongmaple0820/scale-engine 0.17.0 → 0.19.0

package/dist/api/cli.js

@@ -20,7 +20,7 @@ import { createSkillPlan, evaluateSkillGate, loadSkillRoutingPolicy, skillPlanMa
 import { createAdapter, SUPPORTED_AGENTS } from '../adapters/index.js';
 import { LessonExtractor, RuleProposer, HookGenerator, EvolutionEngine } from '../evolution/EvolutionEngine.js';
 import { Doctor } from './doctor.js';
-import { quickStart, detectPlatform } from './quickstart.js';
+import { quickStart, detectPlatform, governanceNextSteps } from './quickstart.js';
 import { SkillDiscovery } from '../skills/SkillDiscovery.js';
 import { inspectRequiredWorkflowSkills, inspectWorkflowSkills } from '../skills/SkillDoctor.js';
 import { evaluateSkillInstallSafety, listSkillRepositoryEntries, recommendSkillWorkflow, renderSkillRepositoryMarkdown, } from '../skills/SkillRepository.js';
@@ -30,7 +30,7 @@ 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';
@@ -47,11 +47,16 @@ 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 { inspectWorkspaceSafety } from '../workflow/WorkspaceSafety.js';
+import { RuntimeEvidenceLedger, SessionLedger, doctorRuntimeEvidence, evaluateFinalReportReadiness, } from '../runtime/index.js';
+import { MemoryFabric, doctorMemoryFabric, renderContextPackMarkdown, renderMemoryLearningCandidateMarkdown, settleMemoryLearning, } from '../memory/index.js';
 import { resolveWorkspaceTopology, workspaceTopologyPath, workspaceTopologyTemplate, } from '../workflow/WorkspaceTopology.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { isAbsolute, 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)
@@ -96,6 +101,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') {
@@ -109,15 +134,15 @@ function evaluateEngineeringStandardsGate(options) {
     }
     const settlement = options.settle && options.artifactsDir
         ? settleEngineeringStandards({
-            projectDir: PROJECT_DIR,
-            scaleDir: SCALE_DIR,
+            projectDir: options.projectDir ?? PROJECT_DIR,
+            scaleDir: options.scaleDir ?? SCALE_DIR,
             taskId: options.taskId,
             artifactsDir: options.artifactsDir,
         })
         : undefined;
     const doctor = settlement?.doctor ?? doctorEngineeringStandards({
-        projectDir: PROJECT_DIR,
-        scaleDir: SCALE_DIR,
+        projectDir: options.projectDir ?? PROJECT_DIR,
+        scaleDir: options.scaleDir ?? SCALE_DIR,
     });
     return {
         mode,
@@ -129,6 +154,16 @@ function evaluateEngineeringStandardsGate(options) {
         standardsImpactPath: settlement?.standardsImpactPath,
     };
 }
+function skippedEngineeringStandardsGate(reason, policy) {
+    void reason;
+    return {
+        mode: normalizeEngineeringStandardsGateMode(policy.engineeringStandardsGate),
+        checked: false,
+        blocked: false,
+        ok: true,
+        findings: [],
+    };
+}
 function normalizeEngineeringStandardsGateMode(value) {
     return value === 'off' || value === 'block' ? value : 'warn';
 }
@@ -172,6 +207,23 @@ function createEngine() {
     });
     return { eventBus, store, fsm, gateway, roleGate, kb, ctx, fsmAgentBridge, workflowEngine };
 }
+function resolveScaleDirForProject(projectDir) {
+    return isAbsolute(SCALE_DIR) ? SCALE_DIR : join(projectDir, SCALE_DIR);
+}
+function createVerificationWorkflowEngine(scaleDir) {
+    ensureDir(scaleDir);
+    const eventBus = new EventBus({ eventsDir: join(scaleDir, 'events') });
+    const capabilityRegistry = new CapabilityRegistry(eventBus);
+    const skillRegistry = new SkillRegistry(eventBus);
+    registerCoreSkills(skillRegistry);
+    registerExternalSkills(skillRegistry, eventBus);
+    return new WorkflowEngine({
+        eventBus,
+        capabilityRegistry,
+        skillRegistry,
+        scaleDir,
+    });
+}
 // ============================================================================
 // session commands
 // ============================================================================
@@ -1357,6 +1409,7 @@ function normalizeWorkspaceTopologyKind(value) {
 const preflight = defineCommand({
     meta: { name: 'preflight', description: 'Run service-aware verification without a task artifact' },
     args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
         'build-cmd': { type: 'string', description: 'Override build command' },
         'lint-cmd': { type: 'string', description: 'Override lint command' },
         'test-cmd': { type: 'string', description: 'Override test command' },
@@ -1369,18 +1422,32 @@ const preflight = defineCommand({
         json: { type: 'boolean', default: false },
     },
     async run({ args }) {
-        const { workflowEngine } = getEngine();
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const scaleDir = resolveScaleDirForProject(projectDir);
+        const workflowEngine = createVerificationWorkflowEngine(scaleDir);
         const preflightProfile = normalizePreflightProfile(args['preflight-profile']);
-        const gateStages = gatesForPreflightProfile(preflightProfile);
         const resolved = resolveVerificationTargets({
-            projectDir: PROJECT_DIR,
-            scaleDir: SCALE_DIR,
+            projectDir,
+            scaleDir,
             profile: args.profile,
             service: args.service,
         });
-        const engineeringStandards = evaluateEngineeringStandardsGate({
-            policy: resolved.policy,
-        });
+        let gateStages = gatesForPreflightProfile(preflightProfile);
+        if (resolved.targets.some(target => target.config.smoke)) {
+            gateStages = ['G8'];
+        }
+        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 workspaceSafety = inspectWorkspaceSafety(projectDir);
+        const engineeringStandards = workspaceSafety.blocked
+            ? skippedEngineeringStandardsGate('Workspace has unresolved git conflicts; resolve them before standards scanning.', resolved.policy)
+            : evaluateEngineeringStandardsGate({
+                policy: resolved.policy,
+                projectDir,
+                scaleDir,
+            });
         const targetResults = [];
         if (!args.json) {
             console.log('\nSCALE Preflight');
@@ -1389,6 +1456,9 @@ const preflight = defineCommand({
             console.log(`  Profile: ${resolved.profileName}`);
             console.log(`  Preflight profile: ${preflightProfile}`);
             console.log(`  Gates: ${gateStages.join(', ')}`);
+            if (workspaceSafety.blocked) {
+                console.log(`  Workspace safety: BLOCKED - ${workspaceSafety.message}`);
+            }
             if (engineeringStandards.checked) {
                 const status = engineeringStandards.blocked ? 'BLOCKED' : engineeringStandards.ok ? 'OK' : 'WARN';
                 console.log(`  Engineering standards: ${status} (${engineeringStandards.mode})`);
@@ -1397,7 +1467,7 @@ const preflight = defineCommand({
                 console.log('  Engineering standards: skipped');
             }
         }
-        for (const target of resolved.targets) {
+        for (const target of commandTargetsSkipped || workspaceSafety.blocked ? [] : resolved.targets) {
             if (!args.json) {
                 const label = target.service ? `${target.service.name} (${target.service.path})` : 'root';
                 console.log(`\n  Target: ${label}`);
@@ -1408,6 +1478,12 @@ const preflight = defineCommand({
                 lint: args['lint-cmd'] ?? target.config.lint,
                 test: args['test-cmd'] ?? target.config.test,
                 coverage: args['coverage-cmd'] ?? target.config.coverage,
+                smoke: target.config.smoke,
+                runtimeEvidence: {
+                    projectDir,
+                    scaleDir,
+                    profile: resolved.profileName,
+                },
                 tddEvidence: args['tdd-evidence'],
                 tddStrict: isTruthyFlag(args['tdd-strict']),
                 gates: gateStages,
@@ -1415,7 +1491,7 @@ const preflight = defineCommand({
             const passed = gates.every(gate => gate.passed);
             targetResults.push({
                 service: target.service?.name,
-                cwd: target.config.cwd ?? PROJECT_DIR,
+                cwd: target.config.cwd ?? projectDir,
                 gates,
                 passed,
             });
@@ -1427,8 +1503,8 @@ const preflight = defineCommand({
                 }
             }
         }
-        const passed = targetResults.length > 0 &&
-            targetResults.every(target => target.passed) &&
+        const passed = (targetResults.length === 0 || targetResults.every(target => target.passed)) &&
+            !workspaceSafety.blocked &&
             !engineeringStandards.blocked;
         const result = {
             phase: 'PREFLIGHT',
@@ -1437,8 +1513,10 @@ const preflight = defineCommand({
             gates: gateStages,
             services: targetResults.map(target => target.service).filter(Boolean),
             policy: resolved.policy,
+            workspaceSafety,
             engineeringStandards,
             targets: targetResults,
+            commandTargetsSkipped,
             passed,
         };
         if (args.json) {
@@ -1471,7 +1549,7 @@ const status = defineCommand({
         const latestTask = tasks[0];
         const taskPayload = latestTask?.payload;
         const workflowState = new WorkflowArtifactWriter(SCALE_DIR).readCurrentState();
-        const currentOpenTasks = workflowState?.taskId === latestTask?.id ? workflowState.openTasks ?? [] : [];
+        const currentOpenTasks = workflowState?.openTasks ?? [];
         const nextOpenTask = nextWorkflowOpenTask(currentOpenTasks);
         const blockers = [];
         const latestBlockingEvidence = latestEvidence.find(record => !record.passed);
@@ -1487,16 +1565,16 @@ const status = defineCommand({
             blockers.push(`Task ${latestTask.id} has no persisted review evidence`);
         }
         const nextCommand = (() => {
+            if (nextOpenTask?.kind === 'command')
+                return nextOpenTask.value;
+            if (nextOpenTask?.kind === 'blocker')
+                return `Resolve workflow blocker: ${nextOpenTask.value}`;
             if (!specs[0])
                 return 'scale define "<feature>" --description "<what to build>"';
             if (!plans[0])
                 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')
@@ -1543,7 +1621,7 @@ const status = defineCommand({
                 level: workflowState.level,
                 phase: workflowState.phase,
                 artifactsDir: workflowState.artifactsDir,
-                openTasks: workflowState.openTasks,
+                openTasks: workflowState.openTasks ?? [],
                 skillIntents: workflowState.skillIntents,
             } : null,
             blockers,
@@ -1575,7 +1653,7 @@ const status = defineCommand({
             for (const blocker of blockers)
                 console.log(`  - ${blocker}`);
         }
-        if (result.workflowState?.openTasks.length) {
+        if ((result.workflowState?.openTasks.length ?? 0) > 0) {
             console.log('\nOpen Tasks:');
             for (const task of result.workflowState.openTasks)
                 console.log(`  - ${task}`);
@@ -1678,8 +1756,8 @@ const init = defineCommand({
             console.log(`   Data dir:      ${result.scaleDir}`);
             console.log(`   Scenario:      ${scenarioMode}`);
             console.log(`\n📋 Next steps:`);
-            console.log(`   → scale doctor`);
-            console.log(`   → scale create Spec "<feature name>"`);
+            for (const step of governanceNextSteps())
+                console.log(`   → ${step}`);
             return;
         }
         // One-click quick start mode
@@ -1689,7 +1767,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,
@@ -1701,8 +1779,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}`);
@@ -1748,7 +1829,7 @@ const init = defineCommand({
                 scaleDir: result.scaleDir,
                 created: result.created,
                 skipped: result.skipped,
-                nextSteps: ['scale doctor', 'scale create Spec "<feature name>"'],
+                nextSteps: governanceNextSteps(),
             }, null, 2));
             return;
         }
@@ -1765,8 +1846,8 @@ const init = defineCommand({
         console.log(`\n📖 Knowledge: ${result.knowledgeDocPath}`);
         console.log(`\n📂 Data dir:  ${result.scaleDir}`);
         console.log(`\n📋 Next steps:`);
-        console.log(`   → scale doctor`);
-        console.log(`   → scale create Spec "<feature name>"`);
+        for (const step of governanceNextSteps())
+            console.log(`   → ${step}`);
     },
 });
 // ============================================================================
@@ -2056,6 +2137,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({
@@ -2221,6 +2478,373 @@ const evidence = defineCommand({
     subCommands: { list: evidenceList, show: evidenceShow },
 });
 // ============================================================================
+// runtime command - session ledger + completion evidence
+// ============================================================================
+function normalizeRuntimeEvidenceKind(value) {
+    const normalized = String(value ?? 'command').trim();
+    const allowed = ['command', 'gate', 'tool', 'skill', 'mcp', 'browser', 'desktop', 'manual', 'final-report'];
+    if (allowed.includes(normalized))
+        return normalized;
+    throw new Error(`Invalid runtime evidence kind "${normalized}"; expected ${allowed.join(', ')}.`);
+}
+function normalizeRuntimeEvidenceStatus(value) {
+    const normalized = String(value ?? '').trim();
+    if (normalized === 'passed' || normalized === 'failed' || normalized === 'skipped')
+        return normalized;
+    throw new Error(`Invalid runtime evidence status "${normalized}"; expected passed, failed, or skipped.`);
+}
+function normalizeRuntimeSessionStatus(value) {
+    const normalized = String(value ?? 'completed').trim();
+    if (normalized === 'active' || normalized === 'completed' || normalized === 'failed' || normalized === 'abandoned')
+        return normalized;
+    throw new Error(`Invalid runtime session status "${normalized}"; expected active, completed, failed, or abandoned.`);
+}
+const runtimeStart = defineCommand({
+    meta: { name: 'start', description: 'Start a runtime session ledger' },
+    args: {
+        'session-id': { type: 'string', description: 'Session id; generated when omitted' },
+        'task-id': { type: 'string', description: 'Task id linked to this session' },
+        agent: { type: 'string', description: 'Agent name' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        summary: { type: 'string', description: 'Short session summary' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const ledger = new SessionLedger({ projectDir: PROJECT_DIR, scaleDir: SCALE_DIR });
+        const session = ledger.start({
+            sessionId: args['session-id'],
+            taskId: args['task-id'],
+            agent: args.agent,
+            level: normalizeTaskArtifactLevel(args.level),
+            summary: args.summary,
+        });
+        if (args.json) {
+            console.log(JSON.stringify(session, null, 2));
+            return;
+        }
+        console.log(`Runtime session started: ${session.sessionId}`);
+        if (session.taskId)
+            console.log(`  Task: ${session.taskId}`);
+        if (session.level)
+            console.log(`  Level: ${session.level}`);
+        console.log(`  Events: ${ledger.sessionFile(session.sessionId)}`);
+    },
+});
+const runtimeEnd = defineCommand({
+    meta: { name: 'end', description: 'End the current or named runtime session' },
+    args: {
+        'session-id': { type: 'string', description: 'Session id; current session is used when omitted' },
+        status: { type: 'string', default: 'completed', description: 'completed, failed, or abandoned' },
+        summary: { type: 'string', description: 'Completion summary' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const ledger = new SessionLedger({ projectDir: PROJECT_DIR, scaleDir: SCALE_DIR });
+        const sessionId = args['session-id'] ?? ledger.current()?.sessionId;
+        if (!sessionId) {
+            console.error('No runtime session id provided and no current runtime session exists.');
+            process.exit(1);
+        }
+        const session = ledger.end(sessionId, normalizeRuntimeSessionStatus(args.status), args.summary);
+        if (args.json) {
+            console.log(JSON.stringify(session, null, 2));
+            return;
+        }
+        console.log(`Runtime session ended: ${session.sessionId}`);
+        console.log(`  Status: ${session.status}`);
+    },
+});
+const runtimeRecord = defineCommand({
+    meta: { name: 'record', description: 'Record command, gate, tool, browser, skill, or manual runtime evidence' },
+    args: {
+        'task-id': { type: 'string', description: 'Task id linked to this evidence' },
+        'session-id': { type: 'string', description: 'Session id linked to this evidence' },
+        kind: { type: 'string', default: 'command', description: 'command, gate, tool, skill, mcp, browser, desktop, manual, final-report' },
+        title: { type: 'string', required: true, description: 'Evidence title' },
+        status: { type: 'string', required: true, description: 'passed, failed, or skipped' },
+        command: { type: 'string', description: 'Exact command or tool invocation, with secrets redacted by SCALE' },
+        'exit-code': { type: 'string', description: 'Exit code when applicable' },
+        summary: { type: 'string', required: true, description: 'Short output summary' },
+        artifacts: { type: 'string', description: 'Comma-separated artifact paths' },
+        'metadata-json': { type: 'string', default: '{}', description: 'Additional JSON metadata' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const current = new SessionLedger({ projectDir: PROJECT_DIR, scaleDir: SCALE_DIR }).current();
+        let metadata = {};
+        try {
+            metadata = JSON.parse(String(args['metadata-json'] ?? '{}'));
+        }
+        catch {
+            console.error('--metadata-json must be valid JSON.');
+            process.exit(1);
+        }
+        const exitCode = args['exit-code'] === undefined || args['exit-code'] === ''
+            ? undefined
+            : Number.parseInt(String(args['exit-code']), 10);
+        if (exitCode !== undefined && Number.isNaN(exitCode)) {
+            console.error('--exit-code must be a number.');
+            process.exit(1);
+        }
+        const ledger = new RuntimeEvidenceLedger({ projectDir: PROJECT_DIR, scaleDir: SCALE_DIR });
+        const record = ledger.record({
+            taskId: args['task-id'] ?? current?.taskId,
+            sessionId: args['session-id'] ?? current?.sessionId,
+            kind: normalizeRuntimeEvidenceKind(args.kind),
+            title: args.title,
+            status: normalizeRuntimeEvidenceStatus(args.status),
+            command: args.command,
+            exitCode,
+            summary: args.summary,
+            artifacts: parseCommaList(args.artifacts),
+            metadata,
+        });
+        if (record.sessionId) {
+            new SessionLedger({ projectDir: PROJECT_DIR, scaleDir: SCALE_DIR }).append(record.sessionId, {
+                type: 'evidence.recorded',
+                message: `${record.status}: ${record.title}`,
+                data: {
+                    evidenceId: record.id,
+                    kind: record.kind,
+                    taskId: record.taskId,
+                },
+            });
+        }
+        if (args.json) {
+            console.log(JSON.stringify(record, null, 2));
+            return;
+        }
+        console.log(`Runtime evidence recorded: ${record.id}`);
+        console.log(`  Status: ${record.status}`);
+        console.log(`  Kind: ${record.kind}`);
+        if (record.redactionApplied)
+            console.log('  Redaction: applied');
+    },
+});
+const runtimeDoctor = defineCommand({
+    meta: { name: 'doctor', description: 'Check runtime session and completion evidence' },
+    args: {
+        'task-id': { type: 'string', description: 'Task id to inspect' },
+        'session-id': { type: 'string', description: 'Session id to inspect' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const report = doctorRuntimeEvidence({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            taskId: args['task-id'],
+            sessionId: args['session-id'],
+            level: normalizeTaskArtifactLevel(args.level),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            if (report.blocked)
+                process.exitCode = 1;
+            return;
+        }
+        console.log('\nSCALE Runtime Doctor');
+        console.log(`  Evidence: ${report.evidence.total} total, ${report.evidence.passed} passed, ${report.evidence.failed} failed, ${report.evidence.skipped} skipped`);
+        for (const check of report.checks) {
+            console.log(`  [${check.status.toUpperCase()}] ${check.name}: ${check.message}`);
+            if (check.fix)
+                console.log(`    Fix: ${check.fix}`);
+        }
+        if (report.blocked)
+            process.exitCode = 1;
+    },
+});
+const runtimeFinalCheck = defineCommand({
+    meta: { name: 'final-check', description: 'Block final delivery claims without passed runtime evidence' },
+    args: {
+        'task-id': { type: 'string', description: 'Task id to inspect' },
+        'session-id': { type: 'string', description: 'Session id to inspect' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const readiness = evaluateFinalReportReadiness({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            taskId: args['task-id'],
+            sessionId: args['session-id'],
+            level: normalizeTaskArtifactLevel(args.level),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(readiness, null, 2));
+            if (readiness.blocked)
+                process.exitCode = 1;
+            return;
+        }
+        console.log('\nSCALE Runtime Final Check');
+        console.log(`  Ready: ${readiness.ready}`);
+        for (const reason of readiness.reasons)
+            console.log(`  [BLOCKER] ${reason}`);
+        if (readiness.blocked)
+            process.exitCode = 1;
+    },
+});
+const runtime = defineCommand({
+    meta: { name: 'runtime', description: 'Runtime session ledger and completion evidence governance' },
+    subCommands: {
+        start: runtimeStart,
+        end: runtimeEnd,
+        record: runtimeRecord,
+        doctor: runtimeDoctor,
+        'final-check': runtimeFinalCheck,
+    },
+});
+// ============================================================================
+// memory command - runtime evidence + knowledge + graph context packs
+// ============================================================================
+function parseMemoryBudget(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    const parsed = Number.parseInt(String(value), 10);
+    if (Number.isNaN(parsed) || parsed <= 0) {
+        throw new Error('--budget must be a positive integer.');
+    }
+    return parsed;
+}
+const memoryPack = defineCommand({
+    meta: { name: 'pack', description: 'Build a compact context pack from runtime evidence, session events, knowledge, and graph status' },
+    args: {
+        task: { type: 'string', required: true, description: 'Current task or question' },
+        'task-id': { type: 'string', description: 'Task id to scope evidence and session data' },
+        'session-id': { type: 'string', description: 'Session id to scope session events' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        files: { type: 'string', description: 'Comma-separated files or modules in scope' },
+        budget: { type: 'string', description: 'Maximum estimated tokens for the context pack' },
+        json: { type: 'boolean', default: false },
+    },
+    async run({ args }) {
+        let budgetTokens;
+        try {
+            budgetTokens = parseMemoryBudget(args.budget);
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        const { kb } = getEngine();
+        const pack = await new MemoryFabric({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            knowledgeBase: kb,
+        }).createContextPack({
+            task: args.task,
+            taskId: args['task-id'],
+            sessionId: args['session-id'],
+            level: normalizeTaskArtifactLevel(args.level),
+            files: parseCommaList(args.files),
+            budgetTokens,
+        });
+        if (args.json) {
+            console.log(JSON.stringify(pack, null, 2));
+            return;
+        }
+        console.log(renderContextPackMarkdown(pack));
+    },
+});
+const memoryDoctor = defineCommand({
+    meta: { name: 'doctor', description: 'Check whether a task context pack is available and within token budget' },
+    args: {
+        task: { type: 'string', required: true, description: 'Current task or question' },
+        'task-id': { type: 'string', description: 'Task id to scope evidence and session data' },
+        'session-id': { type: 'string', description: 'Session id to scope session events' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        files: { type: 'string', description: 'Comma-separated files or modules in scope' },
+        budget: { type: 'string', description: 'Maximum estimated tokens for the context pack' },
+        json: { type: 'boolean', default: false },
+    },
+    async run({ args }) {
+        let budgetTokens;
+        try {
+            budgetTokens = parseMemoryBudget(args.budget);
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        const { kb } = getEngine();
+        const report = await doctorMemoryFabric({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            knowledgeBase: kb,
+        }, {
+            task: args.task,
+            taskId: args['task-id'],
+            sessionId: args['session-id'],
+            level: normalizeTaskArtifactLevel(args.level),
+            files: parseCommaList(args.files),
+            budgetTokens,
+        });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            if (!report.ok)
+                process.exitCode = 1;
+            return;
+        }
+        console.log('\nSCALE Memory Doctor');
+        console.log(`  Budget: ${report.pack.budget.used}/${report.pack.budget.limit} estimated tokens`);
+        for (const check of report.checks) {
+            console.log(`  [${check.status.toUpperCase()}] ${check.name}: ${check.message}`);
+        }
+        if (!report.ok)
+            process.exitCode = 1;
+    },
+});
+const memorySettle = defineCommand({
+    meta: { name: 'settle', description: 'Settle runtime evidence into a reviewable memory learning candidate' },
+    args: {
+        task: { type: 'string', required: true, description: 'Current task or question' },
+        'task-id': { type: 'string', description: 'Task id to scope evidence and session data' },
+        'session-id': { type: 'string', description: 'Session id to scope session events' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        files: { type: 'string', description: 'Comma-separated files or modules in scope' },
+        budget: { type: 'string', description: 'Maximum estimated tokens for the context pack' },
+        json: { type: 'boolean', default: false },
+    },
+    async run({ args }) {
+        let budgetTokens;
+        try {
+            budgetTokens = parseMemoryBudget(args.budget);
+        }
+        catch (e) {
+            console.error(e.message);
+            process.exit(1);
+        }
+        const { kb } = getEngine();
+        const pack = await new MemoryFabric({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            knowledgeBase: kb,
+        }).createContextPack({
+            task: args.task,
+            taskId: args['task-id'],
+            sessionId: args['session-id'],
+            level: normalizeTaskArtifactLevel(args.level),
+            files: parseCommaList(args.files),
+            budgetTokens,
+        });
+        const settlement = settleMemoryLearning({
+            projectDir: PROJECT_DIR,
+            scaleDir: SCALE_DIR,
+            pack,
+        });
+        if (args.json) {
+            console.log(JSON.stringify(settlement, null, 2));
+            return;
+        }
+        console.log(renderMemoryLearningCandidateMarkdown(settlement.candidate));
+        console.log(`\nWrote: ${settlement.files.markdown}`);
+    },
+});
+const memory = defineCommand({
+    meta: { name: 'memory', description: 'Memory Fabric context packs and budget diagnostics' },
+    subCommands: { pack: memoryPack, doctor: memoryDoctor, settle: memorySettle },
+});
+// ============================================================================
 // out-of-scope command — 借鉴 mattpocock/skills 的 .out-of-scope/ 设计
 // ============================================================================
 const outOfScopeAdd = defineCommand({
@@ -2453,6 +3077,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,
         });
@@ -3005,6 +3630,7 @@ const main = defineCommand({
         stats,
         preflight,
         governance,
+        artifact,
         assets,
         standards,
         metrics,
@@ -3013,6 +3639,8 @@ const main = defineCommand({
         status,
         workflow,
         evidence,
+        runtime,
+        memory,
         diagnose,
         tdd,
         tool,