@haaaiawd/loom 1.3.1 → 2.0.1

package/README.md

@@ -1,461 +1,214 @@
-# LOOM
+<p align="center"><strong>English</strong> · <a href="README.zh-CN.md">简体中文</a></p>
 
-> **Loop + Orchestration + Ontology + Mind**
->
-> 哲学是经线，意图是纬线，loop 的往复就是织机运作，织出软件。
+<p align="center">
+  <img src="docs/brand/loom-readme-header.svg" alt="LOOM — Keep the whole. Continue the work." width="100%">
+</p>
 
----
+<p align="center">
+  <a href="https://www.npmjs.com/package/@haaaiawd/loom"><img src="https://img.shields.io/npm/v/%40haaaiawd%2Floom?style=flat-square&amp;color=4169E1&amp;label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A518-17212B?style=flat-square" alt="Node.js 18 or newer">
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-9AD8C2?style=flat-square&amp;labelColor=17212B" alt="MIT license"></a>
+</p>
 
-## LOOM 是什么
+<p align="center"><strong>The human talks to the Agent. LOOM helps the Agent remember, understand, and continue.</strong></p>
 
-LOOM 是一个**哲学驱动的 Agent 质量框架**，核心理念：
+LOOM is invisible project-understanding and continuity infrastructure for AI Agents. It supports
+any work that can be materially advanced through code or command-line tools: software, operations,
+research workflows, office automation, data work, and highly personalized projects.
 
-**让 Agent 先拥有项目判断，再为当前任务编译专业能力；在可靠完成之上，通过比较与独立证据追求出众。**
-
-LOOM 的核心机制：
-1. **Project Doctrine** 从项目事实中形成长期判断，而不是套用规范模板
-2. **Intent + Contract** 同时定义可靠完成的底线与可选的质量上限
-3. **Expertise Compiler** 为当前任务临时组装领域、品味、作者、批评与验证能力
-4. **Quality Arena + Quality Proof** 用机制不同的候选和独立证据支撑质量提升
-5. **Authorship + Atelier** 在真正需要创作判断时形成作者命题、媒介原型与可审计选择
-
----
-
-## 核心概念
-
-| 概念 | 一句话解释 |
-|---|---|
-| **哲学** | 项目的价值观和工程原则——为什么存在、什么不做、冲突时谁优先。由 Weaver 从真实思想体系织造，不是模板填空 |
-| **Intent** | 一个意图单元——不是"做什么"（任务），是"为什么做"（意图）。每个 Intent 有验收契约，Keeper 据此判定实现是否忠实 |
-| **Intent Map** | 所有 Intent 的依赖图（JSON）。Architect 绘制，定义拓扑序和依赖关系 |
-| **Capability Graph** | 先用 Lens Contract 审视用户旅程、交互、视觉、内容、系统与风险，再用 Capability Domains 声明 UI/UX、3D 光影、安全、心理学等真正相关的专业来源；每个 capability 经 Architect 初判与独立子代理的 Impact Gate 审查，high 至少占 30%，不能靠降级影响等级跳过外部获取，最后才展开问题面、能力缺口、风险和证据并回链 Intent |
-| **Expertise Pack** | Forge 通过真实外部检索为当前 Intent 编译的来源化核心信息组；绑定 revision，不成为永久规则 |
-| **Authorial Stance** | 针对单个 Intent 编译的创作命题、选择、拒绝项、媒介语法和验证视角，不是 Persona 扮演 |
-| **Atelier Path** | 可选创作深路径：冻结基线、形成机制不同候选、比较或保留原版，并把证据写入唯一 Atelier Record |
-| **Quality Arena** | 以基线和机制不同候选进行探索、比较、实现与观察 |
-| **Quality Proof** | Keeper 独立验证完成与质量声明，证据不足时不允许宣称提升 |
-| **Intent Loop** | 选择 → 编译专业能力 → 实现/比较 → 独立证明 → 闭合或回流 |
-| **Keeper** | 独立验证角色——不继承 Forge 的解释，从磁盘重新加载意图和契约 |
-| **底线** | 不可妥协的约束（BASELINE.md 5 条 + 项目特定底线）。角色激活时强制加载，哲学不能覆盖 |
-
-### Intent Loop 怎么跑
+The human does not learn a framework or operate a CLI. They describe what they want, answer useful
+questions, disagree, delegate decisions, and watch the work become real. The Agent uses LOOM in the
+background to preserve the whole project across context compression, new sessions, and implementation.
 
