@haaaiawd/loom 0.10.0 → 1.1.0

package/cli/help/asset.md

@@ -0,0 +1,36 @@
+# Asset Library Protocol
+
+Asset Library is the versioned, local-first source of truth for project materials. It stores asset bytes under `.loom/vN/08_ASSET_LIBRARY/files/` and metadata in `manifest.json`. A remote URL, successful download, or HTTP 200 is never proof that an asset is renderable in the target host.
+
+## Import
+
+```bash
+loom asset import ./approved-image.png \
+  --kind image \
+  --tags "庆祝,表情,项目名" \
+  --source "用户自有素材包" \
+  --author "作者或权利人" \
+  --license "授权说明或许可证" \
+  --approval approved
+```
+
+Import copies an explicitly named ordinary local file, computes SHA-256, derives a stable `ASSET-...` ID, and rejects symbolic links, destination/path escape, duplicate bytes, missing provenance, and unapproved assets. It does not fetch remote material.
+
+## Recoverable import transaction
+
+An evidence-linked import changes three files: the copied bytes, `manifest.json`, and `07_CAPABILITY_GRAPH.json`. Filesystems do not provide one atomic operation across those files, so Loom does not claim that they do. It first prevalidates the complete candidate, then writes same-directory temporary files and a recovery journal (flushed where the filesystem supports it). If an import errors, Loom rolls back to the recorded pre-import state; if the process is interrupted, the next `loom asset validate`, import, or library read recovers the journal before using the library. `loom asset validate` reports a recovered transaction in its JSON output.
+
+## Discover and verify
+
+```bash
+loom asset list
+loom asset search 表情
+loom asset get ASSET-<hash-prefix>
+loom asset validate
+```
+
+Tags are Unicode strings, so Chinese search works without a separate tokenizer for the small local library. Search returns only active `approval: approved` assets; `asset list` remains the audit view. Only approved assets may be used by Forge.
+
+## Evidence links
+
+When importing with `--evidence`, Loom validates the complete prospective manifest and Graph first, then writes both the asset's `evidence_refs` and the evidence node's `asset_refs` as one recoverable transaction. `loom asset validate` checks this reciprocal link plus hashes and provenance. This records bytes and traceability; Keeper must still check the real target host renders the result.

package/cli/help/atelier.md

@@ -0,0 +1,37 @@
+# Atelier
+
+Atelier 是 `quality_strategy=atelier` 的创作深路径。它让 Authorial Stance、基线、候选、
+修正和选择证据成为单个版本化记录，不替代 Intent 状态或 Keeper。
+
+## 何时启用
+
+由 Architect 在 Intent 同时声明：
+
+```json
+{
+  "quality_contract": "相对基线可观察的质量主张与证据方式",
+  "quality_strategy": "atelier",
+  "creative_scope": "允许改变什么；必须保护什么。"
+}
+```
+
+普通任务省略该字段或使用 `adaptive`，不会创建 Atelier Record。
+
+## 工作流
+
+```bash
+loom activate forge --intent INT-001
+loom atelier init INT-001
+loom atelier validate INT-001
+loom atelier get INT-001
+```
+
+记录位于 `.loom/vN/09_ATELIER/INT-001.json`，证据位于
+`.loom/vN/09_ATELIER/files/INT-001/`。
+
+每个候选必须绑定 `stance_revision`。Stance 改变后，旧候选要设置 `archived: true`，
+或在重新检查后写 `requalified_for_stance_revision`。局部创作修正写入 `corrections[]`；
+结构性新发现提交 Capability Graph proposal，由 Architect 裁决。
+
+`loom atelier validate` 只证明记录结构、新鲜度和引用合法，不证明作品优秀。最终质量仍由
+新的 Keeper task 依据 Quality Proof 独立判定。

package/cli/help/capability.md

