@hongmaple0820/scale-engine 0.18.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';
@@ -49,9 +49,12 @@ 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';
@@ -131,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,
@@ -151,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';
 }
@@ -194,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
 // ============================================================================
@@ -1379,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' },
@@ -1391,22 +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,
         });
+        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 engineeringStandards = evaluateEngineeringStandardsGate({
-            policy: resolved.policy,
-        });
+        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');
@@ -1415,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})`);
@@ -1423,7 +1467,7 @@ const preflight = defineCommand({
                 console.log('  Engineering standards: skipped');
             }
         }
-        for (const target of commandTargetsSkipped ? [] : 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}`);
@@ -1434,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,
@@ -1441,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,
             });
@@ -1454,6 +1504,7 @@ const preflight = defineCommand({
             }
         }
         const passed = (targetResults.length === 0 || targetResults.every(target => target.passed)) &&
+            !workspaceSafety.blocked &&
             !engineeringStandards.blocked;
         const result = {
             phase: 'PREFLIGHT',
@@ -1462,6 +1513,7 @@ const preflight = defineCommand({
             gates: gateStages,
             services: targetResults.map(target => target.service).filter(Boolean),
             policy: resolved.policy,
+            workspaceSafety,
             engineeringStandards,
             targets: targetResults,
             commandTargetsSkipped,
@@ -1497,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);
@@ -1513,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')
@@ -1569,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,
@@ -1601,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}`);
@@ -1704,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
@@ -1777,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;
         }
@@ -1794,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}`);
     },
 });
 // ============================================================================
@@ -2426,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({
@@ -3220,6 +3639,8 @@ const main = defineCommand({
         status,
         workflow,
         evidence,
+        runtime,
+        memory,
         diagnose,
         tdd,
         tool,