-```
-Host/Orchestrator 选 Intent（拓扑序第一个 pending 且依赖都 completed 的）
-  ↓
-Host/Orchestrator 更新 status → in_progress
-  ↓
-Forge 编译 Expertise Pack，并在需要时运行 Quality Arena
-  ↓
-Keeper 验证（基础四维；有质量契约时增加 quality_achievement，相对提升时附 Quality Proof）
-  ↓
-判定结果：
-  passed        → status → completed，回到选 Intent
-  deviated      → 与 Forge 对话修正，重新实现重新验证（连续 3 轮升级 blocked）
-  blocked       → status → blocked，停下报告用户
-  pending_human → 等用户补充判定（L3 人类反馈，如游戏手感）
-```
-
-**Loop 终止**：所有 Intent 的 status 为 completed → 项目阶段完成。
-
-对会变更既有用户或系统状态的 Intent，Architect 设 `continuity_required: true`。它不创建第二份需求文档，而是要求同一份 acceptance 明确“哪些旧状态不得消失”与“旧状态 → 操作 → 新状态”的验证序列。此类 Intent 只有结果、守恒、可复现证据（以及按需的质量证明）同时通过，才允许闭合。
+<table>
+  <tr>
+    <td width="33%"><strong>Whole over fragments</strong><br>Keep the result, decisions, systems, and unknowns connected.</td>
+    <td width="33%"><strong>Expertise over costumes</strong><br>Compile project-specific professional judgment, not decorative expert personas.</td>
+    <td width="33%"><strong>Proof over ceremony</strong><br>Use independent handoff, exact done conditions, and disk evidence.</td>
+  </tr>
+</table>
 
----
+## The loop
 
-## 快速开始
-
-### 安装
-
-```bash
-npm install --global @haaaiawd/loom
-loom --version
-```
-
-也可以不做全局安装，直接运行：
-
-```bash
-npx @haaaiawd/loom --help
-```
-
-### 步骤 0：诊断当前阶段
+![The LOOM production loop](docs/loom-production-loop.svg)
 
-```bash
-loom guide
-loom guide --dry-run  # 只读诊断，不写 heartbeat
-```
-
-guide 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
-Agent 每完成一步都跑 guide 确认下一步。
-如果只是审计或探测，不希望产生任何状态写入，用 `loom guide --dry-run`。
-
-当 `guide` 的下一步是 `loom activate <role>` 时，先运行这条命令：它会把该阶段需要的
-规范与版本化输入编译为 Context Pack。`guide` 只负责导航，不输出待阅读文件清单。
+LOOM has three explicit feedback loops: understanding converges on the whole project; a fresh Keeper
+tests the frozen handoff and returns concrete gaps; restartable Tasks carry implementation and evidence
+across interruptions. A failed Keeper does not become a warning that everyone politely ignores—it sends
+the project back to the exact source that needs repair, then requires a changed digest and a new Keeper.
 
-### AUTO 模式
+The loop is adaptive. LOOM does not provide a universal questionnaire, fixed professional roles, or
+a mandatory phase ritual. The Agent keeps clarifying while unknowns could materially change the whole.
+It proceeds when the remaining uncertainty is reversible and local, or when the human explicitly asks
+to skip after hearing the concrete cost.
 
-```bash
-loom auto on      # Agent 在允许阶段连续推进；不会跳过契约、证据或 Keeper 门禁
-loom auto off     # 每步需要用户确认
-```
+## Project truth on disk
 
-### 步骤 1：初始化项目
+An initialized project contains one small semantic backbone:
 
