@hongmaple0820/scale-engine 0.25.0 → 0.27.0

package/docs/MEMORY_FABRIC.md

@@ -1,134 +1,136 @@
-# Memory Fabric
-
-Memory Fabric 是 SCALE 用来降低长会话 token 消耗、提升 Agent 记忆质量的上下文压缩层。它不会把所有历史文档都塞回提示词，而是按任务范围生成一个可审计的 context pack。
-
-它聚合四类信息：
-
-- Runtime Evidence：真实运行过的命令、工具、浏览器、skill、MCP 和人工验证证据。
-- Session Events：当前会话的阶段、工具使用和证据写入事件。
-- Knowledge Recall：从项目知识库召回已验证经验、规则和历史教训。
-- Project Graph：检测 `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
-agentmemory -> gbrain -> scale-local
-```
-
-Commands:
-
-```bash
-scale memory provider init
-scale memory provider status --json
-scale memory provider recall "OAuth callback Redis state" --json
-```
-
-Provider rules:
-
-- `agentmemory` and `gbrain` are external providers and start disabled until endpoint, privacy, retention, and delete boundaries are reviewed.
-- 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.
-
-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.
+# Memory Fabric
+
+Memory Fabric 是 SCALE 用来降低长会话 token 消耗、提升 Agent 记忆质量的上下文压缩层。它不会把所有历史文档都塞回提示词，而是按任务范围生成一个可审计的 context pack。
+
+它聚合四类信息：
+
+- Runtime Evidence：真实运行过的命令、工具、浏览器、skill、MCP 和人工验证证据。
+- Session Events：当前会话的阶段、工具使用和证据写入事件。
+- Knowledge Recall：从项目知识库召回已验证经验、规则和历史教训。
+- Project Graph：检测 `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
+agentmemory -> gbrain -> scale-local
+```
+
+Commands:
+
+```bash
+scale memory provider init
+scale memory provider status --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:
+
+- `agentmemory` and `gbrain` are external providers and start disabled until endpoint, privacy, retention, and delete boundaries are reviewed.
+- 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.

package/docs/README.md

@@ -1,92 +1,102 @@
-# SCALE Engine 文档地图
-
-这个目录同时包含用户指南、治理能力说明、架构参考、历史规划和推广素材。新用户应优先阅读入门入口和当前治理能力文档，历史规划仅作为背景材料。
-
-## 新用户入口
-
-| 文档 | 说明 |
-| --- | --- |
-| [start/README.md](start/README.md) | 入门路径总览 |
-| [start/quickstart.md](start/quickstart.md) | 3 分钟快速开始 |
-| [start/agent-governance-demo.md](start/agent-governance-demo.md) | 官方 demo walkthrough |
-| [start/artifact-lifecycle.md](start/artifact-lifecycle.md) | Artifact 生命周期完整 walkthrough |
-| [../README.md](../README.md) | 项目主页和能力总览 |
-
-## 当前治理能力
-
-| 文档 | 说明 |
-| --- | --- |
-| [RESOURCE_GOVERNANCE.md](RESOURCE_GOVERNANCE.md) | 文档、报告、媒体、脚本、临时产物的生命周期治理 |
-| [ENGINEERING_STANDARDS.md](ENGINEERING_STANDARDS.md) | 日志、安全、ORM、框架、测试、部署等工程规范 |
-| [BACKGROUND_HUNTER.md](BACKGROUND_HUNTER.md) | Background Hunter 只读主动巡检、诊断交接和 ignore baseline |
-| [DEPENDENCY_AUDIT.md](DEPENDENCY_AUDIT.md) | 供应链依赖审计、G7 dependency 子门禁和 dependency policy |
-| [TOOL_ORCHESTRATION.md](TOOL_ORCHESTRATION.md) | skills、MCP、CLI、浏览器、桌面自动化的编排策略 |
-| [RUNTIME_EVIDENCE.md](RUNTIME_EVIDENCE.md) | 会话 ledger、运行时证据和最终交付检查 |
-| [MEMORY_FABRIC.md](MEMORY_FABRIC.md) | Runtime evidence、session events、knowledge recall 和 graph status 的预算化上下文包 |
-| [MEMORY_BRAIN.md](MEMORY_BRAIN.md) | 证据驱动的长期记忆、矛盾检测、dream 整理和 failure replay 沉淀 |
-| [CONTEXT_BUDGET.md](CONTEXT_BUDGET.md) | Context Budget、Progressive Governance、Lazy Loading 和 Governance ROI |
-| [CODE_INTELLIGENCE.md](CODE_INTELLIGENCE.md) | CodeGraph、Graphify 和显式 fallback 的代码智能与探索 ROI |
-| [WORKFLOW_EVAL.md](WORKFLOW_EVAL.md) | Workflow Eval、pass@k 指标、Failure Replay 和改进候选 |
-| [SKILL_RADAR.md](SKILL_RADAR.md) | Skill Radar、能力置信度、证据要求和供应链安全检查 |
-| [THIRD_PARTY_SKILLS.md](THIRD_PARTY_SKILLS.md) | 第三方 skill 致谢、授权边界、引用方式和 vendoring 策略 |
-| [EXTERNAL_REFERENCES.md](EXTERNAL_REFERENCES.md) | 外部项目、skills、MCP、CLI 和适配器引用的完整清单 |
-| [UPGRADE_MANAGEMENT.md](UPGRADE_MANAGEMENT.md) | SCALE CLI、governance pack、skills、MCP 和 CLI 工具的安全升级流程 |
-| [GOVERNANCE_DASHBOARD.md](GOVERNANCE_DASHBOARD.md) | Runtime、eval、memory、resource、HTML artifact 的统一治理面板 |
-| [RELEASE_READINESS.md](RELEASE_READINESS.md) | 发版前质量门槛、官方 demo 和真实项目落地验收 |
-| [DOCUMENT_STANDARDS.md](DOCUMENT_STANDARDS.md) | 文档编写与维护规范 |
-| [GITLAB_FLOW.md](GITLAB_FLOW.md) | GitLab Flow 分支、发版、tag 和临时 worktree 生命周期规范 |
-| [SKILL-REPOSITORY.md](SKILL-REPOSITORY.md) | 受治理 skill repository 和安装安全策略 |
-| [VIBE-TEMPLATES.md](VIBE-TEMPLATES.md) | 可复制的 Vibe Coding 提示词模板 |
-| [LEADERSHIP-PRESETS.md](LEADERSHIP-PRESETS.md) | CEO、CTO、PM、Architect 等内置领导者角色预设 |
-
-## 当前规划与执行蓝图
-
-这些文档描述计划中的架构演进，不代表当前 CLI 已全部实现。进入实现前应按文档中的验收标准和红线逐项拆分任务。
-
-| 文档 | 说明 |
-| --- | --- |
-| [plans/2026-05-20-scale-engine-v2-final-architecture-plan.md](plans/2026-05-20-scale-engine-v2-final-architecture-plan.md) | SCALE Engine V2.0 最终架构落地方案：Prompt Cache、Dashboard 聚合、Background Hunter、供应链门禁、动态/视觉验证和 Evolution Shadow Mode |
-
-## 架构与参考
-
-| 文档 | 说明 |
-| --- | --- |
-| [00-OVERVIEW.md](00-OVERVIEW.md) | 系统概览 |
-| [01-ARCHITECTURE.md](01-ARCHITECTURE.md) | 架构设计 |
-| [02-DATA-MODEL.md](02-DATA-MODEL.md) | 数据模型 |
-| [03-CORE-MODULES.md](03-CORE-MODULES.md) | 核心模块 |
-| [04-INTEGRATION.md](04-INTEGRATION.md) | 平台与集成 |
-| [06-DECISIONS.md](06-DECISIONS.md) | 架构决策记录 |
-
-## 历史规划和过程记录
-
-这些文档是历史上下文，不一定代表当前产品入口：
-
-| 文档 | 说明 |
-| --- | --- |
-| [05-ROADMAP.md](05-ROADMAP.md) | 路线图 |
-| [OPTIMIZATION_PLAN.md](OPTIMIZATION_PLAN.md) | 历史优化计划 |
-| [WEEK1-2-REPORT.md](WEEK1-2-REPORT.md) | 阶段报告 |
-| [TASK_GUARD_SUMMARY.md](TASK_GUARD_SUMMARY.md) | Task Guard 总结 |
-| [TASK_GUARD_WORKFLOW_DEMO.md](TASK_GUARD_WORKFLOW_DEMO.md) | 早期 workflow demo |
-| [plans/2026-05-19-agent-engineering-os-upgrade-plan.md](plans/2026-05-19-agent-engineering-os-upgrade-plan.md) | Agent Engineering OS 升级审核稿：Context Budget、CodeGraph、Memory Brain、Skill Radar、HTML Artifact 和 Eval Harness |
-| [plans/](plans/) | 规划方案和技术方案归档 |
-| [superpowers/](superpowers/) | 外部方法论对照和计划归档 |
-
-## 推广和素材
-
-| 文档 | 说明 |
-| --- | --- |
-| [promote-article-v2.md](promote-article-v2.md) | 推广文章草稿 v2 |
-| [promote-article-v2.html](promote-article-v2.html) | 推广文章 HTML v2 |
-| [promote-article-v3.md](promote-article-v3.md) | 推广文章草稿 v3 |
-| [promote-article-v3.html](promote-article-v3.html) | 推广文章 HTML v3 |
-| [imgs/](imgs/) | 社群二维码和推广图片 |
-
-## 维护规则
-
-- 面向新用户的文档优先放在 `docs/start/`。
-- 当前可执行能力放在根 README 和当前治理能力文档中。
-- 历史规划不要混入新手教程，避免用户把旧计划当成当前事实。
-- 如果 CLI 行为变化，必须同步更新 `README.md`、`docs/start/quickstart.md` 和相关 reference 文档。
-- 如果新增 governance pack，必须同时更新 `README.md`、`docs/start/README.md` 和对应测试。
+# SCALE Engine 文档地图
+
+这个目录同时包含用户指南、治理能力说明、架构参考、历史规划和推广素材。新用户应优先阅读入门入口和当前治理能力文档，历史规划仅作为背景材料。
+
+## 新用户入口
+
+| 文档 | 说明 |
+| --- | --- |
+| [start/README.md](start/README.md) | 入门路径总览 |
+| [start/quickstart.md](start/quickstart.md) | 3 分钟快速开始 |
+| [start/agent-governance-demo.md](start/agent-governance-demo.md) | 官方 demo walkthrough |
+| [start/artifact-lifecycle.md](start/artifact-lifecycle.md) | Artifact 生命周期完整 walkthrough |
+| [../README.md](../README.md) | 项目主页和能力总览 |
+
+## 仓库维护入口
+
+| 文档 | 说明 |
+| --- | --- |
+| [guides/GETTING_STARTED.md](guides/GETTING_STARTED.md) | `scale-engine` 仓库维护者的 15 分钟上手路径 |
+| [guides/DEVELOPMENT_WORKFLOW.md](guides/DEVELOPMENT_WORKFLOW.md) | 本仓库日常开发工作流 |
+| [workflow/README.md](workflow/README.md) | 仓库门禁、分支策略和 workflow 命令面 |
+
+## 当前治理能力
+
+| 文档 | 说明 |
+| --- | --- |
+| [RESOURCE_GOVERNANCE.md](RESOURCE_GOVERNANCE.md) | 文档、报告、媒体、脚本、临时产物的生命周期治理 |
+| [ENGINEERING_STANDARDS.md](ENGINEERING_STANDARDS.md) | 日志、安全、ORM、框架、测试、部署等工程规范 |
+| [BACKGROUND_HUNTER.md](BACKGROUND_HUNTER.md) | Background Hunter 只读主动巡检、诊断交接和 ignore baseline |
+| [DEPENDENCY_AUDIT.md](DEPENDENCY_AUDIT.md) | 供应链依赖审计、G7 dependency 子门禁和 dependency policy |
+| [TOOL_ORCHESTRATION.md](TOOL_ORCHESTRATION.md) | skills、MCP、CLI、浏览器、桌面自动化的编排策略 |
+| [RUNTIME_EVIDENCE.md](RUNTIME_EVIDENCE.md) | 会话 ledger、运行时证据和最终交付检查 |
+| [MEMORY_FABRIC.md](MEMORY_FABRIC.md) | Runtime evidence、session events、knowledge recall 和 graph status 的预算化上下文包 |
+| [MEMORY_BRAIN.md](MEMORY_BRAIN.md) | 证据驱动的长期记忆、矛盾检测、dream 整理和 failure replay 沉淀 |
+| [CONTEXT_BUDGET.md](CONTEXT_BUDGET.md) | Context Budget、Progressive Governance、Lazy Loading 和 Governance ROI |
+| [CODE_INTELLIGENCE.md](CODE_INTELLIGENCE.md) | CodeGraph、Graphify 和显式 fallback 的代码智能与探索 ROI |
+| [WORKFLOW_EVAL.md](WORKFLOW_EVAL.md) | Workflow Eval、pass@k 指标、Failure Replay 和改进候选 |
+| [SKILL_RADAR.md](SKILL_RADAR.md) | Skill Radar、能力置信度、证据要求和供应链安全检查 |
+| [AI_ENGINEERING_OS_POSITIONING.md](AI_ENGINEERING_OS_POSITIONING.md) | Agent Governance Runtime / AI Engineering OS 方向，以及 `scale ai-os plan` 一体化 runtime plan |
+| [THIRD_PARTY_SKILLS.md](THIRD_PARTY_SKILLS.md) | 第三方 skill 致谢、授权边界、引用方式和 vendoring 策略 |
+| [EXTERNAL_REFERENCES.md](EXTERNAL_REFERENCES.md) | 外部项目、skills、MCP、CLI 和适配器引用的完整清单 |
+| [UPGRADE_MANAGEMENT.md](UPGRADE_MANAGEMENT.md) | SCALE CLI、governance pack、skills、MCP 和 CLI 工具的安全升级流程 |
+| [GOVERNANCE_DASHBOARD.md](GOVERNANCE_DASHBOARD.md) | Runtime、eval、memory、resource、HTML artifact 的统一治理面板 |
+| [RELEASE_READINESS.md](RELEASE_READINESS.md) | 发版前质量门槛、官方 demo 和真实项目落地验收 |
+| [DOCUMENT_STANDARDS.md](DOCUMENT_STANDARDS.md) | 文档编写与维护规范 |
+| [GITLAB_FLOW.md](GITLAB_FLOW.md) | GitLab Flow 分支、发版、tag 和临时 worktree 生命周期规范 |
+| [SKILL-REPOSITORY.md](SKILL-REPOSITORY.md) | 受治理 skill repository 和安装安全策略 |
+| [VIBE-TEMPLATES.md](VIBE-TEMPLATES.md) | 可复制的 Vibe Coding 提示词模板 |
+| [LEADERSHIP-PRESETS.md](LEADERSHIP-PRESETS.md) | CEO、CTO、PM、Architect 等内置领导者角色预设 |
+
+## 当前规划与执行蓝图
+
+这些文档描述计划中的架构演进，不代表当前 CLI 已全部实现。进入实现前应按文档中的验收标准和红线逐项拆分任务。
+
+| 文档 | 说明 |
+| --- | --- |
+| [plans/2026-05-20-scale-engine-v2-final-architecture-plan.md](plans/2026-05-20-scale-engine-v2-final-architecture-plan.md) | SCALE Engine V2.0 最终架构落地方案：Prompt Cache、Dashboard 聚合、Background Hunter、供应链门禁、动态/视觉验证和 Evolution Shadow Mode |
+
+## 架构与参考
+
+| 文档 | 说明 |
+| --- | --- |
+| [00-OVERVIEW.md](00-OVERVIEW.md) | 系统概览 |
+| [01-ARCHITECTURE.md](01-ARCHITECTURE.md) | 架构设计 |
+| [02-DATA-MODEL.md](02-DATA-MODEL.md) | 数据模型 |
+| [03-CORE-MODULES.md](03-CORE-MODULES.md) | 核心模块 |
+| [04-INTEGRATION.md](04-INTEGRATION.md) | 平台与集成 |
+| [06-DECISIONS.md](06-DECISIONS.md) | 架构决策记录 |
+
+## 历史规划和过程记录
+
+这些文档是历史上下文，不一定代表当前产品入口：
+
+| 文档 | 说明 |
+| --- | --- |
+| [05-ROADMAP.md](05-ROADMAP.md) | 路线图 |
+| [OPTIMIZATION_PLAN.md](OPTIMIZATION_PLAN.md) | 历史优化计划 |
+| [WEEK1-2-REPORT.md](WEEK1-2-REPORT.md) | 阶段报告 |
+| [TASK_GUARD_SUMMARY.md](TASK_GUARD_SUMMARY.md) | Task Guard 总结 |
+| [TASK_GUARD_WORKFLOW_DEMO.md](TASK_GUARD_WORKFLOW_DEMO.md) | 早期 workflow demo |
+| [plans/2026-05-19-agent-engineering-os-upgrade-plan.md](plans/2026-05-19-agent-engineering-os-upgrade-plan.md) | Agent Engineering OS 升级审核稿：Context Budget、CodeGraph、Memory Brain、Skill Radar、HTML Artifact 和 Eval Harness |
+| [plans/](plans/) | 规划方案和技术方案归档 |
+| [superpowers/](superpowers/) | 外部方法论对照和计划归档 |
+
+## 推广和素材
+
+| 文档 | 说明 |
+| --- | --- |
+| [promote-article-v2.md](promote-article-v2.md) | 推广文章草稿 v2 |
+| [promote-article-v2.html](promote-article-v2.html) | 推广文章 HTML v2 |
+| [promote-article-v3.md](promote-article-v3.md) | 推广文章草稿 v3 |
+| [promote-article-v3.html](promote-article-v3.html) | 推广文章 HTML v3 |
+| [imgs/](imgs/) | 社群二维码和推广图片 |
+
+## 维护规则
+
+- 面向新用户的文档优先放在 `docs/start/`。
+- 面向本仓库维护者的 workflow 文档优先放在 `docs/guides/` 和 `docs/workflow/`。
+- 当前可执行能力放在根 README 和当前治理能力文档中。
+- 历史规划不要混入新手教程，避免用户把旧计划当成当前事实。
+- 如果 CLI 行为变化，必须同步更新 `README.md`、`docs/start/quickstart.md` 和相关 reference 文档。
+- 如果新增 governance pack，必须同时更新 `README.md`、`docs/start/README.md` 和对应测试。