@ai-content-space/loopx 0.2.0 → 0.2.2

package/AGENTS.md

@@ -1,25 +1,24 @@
 # Repository Guidelines
 
-## Iron Law:
+## Iron Law
 
-**All skills must do not  have descriptive content. The content of skills should be clear and unambiguous, and must not be ambiguous.
-Skills should be kept as simple as possible. It is like a Swiss Army knife - versatile but not a universal key.**
+**Skill frontmatter descriptions are required for discovery, but skill bodies should stay operational, clear, and bounded. Avoid vague narrative, broad promises, and ambiguous handoffs. Keep each skill focused: versatile enough to be useful, not a universal key.**
 
 
 
 ## Project Structure & Module Organization
 
-This repository is a Node.js ESM CLI package for loopx, a skill-first workflow harness for Codex-style agents.
+This repository is a Node.js ESM CLI package for loopx, a skill-first workflow harness for Codex and Claude-style agentic coding assistants.
 
 - `src/` contains runtime modules and the `src/cli.mjs` executable.
 - `test/` contains Node test suites, mainly `workflow.test.mjs` and `trellis-hardening.test.mjs`.
-- `skills/` contains bundled agent skills installed by the package.
-- `plugins/loopx/` mirrors plugin-ready skills and plugin install scripts.
+- `skills/` contains canonical skill source files. The v1 installed set is controlled by `LOOPX_BUNDLED_SKILLS` in `src/install-discovery.mjs`; not every local skill source is installed or governed as part of v1.
+- `plugins/loopx/` mirrors the bundled plugin-ready v1 skills and plugin install scripts.
 - `templates/` stores canonical workflow artifact templates.
 - `scripts/` contains postinstall and hook scripts.
-- `assets/`, `docs/`, and `examples/` hold static assets, release notes, and demos.
+- `assets/` and `docs/` hold static assets, release notes, and design/planning documents.
 
-Keep source changes close to the owning module. When changing workflow behavior, update matching tests and any affected skill docs in both `skills/` and `plugins/loopx/skills/` when they are intentionally mirrored.
+Keep source changes close to the owning module. When changing workflow behavior, update matching tests and any affected bundled skill docs in both `skills/` and `plugins/loopx/skills/` when they are intentionally mirrored.
 
 ## Build, Test, and Development Commands
 

package/README.md

@@ -10,7 +10,7 @@
 
 [中文文档](./README.zh-CN.md)
 
-`loopx` bundles a pragmatic set of skills for Codex and Claude-style coding agents. It combines grill-me style clarification with superpowers-style planning, execution, review, and finishing workflows.
+`loopx` installs a pragmatic v1 skill suite for Codex and Claude-style coding agents. It combines grill-me style clarification with superpowers-style planning, execution, review, and finishing workflows.
 
 Recommended v1 flow:
 
@@ -22,6 +22,8 @@ clarify -> spec? -> plan -> subagent-exec | exec -> review -> fix-review? -> fin
 
 ## Skills
 
+The installed and governed v1 skill surface is the list below. The repository may keep auxiliary or compatibility skill sources under `skills/`, but they are not installed by `loopx install-skills` unless they are in the bundled v1 set.
+
 Core workflow skills:
 
 - `clarify`: interview until scope, non-goals, constraints, and decision boundaries are clear.
@@ -44,14 +46,26 @@ Support skills:
 
 ## Artifacts
 
-Human-maintained artifacts live under `docs/loopx/`:
+For the v1 skill-suite workflow, human-maintained artifacts live under `docs/loopx/`:
 
 - `docs/loopx/design/`
 - `docs/loopx/plans/`
 - `docs/loopx/reviews/`
 - `docs/loopx/refactors/`
+- `docs/loopx/specs/`
+
+`finish` may generate spec candidates in `docs/loopx/specs/` when completed work produces stable team rules. These candidates are repo-tracked and must remain visible in the git diff.
+
+Generated support state, hook diagnostics, installer metadata, HTML views, manifests, and runtime JSON remain under `.loopx/`.
 