-```bash
-loom init
+```text
+.loom/
+├── PROJECT.md          concise entry point and map of the current whole
+├── DECISIONS.md        concise history when important decisions supersede earlier ones
+├── design/             product, experience, system, contract, verification, operations, or research docs
+├── capabilities/       one project-specific dossier per recognizable professional field
+├── state.json          confirmed facts, assumptions, unresolved questions, Keeper status
+├── tasks.json          broad Work Map plus the detailed active horizon
+└── eval/               optional Evil Eval scenarios for testing LOOM itself
 ```
 
-**输入**：无（在项目根目录执行）
-**产出**：`.loom/v1/` 目录结构 + 模板文件 + AGENTS.md 锚点
-**下一步**：`loom guide` → 激活 Weaver 织造哲学
+Small projects may need few design documents; large projects may need many. A consequential subsystem,
+experience, interface, contract, or operational concern gets its own document when a fresh Agent must
+understand or verify it independently. `PROJECT.md` maps the whole instead of becoming a thousand-line attic.
 
-### 步骤 2：织造哲学
+### Capability dossiers
 
-```bash
-loom activate weaver
-```
+A dossier exists only when specialist knowledge would change a question, design choice,
+implementation, risk, or verification method. Each dossier represents one recognizable professional
+field—such as UI/UX design, visual art direction, game design, psychology, security, or distributed
+systems. Different fields remain separate even when tightly coupled; their synthesis belongs in the
+design document whose decision they jointly shape. A task technique such as triage, ranking, parsing,
+or caching is not allowed to masquerade as the project's entire capability surface.
 
-**输入**：项目特征（什么类型的项目、目标用户、技术栈、约束）
-**Weaver 会做什么**：扫描 `dimensions/` 判断激活哪些维度 → 搜索高质量参考 → 萃取原则 → 产出哲学文档
-**产出**：`.loom/v1/00_PHILOSOPHY/` 下的哲学文档（PRODUCT_PHILOSOPHY、ENGINEERING_CREED、DECISION_RUBRIC，按需领域哲学，按需 PROJECT_BASELINE）
-**怎么判断合格**：哲学文档有北极星、有反模式清单、有决策取舍规则。如果全是空话，让它重做
-**下一步**：激活 Visionary 定义愿景
+### Work Map and Task
 
-### 步骤 3：定义愿景
+The Work Map may be hundreds or thousands of lines. It is stored, searched, and revised on disk; it
+is not injected into every model context. Planning begins broadly, while detailed steps are compiled
+only for the active horizon.
 
-```bash
-loom activate visionary
-```
+A Task is not a miniature bureaucracy. It is the smallest restartable checkpoint that tells a fresh
+Agent:
 
-**输入**：用户需求（产品要解决什么问题、目标用户是谁）
-**Visionary 会做什么**：基于哲学定义产品愿景 → 为每个 Intent 写意图叙事（"为什么存在"）
-**产出**：`.loom/v1/01_VISION.md`（含北极星 + 意图叙事列表）
-**怎么判断合格**：意图叙事是"为什么"不是"做什么"。如果写成了功能列表，让它重做
-**下一步**：激活 Architect 设计系统
+- what observable result to create;
+- what proves completion;
+- what must not be damaged;
+- which project and capability documents matter;
+- what has happened, what is happening, and what comes next;
+- which evidence already exists and which exact done condition it proves.
 
-### 步骤 4：设计系统
+## Agent quick start
+
+Install the CLI:
 
 ```bash
-loom activate architect
+npm install --global @haaaiawd/loom
+loom --version
 ```
 
-**输入**：愿景文档 + 哲学文档
-**Architect 会做什么**：先展开 Capability Graph → 设计系统边界 → 绘制 Intent Map → 定义完成契约、按需的质量契约与专业能力需求
-**产出**：`.loom/v1/07_CAPABILITY_GRAPH.json` + `07_CAPABILITY_BRIEFS/` + `.loom/v1/02_ARCHITECTURE.md` + `.loom/v1/04_INTENT_MAP.json`
-**怎么判断合格**：高影响图谱节点都有路由、Intent 都可回链到图谱，完成契约可观察，质量契约可比较，依赖无环
-**下一步**：进入 Intent Loop
-
-### 步骤 5：进入 Intent Loop
+Or install from the repository during development:
 
 ```bash
-# Keeper 选 Intent 并更新状态
-loom intent next              # 查看下一个可执行 Intent
-loom intent update INT-001 --status in_progress
-
-# Forge 编译专业能力并实现
-loom activate forge --intent INT-001
-
-# 仅当 Architect 为该 Intent 声明 quality_strategy=atelier
-loom atelier init INT-001
-loom atelier validate INT-001
-
-# Keeper 独立形成 Quality Proof
-loom activate keeper --intent INT-001
-loom verify contract INT-001  # 查看验收契约
-loom verify write --json-file verification.json  # 写入验证记录
-
-# 根据判定结果
-loom intent update INT-001 --status completed    # passed
-loom intent update INT-001 --status blocked      # blocked
-
-# 查看进度
-loom intent status
+npm install --global .
+loom --version
 ```
 
-**Loop 结束**：所有 Intent 为 completed，且 `loom atlas validate` 通过当前版本的决策图谱交付门。
+Inside a project, the Agent runs:
 
-### 步骤 6：决策图谱交付
-
-```bash
-loom atlas build      # 编译当前版本的架构与决策资料模型
-loom atlas --regen    # 输出已装配资料的 Composer Pack，生成 loom-atlas.html
-loom atlas validate   # 校验 Atlas 是否是当前版本合格交付物
-loom atlas            # 打开合格的决策图谱
+```bash
+loom init
+loom context
 ```
 
