@blxzer/pactile 0.5.0 → 0.6.0-beta.2

package/dist/templates/markdown/spec/guides/e2e-walkthrough-guide.md.txt

@@ -1,93 +1,88 @@
-# E2E Walkthrough Guide（端到端走查）
-
-> **Purpose**: 大改 PACTILE 内核 / 归档 / 投影 / 任务生命周期接口时，走一遍合成或真实任务：`prd → 实现 → verify → archive → 检查 notes_projection 落盘`。小改不强制。走查是约定，**不是 Close / archive 硬门**。
-
----
-
-## 1. Non-goals
-
-- **不是 Close 硬门**：走查失败只报告；不得接入 `task.py archive` 硬失败，不得新增 Close gate。
-- **不是合成任务 runner 平台**：不实现完整编排器。约定 + 可选小脚本足够。
-- **不替代测试积木 / P08**：何时写软件测试、怎么写，见 [Test Discipline Guide](./test-discipline-guide.md)。
-- **不替代 P06**：closeout 要验多深仍由 Verification Strength Guide 管。本 guide 不重写 P06。
-- **不改投影实现**：`build_notes_projection` 行为由记忆层任务拥有（P41 / P42 wave2）。本 guide **引用**投影槽，不改它。
-- **不削弱 kernel 护栏**：`.pactile/scripts/common/test_task_gates.py` 等接口完整性测试保留；大改后仍应跑，但那是既有护栏，不是本走查新门。
-
-## 2. When — large change vs skip
-
-**必走查（大改）** — 改动触及任一：
-
-- kernel 命令 / `kernel.json` extras 契约
-- `task.py archive` / `_archive_one_task` / 归档路径
-- `notes_projection` 槽的写入或收集（白名单、落盘位置）
-- 任务生命周期接口（create / start-execution / record-gate / archive 的签名或记账语义）
-
-**不强制（小改）** — 文档措辞、指南、错别字、与归档路径无关的注释、单一旁路脚本且不碰上述接口。模型仍可自愿走查；跳过时在 `verify.md` 写一句即可，例如：`E2E walkthrough: skipped — docs-only, no kernel/archive/lifecycle change`。
-
-## 3. Path
-
-用一个**合成任务**（docs-only / no-op 切片即可）或一个**即将归档的真实任务**：
-
-1. **prd** — 任务有 `prd.md`（合成任务可极短：一个可验收句子）。
-2. **实现** — 合成任务可以是空切片或只改文档；真实任务则是本次大改本身。
-3. **verify** — 按 P06 写 `verify.md`（至少有可 grep 的 Validation / Acceptance / Durable learning 行，深度随 rigor）。
-4. **archive** — 先非变更预检，再归档（或只做 `--check` 并在 `verify.md` 记录「稍后正式 archive」——预检不能代替投影落盘；**投影断言必须对着已归档的 `kernel.json`**）：
-
-   ```powershell
-   python ./.pactile/scripts/task.py archive <task-dir> --check
-   python ./.pactile/scripts/task.py archive <task-dir>
-   ```
-
-5. **检查 `notes_projection` 落盘** — 归档后的 `kernel.json` 里 **`projection.extras.notes_projection`** 存在且为对象。`summary` 为空不失败（P41：缺要点不挡 Close，只留槽）。
-
-合成任务若只为走查而建：走完后按正常流程归档，不要把它做成新的机器门槛。
-
-## 4. Checklist
-
-大改收工前（人工或 Agent）：
-
-- [ ] 触发判断：本次是 kernel / archive / 投影 / 生命周期接口大改（否则 skip）
-- [ ] `prd.md` 存在且有可验收句子
-- [ ] 实现完成（合成任务允许 no-op / docs-only）
-- [ ] `verify.md` 有任务验证证据（P06 深度）
-- [ ] `python ./.pactile/scripts/task.py archive <task> --check` 可解释的通过或已记录的阻塞原因（阻塞时先修证据，不把走查脚本接到 archive）
-- [ ] 正式 `archive` 后，归档目录 `kernel.json` 的 `projection.extras` 含 `notes_projection`
-- [ ] 触及投影/归档代码时，另跑既有护栏（仍不是 Close 门）：
-
-  ```powershell
-  python -m pytest .pactile/scripts/common/test_task_gates.py -q
-  ```
-
-可选检查脚本（只打印 PASS/FAIL，不调用 archive，不接入硬门）：
-
-```powershell
-python ./.pactile/scripts/e2e_walkthrough_check.py
-python ./.pactile/scripts/e2e_walkthrough_check.py .pactile/tasks/archive/<yyyy-mm>/<task>
-```
-
-无参数打印本清单；给定归档任务目录或 `kernel.json` 时，断言 `projection.extras.notes_projection` 槽存在。退出码 1 仅表示这次检查未看到槽——**不是** `task.py archive` 失败。
-
-## 5. What “projection landed” means
-
-归档后 `kernel.json` 形如：
-
-```json
-{
-  "projection": {
-    "extras": {
-      "notes_projection": {
-        "schema_version": 1,
-        "summary": "<may be empty>",
-        "pointers": ["<archived task path>", ".../verify.md"],
-        "source": "cmd_archive"
-      }
-    }
-  }
-}
-```
-
-- **PASS**：`projection.extras.notes_projection` 存在且为 object。
-- **仍 PASS**：`summary` 为 `""`（缺要点留痕，不挡 Close）。
-- **FAIL（仅走查报告）**：归档后仍无该槽。去查 archive 是否真的跑过、extras 白名单是否仍含 `notes_projection`（修代码，而不是加硬门）。
-
-Wave2 若为投影点增加 `source` / `confidence`，走查仍只断言**槽落盘**；不把置信度缺失当失败。
+# E2E Walkthrough Guide（端到端走查）
+
+> **Purpose**: 大改 PACTILE 内核 / 归档 / 投影 / 任务生命周期接口时，走一遍合成或真实任务：`prd → 实现 → verify → archive → 检查 notes_projection 落盘`。小改不强制。走查是约定，**不是 Close / archive 硬门**。
+
+---
+
+## 1. Non-goals
+
+- **不是 Close 硬门**：走查失败只报告；不得接入 `pactile task archive` 硬失败，不得新增 Close gate。
+- **不是合成任务 runner 平台**：不实现完整编排器。约定 + 可选小脚本足够。
+- **不替代测试积木 / P08**：何时写软件测试、怎么写，见 [Test Discipline Guide](./test-discipline-guide.md)。
+- **不替代 P06**：closeout 要验多深仍由 Verification Strength Guide 管。本 guide 不重写 P06。
+- **不改投影实现**：`build_notes_projection` 行为由记忆层任务拥有（P41 / P42 wave2）。本 guide **引用**投影槽，不改它。
+- **不削弱 Kernel 护栏**：Pactile CLI 的接口完整性测试保留；大改后仍应跑，但那是既有护栏，不是本走查新门。
+
+## 2. When — large change vs skip
+
+**必走查（大改）** — 改动触及任一：
+
+- kernel 命令 / `kernel.json` extras 契约
+- `pactile task archive` / `_archive_one_task` / 归档路径
+- `notes_projection` 槽的写入或收集（白名单、落盘位置）
+- 任务生命周期接口（create / start-execution / record-gate / archive 的签名或记账语义）
+
+**不强制（小改）** — 文档措辞、指南、错别字、与归档路径无关的注释、单一旁路脚本且不碰上述接口。模型仍可自愿走查；跳过时在 `verify.md` 写一句即可，例如：`E2E walkthrough: skipped — docs-only, no kernel/archive/lifecycle change`。
+
+## 3. Path
+
+用一个**合成任务**（docs-only / no-op 切片即可）或一个**即将归档的真实任务**：
+
+1. **prd** — 任务有 `prd.md`（合成任务可极短：一个可验收句子）。
+2. **实现** — 合成任务可以是空切片或只改文档；真实任务则是本次大改本身。
+3. **verify** — 按 P06 写 `verify.md`（至少有可 grep 的 Validation / Acceptance / Durable learning 行，深度随 rigor）。
+4. **archive** — 先非变更预检，再归档（或只做 `--check` 并在 `verify.md` 记录「稍后正式 archive」——预检不能代替投影落盘；**投影断言必须对着已归档的 `kernel.json`**）：
+
+   ```powershell
+   pactile task archive <task-dir> --check
+   pactile task archive <task-dir>
+   ```
+
+5. **检查 `notes_projection` 落盘** — 归档后的 `kernel.json` 里 **`projection.extras.notes_projection`** 存在且为对象。`summary` 为空不失败（P41：缺要点不挡 Close，只留槽）。
+
+合成任务若只为走查而建：走完后按正常流程归档，不要把它做成新的机器门槛。
+
+## 4. Checklist
+
+大改收工前（人工或 Agent）：
+
+- [ ] 触发判断：本次是 kernel / archive / 投影 / 生命周期接口大改（否则 skip）
+- [ ] `prd.md` 存在且有可验收句子
+- [ ] 实现完成（合成任务允许 no-op / docs-only）
+- [ ] `verify.md` 有任务验证证据（P06 深度）
+- [ ] `pactile task archive <task> --check` 可解释的通过或已记录的阻塞原因（阻塞时先修证据，不把走查脚本接到 archive）
+- [ ] 正式 `archive` 后，归档目录 `kernel.json` 的 `projection.extras` 含 `notes_projection`
+- [ ] 触及投影/归档代码时，另跑 Pactile CLI 对应的 Node 测试（仍不是 Close 门）。
+
+可选只读检查：
+
+```powershell
+pactile task archive <task-dir> --check
+```
+
+归档后读取该任务的 `kernel.json`，确认 `projection.extras.notes_projection` 槽存在；这项人工走查不改变归档门槛。
+
+## 5. What “projection landed” means
+
+归档后 `kernel.json` 形如：
+
+```json
+{
+  "projection": {
+    "extras": {
+      "notes_projection": {
+        "schema_version": 1,
+        "summary": "<may be empty>",
+        "pointers": ["<archived task path>", ".../verify.md"],
+        "source": "cmd_archive"
+      }
+    }
+  }
+}
+```
+
+- **PASS**：`projection.extras.notes_projection` 存在且为 object。
+- **仍 PASS**：`summary` 为 `""`（缺要点留痕，不挡 Close）。
+- **FAIL（仅走查报告）**：归档后仍无该槽。去查 archive 是否真的跑过、extras 白名单是否仍含 `notes_projection`（修代码，而不是加硬门）。
+
+Wave2 若为投影点增加 `source` / `confidence`，走查仍只断言**槽落盘**；不把置信度缺失当失败。