@@ -0,0 +1,68 @@
+## Capability Graph 指南
+
+Capability Graph 位于 Vision 与 Intent Map 之间：它把项目初衷展开为需要被理解、设计、实现或证明的
+问题面、能力缺口、风险与证据。它不是待办列表，也不替代 Intent Map。
+
+```bash
+loom capability graph
+loom capability frontier
+loom capability get <node-id>
+loom capability coverage
+loom capability compile <intent-id>
+```
+
+## 工作方式
+
+Visionary 给出 outcome、角色、非目标与项目事实。Architect 用项目类型相符的透镜检查用户旅程、
+体验、系统、资产、横切质量和未知；每个透镜必须被展开、覆盖或明确排除。
+
+高影响节点不能停在 `open`。它必须继续展开、生成 Capability Brief、编译为 Intent，或带理由地
+延后/排除。`loom capability frontier` 显示尚未路由的高影响节点；`loom capability coverage` 检查
+图谱与 Intent 的双向追溯。
+
+高影响 `outcome` 还必须有一条真实的观察链：以 `validated_by` 指向 `evidence` 节点。该 evidence 的
+`verification` 对象必须包含 `method`、`target`、`procedure`、`pass_criteria` 和 `artifact`，并以
+`intent_refs` 回链负责产出该证据的 Intent。`target` 写结果真正要被看见、接收或使用的位置，例如目标
+宿主的渲染面、用户拿到的导出文件、外部系统的接收端或人工验收现场。不要把“HTTP 200”“URL 可访问”或
+“本地生成了文件”当作用户已得到结果。
+
+不新增媒体、平台或版权专用节点类型：目标宿主与交付链路用 `concern` / `capability` 表达，许可、来源、
+隐私或平台限制用 `risk` 和 `constrains` 关系表达；只有需要项目化判断时才为相关节点创建 Brief，并在其
+“项目约束”和“产出与验证入口”中写清授权边界与实际交付验证。
+
+```json
+{
+  "id": "EVIDENCE-DELIVERY-RENDER",
+  "kind": "evidence",
+  "title": "在目标宿主中实际呈现交付物",
+  "status": "covered",
+  "impact": "high",
+  "route": "intent",
+  "intent_refs": ["INT-004"],
+  "verification": {
+    "method": "manual_visual",
+    "target": "目标桌面客户端的消息渲染面",
+    "procedure": "在干净会话中发送产物并观察实际渲染",
+    "pass_criteria": "用户无需打开外链即可看见完整内容",
+    "artifact": "verifications/INT-004-host-render.png"
+  },
+  "relationships": []
+}
+```
+
+## Capability Brief
+
+只有高影响、需要调研、需要专业方法或将进入当前 Intent 的能力节点才需要 Brief。Brief 位于：
+
+```text
+.loom/vN/07_CAPABILITY_BRIEFS/<node-id>.md
+```
+
+它写当前项目问题、成功判断、约束、能力获取计划、产出/验证入口与非目标。不要复制通用教程，
+也不要用“你是某领域专家”代替项目化能力说明。
+
+## 编译与回流
+
+`loom capability compile <intent-id>` 只读显示会进入当前 Intent 的图谱节点与 Brief。Forge 激活
+Intent 时会获得同一份输入；发现新依赖、风险或能力缺口时必须回流 Architect 更新 Graph，不能静默
+扩展实现。Keeper 以图谱回链检查高影响问题是否真的被兑现。

package/cli/help/concepts.md