-Atlas 是当前版本的必交付 H5：它解释哲学、愿景、架构、Capability Graph、专业领域、Intent 契约、验证设计与关键决策，不承载项目进度或验证历史。CLI 为资料建立内容 digest；`loom-atlas.html` 必须绑定该 digest 和五个固定审查章节，才能被打开或视为收尾完成。
-
-视觉 Agent 可以自由选择风格和叙事节奏，但内容结构与来源回链固定。所有 Intent 完成后，`loom guide` 会先要求 Atlas，不能跳过。
-
-**版本演进三档**：
-
-| 档位 | 什么时候用 | LOOM 流程 |
-|---|---|---|
-| Patch | 不触及 Intent，只修 bug / 样式 / 实现细节 | 不走 Intent Loop；跑验证并用 `loom patch record` 记录 |
-| Minor | 新增或修改 Intent，但不改变哲学前提、愿景北极星、架构边界 | 当前版本内变更；相关 Intent 进入 `pending` / `needs_review` |
-| Major | 哲学前提、愿景北极星或架构边界变化 | `loom version new` 创建新版本，全套重跑 |
-
-当前版本全部完成后，运行 `loom guide` 会提示按三档判断，而不是默认开新版本。
+When a Task is active, `loom context` also restores a compact execution protocol: reconcile the Task with
+the current workspace and version-control state, inspect relevant tests before editing, choose proof by risk
+and exact `done_when` claims, persist `completed/current/next` at meaningful handoffs, and close only with
+reproducible evidence. It does not impose a ceremonial test or pull request on work that does not need one.
 
