@hongmaple0820/scale-engine 0.25.0 → 0.26.0

package/docs/EXTERNAL_REFERENCES.md

@@ -1,58 +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` |
-| [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
+# 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

package/docs/GITLAB_FLOW.md

@@ -1,125 +1,125 @@
-# GitLab Flow Branch and Worktree Policy
-
-SCALE Engine uses a GitLab Flow variant for this repository:
-
-```text
-feat/* / fix/* / chore/* / docs/* / codex/*
-        -> dev
-        -> master
-        -> vX.Y.Z tag
-        -> npm publish
-
-hotfix:
-        fix forward on dev first when possible
-        -> cherry-pick to hotfix/*
-        -> master
-        -> vX.Y.Z tag
-        -> sync master back to dev
-
-selective release, only when dev contains work that must not ship:
-        master
-        -> release/vX.Y.Z
-        -> cherry-pick selected commits
-        -> master
-        -> vX.Y.Z tag
-        -> sync master back to dev
-```
-
-## Branch Roles
-
-| Branch | Role | Rule |
-| --- | --- | --- |
-| `dev` | Integration and test branch | Merge reviewed short branches here. Do not create direct governed commits on `dev`. |
-| `master` | Production branch | Only verified release/hotfix results land here. Publish from user-created `vX.Y.Z` tags on `master`. |
-| `feat/*`, `feature/*` | Feature branches | Start from current `dev`, merge back to `dev`, then delete. |
-| `fix/*` | Normal bug fix branches | Start from current `dev`, merge back to `dev`, then delete. |
-| `chore/*`, `docs/*`, `codex/*` | Maintenance branches | Short-lived work branches that merge back to `dev`. |
-| `hotfix/*` | Production patch branches | Use only for production fixes. Fix forward to `dev` first when possible, then cherry-pick to hotfix/master. |
-| `release/*` | Selective release branch | Use only when `dev` contains work that must not ship. Start from `master` and cherry-pick the release list. |
-
-## Required Checks
-
-Run the release-grade verification set before merging to `master` or tagging:
-
-```bash
-npm run build
-npx vitest run
-git diff --check
-npm pack --dry-run
-```
-
-Every merge request should run the relevant build/lint/test checks before review is accepted. Do not wait until `master` to discover broken tests.
-
-## Merge and Conflict Rules
-
-- Public branches are not rebased: `dev`, `master`, `release/*`, and `hotfix/*` keep realistic history.
-- Personal short branches may be rebased before merge, but only with `--force-with-lease` and only before review is accepted.
-- Prefer squash merge from short branches into `dev` when one logical change should be easy to revert.
-- Resolve conflicts on the source branch, rerun verification, then merge. Do not resolve release conflicts directly on `master`.
-- Fix bugs forward first: land the fix on `dev` when possible, then cherry-pick the same commit to `hotfix/*` or the selected patch release branch.
-- Commit messages should explain intent and why the chosen path was selected when the decision is not obvious.
-
-## Ship Gate Rules
-
-`scale ship <task-id>` now enforces the branch lifecycle:
-
-- blocked on `dev`, `master`, `main`, and detached HEAD
-- allowed on configured short branches such as `feat/*`, `fix/*`, `chore/*`, `docs/*`, `codex/*`, `release/*`, and `hotfix/*`
-- still requires verification evidence, passing review evidence, and reviewed-file-only staging
-- still blocks dirty or unsafe child repositories in MOE/submodule workspaces
-
-Use:
-
-```bash
-scale workspace status --summary
-scale workspace finish --summary
-scale workspace finish --json
-```
-
-The report includes branch role, whether governed shipping is allowed, and cleanup blockers.
-
-## Worktree Lifecycle
-
-Temporary agent worktrees are safe to remove only when all of these are true:
-
-- root worktree is clean
-- child repositories are clean and pushed when required
-- the temporary branch has no unpushed commits
-- a branch with no upstream is already merged into `dev`/`master`, or it contains no unique work
-
-Cleanup remains dry-run by default:
-
-```bash
-scale workspace cleanup --dir <temporary-worktree> --dry-run --json
-scale workspace cleanup --dir <temporary-worktree> --apply --confirm <branch-or-head> --json
-```
-
-If cleanup is blocked, push the branch, merge it, cherry-pick it into the selected release, or explicitly discard it before removing the worktree.
-
-## Repository Bootstrap
-
-This repository currently treats `dev` as the integration branch and `master` as production. If `dev` falls behind `master` and has no unique commits, fast-forward `dev` to `master` before starting new feature work:
-
-```bash
-git fetch --all --prune
-git switch dev
-git merge --ff-only master
-git push origin dev
-git push github dev
-```
-
-After that, normal work should start from `dev`:
-
-```bash
-git switch dev
-git pull --ff-only origin dev
-git switch -c feat/<short-name>
-```
-
-Before creating a normal release from `dev`, inspect the release delta:
-
-```bash
-git log --oneline master..dev
-```
-
-If every listed commit is intended for the next production release, merge `dev` through the normal release path. If any commit must be excluded, create `release/vX.Y.Z` from `master` and cherry-pick only the approved release list.
+# GitLab Flow Branch and Worktree Policy
+
+SCALE Engine uses a GitLab Flow variant for this repository:
+
+```text
+feat/* / fix/* / chore/* / docs/* / codex/*
+        -> dev
+        -> master
+        -> vX.Y.Z tag
+        -> npm publish
+
+hotfix:
+        fix forward on dev first when possible
+        -> cherry-pick to hotfix/*
+        -> master
+        -> vX.Y.Z tag
+        -> sync master back to dev
+
+selective release, only when dev contains work that must not ship:
+        master
+        -> release/vX.Y.Z
+        -> cherry-pick selected commits
+        -> master
+        -> vX.Y.Z tag
+        -> sync master back to dev
+```
+
+## Branch Roles
+
+| Branch | Role | Rule |
+| --- | --- | --- |
+| `dev` | Integration and test branch | Merge reviewed short branches here. Do not create direct governed commits on `dev`. |
+| `master` | Production branch | Only verified release/hotfix results land here. Publish from user-created `vX.Y.Z` tags on `master`. |
+| `feat/*`, `feature/*` | Feature branches | Start from current `dev`, merge back to `dev`, then delete. |
+| `fix/*` | Normal bug fix branches | Start from current `dev`, merge back to `dev`, then delete. |
+| `chore/*`, `docs/*`, `codex/*` | Maintenance branches | Short-lived work branches that merge back to `dev`. |
+| `hotfix/*` | Production patch branches | Use only for production fixes. Fix forward to `dev` first when possible, then cherry-pick to hotfix/master. |
+| `release/*` | Selective release branch | Use only when `dev` contains work that must not ship. Start from `master` and cherry-pick the release list. |
+
+## Required Checks
+
+Run the release-grade verification set before merging to `master` or tagging:
+
+```bash
+npm run build
+npx vitest run
+git diff --check
+npm pack --dry-run
+```
+
+Every merge request should run the relevant build/lint/test checks before review is accepted. Do not wait until `master` to discover broken tests.
+
+## Merge and Conflict Rules
+
+- Public branches are not rebased: `dev`, `master`, `release/*`, and `hotfix/*` keep realistic history.
+- Personal short branches may be rebased before merge, but only with `--force-with-lease` and only before review is accepted.
+- Prefer squash merge from short branches into `dev` when one logical change should be easy to revert.
+- Resolve conflicts on the source branch, rerun verification, then merge. Do not resolve release conflicts directly on `master`.
+- Fix bugs forward first: land the fix on `dev` when possible, then cherry-pick the same commit to `hotfix/*` or the selected patch release branch.
+- Commit messages should explain intent and why the chosen path was selected when the decision is not obvious.
+
+## Ship Gate Rules
+
+`scale ship <task-id>` now enforces the branch lifecycle:
+
+- blocked on `dev`, `master`, `main`, and detached HEAD
+- allowed on configured short branches such as `feat/*`, `fix/*`, `chore/*`, `docs/*`, `codex/*`, `release/*`, and `hotfix/*`
+- still requires verification evidence, passing review evidence, and reviewed-file-only staging
+- still blocks dirty or unsafe child repositories in MOE/submodule workspaces
+
+Use:
+
+```bash
+scale workspace status --summary
+scale workspace finish --summary
+scale workspace finish --json
+```
+
+The report includes branch role, whether governed shipping is allowed, and cleanup blockers.
+
+## Worktree Lifecycle
+
+Temporary agent worktrees are safe to remove only when all of these are true:
+
+- root worktree is clean
+- child repositories are clean and pushed when required
+- the temporary branch has no unpushed commits
+- a branch with no upstream is already merged into `dev`/`master`, or it contains no unique work
+
+Cleanup remains dry-run by default:
+
+```bash
+scale workspace cleanup --dir <temporary-worktree> --dry-run --json
+scale workspace cleanup --dir <temporary-worktree> --apply --confirm <branch-or-head> --json
+```
+
+If cleanup is blocked, push the branch, merge it, cherry-pick it into the selected release, or explicitly discard it before removing the worktree.
+
+## Repository Bootstrap
+
+This repository currently treats `dev` as the integration branch and `master` as production. If `dev` falls behind `master` and has no unique commits, fast-forward `dev` to `master` before starting new feature work:
+
+```bash
+git fetch --all --prune
+git switch dev
+git merge --ff-only master
+git push origin dev
+git push github dev
+```
+
+After that, normal work should start from `dev`:
+
+```bash
+git switch dev
+git pull --ff-only origin dev
+git switch -c feat/<short-name>
+```
+
+Before creating a normal release from `dev`, inspect the release delta:
+
+```bash
+git log --oneline master..dev
+```
+
+If every listed commit is intended for the next production release, merge `dev` through the normal release path. If any commit must be excluded, create `release/vX.Y.Z` from `master` and cherry-pick only the approved release list.

package/docs/GOVERNANCE_DASHBOARD.md

@@ -1,85 +1,85 @@
-# Governance Dashboard
-
-Status: implemented baseline
-Since: v0.25 development branch
-
-Governance Dashboard turns existing SCALE evidence into a single reviewable HTML page. It does not replace Markdown, JSON, runtime evidence, eval records, or memory. It is a human-facing view over those sources.
-
-## Command
-
-```bash
-scale artifact dashboard
-scale artifact dashboard --task-id <task-id>
-scale artifact dashboard --dir /path/to/project
-scale artifact dashboard --output docs/worklog/tasks/<task-id>/artifacts/governance-dashboard.html
-scale artifact dashboard --json
-```
-
-Default output:
-
-```text
-.scale/reports/governance-dashboard.html
-.scale/reports/governance-dashboard-manifest.json
-```
-
-The default lifecycle is `generated-report` and the default Git policy is `ignore`. Promote or commit only dashboards that are intentionally used as reviewed task evidence or release evidence.
-
-When `--dir` is used and `SCALE_DIR` is not set, the default `.scale` directory is resolved inside the target project directory, not inside the shell's current working directory. This matters for scaffold and multi-repo validation runs.
-
-## Inputs
-
-The dashboard reads existing local evidence:
-
-| Area | Source |
-| --- | --- |
-| Runtime evidence | `.scale/evidence/runtime/` |
-| Workflow eval | `.scale/evals/runs/` and `.scale/evals/failures/` |
-| Workflow metrics | `.scale/metrics/tasks.jsonl` |
-| Gate evidence | `.scale/evidence/GATE-*.json` |
-| Command runs | `.scale/evidence/command-runs/` |
-| Model usage | `.scale/model-usage/usage.jsonl` |
-| Memory Brain | `.scale/memory/brain.sqlite` |
-| Resource Governance | workspace files plus `.scale/resource-policy.json` and `.scale/assets.json` |
-| HTML artifacts | task artifact manifests and rendered HTML files |
-
-## Aggregated Metrics
-
-V2.0 adds `MetricsAggregator` as the dashboard aggregation layer. It keeps the dashboard read-only and derives the following metrics from existing evidence:
-
-- recent task count and first-pass rate
-- average fix iterations
-- gate failure distribution
-- command output compression token savings
-- model usage and prompt-cache savings
-
-Each number must trace back to local JSON/JSONL evidence. If a source is absent, the dashboard reports zero rather than inventing values.
-
-## Status Model
-
-- Runtime evidence failures are blocking.
-- Memory contradictions are blocking.
-- Resource Governance failures are blocking.
-- Open eval failure replays are warnings, because they may be intentional baseline failures or pending improvement work.
-- Missing task HTML artifacts are informational.
-
-This keeps the dashboard useful as a review surface without turning every observation into a hard gate.
-
-## Recommended Use
-
-For M/L/CRITICAL work:
-
-```bash
-scale verify <task-id>
-scale eval run --suite workflow-baseline
-scale memory dream --json
-scale artifact dashboard --task-id <task-id>
-```
-
-For release review:
-
-```bash
-scale artifact dashboard
-scale artifact open --artifact-dir .scale/reports --type governance-dashboard --print-only
-```
-
-The dashboard should be attached to a release or PR only when it is deliberately selected as a review artifact. Routine generated dashboards should stay local.
+# Governance Dashboard
+
+Status: implemented baseline
+Since: v0.25 development branch
+
+Governance Dashboard turns existing SCALE evidence into a single reviewable HTML page. It does not replace Markdown, JSON, runtime evidence, eval records, or memory. It is a human-facing view over those sources.
+
+## Command
+
+```bash
+scale artifact dashboard
+scale artifact dashboard --task-id <task-id>
+scale artifact dashboard --dir /path/to/project
+scale artifact dashboard --output docs/worklog/tasks/<task-id>/artifacts/governance-dashboard.html
+scale artifact dashboard --json
+```
+
+Default output:
+
+```text
+.scale/reports/governance-dashboard.html
+.scale/reports/governance-dashboard-manifest.json
+```
+
+The default lifecycle is `generated-report` and the default Git policy is `ignore`. Promote or commit only dashboards that are intentionally used as reviewed task evidence or release evidence.
+
+When `--dir` is used and `SCALE_DIR` is not set, the default `.scale` directory is resolved inside the target project directory, not inside the shell's current working directory. This matters for scaffold and multi-repo validation runs.
+
+## Inputs
+
+The dashboard reads existing local evidence:
+
+| Area | Source |
+| --- | --- |
+| Runtime evidence | `.scale/evidence/runtime/` |
+| Workflow eval | `.scale/evals/runs/` and `.scale/evals/failures/` |
+| Workflow metrics | `.scale/metrics/tasks.jsonl` |
+| Gate evidence | `.scale/evidence/GATE-*.json` |
+| Command runs | `.scale/evidence/command-runs/` |
+| Model usage | `.scale/model-usage/usage.jsonl` |
+| Memory Brain | `.scale/memory/brain.sqlite` |
+| Resource Governance | workspace files plus `.scale/resource-policy.json` and `.scale/assets.json` |
+| HTML artifacts | task artifact manifests and rendered HTML files |
+
+## Aggregated Metrics
+
+V2.0 adds `MetricsAggregator` as the dashboard aggregation layer. It keeps the dashboard read-only and derives the following metrics from existing evidence:
+
+- recent task count and first-pass rate
+- average fix iterations
+- gate failure distribution
+- command output compression token savings
+- model usage and prompt-cache savings
+
+Each number must trace back to local JSON/JSONL evidence. If a source is absent, the dashboard reports zero rather than inventing values.
+
+## Status Model
+
+- Runtime evidence failures are blocking.
+- Memory contradictions are blocking.
+- Resource Governance failures are blocking.
+- Open eval failure replays are warnings, because they may be intentional baseline failures or pending improvement work.
+- Missing task HTML artifacts are informational.
+
+This keeps the dashboard useful as a review surface without turning every observation into a hard gate.
+
+## Recommended Use
+
+For M/L/CRITICAL work:
+
+```bash
+scale verify <task-id>
+scale eval run --suite workflow-baseline
+scale memory dream --json
+scale artifact dashboard --task-id <task-id>
+```
+
+For release review:
+
+```bash
+scale artifact dashboard
+scale artifact open --artifact-dir .scale/reports --type governance-dashboard --print-only
+```
+
+The dashboard should be attached to a release or PR only when it is deliberately selected as a review artifact. Routine generated dashboards should stay local.