@hongmaple0820/scale-engine 0.40.2 → 0.44.0

package/docs/GOVERNANCE_DASHBOARD.md

@@ -1,92 +0,0 @@
-# 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.
-
-You can inspect the same model-usage ledger directly without opening the HTML dashboard:
-
-```bash
-scale token report --since-days 7
-scale token report --day 2026-05-23 --json
-```
-
-## 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.

package/docs/MEMORY_BRAIN.md

@@ -1,104 +0,0 @@
-# Memory Brain
-
-Memory Brain is SCALE's project-scoped long-term memory layer. It is separate from Memory Fabric:
-
-- Memory Fabric builds a compact context pack for the current task.
-- Memory Brain stores reviewed project knowledge with evidence, confidence, scope, and contradiction checks.
-
-The first version is local-first and uses SQLite:
-
-```text
-.scale/memory/brain.sqlite
-.scale/memory/brain-manifest.json
-```
-
-## Commands
-
-```bash
-scale memory ingest --from evidence --task-id <task-id>
-scale memory ingest --from candidate --candidate-id <candidate-id>
-scale memory ingest --from failure --failure-id <failure-replay-id>
-scale memory query "OAuth callback state design"
-scale memory contradictions
-scale memory dream
-scale memory promote <memory-node-id-or-candidate-id>
-scale memory export --output .scale/memory/export.jsonl
-scale memory import .scale/memory/export.jsonl
-```
-
-## Node Contract
-
-```ts
-interface MemoryNode {
-  id: string
-  type: 'fact' | 'decision' | 'incident' | 'relation' | 'contradiction'
-  title: string
-  summary: string
-  entities: string[]
-  source: 'runtime-evidence' | 'task-artifact' | 'docs' | 'git' | 'manual'
-  evidencePaths: string[]
-  confidence: number
-  scope: 'project' | 'workspace' | 'global-candidate'
-  status: 'candidate' | 'active' | 'stale' | 'rejected'
-  createdAt: string
-  updatedAt: string
-  lastVerifiedAt?: string
-}
-```
-
-## Evidence Rule
-
-Active memory must have at least one evidence path. SCALE blocks promotion when this is not true.
-
-Runtime evidence and learning candidates are ingested as `candidate` records first. `scale memory promote` is the explicit boundary where reviewed memory becomes active.
-
-Failure replay records can also be ingested as `incident` candidates:
-
-```bash
-scale eval run --suite workflow-baseline
-scale eval failures --since 30d
-scale memory ingest --from failure --failure-id <failure-replay-id>
-scale memory promote <memory-node-id>
-```
-
-This connects Eval Harness failures to long-term memory without automatically rewriting project standards. A failure becomes active memory only after promotion and only if the replay artifact is present as evidence.
-
-## Scope Rule
-
-Project memory stays project-scoped by default. `global-candidate` is allowed for export and review, but it cannot be activated inside a project brain. This prevents one project's temporary truth from becoming a global rule.
-
-## Contradiction Rule
-
-`scale memory contradictions` reports conflicts instead of resolving them automatically. Examples:
-
-- one memory says a provider is enabled, another says it is disabled
-- one memory says a route exists, another says it is missing
-- one memory says an operation is allowed, another says it is blocked
-
-The command exits non-zero when active contradictions exist.
-
-## Dream Maintenance
-
-`scale memory dream` is a maintenance pass. It reports:
-
-- promotion candidates
-- stale active memories
-- duplicate groups
-- contradictions
-- suggested docs to update
-- active memories missing evidence
-
-It does not auto-promote standards, rewrite docs, or delete memories.
-
-## Resource Lifecycle
-
-Memory Brain files under `.scale/memory/` are local runtime state by default. Commit only curated exports, documented decisions, or task artifacts that were intentionally reviewed.
-
-Recommended flow:
-
-```text
-runtime evidence -> memory settle -> memory ingest -> memory promote -> docs/standards update when stable
-eval failure replay -> memory ingest --from failure -> memory promote -> workflow rule update when stable
-```
-
-This keeps memory useful without turning every session observation into permanent project truth.

