@hongmaple0820/scale-engine 0.44.0 → 0.46.0

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`.