@hongmaple0820/scale-engine 0.26.0 → 0.27.1

package/README.en.md

@@ -1,14 +1,14 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.26.0-orange?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-0.27.1-orange?style=flat-square" alt="version" />
   <img src="https://img.shields.io/badge/platforms-22-blue?style=flat-square" alt="platforms" />
   <img src="https://img.shields.io/badge/agents-12-blue?style=flat-square" alt="agents" />
   <img src="https://img.shields.io/badge/workflows-10-green?style=flat-square" alt="workflows" />
   <img src="https://img.shields.io/badge/detectors-19-red?style=flat-square" alt="detectors" />
   <img src="https://img.shields.io/badge/tests-verified-brightgreen?style=flat-square" alt="tests" />
-  <img src="https://img.shields.io/badge/npm-0.26.0-cb3837?style=flat-square&logo=npm" alt="npm" />
+  <img src="https://img.shields.io/badge/npm-0.27.1-cb3837?style=flat-square&logo=npm" alt="npm" />
 </p>
 
-# SCALE Engine v0.26.0
+# SCALE Engine v0.27.1
 
 SCALE Engine makes AI coding agents follow engineering rules through executable workflow gates, evidence files, and review constraints instead of relying on prompt discipline alone. It helps humans see what the agent explored, planned, verified, skipped, and why a task is or is not ready to ship.
 
@@ -17,6 +17,74 @@ Mirror: https://gitee.com/hongmaple/scale-engine
 npm: https://www.npmjs.com/package/@hongmaple0820/scale-engine
 Language: [English](README.en.md) | [Chinese](README.md)
 
+## 0.27.0 AI OS Runtime
+
+0.27.0 turns the AI Engineering OS direction into one executable entry point: `scale ai-os plan`. It creates a unified task plan with progressive governance mode, Context Compiler budget output, Memory Provider recall, Skill Routing execution steps, and Governance ROI. An agent can see which context to load, which capabilities to use, what evidence is required, and which risks escalate gates before it starts the task.
+
+```bash
+scale ai-os plan \
+  --task-id TASK-123 \
+  --task "Fix OAuth callback auth token handling and verify browser callback flow" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --budget 8000 \
+  --json
+```
+
+This is not a claim that SCALE replaces human judgment. It is the first testable, explainable, and measurable runtime planning layer for the AI Engineering OS direction.
+
+The near-term target is a one-week push from `ai-os plan` to a runnable beta loop: `ai-os run`, memory providers, Context Compiler v2, Skill Router v2, Adaptive Workflow, Failure Learning, Dashboard, migration, and benchmark evidence. The long-range target is an AI Engineering OS beta in 8-12 weeks, a stable governance runtime in 3-6 months, and a cross-agent engineering operating layer in 6-12 months. See the full roadmap in [AI Engineering OS Strategic Positioning](docs/AI_ENGINEERING_OS_POSITIONING.md).
+
+The current 0.27.0 beta runtime now includes the controlled run entry point: `scale ai-os run --dry-run` reuses the unified plan, produces execution steps, evidence requirements, next actions, and writes the run report to `.scale/ai-os/runs/`. When real verification is required, use guarded mode with explicit `--verify` commands. Commands run through the safe runner by default and are recorded as runtime evidence; failed verification returns a `blocked` JSON report and a non-zero CLI exit code.
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "Fix OAuth callback auth token handling and verify browser callback flow" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --dry-run \
+  --json
+```
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "Fix OAuth callback auth token handling and verify browser callback flow" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --mode guarded \
+  --verify "npm test -- tests/auth/oauth.test.ts" \
+  --json
+```
+
+After multiple runs, use the dashboard to summarize ready/blocked runs, verification commands, pending evidence, and failure learning:
+
+```bash
+scale ai-os dashboard --json
+```
+
+Before a release or milestone review, run the fixed benchmark scenarios to compare context, memory, skill, governance, and dashboard metrics:
+
+```bash
+scale ai-os benchmark --json
+```
+
+Before adopting the 0.27.0 beta runtime in an existing project, create or verify the AI OS runtime state directories:
+
+```bash
+scale ai-os migrate --json
+```
+
+For project-level readiness, run the AI OS doctor. It checks runtime directories, run history, dashboard health, benchmark freshness, and prints the next required action in English or Chinese:
+
+```bash
+scale ai-os doctor --lang en --json
+scale ai-os doctor --lang zh
+```
+
+The standard upgrade path also surfaces this readiness. `scale upgrade check --json` now includes the AI OS doctor result, and `scale upgrade plan --json` adds explicit `ai-os migrate` / `ai-os doctor` steps when a project has not yet adopted the runtime state.
+
 ## Community
 
 SCALE Engine is an engineering workflow governance project for real AI-agent delivery. Contributions, issues, PRs, governance-pack ideas, and field reports are welcome through the source repositories. Chinese users can also follow the WeChat public account for updates, examples, and community entry points.

