@hongmaple0820/scale-engine 0.25.0 → 0.26.0

package/docs/SKILL_RADAR.md

@@ -1,122 +1,122 @@
-# 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
-```
-
-## 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.
-
-## 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.
+# 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
+```
+
+## 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.
+
+## 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,57 +1,57 @@
-# 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) | Optional graph memory provider for brain repos, hybrid search, entity relationships, MCP, and background maintenance. | Not vendored. |
-
-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.
+# 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) | Optional graph memory provider for brain repos, hybrid search, entity relationships, MCP, and background maintenance. | Not vendored. |
+
+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.