-`.loopx/` is for local support state, hook diagnostics, installer metadata, and legacy runtime workflows.
+Local agent memory lives under `.loopx/memory/`:
+
+- `.loopx/memory/MEMORY.md`
+- `.loopx/memory/index.jsonl`
+- `.loopx/memory/entries/`
+- `.loopx/memory/archive/`
+
+`MEMORY.md` is a bounded curated project memory summary. `index.jsonl` is a curated active index for agent file-search, not an append-only log.
 
 ## Installation
 
@@ -94,22 +108,22 @@ Plugin install script:
 node plugins/loopx/scripts/plugin-install.mjs
 ```
 
-The plugin mirrors the canonical `skills/` directory and uses the same install/discovery core.
+The plugin mirrors the canonical bundled v1 skills from `skills/` and uses the same install/discovery core.
 
 ## CLI
 
-The CLI supports installation, diagnostics, rendering, and legacy runtime compatibility:
+The CLI supports installation, diagnostics, rendering, and runtime maintenance:
 
 ```bash
+loopx --version
 loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--yes]
 loopx init [--slug <slug>] [--enable-agent-delegation] [--auto-agent-delegation] [--agent-delegation-threshold <local|critic-only|parallel-review>]
 loopx clarify <slug> [--standard|--deep]
 loopx approve <slug> --from <stage> --to <stage>
-loopx plan [slug] [--direct <spec-path>] [--interactive] [--deliberate]
+loopx plan [slug] [--interactive] [--deliberate]
 loopx build <slug> [--no-deslop]
 loopx build --from-review <review-report-path> [--no-deslop]
 loopx review <slug> [--reviewer <name>]
-loopx archive <slug>
 loopx autopilot <slug> [--reviewer <name>]
 loopx render [slug|--all]
 loopx status [slug] [--json]
@@ -119,8 +133,6 @@ loopx migrate
 loopx repair-install
 ```
 
-Legacy `.loopx/workflows/` commands remain available for compatibility. They are not the v1 skill-suite workflow.
-
 ## Governance
 
 The bundled skill resolver lives at:
@@ -135,4 +147,4 @@ Run deterministic governance checks before release or when changing bundled skil
 node scripts/verify-skills.mjs
 ```
 
-The verifier checks bundled skill frontmatter, plugin mirrors, resolver coverage, local references, package inclusion, version alignment, and public docs.
+The verifier checks the bundled v1 skill frontmatter, plugin mirrors, resolver coverage, local references, package inclusion, version alignment, and public docs. It intentionally verifies the installed v1 skill set, not every auxiliary source directory that may exist under `skills/`.

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 
 [English](./README.md)
 
-`loopx` 为 Codex 和 Claude 风格的 coding agent 打包一组实用 skills。它把 grill-me 式需求澄清和 superpowers 式计划、执行、评审、收尾流程组合成一套可安装、可治理的技能套件。
+`loopx` 为 Codex 和 Claude 风格的 coding agent 安装一组实用的 v1 skills。它把 grill-me 式需求澄清和 superpowers 式计划、执行、评审、收尾流程组合成一套可安装、可治理的技能套件。
 
 推荐 v1 流程：
 
@@ -22,6 +22,8 @@ clarify -> spec? -> plan -> subagent-exec | exec -> review -> fix-review? -> fin
 
 ## Skills
 
+安装和治理意义上的 v1 skill surface 是下面这组。仓库里可以保留辅助或兼容 skill 源文件，但除非它们属于 bundled v1 集合，否则 `loopx install-skills` 不会安装它们。
+
 核心工作流 skills：
 
 - `clarify`：持续追问直到范围、非目标、约束和决策边界清楚。
@@ -44,14 +46,26 @@ clarify -> spec? -> plan -> subagent-exec | exec -> review -> fix-review? -> fin
 
 ## 产物
 
-人工维护的长期产物放在 `docs/loopx/`：
+v1 skill-suite 工作流的人工维护长期产物放在 `docs/loopx/`：
 
 - `docs/loopx/design/`
 - `docs/loopx/plans/`
 - `docs/loopx/reviews/`
 - `docs/loopx/refactors/`
