@hongmaple0820/scale-engine 0.44.0 → 0.45.0

package/docs/reference/cli.md

@@ -0,0 +1,234 @@
+# SCALE Engine CLI Reference
+
+> Auto-generated from source. Run `scale --help` for live output.
+
+## Top-Level Commands
+
+| Command | Description |
+|---------|-------------|
+| `scale init` | Initialize SCALE governance in a project |
+| `scale setup` | Interactive setup wizard |
+| `scale doctor` | Diagnose SCALE installation and configuration |
+| `scale preflight` | Run pre-flight checks |
+| `scale status` | Show project governance status |
+
+## Phase Workflow
+
+| Command | Description |
+|---------|-------------|
+| `scale define` | Define a new task with scope and level |
+| `scale plan` | Generate implementation plan |
+| `scale build` | Execute implementation with TDD |
+| `scale verify` | Run verification gates |
+| `scale review` | Code review and evidence check |
+| `scale ship` | Prepare for release |
+
+## Engines
+
+### Shield (`scale shield`)
+
+Hook-based security engine that intercepts dangerous commands.
+
+| Command | Description |
+|---------|-------------|
+| `scale shield compile` | Compile YAML policies to executable hooks |
+| `scale shield status` | Show shield configuration status |
+| `scale shield test` | Test shield rules |
+
+### Orchestrator (`scale orch`)
+
+Declarative orchestration daemon with git worktree isolation.
+
+| Command | Description |
+|---------|-------------|
+| `scale orch start` | Start orchestration daemon |
+| `scale orch stop` | Stop orchestration daemon |
+| `scale orch status` | Show orchestration status |
+| `scale orch log` | View orchestration logs |
+
+### Cortex (`scale cortex`)
+
+Evidence-driven continuous evolution with instinct extraction.
+
+| Command | Description |
+|---------|-------------|
+| `scale cortex extract` | Extract instincts from observation logs |
+| `scale cortex inject` | Preview SessionStart injection content |
+| `scale cortex metrics` | Show governance metrics |
+| `scale cortex evolve` | Run evolution cycle |
+| `scale cortex verify` | Verify cortex pipeline health |
+
+## Memory
+
+| Command | Description |
+|---------|-------------|
+| `scale memory pack` | Build memory context pack |
+| `scale memory doctor` | Diagnose memory system health |
+| `scale memory settle` | Settle learning candidates |
+| `scale memory ingest` | Ingest evidence into memory |
+| `scale memory query` | Query memory brain |
+| `scale memory contradictions` | Detect memory contradictions |
+| `scale memory dream` | Run memory consolidation |
+| `scale memory promote` | Promote memory node to active |
+| `scale memory export` | Export memory to JSONL |
+| `scale memory import` | Import memory from JSONL |
+
+### Memory Providers
+
+| Command | Description |
+|---------|-------------|
+| `scale memory provider init` | Initialize memory provider config |
+| `scale memory provider status` | Show provider health status |
+| `scale memory provider recall` | Query providers for memories |
+| `scale memory provider use` | Switch active memory provider |
+
+## Code Intelligence
+
+| Command | Description |
+|---------|-------------|
+| `scale codegraph status` | Show codegraph index status |
+| `scale codegraph init` | Initialize codegraph index |
+| `scale codegraph query` | Query code symbols and relationships |
+| `scale codegraph impact` | Analyze change impact |
+| `scale codegraph context` | Build context for code review |
+| `scale codegraph roi` | Show codegraph ROI metrics |
+| `scale codegraph dump` | Dump codegraph data |
+
+## Evaluation
+
+| Command | Description |
+|---------|-------------|
+| `scale eval init` | Initialize evaluation suite |
+| `scale eval run` | Run evaluation suite |
+| `scale eval compare` | Compare evaluation runs |
+| `scale eval report` | Generate evaluation report |
+| `scale eval failures` | List failure records |
+| `scale eval replay` | Replay failure scenarios |
+| `scale eval promote-failure` | Promote failure to learning |
+
+## Workflow
+
+| Command | Description |
+|---------|-------------|
+| `scale workflow list` | List workflow presets |
+| `scale evidence list` | List evidence records |
+| `scale evidence show` | Show evidence details |
+| `scale token record` | Record token usage |
+| `scale token report` | Generate token usage report |
+
+## Runtime
+
+| Command | Description |
+|---------|-------------|
+| `scale runtime start` | Start runtime session |
+| `scale runtime end` | End runtime session |
+| `scale runtime record` | Record runtime evidence |
+| `scale runtime doctor` | Diagnose runtime health |
+| `scale runtime final-check` | Run final delivery check |
+
+## Skills
+
+| Command | Description |
+|---------|-------------|
+| `scale skill scan` | Scan for available skills |
+| `scale skill plan` | Generate skill routing plan |
+| `scale skill doctor` | Diagnose skill configuration |
+| `scale skill check` | Check skill installation safety |
+| `scale skill repo` | Browse skill repository |
+| `scale skill safety` | Evaluate skill supply chain safety |
+| `scale skill radar` | Show skill radar visualization |
+| `scale skill recommend` | Get skill recommendations |
+| `scale skill outdated` | Check for outdated skills |
+
+## Tools
+
+| Command | Description |
+|---------|-------------|
+| `scale tool policy` | Show tool orchestration policy |
+| `scale tool doctor` | Diagnose tool configuration |
+| `scale tool plan` | Generate tool usage plan |
+| `scale tool run` | Run tool with evidence |
+| `scale tool evidence` | Show tool evidence |
+| `scale tool outdated` | Check for outdated tools |
+
+## Governance
+
+| Command | Description |
+|---------|-------------|
+| `scale governance diff` | Show governance drift |
+| `scale governance mode` | Set governance mode |
+| `scale governance roi` | Show governance ROI |
+
+## Configuration
+
+| Command | Description |
+|---------|-------------|
+| `scale config profile` | Manage configuration profiles |
+
+## Upgrade
+
+| Command | Description |
+|---------|-------------|
+| `scale upgrade check` | Check for available upgrades |
+| `scale upgrade plan` | Generate upgrade plan |
+| `scale upgrade apply` | Apply upgrade plan |
+| `scale upgrade rollback` | Rollback latest upgrade |
+
+## Agents
+
+| Command | Description |
+|---------|-------------|
+| `scale agent spawn` | Spawn agent instance |
+| `scale agent list` | List active agents |
+| `scale agent profiles` | Show agent profiles |
+| `scale agent leaders` | Show leadership presets |
+
+## Other
+
+| Command | Description |
+|---------|-------------|
+| `scale diagnose plan` | Generate diagnostic plan |
+| `scale hunt scan` | Background Hunter scan |
+| `scale hunt report` | Generate hunt report |
+| `scale hunt diagnose` | Run hunt diagnostics |
+| `scale hunt ignore` | Add to ignore baseline |
+| `scale dependency audit` | Audit dependencies |
+| `scale tdd slice` | Create TDD slice |
+| `scale quickstart` | Quick start wizard |
+| `scale tui` | Terminal UI |
+| `scale qa` | Quality assurance checks |
+| `scale auto-fix` | Auto-fix common issues |
+| `scale cost-report` | Generate cost report |
+| `scale cost-optimize` | Optimize costs |
+| `scale cross-review` | Cross-agent code review |
+
+## Examples
+
+```bash
+# Initialize project
+scale init
+
+# Run setup wizard
+scale setup --interactive
+
+# Define and execute a task
+scale define "Add user authentication" --level M
+scale plan
+scale build
+scale verify
+scale review
+scale ship
+
+# Memory operations
+scale memory query "authentication patterns"
+scale memory provider status
+scale memory provider use gbrain
+
+# Code intelligence
+scale codegraph query "UserService"
+scale codegraph impact src/auth/login.ts
+
+# Skills
+scale skill scan
+scale skill recommend "implement OAuth"
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hongmaple0820/scale-engine",
-  "version": "0.44.0",
+  "version": "0.45.0",
   "description": "Executable AI agent governance with workflow gates, evidence, skill/tool orchestration, and traceable HTML artifacts",
   "repository": {
     "type": "git",
@@ -25,10 +25,9 @@
   "files": [
     "dist",
     "docs/README.md",
-    "docs/SKILL_RADAR.md",
-    "docs/SKILL-REPOSITORY.md",
-    "docs/EXTERNAL_REFERENCES.md",
-    "docs/THIRD_PARTY_SKILLS.md",
+    "docs/reference",
+    "docs/architecture",
+    "docs/migration",
     "docs/guides",
     "docs/start",
     "docs/workflow",

package/docs/EXTERNAL_REFERENCES.md

@@ -1,66 +0,0 @@
-# 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) | Secondary external memory provider | external provider, fallback-only | Apache-2.0 | `MemoryProviders`, `SkillRepository`, README |
-| [garrytan/gbrain](https://github.com/garrytan/gbrain) | Default graph-backed memory provider | external provider, default-enabled | MIT | `MemoryProviders`, `SkillRepository`, README |
-| [safishamsi/graphify](https://github.com/safishamsi/graphify) | Default knowledge graph and semantic recall source | external provider, default-enabled | review-required | `GraphifyKnowledgeBase`, `CodeIntelligence`, docs |
-| [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | Upstream code intelligence CLI and MCP server for project-local code graph queries | external CLI and MCP reference | MIT | `CodeIntelligence`, `doctor`, quickstart docs |
-| [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` |
-| [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | Governed CLI proxy for output compression and shell wrapping | external CLI reference | review-required | `ToolCapabilityRegistry`, `ToolOrchestrator`, `InstalledSkillsIntegration`, docs |
-| [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

package/docs/SKILL-REPOSITORY.md

@@ -1,57 +0,0 @@
-# SCALE Skill 仓库
-
-这个仓库视图用于让 Agent 按任务渐进式发现、激活和编排 skills/MCP/CLI，而不是一次性把所有能力塞进上下文。
-
-## 渐进式披露
-
-1. 启动时只读取 Skill 元数据和一句话描述。
-2. 任务命中时才读取完整 SKILL.md。
-3. scripts、references、assets 只在明确需要时懒加载。
-
-## 安全安装
-
-- 安装前必须执行安全扫描，阻断 `curl | bash`、`Invoke-Expression`、危险删除和非 HTTPS 来源。
-- npm/npx 来源必须补充 `npm audit signatures`、来源仓库、许可证和版本/commit 固定检查。
-- 任何第三方 Skill 都先进入隔离审查，再写入项目或全局 skills 目录。
-
-## 供应链防护清单
-
-- review-skill-frontmatter
-- inspect-scripts-directory
-- verify-license-and-source
-- verify-attribution-and-notice
-- pin-source-revision
-- npm-audit-signatures
-
-## Skill 目录
-
-| ID | 类别 | 信任 | 主要用途 | 组合建议 |
-| --- | --- | --- | --- | --- |
-| `planning-with-files` | planning | community | Use persistent planning files, progress logs, findings, active-plan selection, and plan attestation for long-running agent work. | memory-brain, web-access, code-reviewer |
-| `agentmemory` | memory | community | Use as an optional external memory provider via REST or MCP when teams want cross-agent persistent memory beyond SCALE local Memory Brain. | memory-brain, mcp-chrome-devtools, codex-cli |
-| `gbrain` | memory | community | Use as the default graph-backed memory provider for long-running project knowledge, entity relationships, and background memory maintenance. | memory-brain, agentmemory, codegraph |
-| `frontend-design` | ui | official | 在 DESIGN.md 和 UX 验收之后补齐前端实现约束、组件状态和落地方式。 | awesome-design-md, ui-ux-pro-max, webapp-testing |
-| `awesome-design-md` | ui | ecosystem | 建立产品级设计规范、品牌语言和 DESIGN.md。 | ui-ux-pro-max, frontend-design |
-| `ui-ux-pro-max` | ui | ecosystem | 补齐体验策略、交互状态和 UI 验收维度。 | awesome-design-md, webapp-testing |
-| `webapp-testing` | testing | official | 验证页面点击、表单、控制台、截图和端到端行为。 | agent-browser, mcp-chrome-devtools |
-| `web-access` | browser | ecosystem | 获取一手资料、动态页面内容、网页证据和来源引用。 | agent-browser, mcp-chrome-devtools |
-| `agent-browser` | browser | ecosystem | 与 Web 页面真实交互，补齐手工验收证据。 | web-access, webapp-testing, mcp-chrome-devtools |
-| `mcp-chrome-devtools` | browser | ecosystem | 调试控制台错误、网络请求、页面状态和性能问题。 | agent-browser, webapp-testing |
-| `cua` | desktop | ecosystem | 操作桌面应用并收集端侧截图、状态和副作用边界证据。 | web-access, agent-browser |
-| `code-reviewer` | review | official | 合并前分级审查缺陷、安全、可维护性和测试风险。 | security-and-hardening, update-docs |
-| `fix` | review | official | 提交前清理格式和 lint 问题。 | code-reviewer |
-| `pr-creator` | review | official | 生成标准 PR 描述和合并前说明。 | code-reviewer, update-docs |
-| `update-docs` | docs | official | 发现并更新受代码变更影响的长期文档。 | documentation-and-adrs |
-| `find-skills` | discovery | ecosystem | 按任务意图搜索合适 Skill，再进入安全扫描。 | web-access |
-| `codex-cli` | agent-cli | official | 外部 CLI 审查和命令级证据。 | gemini-cli, opencode-cli |
-| `gemini-cli` | agent-cli | official | 外部 CLI 审查和命令级证据。 | codex-cli, opencode-cli |
-| `opencode-cli` | agent-cli | ecosystem | 外部 CLI 审查和命令级证据。 | codex-cli, gemini-cli |
-| `agency-agents-zh` | role-library | community | 提供 CEO、CTO、工程、设计、产品等角色预设参考。 | skill-safety-scan |
-
-## Third-Party Attribution
-
-| ID | License | Usage | Notice |
-| --- | --- | --- | --- |
-| `planning-with-files` | MIT | adapted-concept | Inspired by and compatible with OthmanAdi/planning-with-files. SCALE should not copy upstream files unless the MIT license text and attribution are included. |
-| `agentmemory` | Apache-2.0 | external-reference | Optional external integration only. Do not vendor agentmemory code into SCALE without preserving Apache-2.0 license text, modification notices, and any upstream NOTICE obligations. |
-| `gbrain` | MIT | external-reference | Optional external provider only. Do not vendor GBrain code into SCALE without preserving MIT license text, source revision, and modification notices. |

package/docs/SKILL_RADAR.md

@@ -1,135 +0,0 @@
-# Skill Radar
-
-Skill Radar is the active capability selection layer for SCALE. It does not auto-install or blindly run skills. It scores relevant skills, MCP servers, browser tools, desktop automation, and external CLIs against the current task, then returns:
-
-- why the capability matches
-- confidence score
-- safety level
-- required evidence
-- fallback path
-- supply-chain checks before installation or promotion
-
-The goal is to make agents actively use useful tools without turning the project into an unsafe prompt or tool bundle.
-
-## Commands
-
-```bash
-scale skill radar --task "Design upload UI and run browser E2E checks" --files src/pages/upload.tsx
-scale skill radar --task "Automate WPS desktop workflow with CUA" --json
-scale skill radar --task "Review release PR" --phase review --level L --output docs/worklog/tasks/release/skill-radar.md
-scale skill doctor --supply-chain
-scale skill doctor --supply-chain --json
-scale ai-os plan --task "Design upload UI and run browser E2E checks" --files src/pages/upload.tsx --json
-```
-
-## Safety Levels
-
-| Level | Meaning | Default action |
-| --- | --- | --- |
-| `trusted` | Official or low-risk capability with policy enabled | May be recommended when confidence is high |
-| `review-required` | Third-party or ecosystem capability | Require source, license, scripts, and revision review |
-| `restricted` | Browser, desktop, or external execution boundary | Require explicit evidence and side-effect boundaries |
-| `blocked` | Disabled by policy or failed safety review | Do not run; use fallback |
-
-## Confidence
-
-Skill Radar combines:
-
-- task keywords and workflow phase
-- changed file patterns
-- local skill installation
-- tool availability
-- trust level
-- policy status
-- frontend/package evidence
-- safety penalties
-
-The score is not a promise that the tool will work. It is a routing signal. Any recommendation still needs real evidence before the agent can claim success.
-
-## Default Domains
-
-| Domain | Typical triggers | Recommended capability types |
-| --- | --- | --- |
-| `ui` | UI, UX, frontend, component, visual, layout | design skills, visual review, screenshot evidence |
-| `browserAutomation` | browser, E2E, Playwright, Chrome, DevTools | web access, browser automation, DevTools evidence |
-| `desktopAutomation` | desktop, GUI, WPS, WeChat, CUA | disabled by default; manual operator fallback |
-| `externalCli` | Codex, Gemini, OpenCode, external agent CLI | disabled by default; dry-run and output evidence |
-| `review` | PR, merge, release, code review | reviewer skills, severity findings |
-| `docs` | docs, README, ADR, governance asset | doc impact and source-of-truth evidence |
-| `planning` | plans, task_plan, findings, progress, long-running work | file-backed planning, progress logs, plan attestation |
-| `memory` | memory, recall, knowledge, persistent memory, agentmemory, gbrain | provider-routed memory through agentmemory, gbrain, or scale-local fallback |
-| `discovery` | skill, MCP, tool, capability discovery | find-skills plus safety review |
-
-## Evidence Contract
-
-Each recommendation carries required evidence. Examples:
-
-- UI work: `ui-spec`, `design-rationale`, `screenshot`, `visual-review`
-- Browser work: `browser-evidence`, `console-summary`, `network-summary`, `scenario-result`
-- Desktop work: `operator-boundary`, `desktop-screenshot`, `affected-app`
-- External CLI work: `cli-version-check`, `command`, `exit-code`, `output-summary`
-- Review work: `review-report`, `finding-list`, `severity`
-- Planning work: `task-plan`, `findings-log`, `progress-log`, `plan-attestation`
-- Memory work: `memory-provider-health`, `privacy-boundary`, `data-retention-policy`, `query-result`
-
-If evidence is missing, the final delivery should list the capability as unverified rather than claiming it was used successfully.
-
-## Skill Execution Plan
-
-In v0.27.0, `createSkillPlan` and `scale ai-os plan` return an `executionPlan`:
-
-- `strategy`: currently `intent-evidence-graph-v1`
-- `steps`: ordered skill, artifact, and verification actions
-- `reason`: why the step was selected from task intents
-- `evidenceRequired`: what proof must be recorded
-- `fallback`: what to do when the skill, MCP, CLI, or verification path is unavailable
-
-This turns skill routing from a recommendation list into an auditable execution graph. Required steps still need concrete evidence or an explicit skipped/fallback record; recommended steps may be skipped with a reason.
-
-## Supply-Chain Doctor
-
-`scale skill doctor --supply-chain` reviews known skill sources and install commands for:
-
-- HTTPS source requirement
-- `curl | bash`, `wget | sh`, `Invoke-Expression`, and `iex` blocking
-- destructive install patterns
-- npm/npx lifecycle script review
-- required source, license, and revision checks
-- third-party attribution and NOTICE checks
-
-This is intentionally conservative. Third-party skills should start in review-required mode and be promoted only after inspection.
-
-External skill references and acknowledgements are tracked in [Third-Party Skills and External References](THIRD_PARTY_SKILLS.md) and the full [External Reference Inventory](EXTERNAL_REFERENCES.md). SCALE should not vendor community skill code unless the license text, source revision, copyright notice, and modification notes are preserved.
-
-## Policy Integration
-
-Skill Radar reads `.scale/tools.json` through the Tool Policy layer. Defaults:
-
-- UI and browser capabilities are enabled but evidence-required.
-- Desktop CUA is disabled by default.
-- External agent CLIs are disabled by default.
-- Browser tools require captured evidence and should stay in approved domains.
-
-Use Tool Policy to enable a restricted capability deliberately rather than relying on an agent's assumption.
-
-## Fallback Rule
-
-Every recommendation must include a fallback. This prevents tool theater:
-
-```text
-If the capability is missing, unsafe, low-confidence, or policy-blocked,
-the agent must use the fallback and record why the capability was not used.
-```
-
-## Artifact Lifecycle
-
-Skill Radar reports can be written into task artifacts:
-
-```bash
-scale skill radar \
-  --task "Refactor upload page and verify browser flow" \
-  --files src/pages/upload.tsx \
-  --output docs/worklog/tasks/2026-05-19-upload-refactor/skill-radar.md
-```
-
-Keep the report when it is evidence for an M/L/CRITICAL task. Do not commit transient local detection output unless it is part of the reviewed task artifact set.

package/docs/THIRD_PARTY_SKILLS.md

@@ -1,114 +0,0 @@
-# Third-Party Skills and External References
-
-This document records external skill projects that SCALE may learn from, recommend, or integrate with. It is a governance boundary, not a vendoring manifest. The complete cross-repo inventory is maintained in [External Reference Inventory](EXTERNAL_REFERENCES.md).
-
-## Policy
-
-- Do not vendor third-party skill code, images, logos, examples, or marketing copy unless the license review explicitly allows redistribution.
-- Preserve upstream license text, copyright notices, NOTICE files, source URL, and source revision before any vendored or modified redistribution.
-- Mark modified files and document what changed from upstream.
-- Treat optional external services as review-required until privacy, retention, credential, and delete boundaries are reviewed.
-- `scale skill doctor --supply-chain` must include license, attribution, script, and pinned-revision checks for third-party skills.
-- Community skills start as `review-required`; promotion requires real installation evidence and a recorded safety decision.
-
-## Highlighted External References
-
-| Project | License | Upstream | SCALE usage | Redistribution status |
-| --- | --- | --- | --- | --- |
-| Planning with Files | MIT | [OthmanAdi/planning-with-files](https://github.com/OthmanAdi/planning-with-files) | Adapt concepts for file-backed plans, findings, progress logs, active-plan routing, and plan attestation. | Not vendored. |
-| agentmemory | Apache-2.0 | [rohitg00/agentmemory](https://github.com/rohitg00/agentmemory) | Optional external memory provider via REST or MCP for teams that need cross-agent persistent memory beyond local SCALE Memory Brain. | Not vendored. |
-| GBrain | MIT | [garrytan/gbrain](https://github.com/garrytan/gbrain) | Default memory provider route for graph-backed cross-session recall. SCALE verifies that a brain is configured and recall-critical health checks pass; CLI existence alone is not enough. | Not vendored. |
-| awesome-design-md | MIT | [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md) | DESIGN.md catalog for brand, visual language, typography, and design-system direction. `scale setup --pack ui --apply` syncs upstream under `~/.scale/vendor/awesome-design-md` and creates `~/.agents/skills/awesome-design-md/SKILL.md`. | Installed only with explicit setup/apply. |
-| ui-ux-pro-max | Upstream project license | [nextlevelbuilder/ui-ux-pro-max-skill](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | UX, UI state, accessibility, responsive, and acceptance-review skill. `scale setup --pack ui --apply` syncs upstream under `~/.scale/vendor/ui-ux-pro-max` and creates `~/.agents/skills/ui-ux-pro-max/SKILL.md`. | Installed only with explicit setup/apply. |
-| RTK | Upstream project license | [rtk-ai/rtk](https://github.com/rtk-ai/rtk) | Governed CLI proxy for shell-output compression and token savings. SCALE checks `rtk gain` and hook initialization. | External CLI only. |
-| Graphify | Upstream project license | [safishamsi/graphify](https://github.com/safishamsi/graphify) | Knowledge graph artifact provider. SCALE expects `graphify-out/graph.json` and Codex hook/skill freshness before relying on it. | Generated artifacts are project-local. |
-| CodeGraph | Upstream project license | [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph) | Code structure provider for symbol/context exploration. SCALE expects a project `.codegraph/` index. | External CLI/index only. |
-
-Other referenced skills, MCP servers, CLIs, discovery candidates, and adapter targets are listed in [External Reference Inventory](EXTERNAL_REFERENCES.md). Unknown licenses stay `review-required`; do not treat a repository link as redistribution permission.
-
-## Acknowledgements
-
-SCALE acknowledges these upstream projects and contributors:
-
-- `OthmanAdi/planning-with-files`, Copyright (c) 2026 Ahmad Adi.
-- `rohitg00/agentmemory` and its upstream contributors.
-- `garrytan/gbrain` and its upstream contributors.
-- All upstream projects listed in [External Reference Inventory](EXTERNAL_REFERENCES.md) according to their licenses and contribution histories.
-
-The current SCALE implementation records these projects as external references or adapted concepts. It does not copy their source code into this repository.
-
-## Vendoring Checklist
-
-If SCALE later vendors or modifies any third-party skill, the change must include:
-
-1. Full upstream license text in the distributed package.
-2. Upstream copyright and NOTICE material.
-3. Source repository URL and pinned revision.
-4. Modification notes for every copied or changed file.
-5. Tests or doctor checks proving the attribution metadata is present.
-6. README and generated skill repository documentation updates.
-
-## Runtime Boundaries
-
-External memory providers must not be enabled silently. Before use, record:
-
-- provider endpoint and health check evidence
-- project data scope
-- credential boundary
-- retention and deletion policy
-- whether data leaves the local machine or team-controlled infrastructure
-- whether provider writes are disabled, candidate-only, or explicitly enabled
-
-External planning skills must not replace SCALE task evidence. They can improve the plan artifact shape, but final delivery still requires verification output, changed-file evidence, and explicit unverified-risk notes.
-
-## User-Facing Setup
-
-Use the governed installer instead of asking users to discover every upstream command manually:
-
-```bash
-scale setup --pack full
-scale setup --pack full --apply --yes
-scale setup --pack full --json
-```
-
-Default language is Chinese. Running `scale setup` without `--json` starts the interactive wizard: language, dependency pack, memory provider, memory route, and install scope. Use `--lang en` or `SCALE_LANG=en` for English output.
-
-`setup` and `bootstrap deps` now expose report-level `runtimeChecks` before any install command runs. Missing `python`, `bun`, `cargo`, `uv/pipx`, or `node/npm/npx` is shown with a targeted install hint, so users can fix the environment before `--yes`/`--apply`.
-
-Memory provider routing can be configured during setup:
-
-```bash
-scale setup --pack memory --memory-provider scale-local --json
-scale setup --pack memory --memory-provider gbrain --memory-mode external-first --json
-```
-
-Repository maintainers should run the setup smoke before release or after changing installer behavior:
-
-```bash
-npm run smoke:setup
-make setup-smoke
-```
-
-The smoke is intentionally non-destructive: it validates bilingual output, `runtimeChecks`, memory-provider routing writes in a temp `.scale`, and CodeGraph/Graphify status discovery without running third-party installers.
-
-For a real installer smoke in an isolated home directory, verify both the skill adapter and the upstream vendor checkout:
-
-```bash
-scale setup --pack ui --include awesome-design-md --apply --yes
-test -f ~/.agents/skills/awesome-design-md/SKILL.md
-test -d ~/.scale/vendor/awesome-design-md
-```
-
-For OS-specific failures, run:
-
-```bash
-scale doctor env --json
-```
-
-This reports platform, shell discovery, PATH shape, core tools, package managers, and optional third-party runtimes in one machine-readable payload.
-
-`frontend-design` is no longer part of the default UI install path. The default UI stack is:
-
-- `awesome-design-md` for brand, visual language, and `DESIGN.md`.
-- `ui-ux-pro-max` for UX flow, UI state, accessibility, and responsive acceptance.
-- `frontend-design` only when explicitly requested with `--include frontend-design`.