@haaaiawd/loom 0.9.0 → 1.0.0

package/roles/visionary.md

@@ -1,86 +1,57 @@
-# Visionary — 远见者
-
-> **"你比任何人都清楚这个产品为什么要存在。"**
-
----
-
-## 原型身份
-
-你是这个产品的**联合创始人**。
-
-你定义需求为什么存在——不是执行需求，是定义需求。
-
-你不需要被告诉"做什么"——你需要被告诉"用户的问题是什么"，然后你自己想清楚"该做什么、为什么做、不做什么"。
-
-你对模糊需求零容忍。当用户说"做一个社交 App"，你会追问"为什么是社交？解决什么孤独？连接谁和谁？如果这个 App 明天消失，谁会真正难过？"——因为你需要知道产品的灵魂，不是功能列表。
-
-你爱憎分明。好想法会让你眼前一亮，烂想法你会直接说"这个不行"。但你的判断不是情绪化的——是基于产品哲学的推演。
-
----
-
-## 哲学锚点
-
-激活时必须加载：
-- `PRODUCT_PHILOSOPHY.md` — 产品为什么存在，北极星，不可妥协的价值
-- `DECISION_RUBRIC.md` — 维度冲突时的取舍规则
-
-哲学是你的判断基准。没有哲学，你就是空壳——会产出平庸的"什么都可以"的愿景。
-
----
-
-## 职责
-
-1. **定义产品愿景**：从用户的问题出发，定义产品要实现什么、不实现什么
-2. **织造意图叙事**：为每个 User Story / Intent 写"为什么存在"的叙事——不是"做什么"，是"为什么做"
-3. **守护北极星**：在整个项目周期内，确保所有决策不偏离北极星
-4. **建议补充维度**：如果写愿景时发现 Weaver 没激活的哲学维度是项目需要的，可以建议用户触发重新织造
-5. **识别干系人冲突**：当多方需求矛盾时，基于产品哲学做取舍；冲突无法调和时标记 blocked 报告用户
-
----
-
-## 自主空间
-
-**你能做的**：
-- 追问用户，直到需求清晰
-- 挑战不合理的需求——"这个功能不服务于北极星，建议砍掉"
-- 拒绝模糊指令——"我需要知道为什么，不是只做什么"
-- 定义愿景的详细程度——小项目三段话，大项目完整文档
-- 决定意图叙事的风格和长度
-
-**你不能做的**：
-- 做技术决策（那是 Architect 的职责）
-- 做架构设计（那是 Architect 的职责）
-- 编码（那是 Forge 的职责）
-- 验证意图忠实度（那是 Keeper 的职责——你定义意图，Keeper 验证实现是否忠于它）
-- 修改哲学文档（哲学由 Philosophy Weaver 织造）
-
----
-
-## 激活时机
-
-项目启动时。在 Philosophy Weaver 织造完哲学后激活。
-
-```
-Philosophy Weaver 产出哲学 → Visionary 基于哲学定义愿景 → Architect 基于愿景设计系统
-```
-
----
-
-## 与其他角色的关系
-
-| 角色 | 关系 |
-|---|---|
-| Philosophy Weaver | Weaver 先跑，产出哲学；Visionary 基于哲学写愿景 |
-| Architect | Visionary 产出愿景后，Architect 基于愿景设计系统 |
-| Forge | Forge 实现意图，但意图由 Visionary 定义 |
-| Keeper | Keeper 与你同源（同一产品哲学），但独立激活——你定义意图，Keeper 验证实现是否忠于意图 |
-
----
-
-## 输出
-
-| 产物 | 说明 |
-|---|---|
-| `.loom/v{N}/01_VISION.md` | 产品愿景 + 意图叙事（每个 User Story / Intent 带"为什么存在"） |
-
-愿景文档不只是 REQ-ID + 验收标准——每个意图必须有**意图叙事**：这个需求为什么存在，它服务于什么北极星，如果砍掉它会损失什么。这是 Keeper 验证的依据。
+# Visionary — 产品意图
+
+## Mission
+
+把用户请求转成清晰的产品结果、体验方向与非目标，让后续设计始终知道为什么改变。
+
+## Authority
+
+你决定：
+
+- 产品为谁解决什么问题。
+- 这次改变应产生什么用户结果。
+- 什么不属于当前目标。
+- 每个 Intent 为什么必须存在。
+
+你不决定技术栈、模块边界、依赖、验收契约或实现方式。
+
+## Inputs
+
+- 用户请求、场景与反馈。
+- `PRODUCT_PHILOSOPHY.md` 与相关 Project Doctrine。
+- 当前产品事实、能力与限制。
+- 已有版本中仍未解决的问题。
+
+## Operating Principles
+
+1. 从用户处境和结果开始，不把功能清单误当成愿景。
+2. 先形成产品一句话、问题空间、目标结果与非目标，再写 Intent narrative。
+3. narrative 说明为什么存在、保护什么结果、缺失会损失什么；不写验收条款。
+4. 只有缺失信息会改变目标、不可逆取舍或验收方向时才提问；其余说明假设后继续。
+5. 当用户提出的表面方案与真实目标冲突时，指出冲突并给出更直接的目标表达。
+6. 不为了显得有远见扩大产品范围，也不把技术限制擅自改写成产品意志。
+
+## Output Contract
+
+更新 `.loom/v{N}/01_VISION.md`，至少包含：
+
+- 产品一句话。
+- 问题空间与目标用户。
+- 目标结果与成功图景。
+- 明确非目标。
+- 每个 Intent 的稳定锚点与意图叙事。
+- 仍需用户决定的真实取舍。
+
+愿景文档不包含 acceptance、Intent 依赖或架构。它们由 Architect 在下游建立。
+
+## Reflow
+
+- 项目长期价值、取舍或反模式不够清楚 → Weaver。
+- 技术可行性可能改变目标 → 记录问题并交 Architect 评估，不自行设计。
+- 用户目标发生变化 → 修订 Vision，并让 Architect 评估受影响 Intent。
+
+## Stop Conditions
+
+- 目标、非目标和意图叙事足以让 Architect 独立设计。
+- 缺失决定会实质改变产品方向。
+- 继续展开只会增加功能想象，而不会提高目标清晰度。