package/README.md

@@ -1,14 +1,14 @@
 <p align="center">
-  <img src="https://img.shields.io/badge/version-0.26.0-orange?style=flat-square" alt="version" />
+  <img src="https://img.shields.io/badge/version-0.27.1-orange?style=flat-square" alt="version" />
   <img src="https://img.shields.io/badge/platforms-22-blue?style=flat-square" alt="platforms" />
   <img src="https://img.shields.io/badge/agents-12-blue?style=flat-square" alt="agents" />
   <img src="https://img.shields.io/badge/workflows-10-green?style=flat-square" alt="workflows" />
   <img src="https://img.shields.io/badge/detectors-19-red?style=flat-square" alt="detectors" />
   <img src="https://img.shields.io/badge/tests-verified-brightgreen?style=flat-square" alt="tests" />
-  <img src="https://img.shields.io/badge/npm-0.26.0-cb3837?style=flat-square&logo=npm" alt="npm" />
+  <img src="https://img.shields.io/badge/npm-0.27.1-cb3837?style=flat-square&logo=npm" alt="npm" />
 </p>
 
-# SCALE Engine v0.26.0
+# SCALE Engine v0.27.1
 
 SCALE Engine 让 AI Agent 不再只靠“自觉”遵守工程规范。它把探索、规划、实现、验证、评审、发版这些要求变成可执行的命令、门禁和证据文件，让人类可以看见 Agent 做了什么、跳过了什么、为什么能交付或不能交付。
 
@@ -17,6 +17,74 @@ SCALE Engine 让 AI Agent 不再只靠“自觉”遵守工程规范。它把探
 npm：https://www.npmjs.com/package/@hongmaple0820/scale-engine
 语言：[中文](README.md) | [English](README.en.md)
 
