pi-matt-pocock 0.1.0 → 0.2.0

package/ARCHITECTURE.zh-CN.md

@@ -0,0 +1,216 @@
+# pi-matt-pocock 架构说明
+
+`pi-matt-pocock` 将 [mattpocock/skills](https://github.com/mattpocock/skills) 中选定的工程方法适配为 Pi 的**目录驱动能力网关**。它不是上游仓库的完整镜像，也不把每份上游 `SKILL.md` 注册为 Pi skill。
+
+## 核心模型：procedureCatalog manifest
+
+`src/catalog.json` 中的 `procedureCatalog` manifest 是能力与资源关系的单一事实来源，`src/catalog.ts` 提供类型化查询与校验。命令菜单、模型可见能力、工作流入口、route 标题与说明、阶段、别名、依赖、引用披露、合法迁移和完整性检查都从目录派生，而不是分别维护 route/procedure 巨型枚举。
+
+目录中的资源分为四类：
+
+- **workflow（工作流 procedure）**：可位于一个或多个持久化 route 中；部分也可作为 standalone capability 运行。
+- **standalone capability（独立能力）**：目录中标记 `standalone` 的 workflow 或 utility，可一次性运行，不创建持久化工作流状态。
+- **reference（参考资料）**：只在当前 procedure 或已加载 reference 明确披露后可访问。
+- **asset（资产）**：procedure 使用的脚本或模板，不作为公共能力入口。
+
+每条目录记录还声明调用模式：`model`、`user` 或 `internal`。模型基线网关只枚举 `model` 且可独立运行的能力；`/matt-pocock` 菜单可展示全部 standalone capability。内部 reference 与 asset 不会成为顶层菜单项或全局 skill。
+
+## 单一用户入口与渐进式 tool
+
+包只有一个命令入口 `/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` | 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
+[matt pocock] started
+
+fix the login redirect
+```
+
+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 重复全仓验证。
+
+评审仍分别给出 Standards 与 Spec 结论，但小范围改动可由一个全新上下文的 reviewer 完成两个维度；只有规模、专业分工或仓库规则需要时才拆成多个 reviewer。当前对话中已确认的需求与验收场景可作为本地未提交任务的 spec，不必为了评审创建 issue tracker 或提交。
+
+评审 Work 完成表示报告已交付，不等于实现 PASS。独立评审或限定 reviewer 任务返回报告即可结束，包括 REWORK；不擅自修改实现，也不等待问题被修复。Leader 或实现负责人负责按根因合并问题、补齐相邻场景及后续交付。
+
+复核前先保存旧报告，并准备保留的基线、新候选指纹、修复差异、原发现与安全检查范围。Agent Teams 的 reopen 会清除旧 result，但不会更新 description；reopen reason 和 assign 也不会自动传递新的复核说明。仅当原 description 已指向“当前尝试的权威 brief”时，才先更新该 brief，再 reopen/assign，且复核期间保持内容稳定。原描述固定了旧候选或没有此引用时，用完整新描述创建范围受限的后续 Work，并通过 dependsOn 关联已完成评审。它是关联的定向复核，不是新一轮广泛评审；仅范围或风险明显变化才扩大评审。
+
+实现交付需等待所有必需结果返回、阻断问题解决且证据适用于最终候选，才调用 complete；仅剩待返回结果时保持工作流活动并让出当前回合。
+
+这些约束属于指导文本，不是新增调度器或跨扩展的强制完成锁；不改变持久化格式，也不强依赖 Agent Teams。
+
+## 合法迁移
+
+每个 workflow placement 在目录中声明 `allowedNext`。迁移时运行时会：
+
+1. 规范化 procedure id 与已知别名；
+2. 验证目标是否位于当前 `{ route, procedure }` 的 `allowedNext`；
+3. 验证目标确实属于同一 route；
+4. 更新 procedure 与 phase，并清空先前加载的 references；
+5. 解析新 bundle 后持久化状态。
+
+不在集合内的迁移会失败并返回允许的候选项。运行时不会把非法目标替换成 route 默认 procedure，也不会用一个覆盖全部路线的 procedure enum 假装迁移有效。
+
+## `requires` 与 `discloses`
+
+目录用两种边表达不同的上下文语义：
+
+- `requires`：执行根 procedure 必须同时加载的依赖。`src/resolver.ts` 递归解析依赖闭包、去重并检测环；这些正文与根 procedure 一起进入 bundle。
+- `discloses`：当前正文允许按需访问、但尚未加载的 reference 或辅助能力。网关只返回可用 id；模型需要时再通过 `matt_pocock_active` 或 standalone reference 模式加载。
+
+已加载 reference 也可以继续披露下一层 reference。运行时根据当前 procedure 与 `loadedReferences` 计算可达集合，拒绝目录图之外的任意文件请求。这既保留方法论所需的强依赖，也避免把所有可选资料一次性塞入上下文。
+
+## 稳定来源标识与体积边界
+
+每个解析后的正文都包在独立来源块中：
+
+```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 与普通内部资源 |
+| 入口 | 每个 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,38 +1,193 @@
-# Matt Pocock for Pi
+# 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
 
-This package has not yet been released to npm. Install it from a local checkout:
-
 ```bash
-pi install /path/to/pi-packages/packages/matt-pocock
+pi install npm:pi-matt-pocock
 ```
 
-It will be published as `pi-matt-pocock` after its first-release bootstrap.
+## How It Works
+
+`/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.
+
+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 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 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.
+
+## Progressive Tool Disclosure
+
+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.
 
-## Workflow harness
+## Lifecycle Display Lines
 
-`/matt-pocock` opens one routing menu:
+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.
 
-- 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
+### Workflow Phase Titles
 
-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.
+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
+}
+```
 
-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.
+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 [TODO.md](TODO.md) for lifecycle automation that remains deliberately deferred.
+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.0",
+  "version": "0.2.0",
   "type": "module",
   "description": "BDD-first engineering and productivity skills adapted from Matt Pocock's skills",
   "keywords": [
@@ -27,18 +27,23 @@
     "procedures",
     "TODO.md",
     "LICENSE",
-    "README.md"
+    "README.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": "workspace:*"
+    "@fradser/pi-kit": "0.5.0"
   },
   "pi": {
     "extensions": [
       "./index.ts"
     ]
   }
-}
+}

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.
 

