@haaaiawd/loom 1.3.1 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (84) hide show
  1. package/CHANGELOG.md +11 -86
  2. package/CONTRIBUTING.md +37 -0
  3. package/EVIL_EVAL.md +112 -0
  4. package/README.md +193 -445
  5. package/README.zh-CN.md +174 -0
  6. package/SECURITY.md +11 -0
  7. package/cli/bin/loom.js +171 -998
  8. package/cli/src/protocol.js +367 -0
  9. package/cli/src/store.js +626 -0
  10. package/design.md +194 -0
  11. package/docs/PROMPT_CATALOG.md +99 -0
  12. package/docs/RELEASE_CHECKLIST.md +53 -0
  13. package/docs/UX_FLOW.md +171 -0
  14. package/docs/brand/loom-mark.svg +18 -0
  15. package/docs/brand/loom-readme-header.svg +34 -0
  16. package/docs/brand/loom-readme-header.zh-CN.svg +29 -0
  17. package/docs/loom-eval-loop.drawio +21 -0
  18. package/docs/loom-eval-loop.svg +56 -0
  19. package/docs/loom-production-loop.drawio +41 -0
  20. package/docs/loom-production-loop.svg +92 -0
  21. package/package.json +43 -40
  22. package/EXTERNAL_ACQUISITION_DESIGN.md +0 -143
  23. package/cli/help/asset.md +0 -36
  24. package/cli/help/atelier.md +0 -37
  25. package/cli/help/atlas.md +0 -48
  26. package/cli/help/capability.md +0 -118
  27. package/cli/help/concepts.md +0 -105
  28. package/cli/help/doctor.md +0 -80
  29. package/cli/help/expertise.md +0 -52
  30. package/cli/help/loop.md +0 -134
  31. package/cli/help/patch.md +0 -33
  32. package/cli/help/proposals.md +0 -21
  33. package/cli/help/version.md +0 -136
  34. package/cli/help/workflow.md +0 -116
  35. package/cli/src/activate.js +0 -505
  36. package/cli/src/asset-library.js +0 -384
  37. package/cli/src/atelier.js +0 -331
  38. package/cli/src/atlas.js +0 -282
  39. package/cli/src/auto.js +0 -116
  40. package/cli/src/capability-graph.js +0 -724
  41. package/cli/src/capability-proposals.js +0 -225
  42. package/cli/src/diagnostics.js +0 -859
  43. package/cli/src/expertise-pack.js +0 -336
  44. package/cli/src/guide.js +0 -548
  45. package/cli/src/help.js +0 -41
  46. package/cli/src/init.js +0 -187
  47. package/cli/src/intent-draft.js +0 -303
  48. package/cli/src/intent-map.js +0 -747
  49. package/cli/src/patch.js +0 -214
  50. package/cli/src/philosophy.js +0 -331
  51. package/cli/src/shared/intent-ref.js +0 -38
  52. package/cli/src/shared/md-utils.js +0 -125
  53. package/cli/src/shared/paths.js +0 -73
  54. package/cli/src/shared/proof-reference.js +0 -19
  55. package/cli/src/shared/verification-method.js +0 -32
  56. package/cli/src/verify.js +0 -394
  57. package/cli/src/version.js +0 -134
  58. package/dimensions/AUTHORSHIP.md +0 -45
  59. package/dimensions/PART_DECOMPOSITION.md +0 -42
  60. package/dimensions/SEARCH_METHODOLOGY.md +0 -101
  61. package/dimensions/examples/AGENT_SYSTEM/README.md +0 -219
  62. package/dimensions/examples/CLI_TOOL/README.md +0 -163
  63. package/dimensions/universal/COLLABORATION_PHILOSOPHY.md +0 -28
  64. package/dimensions/universal/ENGINEERING_CREED.md +0 -30
  65. package/dimensions/universal/PRODUCT_PHILOSOPHY.md +0 -32
  66. package/meta/BASELINE.md +0 -91
  67. package/meta/INTENT_LOOP.md +0 -296
  68. package/meta/PHILOSOPHY_WEAVER.md +0 -110
  69. package/meta/ROLE_ACTIVATION.md +0 -114
  70. package/roles/architect.md +0 -92
  71. package/roles/forge.md +0 -110
  72. package/roles/impact-reviewer.md +0 -37
  73. package/roles/keeper.md +0 -113
  74. package/roles/visionary.md +0 -57
  75. package/templates/ASSET_LIBRARY_MANIFEST_TEMPLATE.json +0 -10
  76. package/templates/ATELIER_RECORD_TEMPLATE.json +0 -48
  77. package/templates/ATLAS_TEMPLATE.html +0 -104
  78. package/templates/CAPABILITY_BRIEF_TEMPLATE.md +0 -36
  79. package/templates/CAPABILITY_GRAPH_EXAMPLE.json +0 -188
  80. package/templates/CAPABILITY_GRAPH_TEMPLATE.json +0 -78
  81. package/templates/EXPERTISE_PACK_TEMPLATE.json +0 -22
  82. package/templates/INTENT_MAP_TEMPLATE.json +0 -85
  83. package/templates/PHILOSOPHY_TEMPLATE.md +0 -44
  84. package/templates/VISION_TEMPLATE.md +0 -44