-**CLI 命令一览**：
-
-| 命令 | 用途 |
-|---|---|
-| `loom init` | 初始化项目 |
-| `loom guide` | 诊断当前阶段，输出下一步引导 |
-| `loom guide --dry-run` | 只读诊断当前阶段，不写 heartbeat |
-| `loom auto on\|off\|status` | AUTO 模式开关 |
-| `loom activate <role>` | 输出角色激活提示词 |
-| `loom activate <role> --intent <id>` | 输出仅含指定 draft/官方 Intent 的角色上下文 |
-| `loom atlas build` | 编译当前版本的 Atlas Model |
-| `loom atlas --regen` | 输出 command-assembled Composer Pack，生成 `loom-atlas.html` |
-| `loom atlas status\|validate` | 检查资料与 HTML 是否新鲜、完整且可交付 |
-| `loom atlas` | 打开通过校验的决策图谱 |
-| `loom help <topic>` | 分层指南（含 workflow、concepts、loop、capability、atelier、version、patch、doctor、atlas） |
-| `loom version list` | 列出所有版本（* 标记当前） |
-| `loom version new` | 创建新版本 + 自动切换（Major 升级） |
-| `loom version use <v>` | 切换当前版本 |
-| `loom version diff <v1> <v2>` | 对比两个版本的文件差异 |
-| `loom patch record --json-file <path>` | 写入权威 Patch JSON 并生成 Markdown 投影 |
-| `loom patch list` | 列出当前版本 Patch |
-| `loom patch get <id>` | 查看单条 Patch |
-| `loom patch validate` | 校验 Patch ledger 和生成投影 |
-| `loom intent next` | 下一个可执行 Intent |
-| `loom intent status` | 进度概览 |
-| `loom intent get <id>` | Intent 详情 |
-| `loom intent add --title <text> [--depends-on <ids>]` | 创建当前版本新增 Intent draft |
-| `loom intent revise <id> --reason <text>` | 创建修订 draft 并报告反向依赖 |
-| `loom intent draft <id>` | 查看 draft |
-| `loom intent finalize <id> [--review <ids> --unaffected <ids>]` | 校验 draft 并原子更新官方 Map/topo_order；修订时必须分类全部下游影响 |
-| `loom capability graph\|frontier\|get\|coverage\|compile` | 查看能力图谱、未路由前沿、覆盖缺口和当前 Intent 的能力编译输入 |
-| `loom capability proposal list\|get\|submit\|decide\|close` | 以 provenance 提交新发现，并由 Architect 裁决和闭合 |
-| `loom asset import\|list\|search\|get\|validate` | 管理带来源、许可、哈希、批准状态与 evidence 回链的本地素材 |
-| `loom expertise init\|get\|validate <id>` | 创建和校验 revision-scoped Search Plan、外部来源与 Capability Capsules |
-| `loom atelier init\|get\|validate <id>` | 为显式 Atelier Intent 创建、读取和校验创作记录 |
-| `loom intent deprecate <id> --reason <text>` | 只读评估当前版本弃用影响；加 `--confirm` 并完整分类依赖方后原子写入 |
-| `loom intent narrative <id>` | Intent 意图叙事 |
-| `loom intent trace <id>` | Intent 完整追溯链（依赖+验证+哲学+叙事） |
-| `loom intent diff <v1> <v2>` | 按显式 lineage 比较新建、修订、拆分、合并和未映射 Intent |
-| `loom intent reverse-dep <id>` | 反向依赖（谁依赖这个 Intent） |
-| `loom intent reverse-ref <anchor>` | 反向哲学引用（哪些 Intent 引用这个锚点） |
-| `loom intent update <id> --status <s>` | 更新状态（Keeper 用） |
-| `loom philosophy get <anchor>` | 加载哲学章节 |
-| `loom philosophy impact <anchor>` | 只读返回直接引用该锚点的 Intent 及传递依赖影响 |
-| `loom philosophy revise <anchor> --classification <clarification\|minor\|major> --reason <text>` | 只读评估哲学修订；clarification/minor 加 `--confirm` 和完整分区后写审计 ADR |
-| `loom verify contract <id>` | 获取验收契约 |
-| `loom verify write --json-file <path>` | 写入验证记录 |
-| `loom verify history <ref> --across-versions` | 沿 predecessors 读取各 owning version 的本地验证历史 |
-| `loom doctor` | 项目健康检查 |
-| `loom context` | 上下文摘要（Agent 重启后一条命令获取状态） |
-
-读命令 `intent get`、`intent narrative`、`intent trace` 和 `verify history` 支持 `v1:INT-003` 形式的跨版本引用；裸 ID 仍指当前版本。历史引用只读。跨版本沿革必须显式写在可选 `lineage.predecessors` 中，同 ID 或同标题不会建立映射，且 lineage 不属于 `depends_on`。
-
-弃用只适用于当前版本中已 `completed` 的 Intent。首次运行 `loom intent deprecate <id> --reason "<why>"` 只返回目标、直接/传递依赖方、各自状态和确认命令，不写文件。确认时用 `--review` 与 `--unaffected` 将所有依赖方恰好分类一次；叶子 Intent 不需要分类参数。弃用记录写入 `lifecycle.deprecation`，目标仍为 `completed`，依赖和契约不被修改。重复确认会明确失败。
-
-哲学修订由 CLI 分析后果和记录审计，不由 CLI 自动改写哲学文本。`philosophy impact` 与未确认的 `philosophy revise` 严格只读。确认 clarification 时全部受影响 Intent 必须归入 `--unaffected`；确认 minor 时可将确需重验的 Intent 归入 `--review`，其中 `completed` 才转为 `needs_review`。两者都不改 acceptance，并在 `03_DECISIONS/PHIL-REV-NNN.md` 记录审计。Major 永不修改当前版本，只返回 `loom version new`。
-
----
-
-## 系统结构
+The Agent edits `.loom/PROJECT.md`, design documents, and capability dossiers as human-readable project truth. Structured
+writes use JSON files so long content remains auditable and shell quoting does not corrupt it:
 
+```bash
+loom record --json-file understanding-update.json
+loom design add product --title "Product definition" --kind product
+loom design add local-analysis --title "Local analysis system" --kind system
+loom design add acceptance --title "Vertical-slice verification" --kind verification
+loom capability add ui-ux-design --title "UI/UX design"
+loom capability add behavioral-psychology --title "Behavioral psychology"
+loom task plan --json-file initial-work-map.json
+loom project ready
 ```
