@hongmaple0820/scale-engine 0.19.0 → 0.20.0

package/dist/workflow/GovernanceTemplates.js

@@ -202,10 +202,10 @@ scale verify <task-id> --profile default
 scale verify <task-id> --service <service-name>
 scale verify <task-id> --artifact-gate warn
 scale verify <task-id> --artifact-gate block
-scale verify <task-id> --require-installed-skills
-scale verify <task-id> --profile productSmoke
-scale task-artifacts check --dir docs/worklog/tasks/<task-dir> --level L
-scale artifact render --task-id <task-dir> --type release-report
+scale verify <task-id> --require-installed-skills
+scale verify <task-id> --profile productSmoke
+scale task-artifacts check --dir docs/worklog/tasks/<task-dir> --level L
+scale artifact render --task-id <task-dir> --type release-report
 scale artifact doctor --task-id <task-dir>
 \`\`\`
 
@@ -301,15 +301,15 @@ Default policy:
 - unsafe HTML sinks, dynamic code execution, empty catch blocks, and type suppressions require remediation before release.
 - framework and architecture rules live in \`.scale/frameworks.json\` and module standards docs.
 - \`.scale/frameworks.json > bannedImports\` blocks direct use of deprecated ORMs, unsafe SDKs, or off-system UI components.
-- \`.scale/frameworks.json > lastReviewedAt/reviewIntervalDays\` warns when module framework decisions need review.
-- \`.scale/engineering-standards.json > blockingRules\` promotes selected warning rule IDs to release-blocking findings.
-- \`.scale/engineering-standards.json > allowedFindingPatterns\` allows narrow rule/path/evidence exceptions without hiding unrelated findings in the same file.
-- \`.scale/engineering-standards-baseline.json\` may hold known legacy findings during rollout, but normal task gates should prefer \`--changed\` or \`--changed-files\` so new work is blocked without forcing a whole-repo cleanup.
-- \`.scale/verification.json > policy.engineeringStandardsGate\` controls whether preflight and task verification treat standards as \`off\`, \`warn\`, or \`block\`.
-- \`.scale/product-smoke.json\` defines real product-path probes. Use it to prove a routed user/business flow, not only build, unit tests, or \`/health\`.
-- \`.scale/verification.json > policy.productSmokeGate\` controls whether missing or failed product smoke evidence warns or blocks M/L/CRITICAL delivery.
-- Full standards scans are for release readiness, scheduled remediation, and architecture cleanup. Changed-file scans are the default for day-to-day feature and bug branches.
-- Use \`scale standards baseline --write\` only during an explicit rollout or remediation planning task. It writes the machine-readable baseline and a \`standards-legacy-debt.md\` classification report for staged cleanup.
+- \`.scale/frameworks.json > lastReviewedAt/reviewIntervalDays\` warns when module framework decisions need review.
+- \`.scale/engineering-standards.json > blockingRules\` promotes selected warning rule IDs to release-blocking findings.
+- \`.scale/engineering-standards.json > allowedFindingPatterns\` allows narrow rule/path/evidence exceptions without hiding unrelated findings in the same file.
+- \`.scale/engineering-standards-baseline.json\` may hold known legacy findings during rollout, but normal task gates should prefer \`--changed\` or \`--changed-files\` so new work is blocked without forcing a whole-repo cleanup.
+- \`.scale/verification.json > policy.engineeringStandardsGate\` controls whether preflight and task verification treat standards as \`off\`, \`warn\`, or \`block\`.
+- \`.scale/product-smoke.json\` defines real product-path probes. Use it to prove a routed user/business flow, not only build, unit tests, or \`/health\`.
+- \`.scale/verification.json > policy.productSmokeGate\` controls whether missing or failed product smoke evidence warns or blocks M/L/CRITICAL delivery.
+- Full standards scans are for release readiness, scheduled remediation, and architecture cleanup. Changed-file scans are the default for day-to-day feature and bug branches.
+- Use \`scale standards baseline --write\` only during an explicit rollout or remediation planning task. It writes the machine-readable baseline and a \`standards-legacy-debt.md\` classification report for staged cleanup.
 
 ## Automation Templates
 
@@ -742,67 +742,67 @@ TBD
 `;
 }
 function productSmokeTemplate() {
-    return `# Product Smoke
-
-## Real Product Path
-
-Describe the smallest end-to-end path that proves the change works through the real product boundary.
-
-Example:
-
-\`\`\`text
-UI or client -> gateway/router -> service -> database/storage/queue -> observable result
-\`\`\`
-
-Do not use a green health endpoint as the only proof when the user-facing path depends on routing, authentication, storage, async tasks, browser behavior, or third-party integration.
-
-## Quick Setup
-
-1. Open \`.scale/product-smoke.json\`.
-2. Replace the example command with one real product path command.
-3. Set that probe's \`enabled\` field to \`true\`.
-4. Run \`scale preflight --profile productSmoke --json\`.
-5. Run \`scale runtime final-check --level M --json\`.
-
-\`status: "skipped"\` means no real product path was exercised. It does not count as completion evidence.
-
-## Setup
-
-- Base URL:
-- Test user or tenant:
-- Required fixtures:
-- Services that must be running:
-
-## Smoke Commands
-
-| Command | Expected Result | Evidence Artifact |
-| --- | --- | --- |
-| TBD | TBD | TBD |
-
-## Runtime Evidence
-
-Record at least one runtime evidence item:
-
-\`\`\`bash
-scale runtime record \\
-  --kind command \\
-  --title "Product smoke: <flow>" \\
-  --status passed \\
-  --command "<exact smoke command>" \\
-  --exit-code 0 \\
-  --summary "<business result, task id, status, or observable output>" \\
-  --artifacts ".agent/logs/<service>/<smoke>.json" \\
-  --metadata-json '{"productSmoke":true,"realProductPath":true}'
-\`\`\`
-
-## Assertions
-
-- [ ] Request crossed the real product boundary, not only an isolated unit.
-- [ ] Authentication or user identity path was exercised when relevant.
-- [ ] Persistence/storage/queue side effect was verified when relevant.
-- [ ] Async task or eventual state was polled to terminal status when relevant.
-- [ ] Failure output is specific enough to diagnose the failing layer.
-- [ ] Runtime artifacts are ignored or deliberately promoted according to resource governance.
+    return `# Product Smoke
+
+## Real Product Path
+
+Describe the smallest end-to-end path that proves the change works through the real product boundary.
+
+Example:
+
+\`\`\`text
+UI or client -> gateway/router -> service -> database/storage/queue -> observable result
+\`\`\`
+
+Do not use a green health endpoint as the only proof when the user-facing path depends on routing, authentication, storage, async tasks, browser behavior, or third-party integration.
+
+## Quick Setup
+
+1. Open \`.scale/product-smoke.json\`.
+2. Replace the example command with one real product path command.
+3. Set that probe's \`enabled\` field to \`true\`.
+4. Run \`scale preflight --profile productSmoke --json\`.
+5. Run \`scale runtime final-check --level M --json\`.
+
+\`status: "skipped"\` means no real product path was exercised. It does not count as completion evidence.
+
+## Setup
+
+- Base URL:
+- Test user or tenant:
+- Required fixtures:
+- Services that must be running:
+
+## Smoke Commands
+
+| Command | Expected Result | Evidence Artifact |
+| --- | --- | --- |
+| TBD | TBD | TBD |
+
+## Runtime Evidence
+
+Record at least one runtime evidence item:
+
+\`\`\`bash
+scale runtime record \\
+  --kind command \\
+  --title "Product smoke: <flow>" \\
+  --status passed \\
+  --command "<exact smoke command>" \\
+  --exit-code 0 \\
+  --summary "<business result, task id, status, or observable output>" \\
+  --artifacts ".agent/logs/<service>/<smoke>.json" \\
+  --metadata-json '{"productSmoke":true,"realProductPath":true}'
+\`\`\`
+
+## Assertions
+
+- [ ] Request crossed the real product boundary, not only an isolated unit.
+- [ ] Authentication or user identity path was exercised when relevant.
+- [ ] Persistence/storage/queue side effect was verified when relevant.
+- [ ] Async task or eventual state was polled to terminal status when relevant.
+- [ ] Failure output is specific enough to diagnose the failing layer.
+- [ ] Runtime artifacts are ignored or deliberately promoted according to resource governance.
 `;
 }
 function planTemplate() {
@@ -983,132 +983,132 @@ function productSmokeConfigTemplate(mode) {
     }, null, 2) + '\n';
 }
 function productSmokePowerShellScript() {
-    return `# Product smoke probe runner generated by scale-engine.
-$ErrorActionPreference = "Stop"
-
-$Root = (Resolve-Path (Join-Path $PSScriptRoot "..\\..")).Path
-$ConfigPath = Join-Path $Root ".scale\\product-smoke.json"
-$LogDir = Join-Path $Root ".agent\\logs"
-$LogPath = Join-Path $LogDir "product-smoke.json"
-
-New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
-
-$NodeProgram = @'
-${productSmokeNodeProgram()}
-'@
-
-$TempFile = [System.IO.Path]::GetTempFileName() + ".js"
-Set-Content -Path $TempFile -Value $NodeProgram -Encoding UTF8
-try {
-  node $TempFile $ConfigPath $LogPath
-  exit $LASTEXITCODE
-} finally {
-  Remove-Item -Force $TempFile -ErrorAction SilentlyContinue
-}
+    return `# Product smoke probe runner generated by scale-engine.
+$ErrorActionPreference = "Stop"
+
+$Root = (Resolve-Path (Join-Path $PSScriptRoot "..\\..")).Path
+$ConfigPath = Join-Path $Root ".scale\\product-smoke.json"
+$LogDir = Join-Path $Root ".agent\\logs"
+$LogPath = Join-Path $LogDir "product-smoke.json"
+
+New-Item -ItemType Directory -Force -Path $LogDir | Out-Null
+
+$NodeProgram = @'
+${productSmokeNodeProgram()}
+'@
+
+$TempFile = [System.IO.Path]::GetTempFileName() + ".js"
+Set-Content -Path $TempFile -Value $NodeProgram -Encoding UTF8
+try {
+  node $TempFile $ConfigPath $LogPath
+  exit $LASTEXITCODE
+} finally {
+  Remove-Item -Force $TempFile -ErrorAction SilentlyContinue
+}
 `;
 }
 function productSmokeShellScript() {
-    return `#!/usr/bin/env sh
-set -eu
-
-ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
-CONFIG_PATH="$ROOT/.scale/product-smoke.json"
-LOG_DIR="$ROOT/.agent/logs"
-LOG_PATH="$LOG_DIR/product-smoke.json"
-
-mkdir -p "$LOG_DIR"
-
-node - "$CONFIG_PATH" "$LOG_PATH" <<'NODE'
-${productSmokeNodeProgram()}
-NODE
+    return `#!/usr/bin/env sh
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
+CONFIG_PATH="$ROOT/.scale/product-smoke.json"
+LOG_DIR="$ROOT/.agent/logs"
+LOG_PATH="$LOG_DIR/product-smoke.json"
+
+mkdir -p "$LOG_DIR"
+
+node - "$CONFIG_PATH" "$LOG_PATH" <<'NODE'
+${productSmokeNodeProgram()}
+NODE
 `;
 }
 function productSmokeNodeProgram() {
-    return `const fs = require('fs');
-const cp = require('child_process');
-const path = require('path');
-
-const configPath = process.argv[2];
-const logPath = process.argv[3];
-
-function writeReport(report) {
-  fs.mkdirSync(path.dirname(logPath), { recursive: true });
-  fs.writeFileSync(logPath, JSON.stringify(report, null, 2) + '\\n', 'utf8');
-  process.stdout.write(JSON.stringify(report, null, 2) + '\\n');
-}
-
-if (!fs.existsSync(configPath)) {
-  writeReport({
-    version: 1,
-    status: 'failed',
-    verifiedAt: new Date().toISOString(),
-    message: 'Missing .scale/product-smoke.json',
-    results: []
-  });
-  process.exit(1);
-}
-
-const config = JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^\\uFEFF/, ''));
-const probes = Array.isArray(config.probes) ? config.probes.filter(probe => probe && probe.enabled === true) : [];
-
-if (probes.length === 0) {
-  const status = config.emptyProbeBehavior === 'block' ? 'failed' : 'skipped';
-  writeReport({
-    version: 1,
-    status,
-    verifiedAt: new Date().toISOString(),
-    message: 'No enabled product smoke probes. Enable probes in .scale/product-smoke.json after defining the real product path.',
-    results: []
-  });
-  process.exit(status === 'failed' ? 1 : 0);
-}
-
-const results = probes.map((probe) => {
-  const startedAt = new Date().toISOString();
-  const expectedExitCode = Number.isInteger(probe.expected && probe.expected.exitCode) ? probe.expected.exitCode : 0;
-  const command = String(probe.command || '');
-  if (!command.trim()) {
-    return {
-      id: String(probe.id || 'unnamed-probe'),
-      description: String(probe.description || ''),
-      command,
-      expectedExitCode,
-      exitCode: 1,
-      status: 'failed',
-      startedAt,
-      endedAt: new Date().toISOString(),
-      outputTail: 'Probe command is empty'
-    };
-  }
-  const result = cp.spawnSync(command, {
-    cwd: process.cwd(),
-    shell: true,
-    encoding: 'utf8',
-    timeout: Number(config.timeoutMs || 180000)
-  });
-  const output = String(result.stdout || '') + String(result.stderr || '') + String(result.error ? result.error.message : '');
-  const exitCode = typeof result.status === 'number' ? result.status : 1;
-  return {
-    id: String(probe.id || 'unnamed-probe'),
-    description: String(probe.description || ''),
-    command,
-    expectedExitCode,
-    exitCode,
-    status: exitCode === expectedExitCode ? 'passed' : 'failed',
-    startedAt,
-    endedAt: new Date().toISOString(),
-    outputTail: output.length > 2000 ? output.slice(-2000) : output
-  };
-});
-
-const failed = results.filter(result => result.status !== 'passed');
-writeReport({
-  version: 1,
-  status: failed.length === 0 ? 'passed' : 'failed',
-  verifiedAt: new Date().toISOString(),
-  results
-});
-process.exit(failed.length === 0 ? 0 : 1);
+    return `const fs = require('fs');
+const cp = require('child_process');
+const path = require('path');
+
+const configPath = process.argv[2];
+const logPath = process.argv[3];
+
+function writeReport(report) {
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  fs.writeFileSync(logPath, JSON.stringify(report, null, 2) + '\\n', 'utf8');
+  process.stdout.write(JSON.stringify(report, null, 2) + '\\n');
+}
+
+if (!fs.existsSync(configPath)) {
+  writeReport({
+    version: 1,
+    status: 'failed',
+    verifiedAt: new Date().toISOString(),
+    message: 'Missing .scale/product-smoke.json',
+    results: []
+  });
+  process.exit(1);
+}
+
+const config = JSON.parse(fs.readFileSync(configPath, 'utf8').replace(/^\\uFEFF/, ''));
+const probes = Array.isArray(config.probes) ? config.probes.filter(probe => probe && probe.enabled === true) : [];
+
+if (probes.length === 0) {
+  const status = config.emptyProbeBehavior === 'block' ? 'failed' : 'skipped';
+  writeReport({
+    version: 1,
+    status,
+    verifiedAt: new Date().toISOString(),
+    message: 'No enabled product smoke probes. Enable probes in .scale/product-smoke.json after defining the real product path.',
+    results: []
+  });
+  process.exit(status === 'failed' ? 1 : 0);
+}
+
+const results = probes.map((probe) => {
+  const startedAt = new Date().toISOString();
+  const expectedExitCode = Number.isInteger(probe.expected && probe.expected.exitCode) ? probe.expected.exitCode : 0;
+  const command = String(probe.command || '');
+  if (!command.trim()) {
+    return {
+      id: String(probe.id || 'unnamed-probe'),
+      description: String(probe.description || ''),
+      command,
+      expectedExitCode,
+      exitCode: 1,
+      status: 'failed',
+      startedAt,
+      endedAt: new Date().toISOString(),
+      outputTail: 'Probe command is empty'
+    };
+  }
+  const result = cp.spawnSync(command, {
+    cwd: process.cwd(),
+    shell: true,
+    encoding: 'utf8',
+    timeout: Number(config.timeoutMs || 180000)
+  });
+  const output = String(result.stdout || '') + String(result.stderr || '') + String(result.error ? result.error.message : '');
+  const exitCode = typeof result.status === 'number' ? result.status : 1;
+  return {
+    id: String(probe.id || 'unnamed-probe'),
+    description: String(probe.description || ''),
+    command,
+    expectedExitCode,
+    exitCode,
+    status: exitCode === expectedExitCode ? 'passed' : 'failed',
+    startedAt,
+    endedAt: new Date().toISOString(),
+    outputTail: output.length > 2000 ? output.slice(-2000) : output
+  };
+});
+
+const failed = results.filter(result => result.status !== 'passed');
+writeReport({
+  version: 1,
+  status: failed.length === 0 ? 'passed' : 'failed',
+  verifiedAt: new Date().toISOString(),
+  results
+});
+process.exit(failed.length === 0 ? 0 : 1);
 `;
 }
 function packageVersion() {

package/docs/CODE_INTELLIGENCE.md

@@ -0,0 +1,138 @@
+# Code Intelligence
+
+SCALE uses an adapter-first code intelligence layer. It can consume external code graph tools when they exist, read graph artifacts such as Graphify outputs, and fall back to a scoped internal source scan when no provider is available.
+
+The goal is not to replace IDE indexing. The goal is to make exploration measurable:
+
+- which provider answered the query
+- whether fallback was used
+- which files are likely relevant
+- how many file reads were avoided
+- what confidence the result has
+
+## Quick Start
+
+Create the optional provider configuration:
+
+```bash
+scale codegraph init
+```
+
+Inspect provider availability:
+
+```bash
+scale codegraph status
+scale codegraph status --json
+```
+
+Query code intelligence:
+
+```bash
+scale codegraph query "UserService.create"
+scale codegraph impact --symbol UserService.create
+scale codegraph context --symbol UserService.create --budget 2000
+scale codegraph roi --symbol UserService.create
+```
+
+## Configuration
+
+The configuration file lives at:
+
+```text
+.scale/code-intelligence.json
+```
+
+Default shape:
+
+```json
+{
+  "version": "1.0",
+  "providers": [
+    {
+      "id": "codegraph",
+      "type": "external-cli",
+      "enabled": true,
+      "command": "codegraph",
+      "capabilities": ["symbols", "callers", "callees", "impact", "context"]
+    },
+    {
+      "id": "graphify",
+      "type": "artifact",
+      "enabled": true,
+      "manifest": "graphify-out/GRAPH_REPORT.md",
+      "capabilities": ["summary", "module-map", "context"]
+    }
+  ],
+  "fallback": {
+    "enabled": true,
+    "tools": ["internal-scan", "rg", "read"]
+  }
+}
+```
+
+## Provider Types
+
+| Type | Use |
+| --- | --- |
+| `external-cli` | Detects an installed external code graph command. SCALE does not auto-install it. The first version treats this as availability evidence until a stable command contract is configured. |
+| `artifact` | Reads a local graph manifest or report file. JSON manifests can provide symbol impact data. |
+| fallback | Uses a bounded internal source scan when providers are unavailable or return no hits. |
+
+## JSON Artifact Provider
+
+Artifact providers can point at a JSON manifest:
+
+```json
+{
+  "symbols": [
+    {
+      "name": "UserService.create",
+      "file": "src/user.ts",
+      "callers": ["src/api.ts"],
+      "callees": ["src/db.ts"]
+    }
+  ],
+  "files": [
+    {
+      "path": "src/user.ts",
+      "symbols": ["UserService.create"]
+    }
+  ]
+}
+```
+
+This allows SCALE to answer impact queries without reading the whole repository.
+
+## ROI Metrics
+
+Code intelligence reports include:
+
+| Metric | Meaning |
+| --- | --- |
+| `graphHits` | Number of hits from graph providers. |
+| `fallbackCount` | Whether fallback was needed. |
+| `baselineFileReads` | Estimated broad exploration file reads. |
+| `recommendedFileReads` | Scoped file reads recommended by the query result. |
+| `fileReadsSaved` | Estimated avoided reads. |
+| `toolCallsSaved` | Estimated avoided exploration tool calls. |
+
+These numbers are deliberately conservative. They are a local signal for whether graph-assisted exploration is worth keeping default for a task class.
+
+## Governance ROI
+
+`scale governance roi` can include code intelligence:
+
+```bash
+scale governance roi --symbol UserService.create
+scale governance roi --code-query createUser
+```
+
+When a graph provider answers, the module is reported as measured evidence. When fallback is used, the module is reported as estimated and needs more evidence before becoming a stronger default.
+
+## Policy
+
+- SCALE must run when no code graph provider is installed.
+- Missing providers must produce explicit fallback, not silent success.
+- External tools are detected but not installed automatically.
+- Source files are read only through a bounded fallback scan.
+- Large generated graph outputs should stay outside default prompt context; use summaries and file paths.

package/docs/CONTEXT_BUDGET.md

@@ -0,0 +1,87 @@
+# Context Budget And Progressive Governance
+
+Status: implemented baseline
+Since: v0.20 development branch
+
+This feature keeps SCALE from becoming its own context pollution source. It separates always-loaded rules from on-demand documents, runtime evidence, historical archives, and generated artifacts.
+
+## Commands
+
+Report token cost by context category:
+
+```bash
+scale context budget --json
+```
+
+Write the report to `.scale/context-budget.json`:
+
+```bash
+scale context budget --write
+```
+
+Check thresholds:
+
+```bash
+scale context doctor --max-always 2500 --max-task 8000
+```
+
+Build a lazy-loaded task context pack:
+
+```bash
+scale context pack \
+  --task "Review frontend route with browser evidence" \
+  --level L \
+  --files src/routes/upload.tsx \
+  --budget 4000 \
+  --json
+```
+
+Evaluate progressive governance mode:
+
+```bash
+scale governance mode \
+  --task "Change auth permissions and database migration" \
+  --files src/auth/user.ts,migrations/001.sql \
+  --requested-mode minimal \
+  --json
+```
+
+Report governance benefit and overhead:
+
+```bash
+scale governance roi \
+  --task-id TASK-123 \
+  --task "Review frontend route with browser evidence" \
+  --files src/routes/upload.tsx \
+  --json
+```
+
+## Categories
+
+| Category | Meaning | Loading Policy |
+| --- | --- | --- |
+| `always` | Tiny entrypoint rules and source-of-truth governance config | Keep under strict token budget |
+| `on-demand` | Domain docs and governance guides | Load only when task trigger matches |
+| `evidence` | Runtime evidence and task artifacts | Summarize and reference by path |
+| `archive` | Historical plans and old roadmap context | Do not load unless explicitly requested |
+| `generated` | HTML reports, screenshots, graph outputs, generated artifacts | Keep manifest-only by default |
+
+## Progressive Governance
+
+SCALE now has a baseline risk classifier. It keeps low-risk documentation work in `minimal` mode and escalates risky tasks to `standard`, `expanded`, or `critical`.
+
+Examples:
+
+| Signal | Mode |
+| --- | --- |
+| README typo | `minimal` |
+| normal implementation task | `standard` |
+| UI, browser, E2E, public interface, or cross-module work | `expanded` |
+| auth, permission, secret, database, migration, production config, release, or destructive operation | `critical` |
+
+This is not a replacement for verification. It only decides which governance behavior should activate.
+
+## Governance ROI
+
+`scale governance roi` reports both benefit and overhead. Early ROI is estimated from context budget and risk signals. Later versions should replace estimates with measured eval data such as file reads saved, tool calls saved, fix iterations reduced, and human corrections avoided.
+