@@ -1,118 +0,0 @@
1
- ## Capability Graph 指南
2
-
3
- Capability Graph 位于 Vision 与 Intent Map 之间:它把项目初衷展开为需要被理解、设计、实现或证明的
4
- 问题面、能力缺口、风险与证据。它不是待办列表,也不替代 Intent Map。
5
-
6
- ```bash
7
- loom capability graph
8
- loom capability frontier
9
- loom capability get <node-id>
10
- loom capability coverage
11
- loom capability compile <intent-id>
12
- ```
13
-
14
- ## 工作方式
15
-
16
- Visionary 给出 outcome、角色、非目标与项目事实。Architect 用项目类型相符的透镜检查用户旅程、
17
- 体验、系统、资产、横切质量和未知;每个透镜必须被展开、覆盖或明确排除。
18
-
19
- ## Lens Contract:先检查,再命名能力
20
-
21
- 新建 Graph 必须先写 `lens_contract`。它要求 Architect 对用户旅程、交互与可访问性、视觉与信息表达、内容与沟通、系统与数据、横切质量与风险逐项做出判断:
22
-
23
- - 适用:用 `node_refs` 连到具体的 outcome、concern、capability、risk 或 evidence;
24
- - 不适用:写明基于项目事实的理由;
25
- - 需要额外维度:可以增补自定义透镜,但不能删掉六项必审方向。
26
-
27
- 透镜不是能力节点。`CAP-UI`、`CAP-UX`、`CAP-视觉优化` 这类标题没有用户结果,不能代替能力边界。应写成可观察、可取舍的结果,例如“让错误状态与恢复入口保持可理解”或“让长报告中的证据层级能在窄屏扫读”。一个 capability 可以被多个透镜引用,也可以支持多个 outcome;这正是 Graph 不应退化为 Intent 镜像的原因。
28
-
29
- ## Capability Domains:专业能力从哪里来
30
-
31
- `capability_domains` 记录的不是产品功能,而是会改变设计、实现或验证方法的专业领域。UI/UX、3D 建模、光影与材质、网络安全、心理学、生物学等都可以是 domain;是否进入图谱只看一个问题:**若不了解这个领域,当前方案或判断会不会实质不同?**
32
-
33
- 每个 domain 必须写清专业问题、为什么现在需要,并用 `node_refs` 连接具体 capability;每个 capability 也用 `domain_refs` 回链领域。这样:
34
-
35
- - `DOMAIN-INTERACTION-DESIGN` 可以支撑“状态与恢复可理解”;
36
- - `DOMAIN-3D-LIGHTING` 可以支撑“光影与材质传达空间尺度”;
37
- - `DOMAIN-WEB-SECURITY` 可以支撑“敏感操作具备可恢复的授权边界”;
38
- - `DOMAIN-BEHAVIORAL-PSYCHOLOGY` 可以支撑“敏感沟通不以操控性暗示替代用户选择”。
39
-
40
- 领域不是“我们已经拥有专家”的声明,也不是固定分类表。它只让 Forge 知道:这项具体能力需要什么专业问题、是否应进入外部获取,以及 Keeper 应按什么角度反证。
41
-
42
- 完整、有共享关系的最小例子见 `templates/CAPABILITY_GRAPH_EXAMPLE.json`。它不是可以照抄的产品方案,而是展示如何让 outcome、concern、capability、risk、evidence 和 capability domain 交叉连接。
43
-
44
- ## Impact Gate:先判断代价,后写 Intent
45
-
46
- 在 Graph schema 1.3 中,每个具体 capability 都必须有 `impact_assessment`。它不是形式化打分,而是先把容易被偷懒跳过的问题说清:它影响哪个用户结果?省略或误判的代价是什么?外部知识会不会改变方案或验证?理由是什么?Architect 完成初判后,必须开一个新的 Agent thread / 子代理运行 `loom activate impact-reviewer`,由它将逐项结论写入根级 `impact_review`;同一上下文里的自我复述不算独立审查。
47
-
48
- 若代价为 `hard_to_reverse`,或外部知识会改变决定,CLI 会要求 `impact: high`;这种节点只允许 `external_required`(或省略该字段、采用默认值)。不能把关键能力标为 medium/low,或写 `adaptive`,来绕过外部获取。并且 `high` 必须至少占具体 capability 的 **30%**(向上取整,至少一个);分母不包含 outcome、risk、evidence 等节点,避免靠增加陪跑节点稀释比例。
49
-
50
- ```json
51
- {
52
- "impact": "high",
53
- "impact_assessment": {
54
- "affected_user_result": "用户能以键盘和文字理解时间带,而非只能依赖颜色与拖拽",
55
- "failure_cost": "material",
56
- "external_knowledge_changes_decision": true,
57
- "rationale": "可访问数据表达会改变交互、备用文本和验收方式;普通图表经验不足以替代。"
58
- },
59
- "acquisition_mode": "external_required"
60
- }
61
- ```
62
-
63
- 高影响节点不能停在 `open`。它必须继续展开、生成 Capability Brief、编译为 Intent,或带理由地
64
- 延后/排除。`loom capability frontier` 显示尚未路由的高影响节点;`loom capability coverage` 检查
65
- 图谱与 Intent 的双向追溯。
66
-
67
- 高影响 `outcome` 还必须有一条真实的观察链:以 `validated_by` 指向 `evidence` 节点。该 evidence 的
68
- `verification` 对象必须包含 `method`、`target`、`procedure`、`pass_criteria` 和 `artifact`,并以
69
- `intent_refs` 回链负责产出该证据的 Intent。`target` 写结果真正要被看见、接收或使用的位置,例如目标
70
- 宿主的渲染面、用户拿到的导出文件、外部系统的接收端或人工验收现场。不要把“HTTP 200”“URL 可访问”或
71
- “本地生成了文件”当作用户已得到结果。设计阶段可以先声明计划中的本地 `artifact` 路径;只有负责它的
72
- Intent completed 后,CLI 才要求该证据文件实际存在,避免用空占位文件伪造验证。
73
-
74
- 不新增媒体、平台或版权专用节点类型:目标宿主与交付链路用 `concern` / `capability` 表达,许可、来源、
75
- 隐私或平台限制用 `risk` 和 `constrains` 关系表达;只有需要项目化判断时才为相关节点创建 Brief,并在其
76
- “项目约束”和“产出与验证入口”中写清授权边界与实际交付验证。
77
-
78
- ```json
79
- {
80
- "id": "EVIDENCE-DELIVERY-RENDER",
81
- "kind": "evidence",
82
- "title": "在目标宿主中实际呈现交付物",
83
- "status": "covered",
84
- "impact": "high",
85
- "route": "intent",
86
- "intent_refs": ["INT-004"],
87
- "verification": {
88
- "method": "manual_visual",
89
- "target": "目标桌面客户端的消息渲染面",
90
- "procedure": "在干净会话中发送产物并观察实际渲染",
91
- "pass_criteria": "用户无需打开外链即可看见完整内容",
92
- "artifact": "verifications/INT-004-host-render.png"
93
- },
94
- "relationships": []
95
- }
96
- ```
97
-
98
- ## Capability Brief
99
-
100
- 只有高影响、需要调研、需要专业方法或将进入当前 Intent 的能力节点才需要 Brief。Brief 位于:
101
-
102
- ```text
103
- .loom/vN/07_CAPABILITY_BRIEFS/<node-id>.md
104
- ```
105
-
106
- 它写当前项目问题、成功判断、约束、能力获取计划、产出/验证入口与非目标。不要复制通用教程,
107
- 也不要用“你是某领域专家”代替项目化能力说明。
108
-
109
- ## 编译与回流
110
-
111
- `loom capability compile <intent-id>` 只读显示会进入当前 Intent 的图谱节点与 Brief。Forge 激活
112
- Intent 时会获得同一份输入;发现新依赖、风险或能力缺口时必须回流 Architect 更新 Graph,不能静默
113
- 扩展实现。Keeper 以图谱回链检查高影响问题是否真的被兑现。
114
-
115
- Capability 节点可选声明 `acquisition_mode: adaptive | external_required | project_only`。
116
- schema 1.3 的 high capability 只允许 `external_required` 或省略(默认即为 `external_required`);
117
- 较低影响的 `project_only` 必须附 `acquisition_rationale`。Graph 只保存获取必要性,不保存网站、Skill 名称或
118
- 搜索词;Forge 在本轮 Expertise Pack 中按项目信号派生查询并记录真实来源。
@@ -1,105 +0,0 @@
1
- ## LOOM 核心概念
2
-
3
- LOOM 用一条完整链路把长期判断、当前意图、专业能力、创造性探索和独立证明连起来:
4
-
5
- ```text
6
- Doctrine → Intent narrative → Capability Graph → Contract
7
- → Expertise Compiler → Quality Arena → Quality Proof
8
- → Reflow
9
- ```
10
-
11
- 最后三步合称 **LOOM Quality Engine**。
12
-
13
- ## Doctrine
14
-
15
- 项目长期使用的判断系统:保护什么、冲突时如何取舍、什么算优秀、哪些反模式不能接受。
16
- Weaver 从项目事实和决策相关证据中织造 Doctrine;它不预写产品需求、架构或实现步骤。
17
-
18
- ## Intent
19
-
20
- 一个需要保护的产品结果,而不是任务清单。每个 Intent 包含:
21
-
22
- - `narrative_ref`:为什么存在。
23
- - `revision`:语义版本。
24
- - `depends_on`:依赖关系。
25
- - `acceptance`:完成契约,即 Reliability Floor。
26
- - `continuity_required`:仅对会修改既有用户或系统状态的 Intent 启用;要求守恒证据,但不另存一份契约。
27
- - `quality_contract`:可选的质量契约,即 Distinctive Ceiling。
28
- - `capability_needs`:可选的专业能力需求。
29
- - `creative_scope`:可选的探索边界。
30
- - `philosophy_anchors`、`status` 与 `verification_method`。
31
-
32
- Architect 是 Intent DAG 与两类契约的唯一负责人。
33
-
34
- ## Capability Graph
35
-
36
- Capability Graph 位于 Vision 和 Intent Map 之间。它将项目初衷展开成 `outcome`、`concern`、`capability`、`risk`、`evidence` 五类节点,描述哪些问题必须被理解、设计、实现或证明。
37
-
38
- 它不是执行 DAG,也不替代 Intent Map:Graph 保留未知、研究与分叉;Intent 只保留边界明确、能独立验收的承诺。高影响节点必须有明确路由(继续展开、Brief、Intent、延后或排除),每个 Intent 必须回链至少一个图谱节点。只有需要专业方法、调研或即将进入当前 Intent 的节点才创建短小的项目化 Capability Brief。
39
-
40
- 在 schema 1.3 中,每个具体 capability 先经过 **Impact Gate**:Architect 说明它影响的用户结果、错判代价、外部知识是否会改变决定与理由;新的 Agent thread / 子代理通过 `loom activate impact-reviewer` 独立复审并写入 `impact_review`。若错判不可逆或外部知识会改变决定,节点必须是 high、必须外部获取;high 至少占 capability 的 30%(向上取整,至少一个),不能用大量普通节点稀释。
41
-
42
- ## System Boundary
43
-
44
- LOOM 不假装能够清除宿主 Agent 的既有记忆。`loom activate` 生成有序 Context Pack,
45
- 明确当前角色、当前 Intent、硬约束、成功契约与停止条件;系统和用户指令始终优先。
46
-
47
- ## Expertise Compiler
48
-
49
- Forge 针对当前 Intent 临时组装一个 Expertise Pack。先由 Capability Graph 编译关联节点和 Capability Brief,再回答:
50
-
51
- 1. 这是什么专业问题。
52
- 2. 优秀作品的判断标准是什么。
53
- 3. 哪些项目事实和约束会改变做法。
54
- 4. 应加载哪些真实能力、资料或工具。
55
- 5. 最可能出现哪些“合格但平庸”的失败。
56
- 6. 如何验证专业质量。
57
-
58
- 能力名称只表示“可发现”;只有真实加载并转化为任务判断的内容才算进入 Expertise Pack。
59
- 当 External Acquisition Gate 为 required 时,Forge 只能自行派生 Search Plan,内容必须来自
60
- 实际打开的 Skill、网络、官方文档或研究资料;Pack 写入当前 Intent revision 的
61
- `10_EXPERTISE_PACKS`,每个 Capability Capsule 都直接回链来源。Pack 仅服务当前任务,不成为
62
- 长期 Doctrine。
63
-
64
- ## Quality Arena
65
-
66
- Forge 的实现环境。结果显然时走直接路径;当目标是“更好、惊艳、出众”时:
67
-
68
- ```text
69
- Baseline → Mechanism-different Candidates → Compare → Realize → Observe → Adjust
70
- ```
71
-
72
- 候选必须依赖不同机制,而不是同一方案换皮。没有候选真实胜过基线时,保留原方案是合法结论。
73
-
74
- ## Quality Proof
75
-
76
- Keeper 在独立上下文中验证:
77
-
78
- - `intent_fidelity`
79
- - `philosophy_consistency`
80
- - `baseline_compliance`
81
- - `acceptance_achievement`
82
- - `preservation_achievement`(仅 `continuity_required` 时)
83
- - `quality_achievement`(仅有 `quality_contract` 时)
84
-
85
- 质量提升声明必须有 Quality Proof:修改前基线、可观察主张、候选选择依据、稳定性证据与代价。
86
- 完成可以通过而质量未通过;此时不得宣称“更好”。
87
-
88
- ## Reflow
89
-
90
- 发现问题时回到真正拥有该问题的层:
91
-
92
- - 长期价值判断 → Weaver
93
- - 产品目标与 narrative → Visionary
94
- - 系统边界、Intent、契约 → Architect
95
- - 图谱遗漏、未路由高影响节点或新的能力缺口 → Architect 更新 Capability Graph
96
- - 专业能力与实现 → Forge
97
- - 证据不足或判定偏离 → Keeper
98
-
99
- 相关入口:
100
-
101
- - `loom context`
102
- - `loom intent next|get|trace|validate`
103
- - `loom activate <role> --intent <id>`
104
- - `loom verify contract|write|pass|history`
105
- - `loom doctor`
@@ -1,80 +0,0 @@
1
- ## 诊断与恢复
2
-
3
- ```bash
4
- loom doctor
5
- loom context
6
- ```
7
-
8
- `doctor` 只检查能够机械判断的系统一致性,不假装用规则替代专业判断。
9
-
10
- ## 主要诊断
11
-
12
- | 类型 | 严重度 | 含义 |
13
- |---|---|---|
14
- | `cycle` | fatal | Intent DAG 有环 |
15
- | `project_document_missing` | high | Vision、Architecture、Verification 或哲学三件套缺失 |
16
- | `project_document_template` | high | 必需文档仍是初始化模板,尚未成为项目判断 |
17
- | `orphan_philosophy_ref` | high | Doctrine 引用不存在 |
18
- | `orphan_philosophy_anchor` | high | Doctrine 文件存在,但 Intent 指向的章节锚点不存在 |
19
- | `intent_narrative_invalid` | high | Intent 的 narrative_ref 无法解析到当前 Vision |
20
- | `intent_contract_invalid` | high | Intent 的 acceptance 或其 Verification 引用无法解析 |
21
- | `orphan_dependency` | high | Intent 依赖不存在 |
22
- | `completed_no_record` | high | completed 没有验证记录 |
23
- | `completed_verification_not_passed` | high | 最新记录不能闭合当前 revision |
24
- | `stale_verification` | high | passed 记录早于当前 revision |
25
- | `quality_dimension_missing` | high | 有质量契约,但缺少通过的质量维度 |
26
- | `preservation_dimension_missing` | high | 启用了状态守恒门,但缺少通过的守恒维度 |
27
- | `inspiration_source` | high/medium | Doctrine 证据不可追溯、缺理由或仍是模板 |
28
- | `verification_method_drift` | high | 声明的验证方式与复现证据不一致 |
29
- | `capability_impact_gate_missing` | high | Capability Graph 未完成独立 Impact Review,或试图绕过 high / 外部获取门禁 |
30
- | `in_progress_no_record` | medium | 工作可能中断 |
31
- | `zombie` | medium | Intent 长时间无活动 |
32
-
33
- ## Doctrine 证据
34
-
35
- ```bash
36
- loom philosophy check
37
- ```
38
-
39
- 校验只要求:
40
-
41
- - 至少有实际使用的证据条目。
42
- - 每条证据有选择或转译理由。
43
- - 每条证据有 URL、`file://` 或 `local:` 可追溯位置。
44
-
45
- 不要求固定数量、不排斥 Wikipedia,也不强制来源多样性。来源是否足以支持主张由 Weaver 与审阅者
46
- 判断;CLI 只阻止空白、装饰性名字和不可追溯引用。
47
-
48
- ## Quality Proof
49
-
50
- 有 `quality_contract` 的 Intent 若写入 `passed`:
51
-
52
- - `dimensions.quality_achievement` 必须存在并通过。
53
- - 声明相对提升时,`dimensions.quality_achievement.quality_proof_ref` 指向基线比较与稳定性证据。
54
-
55
- 快速命令:
56
-
57
- ```bash
58
- loom verify pass <id> --summary "<证据>" --quality-proof "<ref>" \
59
- --verified-by "<keeper-thread-or-human>" \
60
- --verification-context independent_thread
61
- ```
62
-
63
- 若只达到完成契约,写 `deviated` 或完整验证记录,不要伪造质量通过。
64
-
65
- ## 恢复
66
-
67
- - Forge 中断:检查真实产物后继续,或把 Intent 回退到 `pending`。
68
- - Intent Map 损坏:从 Git 恢复,再运行 `loom intent validate`。
69
- - 哲学锚点失效:运行 `loom philosophy get <file#anchor>`,修正 Intent 引用到实际存在的章节,而不是只确认 Markdown 文件还在。
70
- - 验证记录丢失:重新独立验证,不从旧会话记忆补写。
71
- - 所有 Intent 已完成但 Atlas 缺失或过期:运行 `loom atlas --regen` 生成 `loom-atlas.html`,再运行 `loom atlas validate`。
72
-
73
- 追溯入口:
74
-
75
- ```bash
76
- loom intent trace <id>
77
- loom intent reverse-dep <id>
78
- loom intent reverse-ref <anchor>
79
- loom verify history <id>
80
- ```
@@ -1,52 +0,0 @@
1
- # External Acquisition 与 Expertise Pack
2
-
3
- LOOM 把“知道任务需要某项能力”和“真正获得了这项能力”分开。Capability Graph 只决定是否
4
- 需要外部获取;Forge 在当前 Intent 中派生查询、实际检索,再把有来源的核心信息编译成
5
- Capability Capsules。
6
-
7
- ```bash
8
- loom capability compile <intent-id>
9
- loom expertise init <intent-id>
10
- # 编辑 .loom/vN/10_EXPERTISE_PACKS/<intent-id>.json,并实际执行检索
11
- loom expertise validate <intent-id>
12
- loom activate forge --intent <intent-id>
13
- ```
14
-
15
- ## 什么时候强制
16
-
17
- - capability 显式声明 `acquisition_mode: external_required`;
18
- - 或高影响 capability 没有显式声明模式(默认即为 `external_required`)。
19
-
20
- Graph schema 1.3 中,高影响 capability 不允许 `adaptive` 或 `project_only`:它必须实际检索。
21
- 中低影响任务默认为 `adaptive`;仅依赖未公开内部协议、外部知识不会改变做法的机械任务可以用
22
- `project_only`,但必须写 `acquisition_rationale`。若外部知识仍可能改变方案,应回流 Impact Gate 上调,
23
- 而不是把检索省掉。
24
-
25
- ## Search Plan
26
-
27
- Forge 根据 capability question、Capability Brief、Intent narrative、质量契约、creative
28
- scope、媒介约束和基线缺口派生查询。每个 `external_required` capability 都是一项主动探索:先写清它需要回答的专业决定,再记录哪一条来源会让设计、实现或验证路径不同。关键词是运行时证据,不写回 Graph。
29
-
30
- 必须实际使用 Skill registry、网络、官方文档或研究资料。模型自行生成的原则、没有打开的
31
- 搜索摘要和只看标题的结果都不能登记为来源。首个来源如果只是通用建议、无法改变具体决定或与另一来源冲突,继续探索或回流,不得把它凑成 Capsule。每个计划必须写停止条件,避免无边界浏览。
32
-
33
- ## Capability Capsule
34
-
35
- 每个 required capability 至少有一个 Capsule,包含:
36
-
37
- - 专业问题与适用时机;
38
- - 规则和工作流;
39
- - 决策门与失败模式;
40
- - 可观察验证信号;
41
- - 至少一个直接外部来源引用。
42
-
43
- Pack 只保存项目化综合和定位信息,不复制第三方 Skill 或网页正文,也不会自动变成 Doctrine
44
- 或通用 Skill。Intent revision 改变后,旧 Pack 自动失效。
45
-
46
- ## Keeper
47
-
48
- CLI 能检查 Pack 当前、来源可定位、Capsule 直接引用外部资料,但不能仅凭 JSON 判断来源是否
49
- 真的支持结论。Keeper 必须在独立 task 中重新打开至少一个关键来源,核对规则与判断门,并让
50
- `loom verify pass` 将当前 Pack 的内容摘要绑定进验证记录;之后 Pack 内容发生变化必须重验。
51
-
52
- 更多设计边界见 `EXTERNAL_ACQUISITION_DESIGN.md`。
package/cli/help/loop.md DELETED
@@ -1,134 +0,0 @@
1
- ## Intent Loop 与 Quality Engine
2
-
3
- 每个 Intent 独立运行,直到当前 revision 被证据闭合。
4
-
5
- ```text
6
- Select → Compile Expertise → Explore/Direct → Realize
7
- → Self-check → Independent Proof → Close/Reflow
8
- ```
9
-
10
- ## 1. 选择与锁定
11
-
12
- ```bash
13
- loom intent next
14
- loom intent update <id> --status in_progress
15
- loom activate forge --intent <id>
16
- ```
17
-
18
- Context Pack 只注入当前角色和当前 Intent 的相关事实,但不会、也无法清除宿主会话的旧记忆。
19
- Forge 必须以磁盘事实和当前 Pack 为准,发现冲突时报告。
20
-
21
- ## 2. Expertise Compiler
22
-
23
- Forge 先形成任务级 Expertise Pack:
24
-
25
- - 专业问题与任务类型。
26
- - 卓越判断标准和反模式。
27
- - 项目事实、硬约束与可变空间。
28
- - 已实际加载的技能、资料、工具及其用途。
29
- - Critic 视角与验证方法。
30
-
31
- Pack 是任务级认知配置,不写成新的长期规范。高影响 capability 默认进入 External Acquisition Gate;若明确选择 `adaptive`,也必须写明为何此处不启用外部获取。Pack
32
- 必须落盘到 `10_EXPERTISE_PACKS/<intent-id>.json`:Search Plan 可由 AI 派生,但 Capsule 内容
33
- 必须来自实际打开的外部来源,并写出判断门、失败模式和验证信号。明显的机械任务可以保持
34
- `adaptive`;高质量任务必须足以解释为什么某个专业手法适合这个项目。
35
-
36
- ## 3. Quality Arena
37
-
38
- 完成目标明确且不存在实质质量选择时,走直接路径。
39
-
40
- 当 `quality_contract` 要求相对提升时:
41
-
42
- 1. 记录修改前 Baseline。
43
- 2. 产生少量机制不同的候选。
44
- 3. 按完成契约、质量契约、Doctrine 和实际成本比较。
45
- 4. 实现最优候选并观察真实产物。
46
- 5. 不胜过基线就保留原方案或回流契约,不强改。
47
-
48
- ## 4. Quality Proof
49
-
50
- ```bash
51
- loom activate keeper --intent <id>
52
- loom verify contract <id>
53
- ```
54
-
55
- Keeper 独立检查基础四维;有质量契约时增加第五维:
56
-
57
- ```json
58
- {
59
- "intent_id": "INT-001",
60
- "verdict": "passed",
61
- "timestamp": "2026-07-28T12:00:00.000Z",
62
- "summary": "具体、可定位、可复现的判定摘要",
63
- "verification_provenance": {
64
- "verified_by": "keeper thread 或人类复核标识",
65
- "context": "independent_thread"
66
- },
67
- "reproduction_command": "npm test",
68
- "dimensions": {
69
- "intent_fidelity": {
70
- "verdict": "passed",
71
- "evidence": "对照 narrative 的用户结果,真实产物保持了目标与非目标"
72
- },
73
- "philosophy_consistency": {
74
- "verdict": "passed",
75
- "evidence": "对照引用原则与反模式,关键取舍和例外均有项目依据"
76
- },
77
- "baseline_compliance": {
78
- "verdict": "passed",
79
- "evidence": "B1-B5 与项目底线逐项检查,未发现失守"
80
- },
81
- "acceptance_achievement": {
82
- "verdict": "passed",
83
- "evidence": "完成契约的可观察行为均已复现"
84
- },
85
- "quality_achievement": {
86
- "verdict": "passed",
87
- "evidence": "相对修改前基线,目标信号达到契约阈值且回归保持稳定",
88
- "quality_proof_ref": "artifacts/quality-proof.md#INT-001"
89
- }
90
- }
91
- }
92
- ```
93
-
94
- 快捷写入 `passed` 时,也必须声明这一来源:
95
-
96
- ```bash
97
- loom verify pass INT-001 --summary "..." \
98
- --verified-by "keeper-run-123" \
99
- --verification-context independent_thread
100
- ```
101
-
102
- 若 Intent 声明 `continuity_required: true`,Keeper 还必须写入并通过:
103
-
104
- ```json
105
- "preservation_achievement": {
106
- "verdict": "passed",
107
- "evidence": "复现旧状态 → 本轮操作 → 新状态;列出保留的旧值、完成状态或可见行为。"
108
- }
109
- ```
110
-
111
- 这不是第二份契约:具体保留规则和操作序列仍写在 `acceptance`。通过快捷命令闭合时,必须显式提供
112
- `--preservation-evidence "..."`。
113
-
114
- 存在 `quality_contract` 时强制 `quality_achievement`;只有声明相对提升时才需要
115
- `quality_proof_ref`。Quality Proof 至少说明基线、主张、候选机制、选择证据、稳定性和代价。
116
-
117
- ## 5. 判定与回流
118
-
119
- | verdict | 动作 |
120
- |---|---|
121
- | `passed` | `loom intent done <id>` |
122
- | `deviated` | 回到真正的问题拥有者,修正后重验 |
123
- | `blocked` | 标记阻塞并报告缺失条件 |
124
- | `pending_human` | 只在确需人类感知或授权时使用 |
125
-
126
- 完成通过但质量未通过时,结果可以保留为可靠完成,但不得声称质量提升;由用户决定继续 Arena、
127
- 降低或修订质量契约,还是接受当前结果。
128
-
129
- Intent 语义变化必须递增 revision;任何完成态 Intent 回流也会递增验证 epoch。旧 revision 或旧 epoch 的 passed 记录都不会闭合当前 Intent;修订 Intent 时必须完整分类全部直接和传递下游,已完成下游会一并回流复验。
130
-
131
- ## 6. Goal 与闭环
132
-
133
- 把当前 Intent 视为一次 Codex goal 的可闭合单元。goal 只能在“结果、适用时的状态守恒、可复现证据、按需的质量证明”同时成立后完成;
134
- goal/status 不能替代 Keeper 验证。状态型任务默认保留或合并旧内容,删除和覆盖必须在 acceptance 中显式授权。
package/cli/help/patch.md DELETED
@@ -1,33 +0,0 @@
1
- ## Patch 审计工作流
2
-
3
- Patch 只处理不改变 Intent 或验收契约的实现修正。`06_CHANGELOG.json` 是唯一权威来源,`06_CHANGELOG.md` 是 CLI 确定性生成的只读投影,不要手工编辑。
4
-
5
- ```bash
6
- # 修改并自行运行验证后,准备输入文件
7
- loom patch record --json-file patch.json
8
- loom patch list
9
- loom patch get PATCH-001
10
- loom patch validate
11
- ```
12
-
13
- 输入格式:
14
-
15
- ```json
16
- {
17
- "summary": "修复空输入崩溃",
18
- "reason": "解析器遗漏空字符串边界",
19
- "affects": ["INT-001"],
20
- "files": ["src/parser.js", "test/parser.test.js"],
21
- "verification": [
22
- { "command": "npm test", "result": "passed" },
23
- { "method": "agent-browser screenshot", "result": "passed", "evidence": "浅色和深色背景下均清晰可读" }
24
- ]
25
- }
26
- ```
27
-
28
- - `affects` 可省略;提供时每个 ID 必须存在于当前 Intent Map。
29
- - `files` 必须是安全的项目相对路径。
30
- - `verification` 每项提供 `command` 或 `method`,可附具体 `evidence`;至少有一个 `passed`。CLI 只记录结果,绝不执行命令。
31
- - Patch 只能在当前版本全部 Intent 完成后记录;未完成的能力变化必须走 Intent Loop。
32
- - `id` 和 `timestamp` 由 CLI 分配,输入中不要提供。
33
- - `loom patch validate` 校验 JSON 全量记录及 Markdown 是否与 JSON 完全一致。
@@ -1,21 +0,0 @@
1
- # Capability Graph Change Proposals
2
-
3
- New user requirements, research findings, and implementation discoveries are candidates, not silent changes to the official Capability Graph or current Intent.
4
-
5
- ```bash
6
- loom capability proposal submit --json-file ./CGP-NEW-REQUIREMENT.json
7
- loom capability proposal list
8
- loom capability proposal get CGP-NEW-REQUIREMENT
9
- loom capability proposal decide CGP-NEW-REQUIREMENT graph_update --rationale "..."
10
- loom capability proposal close CGP-NEW-REQUIREMENT --resolution-file ./CGP-NEW-REQUIREMENT-resolution.json
11
- ```
12
-
13
- Each proposal records an origin, provenance (source, observation time, concrete evidence), candidate kind, title and why-now. Candidate kinds are `outcome`, `constraint`, `capability`, `risk`, and `evidence`.
14
-
15
- Only Architect decides whether it is already covered, needs a Graph update, changes an Intent or acceptance contract, belongs in Minor/Major, or is rejected. A decision still blocks the loop until a structured resolution closes it; an arbitrary path or prose string is not evidence.
16
-
17
- The resolution is decision-specific and is checked against the current version after the decision baseline: `graph_update` names changed Graph nodes (which must carry the proposal ID); `intent_change` names changed Intents; `acceptance_change` names Intents whose acceptance artifact changed; `covered` names the already-effective Graph coverage plus a rationale; and `minor`, `major`, or `reject` references a newly written `03_DECISIONS/` artifact naming the proposal. A `constraint` decided as `graph_update` must additionally appear in the formal Graph `constraints` array with its affected node IDs.
18
-
19
- For `covered_by`, use both `covered_by: "NODE-ID"` and a `{ "type": "covered_by", "target": "NODE-ID" }` relationship. The target must be a different, currently covered node with a direct route; chained or self-referential coverage is rejected.
20
-
21
- Forge and Keeper may submit candidates but cannot use them to expand their active scope.