@hongmaple0820/scale-engine 0.24.0 → 0.26.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,12 +1,12 @@
-# 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
-
+# 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
@@ -19,58 +19,58 @@ Include provider-specific prompt cache policy:
 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 |
+
+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
@@ -91,23 +91,23 @@ Provider behavior:
 | 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.
-
+
+## 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.
+

package/docs/EXTERNAL_REFERENCES.md

@@ -0,0 +1,63 @@
+# External Reference Inventory
+
+This inventory is the source of truth for external projects, community skills, MCP servers, CLIs, and adapter targets referenced by SCALE. It complements [Third-Party Skills and External References](THIRD_PARTY_SKILLS.md).
+
+The inventory is intentionally conservative:
+
+- A row here is an acknowledgement and governance record, not a claim that upstream code is vendored.
+- License is only marked when it has been explicitly reviewed in this repository. Unknown or unverified projects stay `review-required`.
+- Any future vendoring, source copying, modified redistribution, bundled assets, logos, examples, or generated derivatives must preserve upstream license text, copyright notices, NOTICE files, source URL, pinned revision, and modification notes.
+- External services and memory providers remain disabled or read-only by default until privacy, retention, credential, and deletion boundaries are reviewed.
+
+## Current References
+
+| Upstream | Role in SCALE | Usage status | License status | Primary source surface |
+| --- | --- | --- | --- | --- |
+| [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files) | File-backed planning workflow reference | adapted concept, not vendored | MIT | `SkillRepository`, README, `THIRD_PARTY_SKILLS` |
+| [rohitg00/agentmemory](https://github.com/rohitg00/agentmemory) | Optional external memory provider | external provider, read-only by default | Apache-2.0 | `MemoryProviders`, `SkillRepository`, README |
+| [garrytan/gbrain](https://github.com/garrytan/gbrain) | Optional graph memory provider | external provider, read-only by default | MIT | `MemoryProviders`, `SkillRepository`, README |
+| [anthropics/skills](https://github.com/anthropics/skills) | Frontend and webapp testing skill references | external skill reference | review-required | `SkillRepository`, `SkillCatalog`, `ToolCapabilityRegistry` |
+| [anthropics/claude-code](https://github.com/anthropics/claude-code) | Graphify and playwright-interactive skill references | optional discovery reference | review-required | `SkillDiscovery` |
+| [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) | Design system and DESIGN.md guidance | external skill reference | review-required | `SkillRepository`, `ExternalSkills`, `SkillDoctor` |
+| [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | UI/UX design intelligence reference | external skill reference | review-required | `SkillRepository`, `ExternalSkills`, `ToolCapabilityRegistry` |
+| [eze-is/web-access](https://github.com/eze-is/web-access) | Web research and browser automation skill | external skill reference | review-required | `SkillRepository`, `ExternalSkills`, `SkillDoctor` |
+| [vercel-labs/agent-browser](https://github.com/vercel-labs/agent-browser) | Browser automation CLI | external CLI reference | review-required | `SkillRepository`, `ExternalSkills`, `ToolCapabilityRegistry` |
+| [ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) | Chrome DevTools MCP integration | MCP reference | review-required | `SkillRepository`, `ExternalSkills`, `ToolCapabilityRegistry` |
+| [trycua/cua](https://github.com/trycua/cua) | Desktop computer-use automation | restricted external automation reference | review-required | `SkillRepository`, `ExternalSkills`, `ToolCapabilityRegistry` |
+| [microsoft/playwright](https://github.com/microsoft/playwright) | Browser automation and validation | optional discovery reference | review-required | `SkillDiscovery` |
+| [google-gemini/gemini-cli](https://github.com/google-gemini/gemini-cli) | Gemini CLI and community skill examples | external CLI and skill reference | review-required | `SkillRepository`, `SkillCatalog`, adapters |
+| [openai/codex](https://github.com/openai/codex) | Codex CLI adapter and external reviewer | external CLI reference | review-required | `SkillRepository`, `ExternalSkills`, adapters |
+| [sst/opencode](https://github.com/sst/opencode) | OpenCode CLI reference used by routing | external CLI reference | review-required | `SkillRepository`, `ExternalSkills`, `SkillDoctor` |
+| [opencode-ai/opencode](https://github.com/opencode-ai/opencode) | OpenCode adapter source comment | adapter target reference | review-required | `OpenCodeAdapter` |
+| [facebook/react](https://github.com/facebook/react) | React fix skill example | external skill reference | review-required | `SkillRepository`, `SkillCatalog` |
+| [vercel/next.js](https://github.com/vercel/next.js) | Next.js documentation update skill example | external skill reference | review-required | `SkillRepository`, `SkillCatalog` |
+| [vercel-labs/skills](https://github.com/vercel-labs/skills) | Skill discovery example | external skill reference | review-required | `SkillRepository`, `SkillCatalog` |
+| [Shubhamsaboo/awesome-llm-apps](https://github.com/Shubhamsaboo/awesome-llm-apps) | Full-stack agent skill example | external skill reference | review-required | `SkillCatalog` |
+| [jnMetaCode/agency-agents-zh](https://github.com/jnMetaCode/agency-agents-zh) | Chinese role preset reference | external preset reference | review-required | `SkillRepository` |
+| [yizhiyanhua-ai/fireworks-tech-graph](https://github.com/yizhiyanhua-ai/fireworks-tech-graph) | Diagram skill discovery and installer reference | optional install reference | review-required | `ExternalSkills`, `SkillDiscovery`, `SkillInstaller` |
+| [github/awesome-copilot](https://github.com/github/awesome-copilot) | Excalidraw diagram skill source | optional install reference | review-required | `ExternalSkills`, `SkillInstaller`, installation workflow doc |
+| [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) | Architecture diagram skill reference | optional install reference | review-required | `ExternalSkills`, `SkillDiscovery`, `SkillInstaller` |
+| [heygen-com/hyperframes](https://github.com/heygen-com/hyperframes) | Video generation CLI reference | optional install reference | review-required | `ExternalSkills`, `SkillDiscovery`, `SkillInstaller` |
+| [op7418/guizang-ppt-skill](https://github.com/op7418/guizang-ppt-skill) | PPT generation skill reference | optional install reference | review-required | `ExternalSkills`, `SkillDiscovery`, `SkillInstaller` |
+| [QwenLM/qwen-code](https://github.com/QwenLM/qwen-code) | QCoder adapter target | adapter target reference | review-required | `QCoderAdapter` |
+| [Qoder docs](https://docs.qoder.com/) | Qoder adapter target | adapter target reference | review-required | `QoderAdapter` |
+| JCode | JCode adapter target; upstream source and license still need review | provisional adapter target reference | review-required | `JCodeAdapter` |
+| [Cline docs](https://docs.cline.bot/) | Cline adapter target | adapter target reference | review-required | `ClineAdapter` |
+| [Kilo Code docs](https://docs.kilocode.ai/) | Kilo Code adapter target | adapter target reference | review-required | `KiloCodeAdapter` |
+| [Google Antigravity docs](https://antigravity.google/docs/) | Antigravity adapter target | adapter target reference | review-required | `AntigravityAdapter` |
+| [openclaw-ai/openclaw](https://github.com/openclaw-ai/openclaw) | OpenClaw adapter target | adapter target reference | review-required | `OpenClawAdapter` |
+| [hermes-ai/hermes](https://github.com/hermes-ai/hermes) | Hermes adapter target | adapter target reference | review-required | `HermesAdapter` |
+| [Hmbown/deepseek-tui](https://github.com/Hmbown/deepseek-tui) | DeepSeek TUI adapter target | adapter target reference | review-required | `DeepSeekTuiAdapter` |
+| [Aider-AI/aider](https://github.com/Aider-AI/aider) | Aider adapter target | adapter target reference | review-required | `AiderAdapter` |
+
+## Required Maintenance
+
+When a new GitHub upstream is referenced from `src/skills`, `src/tools`, `src/adapters`, or current tool orchestration docs, update this inventory in the same change. `tests/docs/externalReferences.test.ts` scans those surfaces and fails if a referenced upstream is missing from this file.
+
+Before promoting any `review-required` item to a declared license status, record:
+
+1. upstream license file and revision
+2. upstream copyright and NOTICE obligations
+3. whether SCALE vendors code, adapts concepts, or only links to the project
+4. modification notes for copied or derived files
+5. installation, script, and permission review evidence