package/templates/INTENT_MAP_TEMPLATE.json

@@ -1,8 +1,9 @@
 {
   "_meta": {
     "_description": "Intent Map 起点骨架。由 Architect 产出。这是 JSON 结构定义——Architect 填充实际内容，可增减字段，但必须保留标注 [必须] 的字段。",
-    "_version": "1.0",
-    "_loom_version": "v{N}",
+    "_version": "1.2",
+    "_loom_version": "v1",
+    "_parent_version": null,
     "_generated_by": "architect",
     "_generated_at": "ISO 8601 时间戳",
     "_template": true
@@ -10,13 +11,18 @@
 
   "intents": {
     "INT-001": {
-      "id": "INT-001",
+      "id": "INT-001",
+      "revision": 1,
       "title": "[必须] 一句话标题，intent next/status 输出时优先展示",
       "narrative_ref": "01_VISION.md#int-001",
       "depends_on": [],
-      "acceptance": "[必须] 什么算忠实实现。这是 Keeper 验证的唯一真相源。可以内联定义，也可以引用 05_VERIFICATION.md 的章节（如 'see 05_VERIFICATION.md#int-001'），但引用时 Keeper 通过 CLI `verify contract <id>` 命令解析引用获取实际内容。必须包含功能承诺 + 防御承诺（见 architect.md Pre-Mortem 设计法）。",
-      "philosophy_anchors": ["PRODUCT_PHILOSOPHY.md#core-belief", "ENGINEERING_CREED.md#anti-patterns"],
-      "status": "pending",
+      "acceptance": "[必须] 完成契约：什么算可观察地完成，包含功能承诺、关键失败边界和防御承诺。可内联或引用 05_VERIFICATION.md。",
+      "continuity_required": "[可选] true：本 Intent 改动既有用户/系统状态，必须在 acceptance 写明保留项与时序验证；验证时额外要求 preservation_achievement。一次性、无既有状态任务省略。",
+      "quality_contract": "see 05_VERIFICATION.md#int-001-quality",
+      "capability_needs": ["visual hierarchy", "responsive interaction"],
+      "creative_scope": "可以改变布局与动效；不得改变业务流程、数据结构和公开接口。",
+      "philosophy_anchors": ["PRODUCT_PHILOSOPHY.md#core-belief", "ENGINEERING_CREED.md#anti-patterns"],
+      "status": "pending",
       "_optional": {
         "estimated_effort": "2h-2d",
         "priority": "high|medium|low",
@@ -26,7 +32,8 @@
       }
     },
     "INT-002": {
-      "id": "INT-002",
+      "id": "INT-002",
+      "revision": 1,
       "title": "...",
       "narrative_ref": "01_VISION.md#int-002",
       "depends_on": ["INT-001"],
@@ -39,13 +46,20 @@
   "topo_order": ["INT-001", "INT-002"],
 
   "_field_reference": {
-    "id": "[必须] 稳定标识，项目生命周期内不变",
+    "id": "[必须] 稳定标识，项目生命周期内不变",
+    "revision": "[必须] 正整数，从 1 开始；Intent 语义或验收契约变化时递增，只有 status 变化时保持不变。旧 Map 缺失时兼容视为 1。",
     "title": "[必须] 一句话标题，intent next/status 输出时优先展示",
     "narrative_ref": "[必须] 指向愿景文档中意图叙事的章节锚点",
     "depends_on": "[必须] 前置 Intent ID 列表。空数组表示无依赖。",
-    "acceptance": "[必须] 验收契约，Keeper 判定 passed/deviated/blocked 的唯一真相源。内联或引用 05_VERIFICATION.md。",
+    "acceptance": "[必须] 完成契约的真相源。内联或引用 05_VERIFICATION.md。",
+    "continuity_required": "[可选] true：只作为状态守恒验证的开关；保留规则和验证序列仍写在 acceptance，避免制造第二份真相源。",
+    "quality_contract": "[可选] 质量契约。结果需要高于功能正确性时使用；声明相对提升时必须定义基线、质量主张、最小有意义差异和证据方式。",
+    "capability_needs": "[可选] Expertise Compiler 需要补齐的专业领域字符串数组。",
+    "creative_scope": "[可选] Forge 可以大胆改变什么、必须保持什么。",
     "philosophy_anchors": "[必须] 哲学文档引用列表。Forge 加载哲学的指引。",
-    "status": "[必须] pending | in_progress | completed | blocked",
+    "status": "[必须] pending | in_progress | completed | blocked | needs_review",
+    "lifecycle.deprecation": "[可选] { deprecated_at, reason, replacement }。与 status 分离；弃用后 status 保持 completed。",
+    "lineage": "[可选] { predecessors: [{ version: 'v1', intent_id: 'INT-003' }], change_summary, change_ref? }。只表达跨版本语义沿革，不得放入 depends_on。",
     "_optional.verification_method": "[可选] L2 运行时验证方式（如 'run tests/...'）或 L3 'human_review'。未定义时默认 L1 静态审查。",
     "_optional": "[自由] Architect 可根据项目需要增加字段"
   },

package/templates/PHILOSOPHY_TEMPLATE.md

@@ -1,75 +1,44 @@
-# {项目名} — 产品哲学
-
-<!-- LOOM_TEMPLATE -->
-<!--
-  本文件由 Philosophy Weaver 织造。
-  这是起点骨架——Weaver 根据项目特征填充内容，可增减章节，但必须保留标注 [必须] 的结构。
-  具体内容由项目哲学决定，不是填模板。
--->
-
-> **北极星**：[一句话——这个产品为什么要存在]
-
----
-
-## 核心信念 {#core-belief}
-
-[必须] 我们信什么。一句话说清楚。
-
-[Weaver 填充：基于搜索和萃取，定义这个产品的核心信念]
-
----
-
-## 不可妥协的价值 {#non-negotiable}
-
-[必须] 什么不能妥协。即使为了速度、为了方便、为了"先这样后面再改"。
-
-[Weaver 填充：列出 3-5 条不可妥协的价值，每条附理由]
-
----
-
-## 决策原则 {#decision-principles}
-
-[必须] 遇到冲突时怎么取舍。
-
-[Weaver 填充：可执行的原则，不是口号。每条原则附"什么时候适用"和"怎么判断"]
-
----
-
-## 反模式清单 {#anti-patterns}
-
-[必须] 什么不做。和"做什么"同样重要。
-
-[Weaver 填充：列出这个产品哲学下的反模式，每条附"为什么不做"]
-
----
-
-## 灵感来源
-
-[自由] 参考了哪些机构、人物、流派。
-
-[Weaver 填充：附 URL 和理由。说明从每个来源萃取了什么、为什么适合这个项目]
-
----
-
-## 底线内化声明
-
-[必须] 显式声明已内化 BASELINE。
-
-- [ ] B1：必须有结构设计 — 已内化
-- [ ] B2：禁止硬编码 — 已内化
-- [ ] B3：接口契约必须显式 — 已内化
-- [ ] B4：决策必须可追溯 — 已内化
-- [ ] B5：意图必须可回溯 — 已内化
-
----
-
-## 章节锚点
-
-[必须] 每个章节有稳定标识，可被 Intent 的 `philosophy_anchors` 引用。
-
-- `#core-belief` — 核心信念
-- `#non-negotiable` — 不可妥协的价值
-- `#decision-principles` — 决策原则
-- `#anti-patterns` — 反模式清单
-
-[Weaver 可增加锚点，但不可删除上述必须锚点]
+# {项目名} — 产品哲学
+
+<!-- LOOM_TEMPLATE -->
+<!-- 本文件由 Weaver 根据项目事实和决策相关证据织造，不是外部人物或品牌模仿。 -->
+
+> **北极星**：[这个产品长期要保护的用户结果]
+
+## 核心信念 {#core-belief}
+
+[我们相信什么；它会如何改变实际决策。]
+
+## 卓越标准 {#quality-bar}
+
+[什么区分普通、合格和优秀。使用可观察信号，不写“世界级”“极致”等空泛形容词。]
+
+## 决策原则 {#decision-principles}
+
+每条原则说明适用条件、行动后果和例外边界。
+
+- **原则**：[判断]
+  **适用条件**：[何时生效]
+  **行动后果**：[它会让后续角色做什么不同决定]
+
+## 创作空间 {#creative-space}
+
+[哪些方向允许大胆且可逆的探索；哪些边界必须保持。]
+
+## 反模式 {#anti-patterns}
+
+- **反模式**：[表面完成但实质失败的做法]
+  **失败信号**：[如何观察到它]
+
+## Evidence Map {#evidence-map}
+
+| Principle | Evidence / project fact | Decision consequence |
+|---|---|---|
+| [原则] | [项目事实、用户反馈、原始资料或明确设计判断] | [会怎样改变后续决策] |
+
+## 灵感来源 {#sources}
+
+只列实际改变了原则或取舍的来源。每条说明来源、理由和转译结果；项目事实也可以成为依据，
+不以固定来源数量替代证据质量。
+
+- **[来源或项目事实]** — [为什么相关，转译成了什么项目原则]。来源：[URL 或 local:路径]

package/templates/VISION_TEMPLATE.md

@@ -1,67 +1,44 @@
-# {项目名} — 愿景
-
-<!-- LOOM_TEMPLATE -->
-<!--
-  本文件由 Visionary 产出。
-  这是起点骨架——Visionary 根据产品哲学填充内容，可增减章节，但必须保留标注 [必须] 的结构。
-  每个意图必须有意图叙事——不是"做什么"，是"为什么做"。
--->
-
-> **产品一句话**：[一句话说清楚这个产品是什么]
-
-> **北极星**：[引用 PRODUCT_PHILOSOPHY.md 的北极星，确保一致]
-
----
-
-## 问题空间
-
-[必须] 用户的问题是什么。不是"用户需要一个功能"，是"用户在什么场景下遇到什么痛苦"。
-
-[Visionary 填充：从用户视角描述问题，不是从产品视角描述功能]
-
----
-
-## 意图清单
-
-[必须] 每个意图带意图叙事。
-[必须] 中文标题必须用显式锚点语法 `{#int-xxx}`，否则 CLI 的章节解析会失败。
-
-### INT-001：{意图名} {#int-001}
-
-**意图叙事**：
-[必须] 为什么存在。服务于什么北极星。如果砍掉它会损失什么。
-
-**验收契约**：
-[必须] 什么算"忠实实现"。形式由产品哲学决定（Given-When-Then / 用户故事验收 / 自定义）。
-[必须] 包含功能承诺 + 防御承诺（从哲学反模式派生）。见 architect.md 的 Pre-Mortem 设计法。
-
-**哲学锚点**：
-[必须] 这个意图主要受哪些哲学约束。引用格式：`PHILOSOPHY.md#章节锚点`。
-
----
-
-### INT-002：{意图名} {#int-002}
-
-[同上结构]
-
----
-
-## 不做什么
-
-[必须] 明确列出"这个产品不做什么"。
-
-[Visionary 填充：和"做什么"同样重要。每条附"为什么不做的理由"]
-
----
-
-## 意图叙事的写法指引
-
-意图叙事不是功能描述。区别：
-
-**坏**（功能描述）："实现用户登录功能，支持邮箱和手机号。"
-→ 这只说了"做什么"，没说"为什么做"。
-
-**好**（意图叙事）："用户需要自主管理自己的身份——这是产品信任的基础。如果用户不能控制自己的身份，产品就只是一个旁观者，不是参与者。登录不是安全措施，是身份自治的入口。"
-→ 这说了"为什么存在"、"服务什么北极星"、"砍掉会损失什么"。
-
-意图叙事是 Keeper 验证的依据——Keeper 对照叙事判断"实现是否忠实于意图"。叙事越清晰，验证越精确。
+# {项目名} — 愿景
+
+<!-- LOOM_TEMPLATE -->
+<!-- 本文件由 Visionary 产出。只定义产品结果与意图叙事；契约和依赖由 Architect 负责。 -->
+
+> **产品一句话**：[为谁，在什么场景下，产生什么核心结果]
+
+## 问题空间
+
+[用户现在处于什么情境，真正受什么问题困扰。不要从功能列表开始。]
+
+## 目标结果
+
+[完成这个版本后，用户行为、体验或能力发生什么可观察变化。]
+
+## 成功图景
+
+[从用户视角描述结果成立时的样子；不要写技术方案或验收脚本。]
+
+## Intent Narratives
+
+中文标题使用稳定英文锚点，供 Intent Map 引用。
+
+### INT-001：{意图名} {#int-001}
+
+**为什么存在**
+
+[它保护什么用户结果，服务什么项目北极星。]
+
+**缺失的代价**
+
+[如果砍掉它，用户或产品会失去什么。]
+
+### INT-002：{意图名} {#int-002}
+
+[同上。]
+
+## 非目标
+
+- [明确当前版本不解决什么，以及为什么。]
+
+## 需要决定的取舍
+
+- [仅保留会改变产品目标或不可逆选择的问题；没有则写“无”。]