pi-matt-pocock 0.2.1 → 0.3.0

package/ARCHITECTURE.zh-CN.md

@@ -2,6 +2,8 @@
 
 `pi-matt-pocock` 将 [mattpocock/skills](https://github.com/mattpocock/skills) 中选定的工程方法适配为 Pi 的**目录驱动能力网关**。它不是上游仓库的完整镜像，也不把每份上游 `SKILL.md` 注册为 Pi skill。
 
+上游检查已更新至 `d81f3a1`。新增 `pr`（模型与命令可用）和 `retro`（用户命令）能力；词汇表采用 `GLOSSARY.md`，旧 reference id `CONTEXT-FORMAT` 通过别名继续可恢复。上游移除的 `resolving-merge-conflicts` 保留为本地兼容能力。开发依赖与可执行运行 fixture 都按包内实际解析结果验证 Pi v1.0。
+
 ## 核心模型：procedureCatalog manifest
 
 `src/catalog.json` 中的 `procedureCatalog` manifest 是能力与资源关系的单一事实来源，`src/catalog.ts` 提供类型化查询与校验。命令菜单、模型可见能力、工作流入口、route 标题与说明、阶段、别名、依赖、引用披露、合法迁移和完整性检查都从目录派生，而不是分别维护 route/procedure 巨型枚举。
@@ -42,16 +44,16 @@
 启动 route 时，`src/workflow.ts` 从目录查找唯一入口，并创建如下持久化状态：
 
 ```text
-version / workItemId / route / procedure / phase / status / loadedReferences
+version / workItemId / route / procedure / phase / status / loadedReferences / deliveredProcedures
 ```
 
 - `workItemId` 是每次工作流启动时生成的稳定 UUID，用于区分独立工作项。
 - 活动记录的 `status` 为 `active`。
 - 结束记录保留同一 `workItemId`，`status` 为 `completed` 或 `cancelled`；取消记录可包含原因。
-- 状态通过 `pi.appendEntry` 写入 session branch。重启时只恢复最新的有效 `active` 记录；最新记录已结束时不会恢复旧活动状态。
+- 状态通过 `pi.appendEntry` 写入 session branch。Pi v1.0 的 session start、tree navigation 和 context compaction 都以当前分支最新记录为准；记录已结束、损坏或版本不兼容时，不会回退恢复旧活动状态。
 - 恢复前会重新验证 route、procedure 与资源 bundle。无效的陈旧状态会被明确记录为 `cancelled`，而不是静默回退到 route 默认入口。
 
-工作流启动、恢复或迁移时会返回当前 procedure bundle。之后每个 agent turn 只追加紧凑 guidance，包含 `workItemId`、当前阶段、合法下一步、可加载 reference 与终止责任，不会把整个目录反复注入 system prompt。
+扩展实例独立持有运行状态，避免同一进程中多个会话串扰。工作流启动或恢复时会返回完整的当前 procedure bundle；迁移只交付本次连续上下文中尚未交付的正文。压缩上下文后重置交付集合并静默注入当前完整 bundle。之后每个 agent turn 只追加紧凑 guidance，包含 `workItemId`、当前阶段、合法下一步、可加载 reference 与终止责任，不会把整个目录反复注入 system prompt。
 
 模型可以通过 `matt_pocock_active` 明确完成工作流；完成不再依赖用户进入菜单。用户仍可从同一 `/matt-pocock` 菜单迁移、完成或取消，作为显式控制入口。
 
@@ -76,13 +78,13 @@ version / workItemId / route / procedure / phase / status / loadedReferences
 | `hard-bug` | Reproducing & Diagnostics；Implementation；Code Review |
 | `architecture` | Architecture Survey；Architecture Design；Implementation；Code Review |
 
-route、procedure、phase、workItemId 和状态的持久化结构不变，模型 guidance、工具参数与结果 details 仍使用原标识。展开启动提示时仅显示不同于阶段标题的 `route · <Readable Route Title>`，例如 `route · Hard Bug Diagnosis`，标题复用 `readableRouteTitle()`；若两者相同（如 Task Triage 入口），也省略该字段。不再重复 phase id，也不会展示 procedure 正文。
+route、procedure、phase、workItemId 和状态的持久化结构不变，模型 guidance、工具参数与结果 details 仍使用原标识。启动提示行只显示可读的阶段标题，不再重复 route id 或 route 标题，也不会展示 procedure 正文。
 
-展开仅补充当前提示尚未显示的信息：
+所有 Matt Pocock 行都在折叠状态显示全部事实，不使用展开隐藏字段正文：
 
 - 迁移、完成和参考资料加载不显示重复的 `action` 字段；独立能力和独立参考资料也不把标题再复制为字段。标题完整可见时，这些提示没有展开提示或额外正文。
-- 取消提示只在该结果保存的终止快照包含非空白原因时，展开显示一次 `reason · <stored reason>`，不显示 `action · cancel`，也不读取当前工作流的原因。缺失、空字符串或纯空白原因均不会新增详情或展开提示。
-- 窄终端中的标题或摘要被截断时，由 Pi-kit 共享渲染器提供展开，并使用 Pi 原生换行恢复完整文本；本包不自行计算宽度。仅供模型使用的正文与 metadata 不会触发展开提示。
+- 取消提示在该结果保存的终止快照包含非空白原因时，直接在折叠行内联显示一次 `reason · <stored reason>`，不显示 `action · cancel`，也不读取当前工作流的原因。缺失、空字符串或纯空白原因不会新增正文。
+- 窄终端中的标题或正文行被截断时，由 Pi-kit 共享渲染器提供展开，并使用 Pi 原生换行恢复完整文本；本包不自行计算宽度。仅供模型使用的正文不会触发展开提示。
 
 `matt-pocock-procedure` 消息渲染器负责这条块状提示。用户从 `/matt-pocock` 启动 route/独立能力、用自由文本触发路由、或在菜单里选 “Start a task” 时，procedure 都通过这条可见消息交付，而不是把正文当 user message 贴出：
 
@@ -92,11 +94,15 @@ route、procedure、phase、workItemId 和状态的持久化结构不变，模
 fix the login redirect
 ```
 
-head 单独成行，一个空行分隔，随后是用户自己的任务原文（未提供任务时用可读的阶段标题或能力 id）；整块使用 Pi 原生 user-message 底色（`userMessageBg`），逐行保留换行、过长自动换行，且不提供展开。模型侧仍收到完整正文和 `User target/request:` 段落。恢复会话时仅静默注入 guidance（`display: false`），不新增重复的启动行。旧工具结果即使保存了 route 风格的 subject，也根据该事件保存的 phase 和 action 重新渲染，不读取当前工作流的可变状态，无需迁移会话数据。
+head 单独成行，一个空行分隔，随后是用户自己的任务原文（未提供任务时用可读的阶段标题或能力显示名称）；整块使用 Pi 原生 user-message 底色（`userMessageBg`），逐行保留换行、过长自动换行，且不提供展开。模型侧仍收到完整正文和 `User target/request:` 段落。恢复会话时仅静默注入 guidance（`display: false`），不新增重复的启动行。旧工具结果即使保存了 route 风格的 subject，也根据该事件保存的 phase 和 action 重新渲染，不读取当前工作流的可变状态，无需迁移会话数据。
+
+能力与引用统一使用目录中的可读显示名称；阶段切换菜单使用目标阶段标题，与进入阶段后的状态行一致。命令和持久化数据仍保留原有 id，用户任务原文不改写。
 
 独立能力、参考资料和提问保留各自的展示对象：`started · <capability>`、`started · <capability> · <reference>`、`event · loaded <reference>` 和 `ask · <question>`，不替换成工作流阶段。提问的答案或待定状态保持可见，超时、无 UI 和自定义输入等有效 metadata 仍可展开查看，不重复答案。
 
-从仓库根目录运行 `uv run --no-project packages/matt-pocock/tests/live_smoke.py`，可在真实 Pi CLI 中验证 print 模式、交互终端提示、Ctrl+O 展开、缩至 48 列，以及 `/matt-pocock hard-bug fix the login redirect` 只产生一块 user-message 底色的块状提示。脚本使用临时 HOME 与离线脚本化 provider，不读取用户凭证或调用外部模型。
+从仓库根目录运行 `uv run --no-project packages/matt-pocock/tests/live/live_smoke.py`，可在真实 Pi CLI 中验证 print 模式、交互终端提示、真实选择超时与 Escape 取消、Ctrl+O 展开、缩至 48 列，以及 `/matt-pocock hard-bug fix the login redirect` 只产生一块 user-message 底色的块状提示。脚本使用临时 HOME 与离线脚本化 provider，不读取用户凭证或调用外部模型。
+
+`tests/live/runtime_live.py` 从 catalog 派生全部 route、合法转移和独立能力，在真实 Pi agent loop 中运行，并验证持久化重启；`tests/live/decision_live.py` 通过 PTY 发送实际选择、文本输入与取消按键。运行方式同上。原生进程失败模拟与实际 macOS 对话框验证分别记录。这些验证覆盖 Pi 集成路径，不证明外部模型的决策质量，也不代表每份 procedure 的下游工程任务已执行。
 
 ## 协作验证与完成门槛
 
@@ -149,7 +155,7 @@ head 单独成行，一个空行分隔，随后是用户自己的任务原文（
 
 上游以多份嵌套 `SKILL.md` 分发能力。Pi 会递归发现 skill root 下的这些文件，因此 `tdd`、`research`、`implement`、`code-review` 等通用名字可能与用户安装的其他集合冲突，也不天然表达工作项状态和合法阶段迁移。
 
-本包把选定内容保存为 `procedures/*.md`、reference Markdown 或 asset，并由 extension 目录解析。包内不含子 `SKILL.md`：
+本包把选定内容按 catalog 的 kind 分目录保存：可加载的 capability 放在 `procedures/`，按需加载的 reference 放在 `references/`，模板类 asset 放在 `assets/`，并由 extension 解析。包内不含子 `SKILL.md`：
 
 - 名称不会进入全局 skill 命名空间；
 - workflow 与 standalone capability 共用同一个目录和网关；
@@ -160,28 +166,34 @@ head 单独成行，一个空行分隔，随后是用户自己的任务原文（
 
 ## 上游选择与同步校验
 
-[`upstream-selection.json`](upstream-selection.json) 是机器可读的上游选择记录。它把最新检查版本中的每个上游 skill 标为：
+[`upstream/upstream-selection.json`](upstream/upstream-selection.json) 是机器可读的上游选择记录。它把最新检查版本中的每个上游 skill 标为：
 
 - `selected`：映射到本地 catalog id、普通 Markdown resource 与上游调用模式；
 - `excluded`：保留明确排除理由，包括依赖 Claude Code hook 或后台 agent 命令的宿主专属能力。
 
-[`UPSTREAM.md`](UPSTREAM.md) 记录比较 commit、tag、tag commit、最新检查 commit 以及适配规则。[`scripts/check-upstream-sync.mjs`](scripts/check-upstream-sync.mjs) 是同步 checker：不带参数时验证本地元数据和资源；传入已克隆的上游路径时，还会检查完整 skill inventory、调用模式和正文差异。checker 不会自行 clone 或 fetch。
+[`upstream/UPSTREAM.md`](upstream/UPSTREAM.md) 记录比较 commit、tag、tag commit、最新检查 commit 以及适配规则。[`upstream/check-upstream-sync.mjs`](upstream/check-upstream-sync.mjs) 是同步 checker：不带参数时验证本地元数据和资源；传入已克隆的上游路径时，还会检查完整 skill inventory、调用模式和正文差异。checker 不会自行 clone 或 fetch。
 
 贡献者应运行：
 
 ```bash
-node packages/matt-pocock/scripts/check-upstream-sync.mjs
-python3 -m pytest packages/matt-pocock/tests/ -q
-npx tsc --noEmit -p tsconfig.extensions.json
-pnpm --dir packages/matt-pocock pack --dry-run
+node packages/matt-pocock/upstream/check-upstream-sync.mjs
+uv run pytest packages/matt-pocock/tests/ -q
+bun run typecheck
+bun pm pack --destination /tmp --quiet --cwd packages/matt-pocock
 ```
 
 需要核对上游 checkout 时再运行：
 
 ```bash
-node packages/matt-pocock/scripts/check-upstream-sync.mjs --upstream /path/to/mattpocock-skills
+node packages/matt-pocock/upstream/check-upstream-sync.mjs --upstream /path/to/mattpocock-skills
 ```
 
+实际 Pi v1.0 检查见 [`README.md`](README.md) 中的运行命令。目录矩阵从 manifest 派生所有 route、合法迁移和独立能力，通过真实 Pi agent loop 执行，并检查工具启停、持久化、重启、原生树切换与上下文压缩。压缩检查通过 `session_before_compact` 提供固定摘要；Pi 的压缩事件与会话写入仍实际执行，下一次模型上下文需包含恢复后的完整 procedure 来源。
+
+决策、活动菜单和 AbortSignal 检查运行在真实 Pi 终端中。测试使用临时 HOME 和本地固定响应 provider，不读取用户认证，也不验证外部模型的决策质量或 procedure 指导的下游项目任务。故意失败的模拟原生子进程只证明 TUI fallback；独立 macOS smoke 使用实际 `osascript` 验证超时、中止和进程退出，不代替原生按钮选择或物理界面的人工验收。
+
+真实模型检查单独使用 `tests/real_model_live.py`，用例清单位于 `tests/real-model-cases.json`，覆盖 21 个独立能力、5 个工作流入口、自然语言路由和“测试全绿但含需求外行为”的审查回归，共 28 项。`--list` 只列清单；显式 `--case` 或 `--all` 使用当前 Pi provider/model，thinking 为 off，并在每项独立的临时项目中加载生产扩展。认证副本只用于 provider 请求，项目文件工具无法读取；固定验收在 macOS sandbox 中执行，模型不能修改验收文件。产物检查、需要人回答的问题、失败和未运行项分别记录，不以进程正常退出作为成功证据。有待回答问题时，总体状态保持 `awaiting_user`，预期的 pending 验收仍以退出码 0 表示。外部 provider 不可用时停止，不自动更换模型。
+
 ## 与上游纯 skills方案的差异
 
 | 维度 | `mattpocock/skills` | `pi-matt-pocock` |
@@ -199,7 +211,7 @@ node packages/matt-pocock/scripts/check-upstream-sync.mjs --upstream /path/to/ma
 
 工作流进行决策访谈（如 `grilling`、`domain-modeling`）时，通过 `matt_pocock_ask` 工具向用户发起选项选择或自定义输入。默认情况下，使用 Pi 终端内置的 TUI 界面（`ctx.ui.select` / `ctx.ui.input`）。
 
-用户可在 `~/.pi/agent/pi-matt-pocock.json` 中配置是否在本地 macOS 环境下启用系统原生弹窗：
+用户可在 Pi 的 agent 目录下的 `matt-pocock.json` 中配置是否在本地 macOS 环境下启用系统原生弹窗（默认 `~/.pi/agent/matt-pocock.json`；若设置了 `PI_CODING_AGENT_DIR`，则使用该目录）：
 
 ```json
 {
@@ -213,4 +225,10 @@ node packages/matt-pocock/scripts/check-upstream-sync.mjs --upstream /path/to/ma
 - **原生交互体验**：
   1. **列表单选**：调用系统原生 `choose from list` 弹窗展示选项，支持上下键移动、回车选择；
   2. **自定义输入**：当用户选择“输入自定义回答...”时，自动唤起原生文本输入窗口（`display dialog` 带输入框），供用户直接打字；
-  3. **推荐超时自动采纳**：在指定时间内未选择且包含推荐选项时，自动关闭弹窗并采纳推荐选项继续推进。
+  3. **推荐超时自动采纳**：`recommended` 为必填且必须属于候选项；每次提问都装填一个有界截止时间（默认 60 秒，上限 3600 秒），截止到达后同时关闭选择列表和自定义输入并采纳推荐选项，提问不会无限等待。仅实际达到截止时间后才采纳，取消、工具中断或流程切换均保持待定。需要授权的操作应把推荐设为不执行该操作的安全选项，因为截止时间会采纳它。
+
+原生对话框仅在配置 `useNativeDialog: true`（布尔值）时启用。取消信号会关闭 TUI 或终止并回收 osascript 子进程；进程启动、退出或解析失败会回退到 TUI。Catalog 在注册工具前校验别名冲突、重复路由位置和 requires 环；加载 reference 前校验累计上下文的 64 KiB 限额，失败不写入部分状态。独立能力在内存中保存当前披露链，可继续加载 reference 披露的下级资料，不创建持久流程状态；重启能力或跨会话上下文时清空。
+
+开发者完整任务另见 `tests/developer-journey-cases.json`：折扣需求到审查交接、异步缓存故障修复、配置解析的设计/清理/审查/交接，使用真实模型连续多轮调用。运行 `tests/real_model_live.py --cases packages/matt-pocock/tests/developer-journey-cases.json --all --deadline 420 --output /tmp/matt-developer-journeys.json`。独立验收验证公共行为；审查中的因果解释和清理结论另需阅读实际产物验证，不能把测试通过等同于报告正确。
+
+完整任务以实际进入指定阶段及单一工作项身份为验收条件，跨轮次等待 `agent_settled` 后继续；缓存测试覆盖失败前成功缓存和独立的加载中键。这三个任务显式设置最多 80 次工具调用，普通矩阵默认仍为 40 次，预算耗尽后后续轮次也不能绕过。

package/README.md

@@ -38,7 +38,17 @@ Tools are progressively exposed based on active session state:
    - `action: "cancel"`: Cancel the active workflow with an explicit reason.
 3. **Active-only tool**: `matt_pocock_ask`
    - Prompt the user for structured, genuinely user-owned decisions with selectable options.
-   - Supports recommended choices, automatic timeout adoption, and custom text input.
+   - Requires a recommended choice and adopts it when the deadline elapses; supports custom text input. One deadline governs the ask and dismisses both the selector and the custom-answer input; elapsed clock readings alone never imply a timeout. Escape, cancellation, abort, no UI, and a blank custom answer leave the decision pending. Recommendations must match an offered option, so an approval-required action recommends the option that does not act.
+
+## Pi v1.0 runtime boundaries
+
+This extension targets Pi v1.0 (`@earendil-works/pi-*`). Each extension instance owns its workflow state. Session start, tree navigation, and context compaction silently restore the active branch's complete procedure context; subsequent transitions deliver only new bodies. Malformed or incompatible newest records disable workflow-only tools rather than resurrecting older work. Restored phases must match the catalog placement.
+
+Workflow changes and session boundaries dismiss pending questions and menus. A late selection cannot act on a replacement work item. Invalid arguments to `status` or `complete` report usage without cancelling the active work.
+
+Standalone reference loading remembers the current capability's disclosure chain in memory, so a reference can disclose further references without creating workflow state. This chain resets when the capability restarts or the session context changes. Standalone procedures ask decisions in conversation rather than relying on workflow-only tools.
+
+The catalog is validated before tools are registered, including alias conflicts, duplicate route placements, and required dependency cycles. A cumulative reference bundle is validated against the 64 KiB limit before state is persisted. Dialog cancellation propagates to Pi UI and native subprocesses; native process failures fall back to Pi UI.
 
 ## Workflow Routes & Graph Topology
 
@@ -106,8 +116,11 @@ The following curated capabilities are reachable via `matt_pocock_workflow` (`mo
 - **`deslop`**: Eliminating AI code smell patterns while keeping interfaces and tests green.
 - **`wizard`**: Generating interactive human-in-the-loop shell wizards.
 - **`grilling`**: Relentlessly interviewing requirements one question at a time.
-- **`domain-modeling`**: Clarifying ubiquitous domain language and CONTEXT.md.
+- **`domain-modeling`**: Clarifying ubiquitous domain language and GLOSSARY.md.
 - **`tdd`**: Running the BDD-driven red-green automation loop.
+- **`pr`**: Writing a concise PR body with evidence and merge risk.
+
+User-invoked capabilities also appear in the command menu. `/matt-pocock retro` reviews a session and proposes improvements to the agent environment. The upstream glossary rename retains `CONTEXT-FORMAT` as an alias of `GLOSSARY-FORMAT`, so existing workflow records can still restore. `resolving-merge-conflicts` remains a local compatibility capability after its removal upstream.
 
 ## Lifecycle Display Lines
 
@@ -156,13 +169,13 @@ Supported titles by route (not a mandatory execution order):
 | `hard-bug` | Reproducing & Diagnostics; Implementation; Code Review |
 | `architecture` | Architecture Survey; Architecture Design; Implementation; Code Review |
 
-Route and phase ids remain unchanged in tool arguments, model guidance, result details, and persisted state. Expanding a workflow-start row shows only a distinct `route · <Readable Route Title>` (for example, `route · Hard Bug Diagnosis`), using `readableRouteTitle()`. When the route title equals the phase title, as at the Task Triage entry, that field is omitted too. It does not repeat the phase id or expose procedure bodies.
+Route and phase ids remain unchanged in tool arguments, model guidance, result details, and persisted state. A workflow-start row shows the readable phase title only. The row does not repeat the route id or its title, and it does not expose procedure bodies.
 
-Expansion shows information not already visible in the row:
+No Matt Pocock row hides a field body behind expansion. Every row shows its facts in the collapsed transcript:
 
 - Transitions, completion, and reference loads omit repetitive `action` fields; standalone capability and reference rows do not repeat their subjects as fields. When the title fits, these rows have no expand hint or extra detail body.
-- Cancellation expands to `reason · <stored reason>` only when that result's terminal snapshot has a nonblank reason. The reason appears once, never as `action · cancel`, and is not taken from the current workflow. Missing, empty, or whitespace-only reasons add no detail or hint.
-- At narrower widths, Pi-kit's shared renderer can offer expansion to wrap a clipped title or summary with Pi's native wrapping. Model-only content and metadata do not themselves create an expand hint.
+- A cancellation row carries `reason · <stored reason>` inline when that result's terminal snapshot has a nonblank reason. The reason appears once, never as `action · cancel`, and it does not come from the current workflow. A missing, empty, or whitespace-only reason adds no body line.
+- At narrower widths, Pi-kit's shared renderer can offer expansion to wrap a clipped title or body line with Pi's native wrapping. Model-only content does not itself create an expand hint.
 
 The `matt-pocock-procedure` message renderer owns that block layout. A `/matt-pocock` route or capability start (including a freeform routing request and the menu's "Start a task") delivers the procedure through this displayed message instead of posting the procedure text as a user message, while the model still receives the complete body plus any `User target/request:` section. Session restoration reinjects guidance silently (`display: false`), without a duplicate lifecycle event. Saved active-tool results with old route-based subjects are rendered from their recorded phase and action, not the session's current workflow; no session-data migration is needed.
 
@@ -170,17 +183,61 @@ The `matt-pocock-procedure` message renderer owns that block layout. A `/matt-po
 
 These operations keep their own subjects rather than substituting a workflow phase:
 
-- **Reference loading (`load`)**: `[matt pocock] event · loaded <reference>` (e.g. `[matt pocock] event · loaded HTML-REPORT`).
-- **Standalone capability**: `[matt pocock] started · <capability>` (e.g. `[matt pocock] started · research`).
+- **Reference loading (`load`)**: `[matt pocock] event · loaded <reference>` (e.g. `[matt pocock] event · loaded HTML Report`).
+- **Standalone capability**: `[matt pocock] started · <capability>` (e.g. `[matt pocock] started · Diagnosing Bugs`).
 - **Standalone reference**: `[matt pocock] started · <capability> · <reference>`.
-- **`matt_pocock_ask`**: `[matt pocock] ask · <question>`, with the answer or pending status below. Timeout, no-UI, and custom-input metadata remain available on expansion without repeating the answer.
+- **`matt_pocock_ask`**: `[matt pocock] ask · <question>`, with the answer or pending status below. The model-facing result includes the full question followed by the chosen answer as a block quote (`> <answer>`); `(Recommended)` is only a choice label and is omitted from the answer. Timeout, no-UI, and custom-input metadata appear as inline body lines below the answer, which is never repeated.
 - **Fallback**: `[matt pocock] event · workflow updated` when no action or subject is available.
 
-For offline verification in the real Pi CLI, run `uv run --no-project packages/matt-pocock/tests/live_smoke.py` from the repository root. It checks print mode, interactive terminal rows, Ctrl+O expansion, resizing to 48 columns, and `/matt-pocock hard-bug fix the login redirect` delivering one block row on the user-message band, with a scripted provider and temporary home; it does not use your credentials or call an external model.
+Capability and reference names use readable catalog labels consistently. Transition-menu choices use their destination phase titles, matching lifecycle rows. Command identifiers and saved resource ids remain unchanged; user-supplied tasks are displayed verbatim.
+
+Run the actual Pi checks from the repository root:
+
+```bash
+uv run --no-project packages/matt-pocock/tests/live/live_smoke.py
+uv run --no-project packages/matt-pocock/tests/live/runtime_live.py
+uv run --no-project packages/matt-pocock/tests/live/restore_live.py
+uv run --no-project packages/matt-pocock/tests/live/decision_live.py
+uv run --no-project packages/matt-pocock/tests/live/active_menu_live.py
+uv run --no-project packages/matt-pocock/tests/live/abort_live.py
+uv run --no-project packages/matt-pocock/tests/live/adversarial_live.py
+node --import tsx/esm packages/matt-pocock/tests/live/native_real_smoke.ts
+```
+
+The lifecycle check covers print mode, terminal rows, timeout and Escape, Ctrl+O, 48-column resizing, and the user-message band. The catalog matrix derives routes, legal transitions and standalone capabilities from the manifest and exercises them through Pi's agent loop, including persistence, restart, native tree navigation and native compaction. The compaction probe supplies a deterministic summary through `session_before_compact`; Pi still performs compaction and session persistence. Restored procedure sources are checked in the next model context.
+
+The restart boundary check also covers completed/cancelled latest records, incompatible versions, and invalid phase/reference/procedure records, with older active records still present. It verifies inactive tools and guidance, and cancellation records for invalid active state.
+
+The adversarial check opens real Pi selectors and menus, then injects deterministic state changes through the registered handlers. It verifies immediate dismissal, replacement work-item identity, and reference-only loading before and after a user command. Package tests additionally derive resource/alias/disclosure/transition cases from the catalog and test exact UTF-8 size boundaries in disposable package copies.
+
+Repository verification details and reproduced failures are recorded in [the adversarial verification report](tests/reports/ADVERSARIAL-VERIFICATION.md).
+
+The decision and active-menu checks send actual keyboard input through Pi's terminal UI. They cover option/custom input, cancellation, timeout, View, Transition, Cancel and Complete. The abort check interrupts a live selector with an AbortSignal. These Pi checks use an isolated home, allowlisted process settings and a deterministic local provider; they do not inherit provider credentials or validate external-model decisions or downstream project work performed by a procedure.
+
+The decision check deliberately fails a simulated native subprocess to exercise TUI fallback. On macOS, the separate native smoke uses the real `osascript` to verify list/input/prompt timeout and list abort, including process exit. It does not automate native button selection or verify physical rendering. Package tests also typecheck every TypeScript test fixture and verify package-local Pi v1.0 dependency resolution.
+
+The separate real-model matrix covers all 21 standalone capabilities, five workflow entries, natural-language routing, and a review regression where passing tests coexist with unrequested behavior (28 cases). Listing it does not read credentials or start Pi:
+
+```bash
+uv run --no-project packages/matt-pocock/tests/real_model_live.py --list
+uv run --no-project packages/matt-pocock/tests/real_model_live.py --case cap-pr --output /tmp/matt-real-pr.json
+uv run --no-project packages/matt-pocock/tests/real_model_live.py --all --output /tmp/matt-real-matrix.json
+```
+
+`--case` and `--all` call the configured real provider and model, with thinking off. Each case uses a disposable project and agent directory; authentication files are copied with private permissions and deleted afterward. The production extension runs through native Pi RPC. File tools stay inside the project, fixed tests run in a macOS sandbox, and the verifier cannot be modified. Results distinguish verified artifacts, questions awaiting an answer, failures, and skipped cases. If any question is pending, the aggregate remains `awaiting_user`; an expected pending result has exit code 0. A provider failure stops the matrix instead of switching models. These runs are deliberately separate from the credential-free package test suite.
+
+Three multi-turn developer journeys additionally cover an agreed discount feature through review and handoff, async cache incident repair, and configuration cleanup through design, de-slop, review and handoff. Their fixed acceptance tests verify public behavior and independent cache keys; review notes are also inspected for unsupported causal claims and misleading verdicts. Workflow journeys require the actual requested stages and one work item. The harness waits for Pi agent settlement between turns. These longer journeys explicitly allow up to 80 tool calls; the ordinary matrix retains its default 40-call budget, and exhaustion blocks later turns too.
+
+```bash
+uv run --no-project packages/matt-pocock/tests/real_model_live.py --cases packages/matt-pocock/tests/developer-journey-cases.json --list
+uv run --no-project packages/matt-pocock/tests/real_model_live.py --cases packages/matt-pocock/tests/developer-journey-cases.json --all --deadline 420 --output /tmp/matt-developer-journeys.json
+```
+
+The developer journey evidence and observed limitations are documented in [DEVELOPER-JOURNEYS.md](tests/reports/DEVELOPER-JOURNEYS.md).
 
 ## Configuration
 
-You can optionally configure native macOS dialog prompts for `matt_pocock_ask` via `~/.pi/agent/pi-matt-pocock.json`:
+You can optionally configure native macOS dialog prompts for `matt_pocock_ask` via `matt-pocock.json` in Pi's agent directory (`~/.pi/agent/matt-pocock.json`, or `$PI_CODING_AGENT_DIR/matt-pocock.json` when that variable is set):
 
 ```json
 {
@@ -188,10 +245,20 @@ You can optionally configure native macOS dialog prompts for `matt_pocock_ask` v
 }
 ```
 
-By default (`useNativeDialog: false` or missing file), Pi uses its built-in TUI selection dialog. Native dialogs are automatically guarded to only trigger on local macOS GUI sessions (SSH sessions, non-macOS platforms, and CI environments always fall back cleanly to terminal TUI).
+Only the boolean `true` enables native dialogs; strings and numbers keep them disabled. By default (`useNativeDialog: false` or missing file), Pi uses its built-in TUI selection dialog. Native dialogs are automatically guarded to only trigger on local macOS GUI sessions (SSH sessions, non-macOS platforms, and CI environments always fall back cleanly to terminal TUI).
 
-See the detailed [中文架构说明](ARCHITECTURE.zh-CN.md), the upstream [selection metadata](upstream-selection.json) and [sync rules](UPSTREAM.md), and the deliberately deferred items in [TODO.md](TODO.md).
+See the detailed [中文架构说明](ARCHITECTURE.zh-CN.md), the upstream [selection metadata](upstream/upstream-selection.json) and [sync rules](upstream/UPSTREAM.md), and the deliberately deferred items in [TODO.md](TODO.md).
 
 ## License
 
 MIT
+
+Eight additional developer fixtures cover generated frontend HTML, API request boundaries, authorization, versioned migration, operation-count performance, localization, lexical paths and behavioral test design. Together with the earlier journeys, these cover eleven developer task categories. The catalog-derived inventory checks every supported standalone capability and route; JSON boundary checks cover all JSON value classes.
+
+```bash
+uv run --no-project packages/matt-pocock/tests/type_inventory.py
+uv run --no-project packages/matt-pocock/tests/real_model_live.py --cases packages/matt-pocock/tests/expanded-type-cases.json --list
+uv run --no-project packages/matt-pocock/tests/real_model_live.py --cases packages/matt-pocock/tests/expanded-type-cases.json --all --deadline 300 --output /tmp/matt-expanded-types.json
+```
+
+The real-model verifier returns bounded redacted diagnostics and requires an immutable acceptance completion marker, so an early successful process exit cannot silently skip acceptance. See [TEST-TYPES.md](tests/reports/TEST-TYPES.md) for the coverage inventory, actual attempts and limitations. These checks do not establish browser assistive-technology behavior, deployed services, physical input or every possible software task.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-matt-pocock",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "BDD-first engineering and productivity skills adapted from Matt Pocock's skills",
   "keywords": [
@@ -25,13 +25,13 @@
     "index.ts",
     "src",
     "procedures",
+    "references",
+    "assets",
+    "upstream",
     "TODO.md",
     "LICENSE",
     "README.md",
-    "ARCHITECTURE.zh-CN.md",
-    "UPSTREAM.md",
-    "upstream-selection.json",
-    "scripts"
+    "ARCHITECTURE.zh-CN.md"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
@@ -39,11 +39,16 @@
     "typebox": "*"
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.5.1"
+    "@fradser/pi-kit": "0.6.0"
   },
   "pi": {
     "extensions": [
       "./index.ts"
     ]
+  },
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^1.2.0",
+    "@earendil-works/pi-coding-agent": "^1.2.0",
+    "@earendil-works/pi-tui": "^1.2.0"
   }
-}
+}

package/procedures/code-review.md

@@ -1,9 +1,9 @@
 Two-axis review of a task-scoped candidate against an explicit baseline:
 
-- **Standards** — does the code conform to this repo's documented coding standards?
-- **Spec** — does the code faithfully implement the originating issue / PRD / spec? If the spec contains Gherkin scenarios (from [bdd](bdd.md)), those are the authoritative acceptance criteria.
+- **Standards**: does the code conform to this repo's documented coding standards?
+- **Spec** — does the code faithfully implement the originating issue / PRD / spec? If the spec contains Gherkin scenarios (from [bdd](../references/bdd.md)), those are the authoritative acceptance criteria.
 
-For a bounded change, one fresh reviewer can assess both axes and return separate verdicts. Use separate reviewers only when scale, distinct expertise, or repository policy justifies them. Without delegation, assess Standards then Spec and preserve the reports separately. Agent count is not evidence of independence or quality.
+For a bounded change, one fresh reviewer can assess both axes and return separate verdicts. Use separate reviewers only when scale, distinct expertise, or repository policy justifies them. Start each delegated reviewer with a fresh context window, not inherited parent history. Without delegation, assess Standards then Spec and preserve the reports separately. Agent count is not evidence of independence or quality.
 
 Use the confirmed requirements already available; an issue tracker is optional. Read repository issue-tracker guidance only when the spec actually lives there. Missing tracker setup is not a reason to start setup work for a local review.
 
@@ -35,18 +35,18 @@ On top of whatever the repo documents, the Standards axis always carries the **s
 
 Each smell reads *what it is* → *how to fix*; match it against the diff:
 
-- **Mysterious Name** — a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
-- **Duplicated Code** — the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
-- **Feature Envy** — a method that reaches into another object's data more than its own. → move the method onto the data it envies.
-- **Data Clumps** — the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
-- **Primitive Obsession** — a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
-- **Repeated Switches** — the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
-- **Shotgun Surgery** — one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
-- **Divergent Change** — one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
-- **Speculative Generality** — abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
-- **Message Chains** — long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
-- **Middle Man** — a class or function that mostly just delegates onward. → cut it, call the real target direct.
-- **Refused Bequest** — a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
+- **Mysterious Name**: a function, variable, or type whose name doesn't reveal what it does or holds. → rename it; if no honest name comes, the design's murky.
+- **Duplicated Code**: the same logic shape appears in more than one hunk or file in the change. → extract the shared shape, call it from both.
+- **Feature Envy**: a method that reaches into another object's data more than its own. → move the method onto the data it envies.
+- **Data Clumps**: the same few fields or params keep travelling together (a type wanting to be born). → bundle them into one type, pass that.
+- **Primitive Obsession**: a primitive or string standing in for a domain concept that deserves its own type. → give the concept its own small type.
+- **Repeated Switches**: the same `switch`/`if`-cascade on the same type recurs across the change. → replace with polymorphism, or one map both sites share.
+- **Shotgun Surgery**: one logical change forces scattered edits across many files in the diff. → gather what changes together into one module.
+- **Divergent Change**: one file or module is edited for several unrelated reasons. → split so each module changes for one reason.
+- **Speculative Generality**: abstraction, parameters, or hooks added for needs the spec doesn't have. → delete it; inline back until a real need shows.
+- **Message Chains**: long `a.b().c().d()` navigation the caller shouldn't depend on. → hide the walk behind one method on the first object.
+- **Middle Man**: a class or function that mostly just delegates onward. → cut it, call the real target direct.
+- **Refused Bequest**: a subclass or implementer that ignores or overrides most of what it inherits. → drop the inheritance, use composition.
 
 ### AI slop baseline
 
@@ -76,13 +76,21 @@ Give the reviewer both briefs for bounded work, or one brief per reviewer when s
 - The spec or confirmed conversation requirements and scenarios.
 - The brief: "Report: (a) Gherkin scenarios (Given/When/Then) in the spec that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. If the spec contains Gherkin scenarios, those are the authoritative acceptance criteria. Quote the spec line for each finding. Under 400 words."
 
+Unconfirmed scope creep is a Spec finding; non-breaking behavior requires an explicit compatibility requirement before Spec PASS.
+
 If the spec is missing, skip the Spec review and note this in the final report.
 
+### Evidence for causal claims
+
+Before calling a concurrency guard load-bearing, show a reachable interleaving using the actual public API: which operation replaces or deletes the entry, when each callback runs, and how the guard changes the observable result. A hypothetical future invalidation or replacement operation is not evidence about this candidate. If no such operation exists, describe the guard as redundant or a deliberate readability preference, not as a verified race fix. Apply the same standard to other causal claims: distinguish an observed failure, a source-supported possibility, and an untested hypothesis. Green tests alone do not prove the explanation.
+
+A judgement call changes confidence, not the verdict: once the report identifies an unresolved smell, Standards is REWORK even if no lint rule prohibits it. If current evidence shows the candidate is not a smell, explain that refutation and remove it from the findings; naming it a deliberate preference or a safeguard for a hypothetical future API does not resolve it. Do not let a necessary rejection handler justify a separate redundant identity guard by association.
+
 ### 5. Aggregate
 
 Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see _Why two axes_).
 
-End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent.
+End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes: that's the reranking the separation exists to prevent.
 
 ### 5.3 Owner remediation and recheck handoff
 
@@ -107,7 +115,7 @@ In step 5.5's Standards scoring, treat a read memory file as a red flag: if the
 After presenting the two reports, emit a binary verdict per axis:
 
 - **Standards axis**: binary PASS (no unresolved standard violations or smells in the Standards report) / REWORK (any standard violation or listed smell).
-- **Spec axis**: binary PASS (all Gherkin scenarios in the spec demonstrably implemented) / REWORK (any scenario missing/partial/wrong).
+- **Spec axis**: PASS requires every scenario, no unresolved scope creep, and no wrong implementation; otherwise REWORK. Non-breaking fallback requires an explicit compatibility requirement.
 
 **Refute-before-PASS (red-team protocol):** Before assigning PASS to either axis, attempt to refute your own PASS:
 

package/procedures/codebase-design.md

@@ -4,19 +4,19 @@ Design **deep modules**: a lot of behaviour behind a small interface, placed at
 
 ## Glossary
 
-Use these terms exactly — don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
+Use these terms exactly: don't substitute "component," "service," "API," or "boundary." Consistent language is the whole point.
 
-**Module** — anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
+**Module**: anything with an interface and an implementation. Deliberately scale-agnostic: a function, class, package, or tier-spanning slice. _Avoid_: unit, component, service.
 
-**Interface** — everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow — they refer only to the type-level surface).
+**Interface**: everything a caller must know to use the module correctly: the type signature, but also invariants, ordering constraints, error modes, required configuration, and performance characteristics. _Avoid_: API, signature (too narrow, they refer only to the type-level surface).
 
-**Implementation** — what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
+**Implementation**: what's inside a module, its body of code. Distinct from **Adapter**: a thing can be a small adapter with a large implementation (a Postgres repo) or a large adapter with a small implementation (an in-memory fake). Reach for "adapter" when the seam is the topic; "implementation" otherwise.
 
 **Depth** — leverage at the interface: the amount of behaviour a caller (or test) can exercise per unit of interface they have to learn. A module is **deep** when a large amount of behaviour sits behind a small interface, **shallow** when the interface is nearly as complex as the implementation.
 
-**Seam** _(Michael Feathers)_ — a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
+**Seam** _(Michael Feathers)_: a place where you can alter behaviour without editing in that place; the *location* at which a module's interface lives. Where to put the seam is its own design decision, distinct from what goes behind it. _Avoid_: boundary (overloaded with DDD's bounded context).
 
-**Adapter** — a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
+**Adapter**: a concrete thing that satisfies an interface at a seam. Describes *role* (what slot it fills), not substance (what's inside).
 
 **Leverage** — what callers get from depth: more capability per unit of interface they learn. One implementation pays back across N call sites and M tests.
 
@@ -58,7 +58,8 @@ When designing an interface, ask:
 
 ## Principles
 
-- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts — they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
+- **Separate sourced requirements from proposed invariants.** Attribute only verified requirements to a spec. Label unsupported constraints, error modes, and business policies as assumptions or unresolved decisions; a proposed interface does not turn them into existing requirements.
+- **Depth is a property of the interface, not the implementation.** A deep module can be internally composed of small, mockable, swappable parts; they just aren't part of the interface. A module can have **internal seams** (private to its implementation, used by its own tests) as well as the **external seam** at its interface.
 - **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If complexity reappears across N callers, it was earning its keep.
 - **The interface is the test surface.** Callers and tests cross the same seam. If you want to test *past* the interface, the module is probably the wrong shape.
 - **One adapter means a hypothetical seam. Two adapters means a real one.** Don't introduce a seam unless something actually varies across it.
@@ -104,10 +105,10 @@ Good interfaces make testing natural:
 ## Rejected framings
 
 - **Depth as ratio of implementation-lines to interface-lines** (Ousterhout): rewards padding the implementation. We use depth-as-leverage instead.
-- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow — interface here includes every fact a caller must know.
+- **"Interface" as the TypeScript `interface` keyword or a class's public methods**: too narrow: interface here includes every fact a caller must know.
 - **"Boundary"**: overloaded with DDD's bounded context. Say **seam** or **interface**.
 
 ## Going deeper
 
-- **Deepening a cluster given its dependencies** — see [DEEPENING.md](DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
-- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](DESIGN-IT-TWICE.md): use teammates when the teammate facility is available, otherwise develop several designs sequentially, then compare depth, locality, and seam placement.
+- **Deepening a cluster given its dependencies**, see [DEEPENING.md](../references/DEEPENING.md): dependency categories, seam discipline, and replace-don't-layer testing.
+- **Exploring alternative interfaces** — see [DESIGN-IT-TWICE.md](../references/DESIGN-IT-TWICE.md): use teammates when the teammate facility is available, otherwise develop several designs sequentially, then compare depth, locality, and seam placement.

package/procedures/deslop.md

@@ -31,6 +31,8 @@ Resolve the change set before touching anything:
 
 ### 2. Inventory findings
 
+For a compound guard, justify each predicate separately by tracing the exact expression and conversion order on a concrete input. A failure rejected by another predicate does not prove this one necessary. If no distinguishing input is established, record the claimed necessity as unverified rather than converting a redundant check into a proven requirement. Removing a proven inert predicate preserves the accepted grammar and does not require changing the spec or obtaining a new product decision. Reconcile cleanup, review and handoff verdicts against the final candidate after remediation.
+
 Scan the scope once per category. Produce a findings list: category, location (file plus hunk), the offending line quoted, and the replacement plan. A finding without a concrete replacement plan is not ready to fix — leave it as a reported finding.
 
 ### 3. Rewrite
@@ -43,7 +45,7 @@ Apply the plans in one pass, category by category. For each rewrite:
 
 ### 4. Verify
 
-Run the verification the repository already uses — tests, typecheck, and lint. A de-slop pass ends green or it has not ended.
+Run the verification the repository already uses — tests, typecheck, and lint. A de-slop pass ends green or it has not ended. Record each actually failed command and its observed result separately from reasoning about an unexecuted alternative. Do not describe a rejected design, source inspection or hypothetical regression as a test failure unless that candidate was executed and failed. Label untested conclusions and preserve the real verification sequence in cleanup and handoff notes. Reconcile the summary, findings, verdict and handoff against that sequence before finishing; remove contradictory counts or claims about failed attempts.
 
 ### 5. Verdict
 
@@ -53,4 +55,4 @@ Report under three headings:
 - **Findings** — slop that could not be removed without a behavior change, test coverage, or a design decision, each with the reason.
 - **Skipped** — categories skipped because repository tooling already enforces them.
 
-End with a binary verdict: **CLEAN** only if every planned rewrite landed and verification is green; **PARTIAL** when findings remain. Never report CLEAN with unverified skips.
+End with a binary verdict: **CLEAN** only if every planned rewrite landed, verification is green, and no findings remain; **PARTIAL** when findings remain. A retained finding cannot be made CLEAN by excluding it from the rewrite plan. A readability preference is not a behavioral compatibility requirement: if a known redundant check is kept only to document intent, state that reason honestly and keep the finding in the PARTIAL verdict. Proven necessary guards are not clutter; explain their current requirement rather than listing them as unresolved findings. Never report CLEAN with unverified skips.