package/docs/MEMORY_FABRIC.md

@@ -1,161 +0,0 @@
-# Memory Fabric
-
-Memory Fabric 是 SCALE 用来降低长会话 token 消耗、提升 Agent 记忆质量的上下文压缩层。它不会把所有历史文档都塞回提示词，而是按任务范围生成一个可审计的 context pack。
-
-它聚合四类信息：
-
-- Runtime Evidence：真实运行过的命令、工具、浏览器、skill、MCP 和人工验证证据。
-- Session Events：当前会话的阶段、工具使用和证据写入事件。
-- Knowledge Recall：从项目知识库召回已验证经验、规则和历史教训。
-- Project Graph：检测 `graphify-out/graph.json`、`graphify-out/GRAPH_REPORT.md` 或 `.scale/graph/manifest.json`，只引用图谱状态和摘要，不把大型图谱全文塞进上下文。
-
-## 基本命令
-
-生成上下文包：
-
-```bash
-scale memory pack \
-  --task-id 2026-05-18-runtime-evidence \
-  --session-id 2026-05-18-runtime-evidence \
-  --task "继续实现 runtime evidence 与最终交付检查" \
-  --level M \
-  --files src/runtime,src/api/cli.ts \
-  --budget 4000
-```
-
-输出 JSON，便于其他 Agent、CLI 或评审工具读取：
-
-```bash
-scale memory pack \
-  --task "修复 OAuth callback state 过期处理" \
-  --level M \
-  --budget 4000 \
-  --json
-```
-
-检查上下文预算：
-
-```bash
-scale memory doctor \
-  --task "跨模块权限重构" \
-  --level L \
-  --budget 3000
-```
-
-把完成任务后的运行证据沉淀成学习候选：
-
-```bash
-scale memory settle \
-  --task-id 2026-05-18-runtime-evidence \
-  --session-id 2026-05-18-runtime-evidence \
-  --task "继续实现 runtime evidence 与最终交付检查" \
-  --level M \
-  --budget 4000
-```
-
-`settle` 会写入：
-
-```text
-.scale/memory/learning-candidates/<candidate-id>.json
-.scale/memory/learning-candidates/<candidate-id>.md
-```
-
-这些文件是本地运行时学习候选，默认不应该直接提交到 Git。它们的作用是让人类或评审 Agent 判断“这条经验是否值得进入长期知识库、工程规范或模块文档”。
-
-## 预算策略
-
-Memory Fabric 使用估算 token 预算控制上下文规模。优先级从高到低：
-
-1. Runtime Evidence：失败证据和通过证据优先保留。
-2. Session Events：最近会话事件优先保留。
-3. Knowledge Recall：按任务描述和文件范围召回 Top K 知识。
-4. Project Graph：只保留图谱报告路径和短摘要。
-
-当预算不足时，低优先级 section 会被标记为 omitted，并写入原因。这样 Agent 能知道哪些上下文被刻意裁剪，而不是误以为项目没有相关信息。
-
-## 与知识库和自我进化的关系
-
-Memory Fabric 不替代知识库。它是知识库、运行证据和图谱之间的读取层：
-
-- Runtime Evidence 记录“这次实际做过什么”。
-- Knowledge Base 记录“长期可复用的经验和规则”。
-- Graphify 或项目图谱记录“模块之间的结构关系”。
-- Memory Fabric 在每次任务开始、恢复、评审或发版前，生成本次最相关的上下文包。
-
-任务完成后，应该把真正稳定的经验沉淀到知识库或长期维护文档中；`.scale/events/` 和 `.scale/evidence/` 仍然是本地运行时产物，不应默认提交到 Git。
-
-新的推荐闭环是：
-
-```text
-runtime evidence -> memory pack -> memory settle -> 人审 -> knowledge/docs/rules
-```
-
-也就是说，Memory Fabric 先把证据和上下文压缩成候选，不会自动把一次会话里的判断升级成长期规则。存在失败证据时，候选会标记为 `resolve-failures-first`，避免把未闭环问题沉淀成“经验”。
-
-## 推荐使用场景
-
-- 长会话恢复前：先生成 context pack，避免重复读大量文档。
-- 多 Agent 协作前：把 context pack 交给审查 Agent 或测试 Agent。
-- 发版前：用 runtime evidence 和 session events 检查是否存在未闭环失败。
-- 任务结束后：用 `memory settle` 生成学习候选，再决定是否进入知识库、模块文档或工程规范。
-- 大型项目治理：结合 service matrix、resource governance 和 engineering standards，生成任务相关而不是全仓库噪声上下文。
-
-## 当前边界
-
-- 当前版本不内置向量数据库；如果项目配置了 SQLite knowledge base，会使用现有召回接口。
-- 当前版本只检测 Graphify 产物是否存在并生成摘要，不主动运行 Graphify。
-- HTML 可视化报告适合后续加在 context pack 之上；Memory Fabric 的核心产物先保持 JSON/Markdown，方便 diff、测试和 CLI 集成。
-
-## Memory Provider Router
-
-SCALE now treats strong memory systems as providers instead of rebuilding them inside the workflow engine.
-
-Default provider order:
-
-```text
-gbrain -> agentmemory -> scale-local
-```
-
-Commands:
-
-```bash
-scale memory provider init
-scale memory provider status --json
-scale memory provider use gbrain --json
-scale tool doctor --tools gbrain --json
-scale memory provider recall "OAuth callback Redis state" --json
-scale ai-os plan --task "Fix OAuth callback Redis state" --files src/auth/oauth.ts --json
-```
-
-Provider rules:
-
-- `gbrain` is the default external-first provider. SCALE treats CLI existence as insufficient: `scale memory provider status --json` requires a configured brain with working connection/schema checks before marking it available. Full `gbrain doctor --json` warnings that are unrelated to recall, such as local skill resolver issues, are reported as degraded health but do not block read-only recall. If the CLI exists but no brain is configured, the status remains unavailable and points to `gbrain init --pglite`.
-- The preferred remote production path is the official thin-client flow: run `gbrain serve --http` on the host, then configure the local CLI with `gbrain init --mcp-only` so SCALE can keep calling `gbrain query` through the thin client instead of inventing a separate ad-hoc REST contract.
-- `agentmemory` remains optional and can be added as a second provider when teams want cross-agent shared memory.
-- `memory provider use <id>` is the fast path for switching the default route without hand-editing `.scale/memory-providers.json`.
-- External providers are read-only by default. Writes require an explicit provider policy change.
-- `scale-local` remains the fallback provider through Memory Brain and only promotes reviewed, evidence-backed memory.
-- `memory pack` automatically includes a `provider-memory` section when provider recall returns relevant active memories.
-- `ai-os plan` includes both the provider recall summary and the Memory Fabric context pack, so agents can route memory before planning without pretending external memory is always available.
-
-This keeps agents flexible: they can ask the router for memory before planning, verification, review, or release, while SCALE still records which provider was used and why fallback was required.
-
-Setup shortcut:
-
-```bash
-scale setup --pack memory
-scale setup --pack memory --memory-provider scale-local --json
-scale setup --pack memory --memory-provider gbrain --memory-mode external-first --json
-scale memory provider status --json
-```
-
-`setup --memory-provider` is the preferred UX for provider switching during onboarding. It writes the same routing file as `scale memory provider use`, returns `memoryProviderSwitch` in JSON, and keeps external writes disabled unless `--allow-external-write` is explicitly passed.
-
-Remote replay validation:
-
-```bash
-npm run smoke:gbrain
-node scripts/workflow/provider-rehearsal.mjs --skip-graphify --require-gbrain
-```
-
-This is intentionally stronger than `scale memory provider status --json`: it requires a real configured gbrain, writes a temporary page, then reads and queries it through separate CLI processes. If no remote/thin-client brain is configured, the rehearsal must report `blocked` or fail under `--require-gbrain`; falling back to `scale-local` is not a valid substitute for cross-session provider validation.