+## 0.27.0 AI OS Runtime
+
+0.27.0 把战略方向落成了一个可执行入口：`scale ai-os plan`。它会在一次命令里同时生成风险治理模式、Context Compiler 预算结果、Memory Provider 召回结果、Skill Routing 执行计划和 Governance ROI，让 Agent 在开始任务前就知道应该加载什么上下文、调用什么能力、补什么证据、哪些风险会升级门禁。
+
+```bash
+scale ai-os plan \
+  --task-id TASK-123 \
+  --task "修复 OAuth callback auth token 并验证浏览器回调流程" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --budget 8000 \
+  --json
+```
+
+这不是“完全替代人类判断”的声明；它是把 AI Engineering OS 的核心闭环先做成可测试、可解释、可度量的运行时规划层。
+
+短期目标是用一周冲刺把 `ai-os plan` 推进到可运行的 beta 闭环：`ai-os run`、记忆供应商、Context Compiler v2、Skill Router v2、Adaptive Workflow、Failure Learning、Dashboard、迁移和 benchmark。远景目标是 8-12 周形成 AI Engineering OS beta，3-6 个月进入稳定治理运行时，6-12 个月沉淀为跨 Agent 的工程操作层。完整路线图见 [AI Engineering OS 战略定位](docs/AI_ENGINEERING_OS_POSITIONING.md)。
+
+当前 0.27.0 beta runtime 已包含受控运行入口：`scale ai-os run --dry-run` 会复用统一 plan，生成执行步骤、证据要求、下一步动作，并把运行报告写入 `.scale/ai-os/runs/`。需要真实验证时可切到 guarded 模式并显式传入 `--verify`，命令默认通过 safe runner 执行并写入 runtime evidence；验证失败时 JSON 报告会返回 `blocked`，CLI 退出码为非零。
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "修复 OAuth callback auth token 并验证浏览器回调流程" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --dry-run \
+  --json
+```
+
+```bash
+scale ai-os run \
+  --task-id TASK-123 \
+  --task "修复 OAuth callback auth token 并验证浏览器回调流程" \
+  --level L \
+  --files src/auth/oauth.ts,src/ui/callback.tsx \
+  --mode guarded \
+  --verify "npm test -- tests/auth/oauth.test.ts" \
+  --json
+```
+
+运行多次后可以用 dashboard 汇总 ready/blocked、验证命令、pending evidence 和 failure learning：
+
+```bash
+scale ai-os dashboard --json
+```
+
+发版或阶段验收前，用 benchmark 固定样例对比 context、memory、skill、governance 和 dashboard 指标：
+
+```bash
+scale ai-os benchmark --json
+```
+
+旧项目接入 0.27.0 beta runtime 前，可先创建或核验 AI OS 运行态目录：
+
+```bash
+scale ai-os migrate --json
+```
+
+项目级就绪检查可使用 AI OS doctor。它会检查运行态目录、运行历史、dashboard 健康度、benchmark 新鲜度，并按中英文输出下一步动作：
+
+```bash
+scale ai-os doctor --lang zh --json
+scale ai-os doctor --lang en
+```
+
+标准升级入口也会带出这项检查。`scale upgrade check --json` 会包含 AI OS doctor 结果；当项目尚未接入运行态目录时，`scale upgrade plan --json` 会补充明确的 `ai-os migrate` / `ai-os doctor` 步骤。
+
 ## 先怎么学
 
 如果你第一次接触 SCALE，不要从完整命令列表开始读。按这个顺序更容易掌握：

package/dist/api/cli.js

@@ -60,11 +60,12 @@ 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 { runSafeCommand } from '../tools/SafeCommandRunner.js';
 import { doctorHtmlArtifacts, renderHtmlArtifact, resolveHtmlArtifactForOpen, settleHtmlArtifacts, } from '../output/HTMLArtifactLayer.js';
 import { renderGovernanceDashboard } from '../output/GovernanceDashboard.js';
 import { cleanupWorkspaceLifecycle, inspectWorkspaceLifecycle, } from '../workflow/WorkspaceLifecycle.js';
 import { inspectWorkspaceSafety } from '../workflow/WorkspaceSafety.js';
-import { RuntimeEvidenceLedger, SessionLedger, doctorRuntimeEvidence, evaluateFinalReportReadiness, } from '../runtime/index.js';
+import { RuntimeEvidenceLedger, SessionLedger, createAiOsBenchmark, createAiOsDashboard, createAiOsDoctor, createAiOsMigration, createAiOsPlan, createAiOsRun, doctorRuntimeEvidence, evaluateFinalReportReadiness, } from '../runtime/index.js';
 import { MemoryFabric, MemoryBrain, doctorMemoryFabric, renderContextPackMarkdown, renderMemoryLearningCandidateMarkdown, inspectMemoryProviders, recallMemoryProviders, settleMemoryLearning, writeMemoryProvidersConfig, } from '../memory/index.js';
 import { resolveWorkspaceTopology, workspaceTopologyPath, workspaceTopologyTemplate, } from '../workflow/WorkspaceTopology.js';
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
@@ -663,14 +664,13 @@ const verifyTask = defineCommand({
         };
         // Helper: run command and capture exit code
         const runCmd = async (cmd) => {
-            const { spawn } = await import('node:child_process');
-            return new Promise((resolve) => {
-                const child = spawn(cmd, [], { shell: true, stdio: 'pipe' });
-                let output = '';
-                child.stdout?.on('data', (d) => (output += d));
-                child.stderr?.on('data', (d) => (output += d));
-                child.on('close', (code) => resolve({ exitCode: code ?? 1, output }));
-            });
+            try {
+                const result = await runSafeCommand(cmd);
+                return { exitCode: result.exitCode, output: [result.stdout, result.stderr].filter(Boolean).join('\n') };
+            }
+            catch (error) {
+                return { exitCode: 1, output: error instanceof Error ? error.message : String(error) };
+            }
         };
         // Run build
         if (!args['skip-build']) {
@@ -2907,6 +2907,246 @@ const governance = defineCommand({
     meta: { name: 'governance', description: 'Governance template pack tools' },
     subCommands: { diff: governanceDiff, mode: governanceModeCommand, roi: governanceRoiCommand },
 });
+const aiOsPlanCommand = defineCommand({
+    meta: { name: 'plan', description: 'Create a unified AI OS runtime plan for governance, context, memory, skills, and ROI' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        'task-id': { type: 'string', description: 'Task id' },
+        task: { type: 'string', required: true, description: 'Task or requirement description' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        files: { type: 'string', description: 'Comma-separated changed or target files' },
+        services: { type: 'string', description: 'Comma-separated affected services' },
+        budget: { type: 'string', description: 'Maximum estimated tokens for the context compiler' },
+        'requested-mode': { type: 'string', description: 'Requested governance mode: minimal, standard, expanded, or critical' },
+        json: { type: 'boolean', default: false },
+    },
+    async run({ args }) {
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const scaleDir = resolveScaleDirForProject(projectDir);
+        const plan = await createAiOsPlan({
+            projectDir,
+            scaleDir,
+            taskId: args['task-id'] ? String(args['task-id']) : undefined,
+            task: String(args.task),
+            level: normalizeTaskArtifactLevel(args.level),
+            files: parseCommaList(args.files),
+            services: parseCommaList(args.services),
+            budget: parsePositiveIntArg(args.budget, '--budget'),
+            requestedMode: normalizeGovernanceMode(args['requested-mode']),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(plan, null, 2));
+            return;
+        }
+        console.log('SCALE AI OS Runtime Plan');
+        console.log(`  Version: ${plan.version}`);
+        console.log(`  Task: ${plan.task.taskId ?? 'n/a'} ${plan.task.task}`);
+        console.log(`  Governance: ${plan.governance.effectiveMode}`);
+        console.log(`  Context: ${plan.context.totalEstimatedTokens}/${plan.context.task.budget} tokens; saved ${plan.context.compiler?.estimatedTokenSavings ?? 0}`);
+        console.log(`  Memory: ${plan.memory.items.length} item(s); providers ${plan.memory.providerOrder.join(' -> ')}`);
+        console.log(`  Skill steps: ${plan.skillPlan.executionPlan.steps.length}`);
+        console.log(`  ROI: ${plan.roi.summary.recommendation}`);
+        for (const recommendation of plan.recommendations)
+            console.log(`  recommendation: ${recommendation}`);
+    },
+});
+const aiOsRunCommand = defineCommand({
+    meta: { name: 'run', description: 'Run the AI OS beta loop in dry-run or guarded mode and write an execution report' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        'task-id': { type: 'string', description: 'Task id' },
+        task: { type: 'string', required: true, description: 'Task or requirement description' },
+        level: { type: 'string', default: 'M', description: 'Task level: S, M, L, or CRITICAL' },
+        files: { type: 'string', description: 'Comma-separated changed or target files' },
+        services: { type: 'string', description: 'Comma-separated affected services' },
+        budget: { type: 'string', description: 'Maximum estimated tokens for the context compiler' },
+        'requested-mode': { type: 'string', description: 'Requested governance mode: minimal, standard, expanded, or critical' },
+        verify: { type: 'string', description: 'Comma-separated guarded verification commands to run without shell by default' },
+        timeout: { type: 'string', description: 'Verification command timeout in milliseconds' },
+        mode: { type: 'string', description: 'Run mode: dry-run or guarded' },
+        'dry-run': { type: 'boolean', default: false, description: 'Force dry-run mode without executing external commands' },
+        'allow-shell': { type: 'boolean', default: false, description: 'Allow shell execution for trusted local guarded runs' },
+        json: { type: 'boolean', default: false },
+    },
+    async run({ args }) {
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const scaleDir = resolveScaleDirForProject(projectDir);
+        const report = await createAiOsRun({
+            projectDir,
+            scaleDir,
+            taskId: args['task-id'] ? String(args['task-id']) : undefined,
+            task: String(args.task),
+            level: normalizeTaskArtifactLevel(args.level),
+            files: parseCommaList(args.files),
+            services: parseCommaList(args.services),
+            budget: parsePositiveIntArg(args.budget, '--budget'),
+            requestedMode: normalizeGovernanceMode(args['requested-mode']),
+            mode: normalizeAiOsRunMode(args.mode, Boolean(args['dry-run'])),
+            verificationCommands: parseCommaList(args.verify),
+            commandTimeoutMs: parsePositiveIntArg(args.timeout, '--timeout'),
+            allowShell: Boolean(args['allow-shell']),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            if (report.status === 'blocked')
+                process.exitCode = 1;
+            return;
+        }
+        console.log('SCALE AI OS Runtime Run');
+        console.log(`  Version: ${report.version}`);
+        console.log(`  Mode: ${report.mode}`);
+        console.log(`  Status: ${report.status}`);
+        console.log(`  Task: ${report.plan.task.taskId ?? 'n/a'} ${report.plan.task.task}`);
+        console.log(`  Steps: ${report.steps.filter(step => step.status === 'passed').length} passed, ${report.steps.filter(step => step.status === 'planned').length} planned, ${report.steps.filter(step => step.status === 'blocked').length} blocked`);
+        console.log(`  Verification: ${report.verification.commands.filter(command => command.status === 'passed').length}/${report.verification.commands.length} passed`);
+        console.log(`  Evidence: ${report.evidence.produced.length} produced, ${report.evidence.pending.length} pending`);
+        console.log(`  Report: ${report.artifacts.runReport}`);
+        for (const action of report.nextActions.slice(0, 6))
+            console.log(`  next: ${action}`);
+        if (report.status === 'blocked')
+            process.exitCode = 1;
+    },
+});
+const aiOsDashboardCommand = defineCommand({
+    meta: { name: 'dashboard', description: 'Summarize AI OS runtime run reports and verification health' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        limit: { type: 'string', description: 'Maximum latest run rows to include' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const scaleDir = resolveScaleDirForProject(projectDir);
+        const dashboard = createAiOsDashboard({
+            projectDir,
+            scaleDir,
+            limit: parsePositiveIntArg(args.limit, '--limit'),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(dashboard, null, 2));
+            return;
+        }
+        console.log('SCALE AI OS Dashboard');
+        console.log(`  Health: ${dashboard.health.status} (${dashboard.health.score})`);
+        console.log(`  Runs: ${dashboard.summary.totalRuns} total, ${dashboard.summary.readyRuns} ready, ${dashboard.summary.blockedRuns} blocked`);
+        console.log(`  Verification: ${dashboard.summary.verificationCommands} command(s), ${dashboard.summary.failedVerificationCommands} failed`);
+        console.log(`  Failure learning: ${dashboard.summary.failureLearningCandidates} candidate(s)`);
+        for (const run of dashboard.latestRuns) {
+            console.log(`  [${run.status}] ${run.taskId ?? 'n/a'} ${run.task}`);
+        }
+        for (const recommendation of dashboard.recommendations)
+            console.log(`  recommendation: ${recommendation}`);
+        for (const warning of dashboard.warnings)
+            console.log(`  warning: ${warning}`);
+    },
+});
+const aiOsBenchmarkCommand = defineCommand({
+    meta: { name: 'benchmark', description: 'Run fixed AI OS beta benchmark scenarios for context, memory, skill, governance, and dashboard metrics' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        budget: { type: 'string', description: 'Scenario context budget' },
+        json: { type: 'boolean', default: false },
+    },
+    async run({ args }) {
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const scaleDir = resolveScaleDirForProject(projectDir);
+        const benchmark = await createAiOsBenchmark({
+            projectDir,
+            scaleDir,
+            budget: parsePositiveIntArg(args.budget, '--budget'),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(benchmark, null, 2));
+            return;
+        }
+        console.log('SCALE AI OS Benchmark');
+        console.log(`  Scenarios: ${benchmark.summary.scenarios}`);
+        console.log(`  Tokens: ${benchmark.summary.totalEstimatedTokens}/${benchmark.summary.totalBudget}; saved ${benchmark.summary.totalEstimatedTokenSavings}`);
+        console.log(`  Memory items: ${benchmark.summary.totalMemoryItems}`);
+        console.log(`  Skill steps: ${benchmark.summary.totalSkillSteps} (${benchmark.summary.requiredSkillSteps} required)`);
+        console.log(`  Governance modes: ${benchmark.summary.governanceModes.join(', ') || 'none'}`);
+        console.log(`  Dashboard health: ${benchmark.dashboard.health.status}`);
+        for (const scenario of benchmark.scenarios) {
+            console.log(`  [${scenario.governanceMode}] ${scenario.id}: tokens=${scenario.metrics.estimatedTokens}, skills=${scenario.metrics.skillSteps}, memory=${scenario.metrics.memoryItems}`);
+        }
+        for (const recommendation of benchmark.recommendations)
+            console.log(`  recommendation: ${recommendation}`);
+    },
+});
+const aiOsMigrateCommand = defineCommand({
+    meta: { name: 'migrate', description: 'Create or verify AI OS runtime state directories for this project' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const scaleDir = resolveScaleDirForProject(projectDir);
+        const report = createAiOsMigration({ projectDir, scaleDir });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            return;
+        }
+        console.log('SCALE AI OS Migration');
+        console.log(`  Status: ${report.status}`);
+        console.log(`  Created: ${report.created.length}`);
+        console.log(`  Existing: ${report.existing.length}`);
+        console.log(`  Report: ${report.files.migrationReport}`);
+        for (const action of report.nextActions)
+            console.log(`  next: ${action}`);
+        for (const warning of report.warnings)
+            console.log(`  warning: ${warning}`);
+    },
+});
+const aiOsDoctorCommand = defineCommand({
+    meta: { name: 'doctor', description: 'Check AI OS beta runtime readiness, dashboard health, and benchmark freshness' },
+    args: {
+        dir: { type: 'string', default: PROJECT_DIR, description: 'Project directory' },
+        lang: { type: 'string', default: 'en', description: 'Output language zh/en' },
+        'benchmark-max-age-hours': { type: 'string', description: 'Maximum accepted benchmark report age in hours' },
+        json: { type: 'boolean', default: false },
+    },
+    run({ args }) {
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
+        const scaleDir = resolveScaleDirForProject(projectDir);
+        const report = createAiOsDoctor({
+            projectDir,
+            scaleDir,
+            lang: normalizeLangArg(args.lang),
+            benchmarkMaxAgeHours: parsePositiveIntArg(args['benchmark-max-age-hours'], '--benchmark-max-age-hours'),
+        });
+        if (args.json) {
+            console.log(JSON.stringify(report, null, 2));
+            if (report.status === 'blocked')
+                process.exitCode = 1;
+            return;
+        }
+        console.log('SCALE AI OS Doctor');
+        console.log(`  Status: ${report.status}`);
+        console.log(`  Checks: ${report.summary.passedChecks} passed, ${report.summary.warningChecks} warning, ${report.summary.blockedChecks} blocked`);
+        console.log(`  Dashboard: ${report.dashboard.health.status} (${report.dashboard.health.score})`);
+        console.log(`  Benchmark: ${report.benchmark.status}`);
+        for (const check of report.checks)
+            console.log(`  [${check.status}] ${check.id}: ${check.summary}`);
+        for (const action of report.nextActions)
+            console.log(`  next: ${action}`);
+        for (const warning of report.warnings)
+            console.log(`  warning: ${warning}`);
+        if (report.status === 'blocked')
+            process.exitCode = 1;
+    },
+});
+const aiOs = defineCommand({
+    meta: { name: 'ai-os', description: 'AI Engineering OS runtime planning and governance orchestration' },
+    subCommands: {
+        plan: aiOsPlanCommand,
+        run: aiOsRunCommand,
+        dashboard: aiOsDashboardCommand,
+        benchmark: aiOsBenchmarkCommand,
+        migrate: aiOsMigrateCommand,
+        doctor: aiOsDoctorCommand,
+    },
+});
 // ============================================================================
 // upgrade command - Safe workflow/template/capability update planning
 // ============================================================================
@@ -2920,8 +3160,10 @@ const upgradeCheck = defineCommand({
     },
     run({ args }) {
         const lang = normalizeLangArg(args.lang);
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
         const report = createUpgradeCheckReport({
-            projectDir: args.dir,
+            projectDir,
+            scaleDir: resolveScaleDirForProject(projectDir),
             targetScaleVersion: args['target-version'] ? String(args['target-version']) : undefined,
         });
         if (args.json) {
@@ -2936,6 +3178,7 @@ const upgradeCheck = defineCommand({
             console.log(`  治理包: ${report.governancePack.id ?? '无'} v${report.governancePack.currentVersion ?? '无'} -> v${report.governancePack.latestVersion ?? '无'}`);
             console.log(`  受管生成文件: ${report.generatedFiles.clean} 个干净, ${report.generatedFiles.changed} 个本地改动, ${report.generatedFiles.missing} 个缺失`);
             console.log(`  第三方能力策略: ${report.thirdParty.policy}; 需要人工审查: ${report.thirdParty.reviewRequired}`);
+            console.log(`  AI OS Runtime: ${report.aiOsRuntime.status}`);
             console.log('  下一步:');
         }
         else {
@@ -2946,6 +3189,7 @@ const upgradeCheck = defineCommand({
             console.log(`  Governance pack: ${report.governancePack.id ?? 'none'} v${report.governancePack.currentVersion ?? 'none'} -> v${report.governancePack.latestVersion ?? 'none'}`);
             console.log(`  Generated files: ${report.generatedFiles.clean} clean, ${report.generatedFiles.changed} changed, ${report.generatedFiles.missing} missing`);
             console.log(`  Third-party policy: ${report.thirdParty.policy}; review required: ${report.thirdParty.reviewRequired}`);
+            console.log(`  AI OS Runtime: ${report.aiOsRuntime.status}`);
             console.log('  Next:');
         }
         for (const command of report.recommendedCommands)
@@ -2963,8 +3207,10 @@ const upgradePlan = defineCommand({
     },
     run({ args }) {
         const lang = normalizeLangArg(args.lang);
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
         const report = createUpgradePlanReport({
-            projectDir: args.dir,
+            projectDir,
+            scaleDir: resolveScaleDirForProject(projectDir),
             targetScaleVersion: args['target-version'] ? String(args['target-version']) : undefined,
         });
         const htmlPath = args.html ? writeUpgradePlanHtml(report, undefined, lang) : undefined;
@@ -3009,8 +3255,10 @@ const upgradeApply = defineCommand({
     },
     run({ args }) {
         const lang = normalizeLangArg(args.lang);
+        const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
         const result = applyUpgradePlan({
-            projectDir: args.dir,
+            projectDir,
+            scaleDir: resolveScaleDirForProject(projectDir),
             confirm: isTruthyFlag(args.confirm),
         });
         if (args.json) {
@@ -5001,6 +5249,14 @@ function parseToolIds(value) {
 function parseCommaList(value) {
     return parseToolIds(value) ?? [];
 }
+function normalizeAiOsRunMode(value, forceDryRun = false) {
+    if (forceDryRun)
+        return 'dry-run';
+    const normalized = String(value ?? 'dry-run').trim().toLowerCase();
+    if (normalized === 'dry-run' || normalized === 'guarded')
+        return normalized;
+    throw new Error(`Invalid AI OS run mode "${String(value)}"; expected dry-run or guarded.`);
+}
 function createToolExecutionPlanFromArgs(args) {
     const projectDir = resolve(String(args.dir ?? PROJECT_DIR));
     const level = normalizeTaskArtifactLevel(args.level ?? 'M');
@@ -5437,6 +5693,7 @@ const main = defineCommand({
         preflight,
         upgrade,
         governance,
+        'ai-os': aiOs,
         codegraph,
         eval: evalCommand,
         artifact,