@hongmaple0820/scale-engine 0.25.0 → 0.27.0

package/docs/CODE_INTELLIGENCE.md

@@ -1,138 +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.
+# 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

@@ -1,113 +1,155 @@
-# 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
-```
-
-Include provider-specific prompt cache policy:
-
-```bash
-scale context budget --provider anthropic --json
-scale context budget --provider openai --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 |
-
-## Prompt Cache Policy
-
-V2.0 adds a cache policy layer for stable context. The policy is intentionally conservative:
-
-- `always` is cache-eligible by default because it contains stable entrypoint rules and governance source-of-truth config.
-- `on-demand` is not cache-eligible by default because it changes with task intent and can break stable prefix reuse.
-- `evidence`, `archive`, and `generated` are never cache-eligible by default.
-- Unsupported providers still write usage evidence; they do not pretend to support prompt caching.
-
-Provider behavior:
-
-| Provider | Strategy | Usage fields |
-| --- | --- | --- |
-| Anthropic | `anthropic-ephemeral` | `cache_creation_input_tokens`, `cache_read_input_tokens` |
-| OpenAI | `openai-automatic` | `prompt_tokens_details.cached_tokens` |
-| Other | `usage-ledger-only` | normal input/output usage only |
-
-The cache policy does not live in `ModelRouter`. `ModelRouter` selects a model; provider request builders or adapters apply provider-specific cache controls.
-
-## 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.
-
+# 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
+```
+
+Include provider-specific prompt cache policy:
+
+```bash
+scale context budget --provider anthropic --json
+scale context budget --provider openai --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
+```
+
+Build the unified AI OS runtime plan that embeds the context pack with memory, skill routing, adaptive workflow, and ROI:
+
+```bash
+scale ai-os plan \
+  --task-id TASK-123 \
+  --task "Review frontend route with browser evidence" \
+  --level L \
+  --files src/routes/upload.tsx \
+  --budget 8000 \
+  --json
+```
+
+The context pack now uses the baseline Context Compiler. Each candidate section is scored by category, task/file relevance, risk level, and budget fit. The JSON output includes compiler metadata so callers can explain why a section was loaded or omitted:
+
+```json
+{
+  "compiler": {
+    "strategy": "relevance-budget-v1",
+    "budget": 4000,
+    "totalCandidateTokens": 6200,
+    "estimatedTokenSavings": 2200,
+    "ranking": [
+      {
+        "id": "runtime-evidence",
+        "included": true,
+        "score": 292,
+        "matchedSignals": ["evidence", "high-risk-evidence"],
+        "reason": "Evidence is needed for completion and verification claims."
+      }
+    ]
+  }
+}
+```
+
+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 |
+
+## Prompt Cache Policy
+
+V2.0 adds a cache policy layer for stable context. The policy is intentionally conservative:
+
+- `always` is cache-eligible by default because it contains stable entrypoint rules and governance source-of-truth config.
+- `on-demand` is not cache-eligible by default because it changes with task intent and can break stable prefix reuse.
+- `evidence`, `archive`, and `generated` are never cache-eligible by default.
+- Unsupported providers still write usage evidence; they do not pretend to support prompt caching.
+
+Provider behavior:
+
+| Provider | Strategy | Usage fields |
+| --- | --- | --- |
+| Anthropic | `anthropic-ephemeral` | `cache_creation_input_tokens`, `cache_read_input_tokens` |
+| OpenAI | `openai-automatic` | `prompt_tokens_details.cached_tokens` |
+| Other | `usage-ledger-only` | normal input/output usage only |
+
+The cache policy does not live in `ModelRouter`. `ModelRouter` selects a model; provider request builders or adapters apply provider-specific cache controls.
+
+## 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. In v0.27.0, `scale ai-os plan` also attaches ROI modules for:
+
+- `context-budget`
+- `context-compiler`
+- `memory-provider-runtime`
+- `skill-routing-engine`
+- `progressive-governance`
+
+Early ROI is still estimated from context budget, compiler savings, recall count, skill evidence steps, 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.
+