-LOOM/
-├── README.md                    你在这里。系统总览
-│
-├── meta/                        元规范（薄而硬——我们写的核心）
-│   ├── BASELINE.md              不可妥协的底线（5 条）
-│   ├── ROLE_ACTIVATION.md       角色怎么激活、哲学怎么加载
-│   ├── INTENT_LOOP.md           Loop 控制流 + Intent Map + Verification 底线
-│   └── PHILOSOPHY_WEAVER.md     哲学织造器规范
-│
-├── dimensions/                  哲学维度库（Weaver 的弹药库）
-│   ├── SEARCH_METHODOLOGY.md    检索方法论（怎么找到优质思想）
-│   ├── AUTHORSHIP.md             Atelier 启用时加载的作者性方法
-│   ├── universal/               通用层：产品/工程/协作（按需填充）
-│   ├── domain/                  领域层：UX/游戏/后端/AI（按需填充）
-│   └── crosscutting/            交叉层：性能/安全/心理学/增长（按需填充）
-│
-├── roles/                       角色原型定义
-│   ├── visionary.md             远见者——定义愿景，织造意图叙事
-│   ├── architect.md             建筑师——展开图谱，设计系统，绘制 Intent Map
-│   ├── forge.md                 锻造师——在哲学约束下自主实现
-│   └── keeper.md                守护者——验证意图忠实度
-│
-├── cli/                         CLI 传感器层（Agent 通过 CLI 访问磁盘数据）
-│   ├── bin/loom.js              命令入口
-│   ├── src/                     核心库（intent-map / capability / atelier / verify）
-│   ├── help/                    Agent 可直接读取的工作流指南
-│   └── test/                    端到端测试
-│
-└── templates/                   项目级起点骨架
-    ├── PHILOSOPHY_TEMPLATE.md   哲学文档起点
-    ├── VISION_TEMPLATE.md       愿景文档起点
-    ├── INTENT_MAP_TEMPLATE.json Intent Map 起点
-    ├── CAPABILITY_GRAPH_TEMPLATE.json Capability Graph 起点
-    ├── CAPABILITY_BRIEF_TEMPLATE.md   Capability Brief 起点
-    ├── ASSET_LIBRARY_MANIFEST_TEMPLATE.json Asset Library 起点
-    ├── EXPERTISE_PACK_TEMPLATE.json   外部能力获取记录起点
-    ├── ATELIER_RECORD_TEMPLATE.json   Atelier Record 起点
-    └── ATLAS_TEMPLATE.html             决策图谱 H5 起点
-```
-
-### 文档导航
-
-**想了解什么 → 读哪个文件**：
-
-| 想了解 | 读这个 |
-|---|---|
-| 底线是什么、什么不能做 | `meta/BASELINE.md` |
-| Loop 怎么跑、验证怎么判定 | `meta/INTENT_LOOP.md` |
-| 角色怎么激活 | `meta/ROLE_ACTIVATION.md` |
-| 哲学怎么织造 | `meta/PHILOSOPHY_WEAVER.md` |
-| Visionary 做什么 | `roles/visionary.md` |
-| Architect 做什么 | `roles/architect.md` |
-| Forge 做什么 | `roles/forge.md` |
-| Keeper 做什么 | `roles/keeper.md` |
-| 哲学文档长什么样 | `templates/PHILOSOPHY_TEMPLATE.md` |
-| 愿景文档长什么样 | `templates/VISION_TEMPLATE.md` |
-| Capability Graph、Lens Contract 与 Brief 长什么样 | `cli/help/capability.md`、`templates/CAPABILITY_GRAPH_TEMPLATE.json`、`templates/CAPABILITY_GRAPH_EXAMPLE.json` |
-| 为什么必须外部检索、Expertise Pack 怎么闭合 | `cli/help/expertise.md`、`EXTERNAL_ACQUISITION_DESIGN.md` |
-| Author 与 Atelier 怎么工作 | `cli/help/atelier.md`、`dimensions/AUTHORSHIP.md` |
-| 决策图谱如何生成、怎样验收 | `cli/help/atlas.md`、`templates/ATLAS_TEMPLATE.html` |
-| Intent Map 长什么样 | `templates/INTENT_MAP_TEMPLATE.json` |
-| 怎么搜索高质量参考 | `dimensions/SEARCH_METHODOLOGY.md` |
-
----
-
-## 我们写的 vs Agent 生成的
-
-**我们写的**（LOOM 的内核，薄而硬）：
-- `meta/` — 元规范：怎么织造哲学、loop 怎么跑、角色怎么激活、底线是什么
-- `roles/` — 角色原型：每个角色的身份、自主空间、职责
-- `templates/` — 起点骨架：Agent 生成的起点，不是填空模板
-
-**Agent 生成的**（每个项目跑出来的，厚而灵活）：
-- 哲学文档体系（Weaver 决定要几个、多详细）
-- 愿景文档（带意图叙事）
-- 架构文档（根据哲学决定结构）
-- Capability Graph 与按需生成的 Capability Brief
-- Intent Map（意图依赖图，JSON）
-- 验证契约和验证记录
-
-**我们的规范是元规范**——规范"怎么生成规范"，不直接规范"规范长什么样"。
-
----
-
-## 四个角色
-
-| 角色 | 原型 | 职责 | 激活时机 |
-|---|---|---|---|
-| **Visionary** 远见者 | 产品联合创始人 | 定义愿景，织造意图叙事 | 项目启动 |
-| **Architect** 建筑师 | 系统建筑师 | 展开 Capability Graph，设计系统，绘制 Intent Map | Visionary 完成后 |
-| **Forge** 锻造师 | 高级工程师 | 在哲学约束下自主实现 | Intent Loop 实现阶段 |
-| **Keeper** 守护者 | 独立验证者（独立激活） | 从磁盘事实验证意图与质量主张 | Intent Loop 验证阶段 |
 
-Visionary 和 Keeper **同源但独立**——同一个产品哲学，但 Keeper 是"回溯验证者"，作为子代理运行，不继承 Forge 的实现上下文。
+At the transition to material execution, open a fresh Agent thread and give it one short instruction:
 
----
-
-## Intent-Driven Loop
-
-```
-Host/Orchestrator 选 Intent → Forge 加载意图链并自主实现 → Keeper 子代理独立验证 → 判定
-     ↑                                                                    │
-     │                                                                    │
-     └────────────── passed: 闭合，下一个 Intent ──────────────────────────┘
-                      deviated: Keeper 与 Forge 对话修正 → 重新实现 → 重新验证
-                      blocked: 停下，报告用户
+```text
+Run loom keeper prompt in this project and follow it. Decide whether you can responsibly start.
 ```
 