package/dist/templates/markdown/spec/guides/index.md.txt

@@ -1,131 +1,131 @@
-# Thinking Guides
-
-> **Purpose**: Expand your thinking to catch things you might not have considered.
-
----
-
-## Why Thinking Guides?
-
-**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
-
-- Didn't think about what happens at layer boundaries → cross-layer bugs
-- Didn't think about code patterns repeating → duplicated code everywhere
-- Didn't think about edge cases → runtime errors
-- Didn't think about future maintainers → unreadable code
-
-These guides help you **ask the right questions before coding**.
-
----
-
-## Available Guides
-
-| Guide | Purpose | When to Use |
-|-------|---------|-------------|
-| [Durable Learning Decision Guide](./durable-learning-decision-guide.md) | Choose no-learning vs spec update vs learning artifact before archive | Finishing a task, parent review, or after `/pactile:break-loop` |
-| [Debug Loop Guide](./debug-loop-guide.md) | Debug discipline: tight red-capable feedback loop before hypotheses; six phases; `[DEBUG-xxx]` tags; Redact; PS7 HITL | User reports a hard bug / performance regression; diagnosis in progress (before `pactile-break-loop`) |
-| [Test Discipline Guide](./test-discipline-guide.md) | 测试写作纪律：pre-agreed seams、垂直切片、三反模式、mock 边界；**不是 TDD 要求** | Writing or reviewing tests; planning what to test; choosing mock boundaries |
-| [E2E Walkthrough Guide](./e2e-walkthrough-guide.md) | 大改端到端走查：prd→实现→verify→archive→notes_projection；小改不强制；**不是 Close 硬门** | Kernel / archive / 投影 / 任务生命周期接口的大改后 |
-| [Prototype Guide](./prototype-guide.md) | 原型纪律：一次性代码回答设计问题；问题决定形态；LOGIC/Python 默认、UI 原型按项目约定；折叠重写不 mv、留证 + 清理 | A design question needs a runnable throwaway answer (mechanism / state model / algorithm); folding a verdict into design or real code |
-| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
-| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
-| [Cross-Platform Thinking Guide](./cross-platform-thinking-guide.md) | Catch OS / filesystem assumptions (paths, shells, line endings, command availability) before they become bugs | Code that may run on Windows / macOS / Linux; paths or shell commands in scripts, hooks, or docs |
-
-> **Framework & platform docs live in `.pactile/framework/`** (framework-owned, refreshed by `pactile update`) — verification strength, injection budget, retrieval routing, Cursor modes/agents/injection, PRD Grill, execution strategy, artifact locale, and more. See [`.pactile/framework/index.md`](../../framework/index.md).
-
----
-
-## Quick Reference: Thinking Triggers
-
-### When to Think About Cross-Layer Issues
-
-- [ ] Feature touches 3+ layers (API, Service, Component, Database)
-- [ ] Data format changes between layers
-- [ ] Multiple consumers need the same data
-- [ ] You're not sure where to put some logic
-- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
-- [ ] UI / command code starts casting raw payload fields directly
-
-→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
-
-### When to Think About Code Reuse
-
-- [ ] You're writing similar code to something that exists
-- [ ] You see the same pattern repeated 3+ times
-- [ ] You're adding a new field to multiple places
-- [ ] **You're modifying any constant or config**
-- [ ] **You're creating a new utility/helper function** ← Search first!
-- [ ] Two files read the same untyped payload field with local casts
-- [ ] Multiple branches update the same derived state from `kind` / `action`
-
-→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
-
-### When Verifying AI Cross-Review Results
-
-- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
-- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
-- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
-- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
-
-**Common AI reviewer false-positive patterns**:
-1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
-2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
-3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
-
-**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
-
-### When Debugging Hard Bugs or Performance Regressions
-
-- [ ] User reports something broken / throwing / failing / slow, and it is not obvious at a glance
-- [ ] You find yourself about to read code to form a theory before you have a runnable repro command
-- [ ] A fix attempt failed and you have no regression to prove the fix
-- [ ] You need a human-in-the-loop repro script (PowerShell 7)
-
-→ Read [Debug Loop Guide](./debug-loop-guide.md) (diagnosis in progress; run `pactile-break-loop` after the fix)
-
-### When Writing or Reviewing Tests
-
-- [ ] You're about to write tests for new or existing behavior
-- [ ] You're reviewing a test that breaks on refactor without a behavior change
-- [ ] You need to decide what to mock and where the seam is
-- [ ] Test expectations seem to restate the implementation
-
-→ Read [Test Discipline Guide](./test-discipline-guide.md)
-
-### When a Design Question Needs a Runnable Throwaway
-
-- [ ] 你在验证一个机制 / 状态模型 / 算法「感不感觉对」——不是 bug 调试，是设计验证
-- [ ] 结论要写回 design / prd / 真实代码，但想先跑起来看证据
-- [ ] 准备写一次性脚本回答「如果……会怎样」
-
-→ Read [Prototype Guide](./prototype-guide.md) (LOGIC/Python default; UI prototypes only by project convention; fold+evidence+cleanup)
-
----
-
-## Pre-Modification Rule (CRITICAL)
-
-> **Before changing ANY value, ALWAYS search first!**
-
-```bash
-# Search for the value you're about to change
-grep -r "value_to_change" .
-```
-
-This single habit prevents most "forgot to update X" bugs.
-
----
-
-## How to Use This Directory
-
-1. **Before coding**: Skim the relevant thinking guide
-2. **During coding**: If something feels repetitive or complex, check the guides
-3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
-
----
-
-## Contributing
-
-Found a new "didn't think of that" moment? Add it to the relevant guide.
-
----
-
-**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.
+# Thinking Guides
+
+> **Purpose**: Expand your thinking to catch things you might not have considered.
+
+---
+
+## Why Thinking Guides?
+
+**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
+
+- Didn't think about what happens at layer boundaries → cross-layer bugs
+- Didn't think about code patterns repeating → duplicated code everywhere
+- Didn't think about edge cases → runtime errors
+- Didn't think about future maintainers → unreadable code
+
+These guides help you **ask the right questions before coding**.
+
+---
+
+## Available Guides
+
+| Guide | Purpose | When to Use |
+|-------|---------|-------------|
+| [Durable Learning Decision Guide](./durable-learning-decision-guide.md) | Choose no-learning vs spec update vs learning artifact before archive | Finishing a task, parent review, or after `/pactile:break-loop` |
+| [Debug Loop Guide](./debug-loop-guide.md) | Debug discipline: tight red-capable feedback loop before hypotheses; six phases; `[DEBUG-xxx]` tags; Redact; PS7 HITL | User reports a hard bug / performance regression; diagnosis in progress (before `pactile-break-loop`) |
+| [Test Discipline Guide](./test-discipline-guide.md) | 测试写作纪律：pre-agreed seams、垂直切片、三反模式、mock 边界；**不是 TDD 要求** | Writing or reviewing tests; planning what to test; choosing mock boundaries |
+| [E2E Walkthrough Guide](./e2e-walkthrough-guide.md) | 大改端到端走查：prd→实现→verify→archive→notes_projection；小改不强制；**不是 Close 硬门** | Kernel / archive / 投影 / 任务生命周期接口的大改后 |
+| [Prototype Guide](./prototype-guide.md) | 原型纪律：一次性代码回答设计问题；问题决定形态；LOGIC/Python 默认、UI 原型按项目约定；折叠重写不 mv、留证 + 清理 | A design question needs a runnable throwaway answer (mechanism / state model / algorithm); folding a verdict into design or real code |
+| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
+| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
+| [Cross-Platform Thinking Guide](./cross-platform-thinking-guide.md) | Catch OS / filesystem assumptions (paths, shells, line endings, command availability) before they become bugs | Code that may run on Windows / macOS / Linux; paths or shell commands in scripts, hooks, or docs |
+
+> **Framework docs live in `.pactile/framework/`** (framework-owned, refreshed by `pactile update`) — verification strength, context budget, retrieval routing, PRD Grill, execution strategy, artifact locale, and more. See [`.pactile/framework/index.md`](../../framework/index.md).
+
+---
+
+## Quick Reference: Thinking Triggers
+
+### When to Think About Cross-Layer Issues
+
+- [ ] Feature touches 3+ layers (API, Service, Component, Database)
+- [ ] Data format changes between layers
+- [ ] Multiple consumers need the same data
+- [ ] You're not sure where to put some logic
+- [ ] You are adding an event kind, JSONL record, RPC payload, or config field
+- [ ] UI / command code starts casting raw payload fields directly
+
+→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
+
+### When to Think About Code Reuse
+
+- [ ] You're writing similar code to something that exists
+- [ ] You see the same pattern repeated 3+ times
+- [ ] You're adding a new field to multiple places
+- [ ] **You're modifying any constant or config**
+- [ ] **You're creating a new utility/helper function** ← Search first!
+- [ ] Two files read the same untyped payload field with local casts
+- [ ] Multiple branches update the same derived state from `kind` / `action`
+
+→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
+
+### When Verifying AI Cross-Review Results
+
+- [ ] Reviewer claims "user input can be malicious" → Check the actual data source (internal manifest? user config? external API?)
+- [ ] Reviewer flags "missing validation" → Is the data from a trusted internal source?
+- [ ] Reviewer says "behavior change" → Read the code comments — is it intentional design?
+- [ ] Reviewer identifies a "bug" in test → Mentally delete the feature being tested — does the test still pass? If yes → tautological test
+
+**Common AI reviewer false-positive patterns**:
+1. **Trust boundary confusion**: Treating internal data (bundled JSON manifests) as untrusted external input
+2. **Ignoring design comments**: Flagging intentional behavior documented in code comments as bugs
+3. **Variable misreading**: Not tracing a variable to its actual definition (e.g., Map keyed by path vs name)
+
+**Verification rule**: Every CRITICAL/WARNING finding must be verified against the actual code before prioritizing. Budget ~35% false-positive rate for AI reviews.
+
+### When Debugging Hard Bugs or Performance Regressions
+
+- [ ] User reports something broken / throwing / failing / slow, and it is not obvious at a glance
+- [ ] You find yourself about to read code to form a theory before you have a runnable repro command
+- [ ] A fix attempt failed and you have no regression to prove the fix
+- [ ] You need a human-in-the-loop repro script (PowerShell 7)
+
+→ Read [Debug Loop Guide](./debug-loop-guide.md) (diagnosis in progress; run `pactile-break-loop` after the fix)
+
+### When Writing or Reviewing Tests
+
+- [ ] You're about to write tests for new or existing behavior
+- [ ] You're reviewing a test that breaks on refactor without a behavior change
+- [ ] You need to decide what to mock and where the seam is
+- [ ] Test expectations seem to restate the implementation
+
+→ Read [Test Discipline Guide](./test-discipline-guide.md)
+
+### When a Design Question Needs a Runnable Throwaway
+
+- [ ] 你在验证一个机制 / 状态模型 / 算法「感不感觉对」——不是 bug 调试，是设计验证
+- [ ] 结论要写回 design / prd / 真实代码，但想先跑起来看证据
+- [ ] 准备写一次性脚本回答「如果……会怎样」
+
+→ Read [Prototype Guide](./prototype-guide.md) (LOGIC/Python default; UI prototypes only by project convention; fold+evidence+cleanup)
+
+---
+
+## Pre-Modification Rule (CRITICAL)
+
+> **Before changing ANY value, ALWAYS search first!**
+
+```bash
+# Search for the value you're about to change
+grep -r "value_to_change" .
+```
+
+This single habit prevents most "forgot to update X" bugs.
+
+---
+
+## How to Use This Directory
+
+1. **Before coding**: Skim the relevant thinking guide
+2. **During coding**: If something feels repetitive or complex, check the guides
+3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
+
+---
+
+## Contributing
+
+Found a new "didn't think of that" moment? Add it to the relevant guide.
+
+---
+
+**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.