package/docs/RESOURCE_GOVERNANCE.md

@@ -1,92 +0,0 @@
-# Resource Governance
-
-SCALE now treats project outputs as governed resources instead of undifferentiated files.
-
-## Problem
-
-Engineering agents generate many useful but noisy assets:
-
-- maintained product and architecture docs
-- task plans and verification notes
-- E2E reports, screenshots, videos, logs, and coverage output
-- temporary scripts and scratch files
-- reusable automation scripts
-- API contracts and ADRs
-
-Without lifecycle rules these files drift, conflict with the real codebase, or get committed to Git when they should be local evidence only.
-
-## Model
-
-`scale assets scan` classifies resources into:
-
-| Type | Default Git policy | Lifecycle |
-| --- | --- | --- |
-| canonical-doc | commit | maintained |
-| decision-record | commit | immutable |
-| contract | commit | maintained |
-| reusable-script | commit | maintained |
-| task-artifact | review | task-scoped |
-| evidence-report | ignore | generated |
-| generated-media | review/external | generated or review-required |
-| temporary | ignore | temporary |
-
-`.scale/resource-policy.json` owns defaults such as owners, module mapping, runtime directories, and maximum Git file size.
-
-`.scale/assets.json` is the explicit catalog for long-lived project assets and source-of-truth declarations.
-Declared source-of-truth assets are checked by `assets doctor`; if the file disappears, the doctor fails. Maintained assets can also declare `lastReviewedAt` and `reviewIntervalDays` so product, architecture, workflow, and standards documents are rechecked against the current implementation instead of drifting silently:
-
-```json
-{
-  "assets": [
-    {
-      "path": "docs/modules/auth/architecture.md",
-      "type": "canonical-doc",
-      "owner": "auth-team",
-      "module": "auth",
-      "sourceOfTruth": true,
-      "lifecycle": "maintained",
-      "gitPolicy": "commit",
-      "lastReviewedAt": "2026-05-15",
-      "reviewIntervalDays": 90
-    }
-  ]
-}
-```
-
-## Commands
-
-```bash
-scale assets scan --json
-scale assets doctor --json
-scale assets settle --task-id <task-id> --artifact-dir .planning/tasks/<task>
-scale init --governance-pack resource-governance
-```
-
-`assets doctor` fails when runtime evidence or external media is already tracked by Git, or when a declared source-of-truth asset is missing. It warns on large tracked files, expired temporary outputs, ownerless canonical documentation, missing non-source catalog entries, and stale maintained assets.
-
-`assets settle` runs the same checks and appends a settlement section to `resource-impact.md` when a task artifact directory is provided.
-
-## Finish Rule
-
-Before finishing M/L/CRITICAL work:
-
-1. Promote final product, API, or architecture truth into maintained docs.
-2. Keep task-scoped planning, runtime contracts, reality checks, cleanup notes, raw reports, logs, screenshots, videos, and scratch scripts out of long-lived `docs/` unless deliberately promoted.
-3. Run `scale assets scan --json`.
-4. Run `scale assets doctor --json`.
-5. Run `scale assets settle --task-id <task-id> --artifact-dir <task-dir>`.
-6. Delete or archive temporary resources that are no longer needed.
-
-## Task Artifact Boundary
-
-New SCALE task artifacts default to `.planning/tasks/<task>/`, not `docs/worklog/tasks/<task>/`.
-
-Every M/L/CRITICAL task should keep these three evidence files alongside the normal explore/plan/verification/review/summary set:
-
-| File | Purpose |
-| --- | --- |
-| `runtime.md` | Records configuration source, topology, auth mode, and verification boundary. |
-| `reality-check.md` | Separates confirmed behavior from not verified, stub/partial, credential-gated, and environment-gated claims. |
-| `resource-cleanup.md` | Records which outputs stay task-scoped, which are promoted, and which should be deleted or archived. |
-
-`docs/worklog/tasks/` remains a legacy-recognized task-artifact location for existing projects, but generated guidance now points new work to `.planning/tasks/`.

