pi-matt-pocock 0.1.1 → 0.2.0

package/ARCHITECTURE.zh-CN.md

@@ -1,80 +1,216 @@
 # pi-matt-pocock 架构说明
 
-`pi-matt-pocock` 将 [mattpocock/skills](https://github.com/mattpocock/skills) 中适合工程协作的内容，适配为 Pi 内部的**持久化工作流编排器**。它不是把每一份上游 `SKILL.md` 原样公开为一个 Pi skill。
+`pi-matt-pocock` 将 [mattpocock/skills](https://github.com/mattpocock/skills) 中选定的工程方法适配为 Pi 的**目录驱动能力网关**。它不是上游仓库的完整镜像，也不把每份上游 `SKILL.md` 注册为 Pi skill。
 
-术语对照：
+## 核心模型：procedureCatalog manifest
 
-- **workflow harness（工作流编排器）**：负责选择、保存、恢复并推进工程流程的扩展。
-- **route（路线）**：一个大类工程流程，例如 `hard-bug` 或 `idea-to-ship`。
-- **procedure（流程步骤）**：路线内当前正在执行的具体 Markdown 指引，例如 `diagnosing-bugs`、`to-spec` 或 `code-review`。
-- **phase（阶段）**：当前流程步骤所处的可读阶段。
+`src/catalog.json` 中的 `procedureCatalog` manifest 是能力与资源关系的单一事实来源，`src/catalog.ts` 提供类型化查询与校验。命令菜单、模型可见能力、工作流入口、route 标题与说明、阶段、别名、依赖、引用披露、合法迁移和完整性检查都从目录派生，而不是分别维护 route/procedure 巨型枚举。
 
-## 对用户暴露的入口
+目录中的资源分为四类：
 
-包只提供一个管理命令和一个主要编排 tool：
+- **workflow（工作流 procedure）**：可位于一个或多个持久化 route 中；部分也可作为 standalone capability 运行。
+- **standalone capability（独立能力）**：目录中标记 `standalone` 的 workflow 或 utility，可一次性运行，不创建持久化工作流状态。
+- **reference（参考资料）**：只在当前 procedure 或已加载 reference 明确披露后可访问。
+- **asset（资产）**：procedure 使用的脚本或模板，不作为公共能力入口。
 
-- `/matt-pocock`：打开路线菜单、查看状态、手动切换或结束工作流。
-- `matt_pocock_workflow`：模型启动或切换工程工作流时调用。
-- `matt_pocock_ask`：仅在工作流激活期间启用，用于需要用户作出的结构化选择。
+每条目录记录还声明调用模式：`model`、`user` 或 `internal`。模型基线网关只枚举 `model` 且可独立运行的能力；`/matt-pocock` 菜单可展示全部 standalone capability。内部 reference 与 asset 不会成为顶层菜单项或全局 skill。
 
-当前支持五条 route：
+## 单一用户入口与渐进式 tool
 
-| Route | 适用场景 |
+包只有一个命令入口 `/matt-pocock`。同一菜单同时提供：
+
+- 启动五类持久化工作流：`idea-to-ship`、`hard-bug`、`triage`、`wayfinding`、`architecture`；
+- 运行目录中的 standalone capabilities；
+- 查看、迁移、完成或取消当前工作流。
+
+模型侧始终保留一个基线网关：
+
+- `matt_pocock_workflow`
+  - `mode: workflow`：根据 route 启动目录定义的入口 procedure；
+  - `mode: capability`：运行一个模型可达的 standalone capability；
+  - `mode: reference`：加载该 standalone capability 已披露的 reference。
+
+工作流成功启动或恢复后，扩展通过 `pi.setActiveTools()` 渐进启用：
+
+- `matt_pocock_active`：迁移 procedure、加载可访问 reference、完成或取消工作流；
+- `matt_pocock_ask`：通过 Pi 选择 UI 处理真正由用户拥有的结构化决策。
+
+工作流完成、取消或恢复校验失败后，这两个 active-only tool 会被移除。这样基线 schema 不再列出所有 route 与 procedure 的组合，也不会让无活动状态的会话携带迁移、完成和访谈操作。
+
+## 工作流状态与生命周期
+
+启动 route 时，`src/workflow.ts` 从目录查找唯一入口，并创建如下持久化状态：
+
+```text
+version / workItemId / route / procedure / phase / status / loadedReferences
+```
+
+- `workItemId` 是每次工作流启动时生成的稳定 UUID，用于区分独立工作项。
+- 活动记录的 `status` 为 `active`。
+- 结束记录保留同一 `workItemId`，`status` 为 `completed` 或 `cancelled`；取消记录可包含原因。
+- 状态通过 `pi.appendEntry` 写入 session branch。重启时只恢复最新的有效 `active` 记录；最新记录已结束时不会恢复旧活动状态。
+- 恢复前会重新验证 route、procedure 与资源 bundle。无效的陈旧状态会被明确记录为 `cancelled`，而不是静默回退到 route 默认入口。
+
+工作流启动、恢复或迁移时会返回当前 procedure bundle。之后每个 agent turn 只追加紧凑 guidance，包含 `workItemId`、当前阶段、合法下一步、可加载 reference 与终止责任，不会把整个目录反复注入 system prompt。
+
+模型可以通过 `matt_pocock_active` 明确完成工作流；完成不再依赖用户进入菜单。用户仍可从同一 `/matt-pocock` 菜单迁移、完成或取消，作为显式控制入口。
+
+### 生命周期提示中的阶段标题
+
+工作流提示使用事件发生时的实际阶段标题，不使用 `hard-bug` 等 route 标识、route 标题，也不生成任务标题。展示复用 `src/workflow.ts` 的 `readablePhaseTitle()` 映射。例如，工作流经过诊断、实现和审查后结束：
+
+```text
+[matt pocock] started · Reproducing & Diagnostics
+[matt pocock] event · Implementation
+[matt pocock] event · Code Review
+[matt pocock] event · Code Review completed
+```
+
+如果在实现阶段取消，则显示 `[matt pocock] event · Implementation cancelled`。`completed` / `cancelled` 仍表示**整个工作流**结束；前面的标题仅说明结束时所在的阶段，可以是入口阶段，不假设已到达流程末尾。
+
+| Route | 可用阶段标题（不是强制执行顺序） |
 | --- | --- |
-| `idea-to-ship` | 从需求澄清、规格到任务、实现和评审的完整功能工作 |
-| `hard-bug` | 困难、间歇性或回归问题的诊断与修复 |
-| `triage` | 将原始请求或 issue 整理为可执行 brief |
-| `wayfinding` | 为大型、模糊的计划建立决策与实施路径 |
-| `architecture` | 调查并改善代码库架构 |
+| `idea-to-ship` | Shaping & Requirements；Research & Feasibility；Prototyping；Specification Design；Task Decomposition；Implementation；Code Review；Handoff & Summary |
+| `wayfinding` | Initiative Mapping；Research & Feasibility；Prototyping；Specification Design；Task Decomposition；Implementation；Code Review |
+| `triage` | Task Triage；Specification Design；Task Decomposition；Implementation；Code Review |
+| `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 正文。
 
-## 工作流如何运行
+展开仅补充当前提示尚未显示的信息：
+
+- 迁移、完成和参考资料加载不显示重复的 `action` 字段；独立能力和独立参考资料也不把标题再复制为字段。标题完整可见时，这些提示没有展开提示或额外正文。
+- 取消提示只在该结果保存的终止快照包含非空白原因时，展开显示一次 `reason · <stored reason>`，不显示 `action · cancel`，也不读取当前工作流的原因。缺失、空字符串或纯空白原因均不会新增详情或展开提示。
+- 窄终端中的标题或摘要被截断时，由 Pi-kit 共享渲染器提供展开，并使用 Pi 原生换行恢复完整文本；本包不自行计算宽度。仅供模型使用的正文与 metadata 不会触发展开提示。
+
+`matt-pocock-procedure` 消息渲染器负责这条块状提示。用户从 `/matt-pocock` 启动 route/独立能力、用自由文本触发路由、或在菜单里选 “Start a task” 时，procedure 都通过这条可见消息交付，而不是把正文当 user message 贴出：
 
 ```text
-复杂工程请求
-  → 判断是否需要结构化工作流
-  → 选择 route 和当前 procedure
-  → matt_pocock_workflow 加载该 procedure
-  → 将 route / procedure / phase 写入 Pi session
-  → 该步骤完成后切换至下一 procedure
+[matt pocock] started
+
+fix the login redirect
 ```
 
-调用 `matt_pocock_workflow` 后，扩展会校验 route 和 procedure，读取 `procedures/<procedure>.md`，并将当前 `{ route, procedure, phase }` 写入 Pi 的 custom session entry。会话重启时，扩展从同一 branch 的最后一个有效状态恢复当前步骤，因此不会依赖模型从长对话中猜测进度。
+head 单独成行，一个空行分隔，随后是用户自己的任务原文（未提供任务时用可读的阶段标题或能力 id）；整块使用 Pi 原生 user-message 底色（`userMessageBg`），逐行保留换行、过长自动换行，且不提供展开。模型侧仍收到完整正文和 `User target/request:` 段落。恢复会话时仅静默注入 guidance（`display: false`），不新增重复的启动行。旧工具结果即使保存了 route 风格的 subject，也根据该事件保存的 phase 和 action 重新渲染，不读取当前工作流的可变状态，无需迁移会话数据。
+
+独立能力、参考资料和提问保留各自的展示对象：`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，不读取用户凭证或调用外部模型。
+
+## 协作验证与完成门槛
+
+实现阶段由各执行者运行分配的安全局部检查，由一个集成负责人承担共享验证。验证前先确认 HOME、凭证和测试数据的隔离条件；本地命令不等于无生产访问。集成后记录候选版本或本次改动快照，评审与最终检查必须针对同一候选；纳入未跟踪的任务文件，排除原有脏改动和无关工作。后续修改使受影响的证据失效，只重跑适用检查，不要求每个 Agent 重复全仓验证。
 
-当前 procedure 的完整正文只会在**启动、切换或恢复**这个步骤时按需注入。后续 agent turn 只增加简短的阶段 guidance，例如当前应遵循哪个步骤、下一步明确时应自动推进、以及只有什么情况才应询问用户。它不会在每轮重新注入所有流程正文。
+评审仍分别给出 Standards 与 Spec 结论，但小范围改动可由一个全新上下文的 reviewer 完成两个维度；只有规模、专业分工或仓库规则需要时才拆成多个 reviewer。当前对话中已确认的需求与验收场景可作为本地未提交任务的 spec，不必为了评审创建 issue tracker 或提交。
 
-如果任务不属于复杂、多步骤的工程流程，就不应启动该工具；正常处理请求即可。不确定时宁可不进入工作流，也不应猜测一个 route 并加载无关 procedure。
+评审 Work 完成表示报告已交付，不等于实现 PASS。独立评审或限定 reviewer 任务返回报告即可结束，包括 REWORK；不擅自修改实现，也不等待问题被修复。Leader 或实现负责人负责按根因合并问题、补齐相邻场景及后续交付。
 
-## Q：为何不直接公开一堆 skills？更新是不是更麻烦？
+复核前先保存旧报告，并准备保留的基线、新候选指纹、修复差异、原发现与安全检查范围。Agent Teams 的 reopen 会清除旧 result，但不会更新 description；reopen reason 和 assign 也不会自动传递新的复核说明。仅当原 description 已指向“当前尝试的权威 brief”时，才先更新该 brief，再 reopen/assign，且复核期间保持内容稳定。原描述固定了旧候选或没有此引用时，用完整新描述创建范围受限的后续 Work，并通过 dependsOn 关联已完成评审。它是关联的定向复核，不是新一轮广泛评审；仅范围或风险明显变化才扩大评审。
 
-**A：主要收益是控制上下文、避免全局命名冲突，并获得可恢复的流程状态。**
+实现交付需等待所有必需结果返回、阻断问题解决且证据适用于最终候选，才调用 complete；仅剩待返回结果时保持工作流活动并让出当前回合。
 
-上游的纯 skills 方案会把多份 `SKILL.md` 作为可独立发现的能力。`tdd`、`research`、`implement` 和 `code-review` 之类的通用名称容易与用户已安装的其他 skill collection 冲突；它们也不天然记录“当前任务走到了哪一步”。
+这些约束属于指导文本，不是新增调度器或跨扩展的强制完成锁；不改变持久化格式，也不强依赖 Agent Teams。
 
-本包将 procedure 保留为包内普通 Markdown 资源，不含 `SKILL.md`，因此不会被 Pi 递归发现为全局 skills。编排器只在命中工作流后加载当前 procedure，并持久化流程状态。这样保留上游方法论的内容，同时让多阶段工程工作具有明确的进度、自动切换与重启恢复能力。
+## 合法迁移
 
-更新确实不是简单复制上游文件，但工作集中在一个明确的同步边界：选择需要的上游内容，将 `SKILL.md` 转为 `procedures/*.md`，删除宿主专属 frontmatter 和调用语法，并保留 Pi 的会话、UI、工具启停和工程约束。具体同步规则见 [UPSTREAM.md](UPSTREAM.md)。这是一层有意维护的适配，而不是对上游仓库的镜像。
+每个 workflow placement 在目录中声明 `allowedNext`。迁移时运行时会：
 
-## Q：只暴露一个 tool，但 schema 仍列出 procedure，真的节省上下文吗？
+1. 规范化 procedure id 与已知别名；
+2. 验证目标是否位于当前 `{ route, procedure }` 的 `allowedNext`；
+3. 验证目标确实属于同一 route；
+4. 更新 procedure 与 phase，并清空先前加载的 references；
+5. 解析新 bundle 后持久化状态。
 
-**A：不能把“只注册一个 tool”误说成 schema 成本为零。**
+不在集合内的迁移会失败并返回允许的候选项。运行时不会把非法目标替换成 route 默认 procedure，也不会用一个覆盖全部路线的 procedure enum 假装迁移有效。
 
-当前主 tool 的 `route` 固定为五个值；`procedure` 参数会列出该 route 下允许的流程步骤和已知别名。这样模型切换阶段时可受约束地选择有效步骤，扩展也能验证请求，而不是接受一个凭空编造的名称。
+## `requires` 与 `discloses`
 
-因此，schema 仍然有少量 route / procedure 枚举成本。不过它避免了每个独立 skill 各自的发现、描述和完整正文同时进入上下文。更重要的是，体积最大的 procedure 正文按需一次加载；正常后续轮次只保留状态和精简 guidance。
+目录用两种边表达不同的上下文语义：
 
-一个更激进的未来设计可以让路由层只返回 procedure 名，再由运行时查表加载正文，并在不确定时返回空结果而不猜测流程。但这会失去 schema 对阶段切换的即时约束，需要单独权衡可靠性与 token 成本。本包当前选择的是受限枚举加按需正文加载。
+- `requires`：执行根 procedure 必须同时加载的依赖。`src/resolver.ts` 递归解析依赖闭包、去重并检测环；这些正文与根 procedure 一起进入 bundle。
+- `discloses`：当前正文允许按需访问、但尚未加载的 reference 或辅助能力。网关只返回可用 id；模型需要时再通过 `matt_pocock_active` 或 standalone reference 模式加载。
 
-## 与 `mattpocock/skills` 纯 skills 方案的区别
+已加载 reference 也可以继续披露下一层 reference。运行时根据当前 procedure 与 `loadedReferences` 计算可达集合，拒绝目录图之外的任意文件请求。这既保留方法论所需的强依赖，也避免把所有可选资料一次性塞入上下文。
 
-| 维度 | 上游 `mattpocock/skills` | `pi-matt-pocock` |
+## 稳定来源标识与体积边界
+
+每个解析后的正文都包在独立来源块中：
+
+```text
+<procedure-source id="<catalog-id>" source="procedure/<catalog-id>">
+...
+</procedure-source>
+```
+
+`source:procedure/<id>` 不依赖本机安装路径，可供模型、日志与检查器稳定指代来源。根 procedure 与全部 `requires` 内容拼接后按 UTF-8 字节数计算；单个 bundle 上限为 64 KiB。超过上限会直接失败，不会截断正文或静默遗漏依赖。
+
+## 为什么没有子 `SKILL.md`
+
+上游以多份嵌套 `SKILL.md` 分发能力。Pi 会递归发现 skill root 下的这些文件，因此 `tdd`、`research`、`implement`、`code-review` 等通用名字可能与用户安装的其他集合冲突，也不天然表达工作项状态和合法阶段迁移。
+
+本包把选定内容保存为 `procedures/*.md`、reference Markdown 或 asset，并由 extension 目录解析。包内不含子 `SKILL.md`：
+
+- 名称不会进入全局 skill 命名空间；
+- workflow 与 standalone capability 共用同一个目录和网关；
+- reference 只能沿 `discloses` 边访问；
+- 持久化状态、渐进 tool 和终止语义由 Pi extension 统一管理。
+
+因此本包也不需要第二个公共 skill surface，或为每条工作流增加单独命令。
+
+## 上游选择与同步校验
+
+[`upstream-selection.json`](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。
+
+贡献者应运行：
+
+```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
+```
+
+需要核对上游 checkout 时再运行：
+
+```bash
+node packages/matt-pocock/scripts/check-upstream-sync.mjs --upstream /path/to/mattpocock-skills
+```
+
+## 与上游纯 skills方案的差异
+
+| 维度 | `mattpocock/skills` | `pi-matt-pocock` |
 | --- | --- | --- |
-| 分发形式 | 多份独立 `SKILL.md` | 一个 Pi extension 加包内 procedure Markdown |
-| 发现方式 | 每个 skill 都可独立发现 | 只有 `/matt-pocock`、主 workflow tool 和条件启用的问答 tool |
-| 通用名称 | 可能与其他集合的 `tdd`、`research`、`code-review` 冲突 | procedure 不注册为全局 skill，因此无同名冲突 |
-| 正文加载 | 各 skill 独立装载 | 命中 route 后按需加载当前 procedure |
-| 状态 | 通常由模型和对话自行维持 | `route / procedure / phase` 持久化在 Pi session 中 |
-| 重启后 | 需要从对话重新理解进度 | 恢复最后一个有效 workflow state 与当前 procedure |
-| 推进 | 模型根据 skill 内容决定下一步 | 通过相同的 `matt_pocock_workflow` 显式切换并保存 |
-| 更新 | 直接跟随上游 skill 文件 | 选择性同步，并适配 Pi 运行时 |
-
-概括来说，上游仓库是一组可单独使用的方法论；`pi-matt-pocock` 则是一个把这些方法论组织为连续、受状态约束、可恢复工程流程的运行时。
+| 分发 | 多份独立 `SKILL.md` | 一个 Pi extension 与普通内部资源 |
+| 入口 | 每个 skill 独立发现 | 一个 `/matt-pocock` 菜单与目录驱动 gateway |
+| 能力组织 | 文件与 skill 名称 | workflow、standalone capability、reference、asset 分类 |
+| 上下文 | 每个 skill 独立加载 | `requires` 强依赖随根加载，`discloses` reference 按需加载 |
+| 状态 | 主要由对话维持 | `workItemId` 与 active/completed/cancelled 记录持久化 |
+| 推进 | 由方法正文解释 | `allowedNext` 在运行时强制执行 |
+| 公共命名 | 通用 skill 名可能冲突 | 无子 `SKILL.md`，通用 procedure 名不全局注册 |
+| 同步 | 直接跟随上游文件 | selection metadata 与 checker 约束选择性适配 |
+
+## 结构化决策与 macOS 原生弹窗配置
+
+工作流进行决策访谈（如 `grilling`、`domain-modeling`）时，通过 `matt_pocock_ask` 工具向用户发起选项选择或自定义输入。默认情况下，使用 Pi 终端内置的 TUI 界面（`ctx.ui.select` / `ctx.ui.input`）。
+
+用户可在 `~/.pi/agent/pi-matt-pocock.json` 中配置是否在本地 macOS 环境下启用系统原生弹窗：
+
+```json
+{
+  "useNativeDialog": true
+}
+```
+
+- **默认值**：`false`（默认使用终端内置交互，用户不配置或文件不存在时不启用）。
+- **严格环境守卫**：只有在 macOS 本地图形会话中才会唤起系统弹窗；非 macOS 平台、远程 SSH 会话（`SSH_CONNECTION` / `SSH_CLIENT` / `SSH_TTY`）或 CI/自动化环境下会自动优雅降级为终端内置 TUI。
+- **智能动态上下文**：弹窗标题由 AI 提问时指定或自动从当前工作流 Route/Phase 上下文关联派生；按钮文案自动根据提示语语言智能适应，配置文件仅保留 `useNativeDialog` 单一开关，保持极简。
+- **原生交互体验**：
+  1. **列表单选**：调用系统原生 `choose from list` 弹窗展示选项，支持上下键移动、回车选择；
+  2. **自定义输入**：当用户选择“输入自定义回答...”时，自动唤起原生文本输入窗口（`display dialog` 带输入框），供用户直接打字；
+  3. **推荐超时自动采纳**：在指定时间内未选择且包含推荐选项时，自动关闭弹窗并采纳推荐选项继续推进。

package/README.md

@@ -1,8 +1,6 @@
 # pi-matt-pocock
 
-`pi-matt-pocock` is a Pi extension that provides `/matt-pocock`: a persisted
-workflow harness for BDD-first engineering and productivity procedures adapted
-from `mattpocock/skills`.
+`pi-matt-pocock` provides one `/matt-pocock` menu and a catalog-backed capability gateway for engineering workflows and focused procedures adapted from `mattpocock/skills`.
 
 ## Installation
 
@@ -10,28 +8,186 @@ from `mattpocock/skills`.
 pi install npm:pi-matt-pocock
 ```
 
-## Workflow harness
+## How It Works
 
-`/matt-pocock` opens one routing menu:
+`/matt-pocock` starts or manages persisted workflows and runs standalone capabilities. A single `procedureCatalog` manifest classifies bundled resources as workflow procedures, standalone capabilities, references, or assets, and defines their dependencies, disclosures, workflow placement, and legal transitions.
 
-- Start an idea-to-ship flow
-- Diagnose a hard bug
-- Triage incoming work
-- Map a large ambiguous initiative
-- Improve codebase architecture
-- View, transition, or end the current workflow
+The command takes `<route|capability> [task]`, mirroring `/impeccable <capability> [request]`: the first word selects, the rest is your own task, and that task is carried into the procedure prompt and shown in the transcript row. `status` reports the active work item, `transition [target]` moves to a catalog-legal next procedure, `complete` closes it, and `cancel [reason]` records why. An input whose first word matches no route, capability, or action is forwarded verbatim for autonomous routing and supersedes any active workflow; the task itself is never written into the persisted workflow record.
 
-The harness injects only the chosen procedure, persists its current route and
-phase in the Pi session, restores that state on restart, and adds concise
-phase guidance to agent turns. Its structured interview tool is available only
-while a workflow is active, so ordinary questions remain in the conversation.
-When a procedure's done condition makes its next procedure clear, the agent transitions with `matt_pocock_workflow` and continues without waiting for permission. It pauses only for a user-owned decision, unavailable fact, or required external action. The menu's transition option remains available for an explicit user override.
+The package enforces strict engineering disciplines adapted for coding agents:
+- **BDD-first verification**: Executable Gherkin (`Given`/`When`/`Then`) scenarios in `.feature` files define acceptance criteria before coding.
+- **Two-axis code review**: Independent evaluation along the Standards and Spec axes, sealed with a mandatory **Refute-before-PASS** red-team verification protocol.
+- **AI slop elimination**: Dedicated detection and refactoring of fabricated evidence, evidence widening, defensive clutter, mock patching, and vacuous names.
+- **Tracer-bullet vertical slices**: Tasks cut completely through schema, API, UI, and test layers; wide refactors sequence via expand-contract.
+- **Autonomous progression (AFK)**: Non-user-owned next steps advance automatically without redundant permission prompts; user prompts are reserved for genuine design decisions.
 
-Procedures are internal Markdown resources rather than Pi skills, so generic
-workflow names such as `tdd`, `code-review`, and `research` never collide with
-an installed skill collection.
+Procedures remain internal Markdown resources; the package ships no child `SKILL.md` files, so generic names such as `tdd`, `research`, and `code-review` do not become globally discoverable skills.
 
-For the design rationale, lifecycle, context trade-offs, and a comparison with
-upstream `mattpocock/skills`, see the [中文架构说明](ARCHITECTURE.zh-CN.md).
+## Progressive Tool Disclosure
 
-See [TODO.md](TODO.md) for lifecycle automation that remains deliberately deferred.
+Tools are progressively exposed based on active session state:
+
+1. **Baseline tool**: `matt_pocock_workflow`
+   - `mode: "workflow"`: Start an engineering workflow route (`idea-to-ship`, `wayfinding`, `triage`, `hard-bug`, `architecture`).
+   - `mode: "capability"`: Run a model-reachable standalone capability without persistent workflow state.
+   - `mode: "reference"`: Load a reference disclosed by a standalone capability.
+2. **Active-only tool**: `matt_pocock_active`
+   - `action: "transition"`: Advance the workflow to an allowed next procedure.
+   - `action: "load"`: Load an on-demand reference disclosed by the current procedure or loaded dependencies.
+   - `action: "complete"`: Formally complete the active workflow and release 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.
+
+## Workflow Routes & Graph Topology
+
+Each workflow operates as a state machine governed by `src/catalog.json`. Graph reachability is validated automatically at test and startup time, ensuring no orphaned or unreachable procedures exist.
+
+### 1. `idea-to-ship` (Shaping to Delivery)
+- **Entry**: `grill-with-docs` (`shaping`)
+- **Key Flow**:
+  - `grill-with-docs` ⇄ `grill-me` (flexible documentation-driven or conversational interview)
+  - `research` ⇄ `prototype` (bidirectional exploration loop)
+  - `to-spec` → `to-tickets` → `implement` ⇄ `code-review` → `handoff`
+
+### 2. `wayfinding` (Exploration Under Uncertainty)
+- **Entry**: `wayfinder` (`mapping`)
+- **Key Flow**:
+  - `wayfinder` maps decisions onto an issue tracker map.
+  - `research` ⇄ `prototype` (bidirectional investigation loop linked back to map tickets)
+  - `to-spec` → `to-tickets` → `implement` ⇄ `code-review`
+
+### 3. `triage` (Incoming Request & Issue Triage)
+- **Entry**: `triage` (`triage`)
+- **Key Flow**:
+  - `triage` classifies requests into bugs or enhancements and generates durable agent briefs.
+  - Transitions into `to-spec` or `to-tickets` → `implement` ⇄ `code-review`
+
+### 4. `hard-bug` (Diagnostic Feedback Loops)
+- **Entry**: `diagnosing-bugs` (`feedback-loop`)
+- **Key Flow**:
+  - Build minimal reproduction and tight red-green feedback loop before forming hypotheses.
+  - `diagnosing-bugs` → `implement` ⇄ `code-review`
+  - **Diagnostic Return**: `implement` and `code-review` can transition back to `diagnosing-bugs` if a hypothesis is refuted or a new root cause emerges.
+
+### 5. `architecture` (Deepening & Codebase Design)
+- **Entry**: `improve-codebase-architecture` (`survey`)
+- **Key Flow**:
+  - `improve-codebase-architecture` surveys friction and publishes an interactive HTML candidate report.
+  - `improve-codebase-architecture` ⇄ `codebase-design` (formal Architecture Design review of interfaces and deep modules).
+  - Transitions into `implement` ⇄ `code-review`.
+
+## Coordinated implementation and review
+
+Implementation assigns safe local checks to each contributor and shared verification to one integration owner. After integration, name a candidate revision or scoped snapshot; review and final checks must judge that same candidate. Keep unrelated dirty work outside the review baseline, include untracked task files, and invalidate affected evidence when the candidate changes.
+
+Code review retains separate Standards and Spec verdicts, but a bounded change can use one fresh reviewer for both. Separate reviewers are appropriate for distinct expertise, larger scope, or repository policy—not mandatory for every task. Confirmed conversation requirements and acceptance scenarios can serve as the spec for an uncommitted task.
+
+A completed review assignment is not an implementation PASS. A standalone review or bounded reviewer returns its report, including REWORK, without editing the implementation or waiting for repairs. The Leader or implementation owner groups findings by root cause and owns remediation and delivery.
+
+Before a recheck, preserve the prior report and supply the retained baseline, new candidate fingerprint, correction delta, prior findings and safe checks. Agent Teams reopen/assign does not refresh a fixed description or forward the cleared result. Reuse completed review Work only when its description already points to an authoritative current-attempt brief; update that brief before reopening/assignment. Otherwise create bounded follow-up Work with the refreshed description and a dependency on the completed review. This linked recheck is not a new broad review; broaden only for changed scope or risk.
+
+Complete implementation delivery only after required reports arrive, blocking findings are resolved, and applicable verification covers the final candidate. If only required results remain outstanding, yield with the workflow active instead of announcing completion.
+
+These are agent instructions, not a new runtime scheduler or an enforced dependency on Agent Teams. The workflow state format and completion tool contract are unchanged.
+
+## Standalone Capabilities
+
+The following curated capabilities are reachable via `matt_pocock_workflow` (`mode: "capability"`) without initiating persistent workflow state:
+
+- **`research`**: Primary-source research that writes a cited repository note.
+- **`prototype`**: Throwaway code that answers one logic, state, or UI design question.
+- **`code-review`**: Two-axis diff review against repository standards and originating spec.
+- **`diagnosing-bugs`**: Root cause analysis and feedback loop generation for hard bugs.
+- **`codebase-design`**: Deep module and seam design using locality and leverage principles.
+- **`writing-for-agents`**: Authoring and auditing agent instruction files, skills, and AGENTS.md.
+- **`resolving-merge-conflicts`**: Conflict resolution preserving the intent of both branches.
+- **`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.
+- **`tdd`**: Running the BDD-driven red-green automation loop.
+
+## Lifecycle Display Lines
+
+Following `@fradser/pi-kit` lifecycle renderer conventions, all tool invocations and workflow transitions render as compact single-line lifecycle indicators in the transcript instead of dumping raw payloads.
+
+### Workflow Phase Titles
+
+Workflow lifecycle subjects use the readable title of the phase recorded at that event, not the route id, route title, or a generated task title. The mapping is shared through `readablePhaseTitle()` in `src/workflow.ts`.
+
+| Operation | Lifecycle line |
+| --- | --- |
+| `/matt-pocock <route> [task]` start, menu start, or menu transition | `[matt pocock] started` block, then the task or the readable phase title |
+| Agent-invoked workflow start (`matt_pocock_workflow`) | `[matt pocock] started · <Phase Title>` |
+| Transition to a phase | `[matt pocock] event · <Phase Title>` |
+| Complete the workflow | `[matt pocock] event · <Phase Title> completed` |
+| Cancel the workflow | `[matt pocock] event · <Phase Title> cancelled` |
+
+A user-invoked start mirrors `/impeccable`: the head row carries only the label, a blank band row separates it from the body, and the whole block paints on Pi's native user-message band (`userMessageBg`). The body is the user's own task verbatim when they supplied one, otherwise the readable phase or capability name:
+
+```text
+[matt pocock] started
+
+fix the login redirect
+```
+
+Every authored task line keeps its own row, long lines wrap instead of merging, and the block never advertises expansion. Agent-invoked starts stay on the compact inline row because a tool call has no user text to echo.
+
+For example, a `hard-bug` workflow that reaches code review before completion renders:
+
+```text
+[matt pocock] started · Reproducing & Diagnostics
+[matt pocock] event · Implementation
+[matt pocock] event · Code Review
+[matt pocock] event · Code Review completed
+```
+
+Cancelling during implementation instead renders `[matt pocock] event · Implementation cancelled`. Completion and cancellation still end the **entire workflow**; the title identifies its actual phase at termination, which can also be the entry phase. The renderer never assumes the workflow reached its last phase.
+
+Supported titles by route (not a mandatory execution order):
+
+| Route | Phase titles |
+| --- | --- |
+| `idea-to-ship` | Shaping & Requirements; Research & Feasibility; Prototyping; Specification Design; Task Decomposition; Implementation; Code Review; Handoff & Summary |
+| `wayfinding` | Initiative Mapping; Research & Feasibility; Prototyping; Specification Design; Task Decomposition; Implementation; Code Review |
+| `triage` | Task Triage; Specification Design; Task Decomposition; Implementation; Code Review |
+| `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.
+
+Expansion shows information not already visible in the row:
+
+- 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.
+
+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.
+
+### Other Lifecycle Displays
+
+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`).
+- **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.
+- **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.
+
+## Configuration
+
+You can optionally configure native macOS dialog prompts for `matt_pocock_ask` via `~/.pi/agent/pi-matt-pocock.json`:
+
+```json
+{
+  "useNativeDialog": true
+}
+```
+
+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).

package/TODO.md

@@ -1,11 +1,7 @@
 # Deferred automation
 
-The harness already directs the agent to transition immediately when a
-procedure's done condition makes the next applicable procedure clear. These
-remaining lifecycle capabilities need dedicated runtime support:
+The catalog-backed gateway, legal workflow transitions, model-driven completion and cancellation, and standalone capability routing are implemented. The remaining items require broader Pi runtime or policy integration:
 
 - [ ] Automatically create a new Pi session for a workflow phase.
 - [ ] Automatically create teammates for workflow research or review.
 - [ ] Enforce BDD/TDD through tool-level production-write blocking.
-- [ ] Add one Pi command per workflow.
-- [ ] Add a second public `/skill:matt-pocock` surface.

package/UPSTREAM.md

@@ -0,0 +1,63 @@
+# Upstream synchronization
+
+## Recorded revisions
+
+- Repository: `mattpocock/skills`
+- Compared commit: `6654f6b60cd9d5be8b54c6fafe44346dabeb3b76`
+- Comparison tag: `v1.2.3`
+- Resolved tag commit: `6acc160e4e0cd062dbbbd7a1b26ae92855edf07e`
+- Latest checked commit: `3cca18b368ae95cdbdebbff572ccafa662551015`
+
+These values are deliberately separate. The compared commit is the content
+baseline, the comparison tag is the human-readable release marker, the resolved
+tag commit records what that tag pointed to, and the latest checked commit is
+the newest upstream tree reviewed for additions or removals.
+
+The machine-readable selection is in
+[`upstream-selection.json`](upstream-selection.json). It classifies every
+upstream `SKILL.md` present at the latest checked commit as either promoted or
+intentionally excluded. Each promoted skill names its local catalog capability,
+plain Markdown resource, and upstream invocation mode. Each exclusion carries a
+reason; Claude Code hooks and background-agent commands are identified as
+host-specific rather than silently ignored.
+
+## Harness architecture
+
+Upstream distributes nested `SKILL.md` files. Pi recursively discovers any
+such file under a declared skill root, which exposes generic names such as
+`tdd`, `code-review`, and `research` alongside unrelated installed skills.
+
+This package exposes one extension command, `/matt-pocock`. The extension
+selects and injects plain Markdown procedures from `procedures/`; none are Pi
+skills, and the package contains no `SKILL.md` file.
+
+## Sync rules
+
+1. Clone upstream separately and inspect both the compared and latest checked
+   commits before changing local resources.
+2. Run the local metadata check without an upstream checkout:
+
+   ```bash
+   node scripts/check-upstream-sync.mjs
+   ```
+
+3. Run the complete inventory, invocation, and content comparison against an
+   already-cloned checkout. The checker never clones or fetches:
+
+   ```bash
+   node scripts/check-upstream-sync.mjs --upstream /path/to/mattpocock-skills
+   ```
+
+4. Copy selected workflows and supporting files into `procedures/`; never
+   overwrite the extension harness wholesale.
+5. Rename copied upstream `SKILL.md` files to their catalog id plus `.md`.
+   Strip frontmatter, and never ship a `SKILL.md` file.
+6. Remove Claude-only frontmatter, tools, paths, and invocation syntax from
+   copied content. Replace cross-procedure calls with relative links.
+7. Preserve the local BDD/TDD split and Pi-specific interaction,
+   collaboration, instruction-file, and git-agent guidance. An adapted content
+   result is expected when these local contracts differ from upstream.
+8. Classify every new or removed upstream skill in
+   `upstream-selection.json`, then update the four revision fields together.
+9. Re-run the harness feature, isolated sync tests, package tests, and package
+   dry-run after a sync.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-matt-pocock",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "type": "module",
   "description": "BDD-first engineering and productivity skills adapted from Matt Pocock's skills",
   "keywords": [
@@ -28,14 +28,18 @@
     "TODO.md",
     "LICENSE",
     "README.md",
-    "ARCHITECTURE.zh-CN.md"
+    "ARCHITECTURE.zh-CN.md",
+    "UPSTREAM.md",
+    "upstream-selection.json",
+    "scripts"
   ],
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
-    "@earendil-works/pi-tui": "*"
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "dependencies": {
-    "@fradser/pi-kit": "0.4.2"
+    "@fradser/pi-kit": "0.5.0"
   },
   "pi": {
     "extensions": [

package/procedures/HTML-REPORT.md

@@ -39,7 +39,7 @@ Repo name, date, and a compact legend: solid box = module, dashed line = seam, r
 
 ## Candidate card
 
-The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the [codebase-design](codebase-design.md) skill) without ceremony.
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the [codebase-design](codebase-design.md) capability) without ceremony.
 
 Each candidate is one `<article>`:
 
@@ -105,7 +105,7 @@ One larger card. Candidate name, one sentence on why, anchor link to its card. T
 
 ## Tone
 
-Plain English, concise — but the architectural nouns and verbs come straight from the [codebase-design](codebase-design.md) skill. Concision is not an excuse to drift.
+Plain English, concise — but the architectural nouns and verbs come straight from the [codebase-design](codebase-design.md) capability. Concision is not an excuse to drift.
 
 **Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.