-Loop 的单元是意图，验证的核心问题是"实现是否忠实于原始意图"。
-
----
-
-## 五条底线
-
-所有角色、所有哲学、所有项目都必须遵守：
-
-1. **B1：必须有结构设计** — 编码前必须有明确的结构设计
-2. **B2：禁止硬编码** — 密钥、配置、环境值不进代码
-3. **B3：接口契约必须显式** — 对外可观察的接口必须有显式定义
-4. **B4：决策必须可追溯** — 影响架构/接口/技术栈的决策必须记录
-5. **B5：意图必须可回溯** — 任何实现都必须能回溯到原始意图
-
-底线不可被哲学覆盖。哲学内化底线，不是绕过底线。
-
----
+If Keeper returns `needs_revision` or `blocked`, those exact gaps reappear in `loom context`. The Agent
+repairs the relevant project, design, capability, or Task source, prepares a changed digest, and opens a
+different fresh Keeper. If the host cannot create a subagent, the human can open a new window and use the
+same sentence. After the one-time handoff passes, the execution Agent starts and maintains Tasks normally:
 
-## 项目级文档结构
+```bash
+loom task next
+loom task start TASK-001
+loom context
+loom task update TASK-001 --json-file progress.json
+loom task block TASK-001 --json-file block.json
+loom task reopen TASK-001
+loom task reopen TASK-001 --reason "Prior completion evidence was disproven"
+loom task done TASK-001 --json-file evidence.json
+```
 
-Agent 在项目中生成的文档结构：
+Completion is deliberately explicit:
 