package/docs/RUNTIME_EVIDENCE.md

@@ -1,101 +0,0 @@
-# Runtime Evidence
-
-Runtime Evidence 是 SCALE 用来记录 Agent 实际做过什么的运行时证据层。它的目标很直接：没有真实命令、工具、浏览器、skill 或人工验证证据时，Agent 不能声称任务已经完成。
-
-它和现有证据层的关系：
-
-- Gate evidence：回答 build、lint、test、security、review 等门禁是否通过。
-- Tool evidence：回答必需的 skill、MCP、浏览器、桌面自动化或 CLI 工具是否执行过。
-- Runtime evidence：回答当前会话是否具备可信的最终交付证据。
-
-## 存储位置
-
-Runtime 数据写入 SCALE 已忽略的本地运行时目录：
-
-```text
-.scale/
-├── events/
-│   ├── current-session.json
-│   └── sessions/<session-id>.jsonl
-└── evidence/
-    └── runtime/<evidence-id>.json
-```
-
-这些文件默认是本地运行时产物，不应该提交到 Git。需要长期保留时，应把摘要沉淀到任务 summary、ADR、README 或模块文档中，而不是直接提交原始日志。
-
-## 基本流程
-
-启动会话：
-
-```bash
-scale runtime start \
-  --session-id 2026-05-18-runtime-evidence \
-  --task-id 2026-05-18-runtime-evidence \
-  --level M \
-  --agent codex
-```
-
-在真实命令、门禁、浏览器验证、skill 执行、MCP 调用或人工检查之后记录证据：
-
-```bash
-scale runtime record \
-  --title "build" \
-  --kind command \
-  --status passed \
-  --command "npm run build" \
-  --exit-code 0 \
-  --summary "TypeScript build passed"
-```
-
-检查是否允许最终交付：
-
-```bash
-scale runtime final-check \
-  --task-id 2026-05-18-runtime-evidence \
-  --session-id 2026-05-18-runtime-evidence \
-  --level M
-```
-
-检查运行时健康状态：
-
-```bash
-scale runtime doctor --level M
-scale doctor
-```
-
-## 完成规则
-
-M、L、CRITICAL 任务在最终交付前必须满足：
-
-- 当前 task/session 范围内至少有一条 `passed` runtime evidence。
-- 当前 task/session 范围内不能存在 `failed` runtime evidence。
-
-S 级任务可以保持轻量，但一旦存在失败证据，仍然不能声称完成。
-
-## 脱敏规则
-
-Runtime evidence 复用 tool evidence 的脱敏模型。写入 JSON 前会处理命令、摘要、artifact 路径和 metadata 中的敏感字段：
-
-- password
-- token
-- secret
-- authorization
-- cookie
-- credential
-- api key
-- private key
-
-这样可以保留有用证据，同时避免把 token、cookie、密钥等内容写进运行时文件。
-
-## 推荐使用场景
-
-适合记录 runtime evidence 的场景：
-
-- 最终交付检查。
-- 长会话或多阶段任务。
-- 跨 Agent 或外部 CLI review。
-- 浏览器、桌面自动化、MCP、skill 验证。
-- 发版前 preflight。
-- 需要进入后续学习闭环的失败、修复和重试记录。
-
-不要用 runtime evidence 替代长期维护文档。Runtime evidence 是“操作证明”，PRD、ADR、架构文档、README、模块文档才是长期项目契约。