+- `docs/loopx/specs/`
+
+当完成的工作产生稳定团队规则时，`finish` 可以在 `docs/loopx/specs/` 生成 spec candidates。这些候选是 repo-tracked，必须保留在 git diff 中供审阅。
+
+生成的支撑状态、hook 诊断、安装元数据、HTML views、manifests 和 runtime JSON 仍放在 `.loopx/` 下。
 
-`.loopx/` 用于本地支撑状态、hook 诊断、安装元数据和 legacy runtime workflows。
+本地 agent memory 放在 `.loopx/memory/`：
+
+- `.loopx/memory/MEMORY.md`
+- `.loopx/memory/index.jsonl`
+- `.loopx/memory/entries/`
+- `.loopx/memory/archive/`
+
+`MEMORY.md` 是有上限的 curated project memory summary。`index.jsonl` 是用于 agent 文件检索的 curated active index，不是 append-only log。
 
 ## 安装
 
@@ -94,22 +108,22 @@ plugins/loopx/
 node plugins/loopx/scripts/plugin-install.mjs
 ```
 
-插件镜像 canonical `skills/` 目录，并复用同一套 install/discovery core。
+插件镜像 `skills/` 中 canonical bundled v1 skills，并复用同一套 install/discovery core。
 
 ## CLI
 
-CLI 用于安装、诊断、渲染和 legacy runtime 兼容：
+CLI 用于安装、诊断、渲染和 runtime 维护：
 
 ```bash
+loopx --version
 loopx install-skills [--target <codex|claude|all>] [--project] [--mode <copy|symlink>] [--dir <path>] [--yes]
 loopx init [--slug <slug>] [--enable-agent-delegation] [--auto-agent-delegation] [--agent-delegation-threshold <local|critic-only|parallel-review>]
 loopx clarify <slug> [--standard|--deep]
 loopx approve <slug> --from <stage> --to <stage>
-loopx plan [slug] [--direct <spec-path>] [--interactive] [--deliberate]
+loopx plan [slug] [--interactive] [--deliberate]
 loopx build <slug> [--no-deslop]
 loopx build --from-review <review-report-path> [--no-deslop]
 loopx review <slug> [--reviewer <name>]
-loopx archive <slug>
 loopx autopilot <slug> [--reviewer <name>]
 loopx render [slug|--all]
 loopx status [slug] [--json]
@@ -119,8 +133,6 @@ loopx migrate
 loopx repair-install
 ```
 
-Legacy `.loopx/workflows/` 命令仍保留兼容，但不是 v1 skill-suite workflow。
-
 ## 治理
 
 bundled skill resolver 位于：
@@ -135,4 +147,4 @@ skills/RESOLVER.md
 node scripts/verify-skills.mjs
 ```
 
-治理脚本检查 bundled skill frontmatter、plugin mirrors、resolver coverage、本地引用、发布包包含项、版本一致性和公开文档。
+治理脚本检查 bundled v1 skill frontmatter、plugin mirrors、resolver coverage、本地引用、发布包包含项、版本一致性和公开文档。它刻意验证安装意义上的 v1 skill 集合，而不是 `skills/` 下可能存在的每个辅助源目录。

package/docs/loopx/design/loopx-skill-suite-v1-design.md

@@ -2,11 +2,11 @@
 
 ## Context
 
-loopx is moving from a CLI-runtime-first workflow into a skill-first suite for agentic coding assistants. Codex and Claude are supported targets. The CLI remains as installer, governance, diagnostics, rendering, and legacy `.loopx/workflows/` support.
+loopx is moving from a CLI-runtime-first workflow into a skill-first suite for agentic coding assistants. Codex and Claude are supported targets. The CLI remains as installer, governance, diagnostics, rendering, and runtime maintenance.
 
 ## Decision
 
-The v1 product surface is a bundled skill suite:
+The v1 product surface is the installed and governed bundled skill suite:
 
 - `clarify`
 - `spec`