-```
-.loom/
-└── v{N}/                         版本目录（跟随项目演进）
-    ├── 00_PHILOSOPHY/             Weaver 产出
-    │   ├── PRODUCT_PHILOSOPHY.md
-    │   ├── ENGINEERING_CREED.md
-    │   ├── DECISION_RUBRIC.md
-    │   └── ...（按需，Weaver 决定）
-    ├── 01_VISION.md               Visionary 产出（带意图叙事）
-    ├── 02_ARCHITECTURE.md         Architect 产出
-    ├── 03_DECISIONS/              架构决策记录
-    ├── 04_INTENT_MAP.json         意图依赖图（DAG）
-    ├── 05_VERIFICATION.md         每个 Intent 的验证契约
-    ├── 06_CHANGELOG.json          Patch 变更记录（唯一权威来源）
-    ├── 06_CHANGELOG.md            确定性生成的只读投影
-    ├── 07_CAPABILITY_GRAPH.json   问题面、能力缺口、风险、证据与 Intent 回链
-    ├── 07_CAPABILITY_BRIEFS/      按需生成的项目化能力 Brief
-    └── verifications/             Keeper 的验证记录
-        ├── INT-001.json
-        ├── INT-001.md
-        └── ...
+```json
+{
+  "evidence": ["npm test: 21 passed, 0 failed"],
+  "checks": [
+    {
+      "criterion": "The exact done_when sentence from the Task.",
+      "evidence": ["The command, artifact, or observation that proves this criterion."]
+    }
+  ]
+}
 ```
 
----
+Run `loom --help` for the complete command surface. Run `loom check` for structural health. Run
+`loom prompts` to print every cognitive message LOOM can inject: the stable collaboration core,
+runtime protocol, dynamic state layer, all document templates, Keeper prompt, eval conditions, judge
+prompt, and their composition order. See the [prompt and message catalog](docs/PROMPT_CATALOG.md).
 
-## 格式原则
+## What LOOM deliberately removed
 
-| 内容 | 格式 | 理由 |
-|---|---|---|
-| 哲学、愿景、架构、决策 | **MD** | 叙事性，人类可读，Git diff 友好 |
-| Intent Map、验证判定 | **JSON** | 结构化，机器可读，CLI 可查询 |
-| 混合内容 | **JSON + MD + ref 互引** | JSON 存结构，MD 存叙事 |
+LOOM 2 replaces the v1 chain of Doctrine, Vision, Capability Graph, Impact Gate, Intent Map, Expertise
+Pack, Atelier, Quality Arena, per-Intent Keeper, and Atlas with one adaptive understanding loop, a
+scalable graph of design documents, separate professional-field dossiers, one Work Map, and one
+restartable Task contract.
 
-Agent 通过 **CLI 访问** JSON，不直接读文件——省 token、更高效、还能做校验。
+The valuable ideas remain: project judgment, external professional capability, authored choices,
+observable completion, context isolation, and evidence. They no longer require separate roles and gates.
 
----
+## Proving that LOOM helps
 
-## 运行流程
+`loom eval scaffold --json-file scenario.json` creates an Evil Eval scenario with equal model, tools,
+workspace, user facts, and budget across two conditions. The only intended difference is the availability
+of LOOM. Runs are repeated, context is forcibly reset, outputs are blinded and order-swapped, and ceremony,
+user burden, time, and token cost are penalized alongside quality. See [EVIL_EVAL.md](EVIL_EVAL.md).
 
-```
-1. Weaver 织造 Project Doctrine
-   → 读取项目事实 → 提炼长期判断 → 按决策未知搜索 → 转译为原则、边界与 Evidence Map
-
-2. Visionary 定义愿景
-   → 基于哲学写愿景 → 每个意图带意图叙事 → 识别需要的哲学维度
+![The LOOM Evil Eval](docs/loom-eval-loop.svg)
 
-3. Architect 先展开 Capability Graph，再设计系统
-   → 基于愿景检查问题面、能力缺口、风险与证据 → Impact Gate 经独立子代理复审 → 路由高影响节点并外部获取 → 绘制 Intent Map → 定义验证契约
+## Development
 
-4. LOOM Quality Engine
-   → Forge 编译 Expertise Pack → 按需编译 Authorial Stance / 进入 Atelier
-   → Quality Arena 实现/比较 → Keeper 形成 Quality Proof
-   → 循环直到所有 Intent 闭合
+```bash
+npm test
 ```
 
----
-
-## 当前状态
+The v2 test suite exercises the complete loop, including a 250-Task Work Map, context selection,
+superseding decisions, scalable design documents, professional-field separation, capability compilation,
+multi-attempt Keeper revision, stale digest and duplicate-run
+rejection, exact-file Task start, block/reopen including disproven completion, per-done-condition evidence,
+and Evil Eval controls. See the
+[complete UX and loop specification](docs/UX_FLOW.md).
 
-- [x] `meta/` 元规范（4 个文件）
-- [x] `roles/` 角色契约（6 个角色，含独立 Impact Reviewer）
-- [x] `templates/` 起点骨架
-- [x] `README.md` 系统总览
-- [x] `dimensions/SEARCH_METHODOLOGY.md` 检索方法论
-- [x] `cli/` CLI 访问层（Capability Graph / Proposal / Asset Library / Atelier / Quality Proof）
-- [x] `dimensions/AUTHORSHIP.md` 按需创作方法
-- [ ] 继续通过真实项目校准专业维度与 Atelier 的质量增益
+## Documentation
 
----
+| Read this | When you need |
+| --- | --- |
+| [System design](design.md) | The architecture, storage model, invariants, and command contracts |
+| [UX and loop specification](docs/UX_FLOW.md) | Every human, Agent, LOOM, Keeper, and Task transition |
+| [Prompt and message catalog](docs/PROMPT_CATALOG.md) | Every message LOOM injects and how the layers compose |
+| [Evil Eval protocol](EVIL_EVAL.md) | A controlled framework-vs-no-framework comparison |
+| [Changelog](CHANGELOG.md) | What changed in LOOM 2 |
 
-> **LOOM 的信条**：编排而非控制。给 Agent 价值观和边界，让它在边界内自主发挥。底线守住不会崩，哲学填充边界内的内容，loop 确保实现忠实于意图。
+Editable Draw.io sources live beside both flow diagrams in [`docs/`](docs/).