package/procedures/bdd.md

@@ -1,10 +1,10 @@
 # Behavior-Driven Development (BDD)
 
-BDD is not just about tools; it's a methodology for shared understanding and high-quality implementation. This skill governs the **Discovery → Formulation → Automation** lifecycle: Gherkin scenarios define the behavior, and the Automation phase (red-green loop) is delegated to [tdd](tdd.md) (BDD-driven).
+BDD is not just about tools; it's a methodology for shared understanding and high-quality implementation. This procedure governs the **Discovery → Formulation → Automation** lifecycle: Gherkin scenarios define the behavior, and the Automation phase (red-green loop) is delegated to [tdd](tdd.md) (BDD-driven).
 
 When exploring the codebase, read `CONTEXT.md` (if it exists) so test names and interface vocabulary match the project's domain language, and respect ADRs in the area you're touching.
 
-## How to Use This Skill
+## How to Use This Procedure
 
 When the user asks for a feature, bug fix, or refactor, apply the following mindset:
 
@@ -35,7 +35,7 @@ See `./references/gherkin-guide.md` for syntax and storage structure.
 
 ## Automation Phase
 
-The Automation phase (red-green loop) is governed by the [tdd](tdd.md) skill (BDD-driven). When the Gherkin scenario is defined and the seam is agreed, invoke [tdd](tdd.md) for:
+The Automation phase (red-green loop) is governed by the [tdd](tdd.md) capability (BDD-driven). When the Gherkin scenario is defined and the seam is agreed, load [tdd](tdd.md) with `matt_pocock_workflow` (`mode: "capability"`) — it is a package capability, not a Pi skill — for:
 
 - **Seams** — where tests go at the public boundary
 - **Test quality** — what makes a good test, anti-patterns