@@ -1,72 +1,100 @@
-## LOOM 核心概念
-
-## 哲学
-
-项目的价值观和工程原则——为什么存在、什么不做、冲突时谁优先。
-由 Philosophy Weaver 从真实思想体系织造，不是模板填空。
-所有角色激活时强制加载哲学作为共同锚点。
-
-相关命令：
-- \`loom philosophy get <anchor>\` — 加载哲学章节
-- \`loom philosophy list\` — 列出哲学文档
-- \`loom intent reverse-ref <anchor>\` — 哪些 Intent 引用了这个哲学锚点
-
-## Intent
-
-一个意图单元——不是"做什么"（任务），是"为什么做"（意图）。
-每个 Intent 携带：
-- narrative_ref — 意图叙事引用（为什么存在）
-- depends_on — 依赖的 Intent（拓扑序）
-- acceptance — 验收契约（Keeper 据此判定）
-- philosophy_anchors — 哲学锚点（引用哪些哲学原则）
-- status — 状态（pending|in_progress|completed|blocked|needs_review）
-- verification_method — 验证方式（L1 静态|L2 运行时|L3 人类反馈，可选）
-
-相关命令：
-- \`loom intent next\` — 下一个可执行 Intent
-- \`loom intent get <id>\` — Intent 详情
-- \`loom intent narrative <id>\` — 意图叙事
-- \`loom intent trace <id>\` — 完整追溯链
-- \`loom intent reverse-dep <id>\` — 谁依赖这个 Intent
-
-## Intent Map
-
-所有 Intent 的依赖图（JSON）。Architect 绘制，定义拓扑序和依赖关系。
-必须是 DAG（有向无环图），不能有循环依赖。
-
-相关命令：
-- \`loom intent validate\` — 校验结构 + 依赖一致性
-- \`loom intent graph\` — Mermaid 依赖图
-- \`loom intent status\` — 进度概览
-
-## Intent Loop
-
-核心循环：Keeper 选 Intent → Forge 实现 → Keeper 验证 → 闭合或修正。
-每个 Intent 独立走一圈。详细流程见 \`loom help loop\`。
-
-## Keeper
-
-独立验证子代理——不继承 Forge 的实现上下文，从磁盘重新加载意图和契约。
-判定四维度：意图忠实度 / 哲学一致性 / 底线合规 / 验收达成。
-判定结果：passed / deviated / blocked / pending_human。
-
-## 底线
-
-不可妥协的约束（BASELINE.md 5 条 + 项目特定底线）。
-角色激活时强制加载，哲学不能覆盖。违反底线必须立即停止。
-
-## 验证记录
-
-Keeper 每次验证写入一条记录（追加模式），包含：
-- verdict（passed/deviated/blocked/pending_human）
-- 四维度判定
-- 证据
-- 偏离说明（如果 deviated）
-
-deviated 连续 3 轮升级 blocked。pending_human 默认 7 天超时升级 blocked。
-
-相关命令：
-- \`loom verify contract <id>\` — 获取验收契约
-- \`loom verify write --json-file <path>\` — 写入验证记录
-- \`loom verify history <id>\` — 验证历史
-- \`loom verify pending\` — 待验证的 Intent
+## LOOM 核心概念
+
+LOOM 用一条完整链路把长期判断、当前意图、专业能力、创造性探索和独立证明连起来：
+
+```text
+Doctrine → Intent narrative → Capability Graph → Contract
+→ Expertise Compiler → Quality Arena → Quality Proof
+→ Reflow
+```
+
+最后三步合称 **LOOM Quality Engine**。
+
+## Doctrine
+
+项目长期使用的判断系统：保护什么、冲突时如何取舍、什么算优秀、哪些反模式不能接受。
+Weaver 从项目事实和决策相关证据中织造 Doctrine；它不预写产品需求、架构或实现步骤。
+
+## Intent
+
+一个需要保护的产品结果，而不是任务清单。每个 Intent 包含：
+
+- `narrative_ref`：为什么存在。
+- `revision`：语义版本。
+- `depends_on`：依赖关系。
+- `acceptance`：完成契约，即 Reliability Floor。
+- `continuity_required`：仅对会修改既有用户或系统状态的 Intent 启用；要求守恒证据，但不另存一份契约。
+- `quality_contract`：可选的质量契约，即 Distinctive Ceiling。
+- `capability_needs`：可选的专业能力需求。
+- `creative_scope`：可选的探索边界。
+- `philosophy_anchors`、`status` 与 `verification_method`。
+
+Architect 是 Intent DAG 与两类契约的唯一负责人。
+
+## Capability Graph
+
+Capability Graph 位于 Vision 和 Intent Map 之间。它将项目初衷展开成 `outcome`、`concern`、`capability`、`risk`、`evidence` 五类节点，描述哪些问题必须被理解、设计、实现或证明。
+
+它不是执行 DAG，也不替代 Intent Map：Graph 保留未知、研究与分叉；Intent 只保留边界明确、能独立验收的承诺。高影响节点必须有明确路由（继续展开、Brief、Intent、延后或排除），每个 Intent 必须回链至少一个图谱节点。只有需要专业方法、调研或即将进入当前 Intent 的节点才创建短小的项目化 Capability Brief。
+
+## System Boundary
+
+LOOM 不假装能够清除宿主 Agent 的既有记忆。`loom activate` 生成有序 Context Pack，
+明确当前角色、当前 Intent、硬约束、成功契约与停止条件；系统和用户指令始终优先。
+
+## Expertise Compiler
+
+Forge 针对当前 Intent 临时组装一个 Expertise Pack。先由 Capability Graph 编译关联节点和 Capability Brief，再回答：
+
+1. 这是什么专业问题。
+2. 优秀作品的判断标准是什么。
+3. 哪些项目事实和约束会改变做法。
+4. 应加载哪些真实能力、资料或工具。
+5. 最可能出现哪些“合格但平庸”的失败。
+6. 如何验证专业质量。
+
+能力名称只表示“可发现”；只有真实加载并转化为任务判断的内容才算进入 Expertise Pack。
+Pack 仅服务当前任务，不成为长期 Doctrine。
+
+## Quality Arena
+
+Forge 的实现环境。结果显然时走直接路径；当目标是“更好、惊艳、出众”时：
+
+```text
+Baseline → Mechanism-different Candidates → Compare → Realize → Observe → Adjust
+```
+
+候选必须依赖不同机制，而不是同一方案换皮。没有候选真实胜过基线时，保留原方案是合法结论。
+
+## Quality Proof
+
+Keeper 在独立上下文中验证：
+
+- `intent_fidelity`
+- `philosophy_consistency`
+- `baseline_compliance`
+- `acceptance_achievement`
+- `preservation_achievement`（仅 `continuity_required` 时）
+- `quality_achievement`（仅有 `quality_contract` 时）
+
+质量提升声明必须有 Quality Proof：修改前基线、可观察主张、候选选择依据、稳定性证据与代价。
+完成可以通过而质量未通过；此时不得宣称“更好”。
+
+## Reflow
+
+发现问题时回到真正拥有该问题的层：
+
+- 长期价值判断 → Weaver
+- 产品目标与 narrative → Visionary
+- 系统边界、Intent、契约 → Architect
+- 图谱遗漏、未路由高影响节点或新的能力缺口 → Architect 更新 Capability Graph
+- 专业能力与实现 → Forge
+- 证据不足或判定偏离 → Keeper
+
+相关入口：
+
+- `loom context`
+- `loom intent next|get|trace|validate`
+- `loom activate <role> --intent <id>`
+- `loom verify contract|write|pass|history`
+- `loom doctor`

package/cli/help/doctor.md

@@ -1,121 +1,71 @@
-## 诊断与恢复指南
-
-## 健康检查
-
-\`\`\`bash
-loom doctor
-\`\`\`
-
-检测 7 类问题：
-
-| 问题类型 | 严重度 | 说明 |
-|---|---|---|
-| cycle | fatal | 循环依赖（Intent Map 有环） |
-| orphan_philosophy_ref | high | 哲学锚点指向不存在的文件 |
-| orphan_dependency | high | depends_on 引用不存在的 Intent |
-| completed_no_record | high | completed 但无验证记录 |
-| completed_depends_blocked | high | completed 依赖 blocked 的 Intent |
-| inspiration_source | high/medium | 灵感来源质量不达标（源太少/全是 Wikipedia/缺理由） |
-| part_decomposition | high/medium | 缺少实现部分拆解清单（Weaver 跳过了拆解步骤） |
-| in_progress_no_record | medium | in_progress 但无验证记录（可能中断） |
-| zombie | medium | in_progress/blocked 超过 7 天无活动 |
-
-## 灵感来源校验
-
-\`\`\`bash
-loom philosophy check
-\`\`\`
-
-单独校验哲学文档的灵感来源质量。防止 Weaver 从训练数据"背"几个名字就交差。
-
-校验规则：
-- 至少 3 个独立源
-- 至少 2 个非 Wikipedia 链接
-- 每个源必须有选取理由（萃取/转译/启发关系）
-- Wikipedia 占比不超过 70%
-
-不达标时，需要重新织造哲学——真正走搜索漏斗，找原著、论文、工程博客等深度源。
-
-## 实现部分拆解校验
-
-\`\`\`bash
-loom philosophy check
-\`\`\`
-
-同时校验哲学文档是否包含"实现部分清单"——Weaver 是否按 PART_DECOMPOSITION.md 拆解了项目的实现部分。
-
-校验规则：
-- 哲学文档中必须有"实现部分清单"章节（或"部分拆解""Part Decomposition"等）
-- 至少识别到 2 个实现部分（小项目建议 3-5 个，大项目 6-10 个）
-
-缺少时，说明 Weaver 跳过了拆解步骤，需要重新织造——按 PART_DECOMPOSITION.md 的方法论识别项目的实现部分。
-
-## 上下文摘要
-
-\`\`\`bash
-loom context
-\`\`\`
-
-一条命令获取：进度 + 下一个 Intent + 待验证 + 不一致项 + 风险。
-Agent 重启后先跑这个，快速知道"我在哪、接下来做什么"。
-
-## 只读阶段诊断
-
-\`\`\`bash
-loom guide --dry-run
-\`\`\`
-
-用于审计、子代理预演、只读探测。它输出和 `loom guide` 同样的阶段判断，但不写 `.loom/heartbeat.json`。
-
-## Preview 新鲜度诊断
-
-\`\`\`bash
-loom preview status
-\`\`\`
-
-检查 `loom-preview.html` 是否比当前 `.loom/v{N}` 源文件更新。人类要求看 preview 时，Agent 先跑这个命令：
-- `fresh=true`：可以 `loom preview`
-- `fresh=false`：不要打开旧投影，先 `loom preview --regen`
-- 必须看旧投影：`loom preview --stale`
-
-## 崩溃恢复
-
-### Forge 崩溃（Intent 留在 in_progress）
-
-1. 跑 \`loom doctor\` 确认哪些 Intent 状态不一致
-2. 跑 \`loom context\` 看整体状态
-3. 用户决定：
-   - 继续：重新激活 Forge，从当前代码接着做
-   - 重置：\`loom intent update <id> --status pending\`，从头来
-
-### Intent Map 文件损坏
-
-1. \`loom intent validate\` 会检测到格式错误
-2. 从 Git 恢复（.loom/ 应纳入版本控制）
-
-### 验证记录丢失
-
-1. \`loom doctor\` 会检测到 completed 无记录
-2. 重新验证该 Intent，或从 Git 恢复
-
-## 追溯工具
-
-\`\`\`bash
-# Intent 完整追溯链（依赖+验证+哲学+叙事）
-loom intent trace <id>
-
-# 反向依赖（谁依赖这个 Intent → 变更影响评估）
-loom intent reverse-dep <id>
-
-# 反向哲学引用（哪些 Intent 引用这个锚点 → 哲学变更影响评估）
-loom intent reverse-ref <anchor>
-\`\`\`
-
-## 版本控制是前提
-
-LOOM 假设项目使用 Git。所有 .loom/ 下的文件都应纳入版本控制：
-- 文件损坏 → 从 Git 恢复
-- 误操作 → 从 Git 回滚
-- 变更追溯 → Git log 就是审计日志
-
-LOOM 不内置备份、审计、回滚——这些是版本控制的职责。
+## 诊断与恢复
+
+```bash
+loom doctor
+loom context
+```
+
+`doctor` 只检查能够机械判断的系统一致性，不假装用规则替代专业判断。
+
+## 主要诊断
+
+| 类型 | 严重度 | 含义 |
+|---|---|---|
+| `cycle` | fatal | Intent DAG 有环 |
+| `orphan_philosophy_ref` | high | Doctrine 引用不存在 |
+| `orphan_dependency` | high | Intent 依赖不存在 |
+| `completed_no_record` | high | completed 没有验证记录 |
+| `completed_verification_not_passed` | high | 最新记录不能闭合当前 revision |
+| `stale_verification` | high | passed 记录早于当前 revision |
+| `quality_dimension_missing` | high | 有质量契约，但缺少通过的质量维度 |
+| `preservation_dimension_missing` | high | 启用了状态守恒门，但缺少通过的守恒维度 |
+| `inspiration_source` | high/medium | Doctrine 证据不可追溯、缺理由或仍是模板 |
+| `verification_method_drift` | high | 声明的验证方式与复现证据不一致 |
+| `in_progress_no_record` | medium | 工作可能中断 |
+| `zombie` | medium | Intent 长时间无活动 |
+
+## Doctrine 证据
+
+```bash
+loom philosophy check
+```
+
+校验只要求：
+
+- 至少有实际使用的证据条目。
+- 每条证据有选择或转译理由。
+- 每条证据有 URL、`file://` 或 `local:` 可追溯位置。
+
+不要求固定数量、不排斥 Wikipedia，也不强制来源多样性。来源是否足以支持主张由 Weaver 与审阅者
+判断；CLI 只阻止空白、装饰性名字和不可追溯引用。
+
+## Quality Proof
+
+有 `quality_contract` 的 Intent 若写入 `passed`：
+
+- `dimensions.quality_achievement` 必须存在并通过。
+- 声明相对提升时，`dimensions.quality_achievement.quality_proof_ref` 指向基线比较与稳定性证据。
+
+快速命令：
+
+```bash
+loom verify pass <id> --summary "<证据>" --quality-proof "<ref>"
+```
+
+若只达到完成契约，写 `deviated` 或完整验证记录，不要伪造质量通过。
+
+## 恢复
+
+- Forge 中断：检查真实产物后继续，或把 Intent 回退到 `pending`。
+- Intent Map 损坏：从 Git 恢复，再运行 `loom intent validate`。
+- 验证记录丢失：重新独立验证，不从旧会话记忆补写。
+- Preview 过期：`loom preview status` 后使用 `loom preview --regen`。
+
+追溯入口：
+
+```bash
+loom intent trace <id>
+loom intent reverse-dep <id>
+loom intent reverse-ref <anchor>
+loom verify history <id>
+```