@@ -23,7 +23,9 @@ The v1 product surface is a bundled skill suite:
 - `go-style`
 - `kratos`
 
-Legacy runtime skills are not bundled as Codex or Claude skills in v1. Legacy CLI commands may remain for compatibility.
+Runtime-only skills are not installed as Codex or Claude skills in v1.
+
+The repository may retain auxiliary or compatibility skill source directories for development history or adjacent workflows. They are not part of the v1 product surface unless they are listed in the bundled install set and mirrored into the plugin skill set.
 
 ## Workflow
 
@@ -39,16 +41,21 @@ clarify -> spec? -> plan -> subagent-exec | exec -> review -> fix-review? -> fin
 
 `review` is the superpowers `requesting-code-review` workflow under the loopx name. `fix-review` is the superpowers `receiving-code-review` workflow under the loopx name.
 
+`finish` verifies completion, extracts local memory, proposes repo-tracked spec candidates when stable team rules emerged, then presents merge, PR, keep, or discard options.
+
 ## Artifacts
 
-Human-maintained artifacts use `docs/loopx/`:
+Human-maintained v1 skill-suite artifacts use `docs/loopx/`:
 
 - `docs/loopx/design/`
 - `docs/loopx/plans/`
 - `docs/loopx/reviews/`
 - `docs/loopx/refactors/`
+- `docs/loopx/specs/`
+
+Runtime state, hook diagnostics, installer metadata, manifests, generated HTML views, and runtime JSON use `.loopx/`.
 
-Runtime state, hook diagnostics, installer metadata, and legacy workflows use `.loopx/`.
+Local agent memory uses `.loopx/memory/`. `.loopx/memory/MEMORY.md` is bounded curated project memory. `.loopx/memory/index.jsonl` is a curated active index for agent file-search. Stable shared rules belong in `docs/loopx/specs/<domain>.md`, with `docs/loopx/specs/inbox.md` as the fallback domain.
 
 ## Installer
 
@@ -63,11 +70,11 @@ Project-level Claude installation and custom directories are explicit installer
 
 ## Claude Hook
 
-The Claude hook is advisory only. It must not block tools, mutate workflow state, or enforce git safety. It emits next-action context when loopx support or legacy runtime context exists.
+The Claude hook is advisory only. It must not block tools, mutate workflow state, or enforce git safety. It emits next-action context when loopx support context exists.
 
 ## Non-Goals
 
-- No alias skills for renamed superpowers skills.
+- No alias skills in the v1 bundled install surface for renamed superpowers skills.
 - No automatic project-level `.claude/skills` writes in postinstall.
 - No new mandatory CLI state machine for the v1 skill suite.
 - No blocking Claude hook in v1.

package/docs/loopx/plans/loopx-skill-suite-v1-implementation.md

@@ -1,12 +1,12 @@
 # loopx Skill Suite v1 Implementation Plan
 
-> **For agentic workers:** execute task-by-task. Preserve existing user edits and keep legacy CLI runtime compatibility unless a task explicitly changes skill installation behavior.
+> **For agentic workers:** execute task-by-task. Preserve existing user edits and keep runtime maintenance behavior unless a task explicitly changes skill installation behavior.
 
 **Source Design:** `docs/loopx/design/loopx-skill-suite-v1-design.md`
 
 **Goal:** Convert loopx into a Codex and Claude ready skill suite with renamed superpowers-style workflow skills, dual-target installation, and non-blocking Claude hook support.
 
-**Architecture:** `skills/` remains canonical. `plugins/loopx/skills/` mirrors canonical skills for Codex plugin packaging. `src/install-discovery.mjs` owns multi-target installation and lock metadata.
+**Architecture:** `skills/` remains the canonical source root. `plugins/loopx/skills/` mirrors the bundled v1 skill set for Codex plugin packaging, not every auxiliary source directory that may exist under `skills/`. `src/install-discovery.mjs` owns multi-target installation and lock metadata.
 
 **Tech Stack:** Node.js ESM, `node:test`, filesystem APIs from `node:fs/promises`.
 
@@ -23,8 +23,9 @@
 - [ ] Rename canonical superpowers-derived skills to v1 names.
 - [ ] Remove old runtime workflow skills from the bundled install list.
 - [ ] Keep `plan` as the canonical implementation-planning skill.
-- [ ] Mirror all canonical skill files into `plugins/loopx/skills/`.
+- [ ] Mirror all bundled v1 canonical skill files into `plugins/loopx/skills/`.
 - [ ] Update internal references from old names to new `loopx:` names.
+- [ ] Keep auxiliary or compatibility skill sources outside the bundled install list unless explicitly promoted into the v1 product surface.
 
 ### Task 2: Installer Targets
 
@@ -63,6 +64,9 @@
 
 - [ ] Reframe loopx as a skill suite for agentic coding assistants.
 - [ ] Document the new workflow and artifact paths.
+- [ ] Clarify v1 `docs/loopx/` artifacts versus generated runtime support state.
+- [ ] Document finish memory extraction and `docs/loopx/specs/` candidate promotion.
+- [ ] Clarify installed bundled skills versus auxiliary skill source directories.
 - [ ] Document Codex and Claude installation.
 - [ ] Update governance checks for the v1 bundled skill list and mirrors.
 - [ ] Update install tests for dual user targets and hooks.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-content-space/loopx",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Skill-first workflow suite for agentic coding assistants",
   "repository": {
     "type": "git",
@@ -32,7 +32,8 @@
     "src/",
     "skills/",
     "templates/",
-    "plugins/loopx/"
+    "plugins/loopx/",
+    "!plugins/loopx/scripts/plugin-install.test.mjs"
   ],
   "publishConfig": {
     "access": "public"

package/plugins/loopx/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "loopx",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Skill-first workflow suite for agentic coding assistants",
   "skills": "./skills/",
   "interface": {

package/plugins/loopx/skills/clarify/SKILL.md

@@ -3,7 +3,7 @@ name: clarify
 description: "Grills ambiguous loopx work until material questions are answered, then routes to spec or plan using a design gate. Not for clear implementation tasks, approved specs, or code changes."
 when_to_use: "clarify, requirements, ambiguous request, unclear scope, non-goals, decision boundaries, acceptance criteria, 需求澄清, 范围不清"
 metadata:
-  version: "0.2.0"
+  version: "0.2.2"
 ---
 
 # loopx Clarify
@@ -63,11 +63,11 @@ For `needs_spec`, immediately use the `spec` skill with the clarification contex
 Then stop before implementation planning and report:
 
 ```text
-$plan --direct docs/loopx/design/<需求名>需求设计文档.md
+$plan docs/loopx/design/<需求名>需求设计文档.md
 ```
 
-For `direct_to_plan`, immediately use the `plan` skill with the clarification context bundle as the source. `plan` writes:
+For `direct_to_plan`, hand off to the `plan` skill with the clarification context bundle as the source. `plan` writes:
 
 - `docs/loopx/plans/YYYY-MM-DD-<feature-name>.md`
 
-Do not start code changes or implementation planning from `clarify`.
+Do not write implementation plans or start code changes inside `clarify`.

package/plugins/loopx/skills/debug/SKILL.md

@@ -3,7 +3,7 @@ name: debug
 description: "Finds root cause for bugs, failing tests, build failures, regressions, and unexpected behavior before fixes. Not for new feature planning or routine code review."
 when_to_use: "debug, bug, test failure, build failure, regression, unexpected behavior, root cause, 报错, 失败, 回归, 排查"
 metadata:
-  version: "0.2.0"
+  version: "0.2.2"
 ---
 
 # Systematic Debugging

package/plugins/loopx/skills/exec/SKILL.md

@@ -3,7 +3,7 @@ name: exec
 description: "Executes a written loopx implementation plan sequentially with review checkpoints. Not for unclear plans, missing requirements, or subagent-first execution."
 when_to_use: "written implementation plan, inline execution, sequential plan execution, review checkpoints, no subagent lane"
 metadata:
-  version: "0.2.0"
+  version: "0.2.2"
 ---
 
 # Exec

package/plugins/loopx/skills/final-review/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: final-review
+description: "Performs whole-feature review after implementation and staged task review. Not for per-task review, unresolved scope, implementation, or pure documentation polish."
+when_to_use: "final-review, final code review, whole feature review, integration review, pre-finish review, after subagent-exec, runtime risk review, 最终评审"
+metadata:
+  version: "0.2.2"
+---
+
+# Final Review
+
+Run the final whole-feature review after implementation is complete and before `finish`.
+
+**Core principle:** Per-task review catches local issues. Final review hunts integration and runtime risk across the complete feature.
+
+**Announce at start:** "I'm using the final-review skill to review the completed feature."
+
+## When to Use
+
+Use this after:
+- `subagent-exec` completed all planned tasks and per-task reviews
+- `exec` completed a full plan with verification checkpoints
+- ad-hoc implementation is complete and ready for final risk review
+
+Do not use this for:
+- reviewing one task or one small checkpoint (`review` is for that)
+- fixing review feedback (`fix-review` is for that)
+- polishing documentation wording
+- incomplete implementation or failing verification
+
+## Required Inputs
+
+Before dispatching the reviewer, collect:
+- Full feature git range: base SHA before implementation, head SHA now
+- Source requirements: spec, plan, issue, PRD, or accepted task brief
+- Implementation summary: what changed and why
+- Verification evidence: commands run and results
+- Per-task review artifacts, if available
+
+If the git range or requirements are unclear, stop and ask. A final review without a concrete scope is not useful.
+
+## Review Priority
+
+The reviewer must prioritize findings in this order:
+
+1. Runtime bugs, data loss, broken CLI behavior, state corruption
+2. Cross-task integration bugs
+3. Missing edge cases not covered by tests
+4. Test quality problems
+5. Architecture and maintainability issues
+6. Documentation defects that can mislead users or maintainers, omit required operational facts, or contradict actual behavior
+
+Do not report pure documentation polish, style preferences, or wording tweaks. Do report documentation problems that create wrong usage, wrong maintenance decisions, missing required commands, missing migration notes, or false claims.
+
+## Dispatch
+
+Use the platform's native subagent mechanism when available and fill template at `final-reviewer.md`.
+
+**Placeholders:**
+- `{DESCRIPTION}` - concise summary of the completed feature
+- `{REQUIREMENTS}` - source requirements or plan/spec excerpts
+- `{VERIFICATION}` - test commands and results
+- `{PER_TASK_REVIEWS}` - review artifacts or "not available"
+- `{BASE_SHA}` - commit before implementation began
+- `{HEAD_SHA}` - current commit
+
+## Handle Feedback
+
+- Critical and Important findings must be handled before `finish`
+- Use `fix-review` for received feedback
+- Push back only with code, test, or requirement evidence
+- After fixes, run verification again and repeat final review if the fix changed integration behavior
+
+## Common Mistakes
+
+**Running normal review again**
+- Problem: reviewer repeats per-task or documentation comments
+- Fix: use `final-reviewer.md`, which focuses on whole-feature runtime risk
+
+**Letting docs hide real risk**
+- Problem: "docs only" findings are ignored even when users would be misled
+- Fix: distinguish pure polish from operationally incorrect or missing documentation
+
+**Reviewing without base/head SHAs**
+- Problem: reviewer sees an unclear or stale diff
+- Fix: provide an exact git range every time
+
+**Skipping verification evidence**
+- Problem: reviewer cannot judge whether tests prove real behavior
+- Fix: include exact commands and pass/fail output summary

package/plugins/loopx/skills/final-review/final-reviewer.md

@@ -0,0 +1,135 @@
+# Final Reviewer Prompt Template
+
+Use this template when dispatching a final-review subagent.
+
+**Purpose:** Review the complete feature for integration and runtime risk after task-level implementation and review are already done.
+
+```
+Native subagent:
+  description: "Final review completed feature"
+  prompt: |
+    You are a Senior Final Reviewer. Task-level implementation and review have
+    already happened. Your job is not to repeat per-task review. Your job is to
+    find whole-feature risks that can still break users, corrupt state, lose
+    data, or leave important behavior untested.
+
+    ## What Was Implemented
+
+    {DESCRIPTION}
+
+    ## Requirements / Plan / Spec
+
+    {REQUIREMENTS}
+
+    ## Verification Evidence
+
+    {VERIFICATION}
+
+    ## Per-Task Reviews
+
+    {PER_TASK_REVIEWS}
+
+    ## Full Feature Git Range
+
+    **Base:** {BASE_SHA}
+    **Head:** {HEAD_SHA}
+
+    ```bash
+    git diff --stat {BASE_SHA}..{HEAD_SHA}
+    git diff {BASE_SHA}..{HEAD_SHA}
+    ```
+
+    ## Review Priority
+
+    Review in this exact priority order:
+
+    1. Runtime bugs, data loss, broken CLI behavior, state corruption
+    2. Cross-task integration bugs
+    3. Missing edge cases not covered by tests
+    4. Test quality problems
+    5. Architecture and maintainability issues
+    6. Documentation defects that can mislead users or maintainers, omit
+       required operational facts, or contradict actual behavior
+
+    Do not report pure documentation polish, style preferences, or wording
+    tweaks. Do report documentation problems that create wrong usage, wrong
+    maintenance decisions, missing required commands, missing migration notes,
+    or false claims.
+
+    ## What to Check
+
+    **Runtime and state risk:**
+    - Can any command crash, hang, silently no-op, or report success incorrectly?
+    - Can repeated runs corrupt files, state, locks, indexes, caches, or config?
+    - Can user data, generated artifacts, branches, or worktrees be lost?
+    - Are filesystem, process, permission, platform, and concurrency errors handled?
+
+    **Integration risk:**
+    - Do task outputs match later task inputs?
+    - Do CLI flags, exported functions, filenames, state keys, and schemas align?
+    - Does the feature work as a complete workflow, not just as isolated pieces?
+    - Are old data, missing files, and partially completed states handled?
+
+    **Tests:**
+    - Do tests execute real behavior rather than only mocks or snapshots?
+    - Are failure paths, edge cases, repeat runs, and integration paths covered?
+    - Are the verification commands sufficient for the changed surface area?
+
+    **Architecture:**
+    - Is the implementation maintainable within existing module boundaries?
+    - Did the feature add avoidable coupling or hidden global state?
+    - Are abstractions justified by actual complexity?
+
+    **Documentation defects:**
+    - Does documentation contradict actual behavior?
+    - Are required user or maintainer steps missing?
+    - Would a future agent follow the docs and make the wrong change?
+
+    ## Output Format
+
+    ### Findings
+
+    #### Critical
+    [Must fix before finish: data loss, state corruption, broken workflow,
+    security issue, or reliable runtime failure]
+
+    #### Important
+    [Should fix before finish: integration bug, untested edge case, weak test
+    proving too little, misleading docs that affect usage or maintenance]
+
+    #### Minor
+    [Low-risk maintainability or clarity issues. No pure polish.]
+
+    For each finding:
+    - File:line reference
+    - What is wrong
+    - Why it matters
+    - How to fix or what evidence would resolve it
+
+    ### Coverage Notes
+    [Briefly state which runtime paths and tests you inspected.]
+
+    ### Assessment
+
+    **Ready for finish?** [Yes | No | With fixes]
+
+    **Reasoning:** [1-2 sentence risk-based assessment]
+
+    ## Critical Rules
+
+    **DO:**
+    - Read the actual diff, not only reports
+    - Focus on complete workflow behavior
+    - Treat tests as evidence to audit, not proof to trust blindly
+    - Report documentation defects that can mislead or omit required facts
+    - Give file:line references
+
+    **DON'T:**
+    - Repeat task-level nits unless they create whole-feature risk
+    - Report pure documentation polish
+    - Assume per-task reviews caught integration bugs
+    - Give a vague "looks good"
+    - Avoid a clear verdict
+```
+
+**Reviewer returns:** Findings by severity, Coverage Notes, Assessment.