@difflab/pi 0.7.1 → 0.8.0-rc.202610020810.d27e7fc

package/dist/tools/log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/tools/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAoBlF,eAAO,MAAM,aAAa,EAAE,cA0B1B,CAAC"}
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/tools/log.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAclF,eAAO,MAAM,aAAa,EAAE,cAmB1B,CAAC"}

package/dist/tools/review.d.ts

@@ -1,12 +1,6 @@
 import { type ToolDefinition } from '@earendil-works/pi-coding-agent';
-import { run } from '../extensions/processx';
 import { type ReviewComment, type ReviewDraft, type ReviewThreadRecord } from '../review';
 export declare function hasReviewDraft(comments: readonly ReviewComment[], body: string): boolean;
-export declare function reviewBrowserCommand(url: string, platform?: NodeJS.Platform): {
-    command: string;
-    args: string[];
-};
-export declare function openReviewUrl(url: string, execute?: typeof run, platform?: NodeJS.Platform): Promise<boolean>;
 export declare function partitionReviewComments(comments: readonly ReviewComment[], knownFingerprints: ReadonlySet<string>, model: string): {
     checkpointed: {
         source: ReviewComment;
@@ -36,7 +30,7 @@ export declare function partitionReviewComments(comments: readonly ReviewComment
 export declare function reviewResponseResolution(question: boolean, requested?: boolean): boolean;
 export declare function workingTreeReplyDraft(thread: ReviewThreadRecord, body: string): ReviewDraft;
 export declare function resolveReviewThread(comment: ReviewComment, threads: readonly ReviewThreadRecord[]): ReviewThreadRecord | undefined;
+export declare function assertRenderedReviewBody(body: string): void;
 export declare function workingTreeDiff(cwd: string): Promise<string>;
 export declare function createReviewTools(): readonly ToolDefinition[];
-export declare function syncLocalThreadArtifact(path: string, title: string, sessionSlug: string, threads: readonly ReviewThreadRecord[]): Promise<ReviewThreadRecord[]>;
 //# sourceMappingURL=review.d.ts.map

package/dist/tools/review.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/tools/review.ts"],"names":[],"mappings":"AAGA,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAKzG,OAAO,EAAE,GAAG,EAAc,MAAM,wBAAwB,CAAC;AACzD,OAAO,EAwBL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAC;AAwEnB,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAExF;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,GAAE,MAAM,CAAC,QAA2B;;;EAM7F;AAED,wBAAsB,aAAa,CACjC,GAAG,EAAE,MAAM,EACX,OAAO,GAAE,OAAO,GAAS,EACzB,QAAQ,GAAE,MAAM,CAAC,QAA2B,GAC3C,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,EACtC,KAAK,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;EAUd;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAExF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAY3F;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,kBAAkB,GAAG,SAAS,CAmBhC;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAalE;AAID,wBAAgB,iBAAiB,IAAI,SAAS,cAAc,EAAE,CAof7D;AAID,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAwB/B"}
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../src/tools/review.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAMzG,OAAO,EASL,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACxB,MAAM,WAAW,CAAC;AAwDnB,wBAAgB,cAAc,CAAC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAExF;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,EACtC,KAAK,EAAE,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;EAUd;AAED,wBAAgB,wBAAwB,CAAC,QAAQ,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,OAAO,CAExF;AAED,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,kBAAkB,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,CAY3F;AAED,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,aAAa,EACtB,OAAO,EAAE,SAAS,kBAAkB,EAAE,GACrC,kBAAkB,GAAG,SAAS,CAmBhC;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAW3D;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAalE;AAID,wBAAgB,iBAAiB,IAAI,SAAS,cAAc,EAAE,CAkV7D"}

package/dist/tools/setup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/tools/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAyBlF,eAAO,MAAM,eAAe,EAAE,cA8B5B,CAAC;AAEH,eAAO,MAAM,kBAAkB,EAAE,cA0B/B,CAAC"}
+{"version":3,"file":"setup.d.ts","sourceRoot":"","sources":["../../src/tools/setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAc,KAAK,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAwBlF,eAAO,MAAM,eAAe,EAAE,cA6B5B,CAAC;AAEH,eAAO,MAAM,kBAAkB,EAAE,cAyB/B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@difflab/pi",
-  "version": "0.7.1",
+  "version": "0.8.0-rc.202610020810.d27e7fc",
   "description": "Tools and skills for the pi coding agent",
   "repository": {
     "type": "git",
@@ -17,9 +17,6 @@
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
-  "bin": {
-    "diffpi": "./dist/cli.js"
-  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -57,9 +54,8 @@
   },
   "dependencies": {
     "@juicesharp/rpiv-ask-user-question": "^2.10.1",
-    "commander": "^14.0.0",
     "mdast-builder": "1.1.1",
-    "pi-mcp-adapter": "^2.33.0",
+    "pi-mcp-adapter": "^2.38.0",
     "remark-stringify": "11.0.0",
     "unified": "11.0.5",
     "zod": "^4.6.5"

package/skills/diffpi-doctor/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: diffpi-doctor
+description: Check and repair stale global Diffpi agent profiles after a Pi package update. Use when plan or review agents request removed diffpi_modes_* tools or their installed profiles differ from @difflab/pi.
+---
+
+# Diffpi Doctor
+
+1. Call `diffpi_doctor` with `apply: false` to inspect the bundled agent profiles against Pi's global agent directory. This check does not install packages, run full setup, or change settings.
+2. If any profile needs repair, call `diffpi_doctor` with `apply: true`. It updates only bundled `diffpi-*.md` agent profiles from the installed @difflab/pi package and backs up each replaced file. If the package or target cannot be read safely, stop and report the blocker.
+3. Report changed paths and backup location. In each affected Pi session, reload resources or start a new conversation if an old inline system prompt persists. Do not claim this repair validates, marks READY, or executes any plan.

package/skills/diffpi-setup/SKILL.md

@@ -30,7 +30,7 @@ ask_user_question({
       options: [
         {
           label: 'Allow',
-          description: 'Install mise, Node.js, Zellij, Helix, tuicr, and Context Mode when missing.',
+          description: 'Install mise, Node.js, Zellij, Helix, and Context Mode when missing.',
         },
         {
           label: 'Skip',
@@ -43,8 +43,8 @@ ask_user_question({
 });
 ```
 
-Map `None`, `Linear`, and `Jira` to `none`, `linear`, and `jira`. Infer the review forge from the current repository remote; do not ask about tuicr or a single forge during ordinary setup. Only when the user explicitly asks to install hosted VCS MCP integrations, ask a multi-select question for GitHub and GitLab and pass the selected values as `forges`; zero selections means no VCS MCP installation. If the user selects `Skip` or declines the questionnaire, stop without calling `diffpi_setup`. After successful setup, call `diffpi_reload` when the setup result says pi must restart.
+Map `None`, `Linear`, and `Jira` to `none`, `linear`, and `jira`. Infer the review forge from the current repository remote; do not ask about a single forge during ordinary setup. Only when the user explicitly asks to install hosted VCS MCP integrations, ask a multi-select question for GitHub and GitLab and pass the selected values as `forges`; zero selections means no VCS MCP installation. If the user selects `Skip` or declines the questionnaire, stop without calling `diffpi_setup`. After successful setup, call `diffpi_reload` when the setup result says pi must restart.
 
-When the user is using Zed, ask separately whether to bind `cmd-alt-r` to the `diffpi: tuicr review` task. Only pass `bindZedKey: true` when the user opts in; otherwise pass `false`.
+Do not configure Diffpi-managed Zed review keybindings; preserve manually owned editor configuration.
 
-Setup installs Diffpi's bundled agent Markdown into Pi's standard global agent directory. Explain that each default can run through the subagent plugin or as the current inline prompt. `/skill:mode` opens the structured picker. It also accepts `--include-skills`, one agent id, a qualified `skill:agent` id, or `clear`.
+Setup installs Diffpi's bundled agent Markdown into Pi's standard global agent directory. The agents run through the subagent plugin; no inline profile selection is required for plan or review workflows.

package/skills/plan/SKILL.md

@@ -1,31 +1,20 @@
 ---
-name: plan
-description: Create, revise, review, finalize, and execute live Diffpi plans with direct files and one verified plan reviewer.
-allowed-tools: read grep find write edit ask_user_question Agent get_subagent_result steer_subagent diffpi_modes_set diffpi_modes_status plan_verify bash ctx_execute ctx_execute_file watch_ci
+name: diffpi-plan
+description: Create, revise, validate, finalize, and execute live Diffpi plans. Use for natural-language requests to change an existing plan, apply feedback, or update plan tasks; inspect the named plan before editing and do not claim routing guarantees.
 ---
 
 # Plan
 
-`/plan` forwards raw arguments to this skill. Parse the first explicit verb (`init`, `new`, `update`, `annotate`, `finalize`, `go`, `help`); for unknown or empty input, infer a verb from a clear natural-language request. Use `help` only when neither verb nor intent is identifiable; when plan/intent is ambiguous, ask one structured material-decision question. Preserve the exact incoming user request for the Planner. Read the matching reference first. Keep the alias handler thin. Git and project tasks run through `bash` (or the upstream git skill); do not invent tool names for tasks, format, lint, test, CI, or push.
+Route the verb and remaining request to its workflow. Fuzzy-match recognizable natural language; treat argument shapes as hints, not rigid gates. Requests such as “update the cache plan with this feedback”, “revise PLAN.md”, and “apply review notes to the existing plan” should route to `update` when a unique existing plan can be identified. Metadata and examples improve discovery, but do not guarantee host routing; preserve the explicit `/skill:diffpi-plan` form when deterministic selection matters.
 
-## Roles and preflight
+| Input                                        | Workflow                                     |
+| -------------------------------------------- | -------------------------------------------- |
+| `init <slug> [--branch <branch>]`            | [init](references/workflows/init.md)         |
+| `new <slug> <request>`                       | [new](references/workflows/new.md)           |
+| `update <slug> <request>`                    | [update](references/workflows/update.md)     |
+| `validate <slug>`                            | [validate](references/workflows/validate.md) |
+| `finalize <slug>`                            | [finalize](references/workflows/finalize.md) |
+| `go <slug> [--mode no-commit\|commit\|push]` | [go](references/workflows/go.md)             |
+| `help`, missing or unrecognizable request    | [help](references/workflows/help.md)         |
 
-- **Planner** authors and repairs live `PLAN.md` and numbered briefs with frontier/high thinking.
-- **diffpi-plan-reviewer** is exactly one independent frontier/high, read/search-only child. It first calls `diffpi_modes_status` and returns actual model, thinking, and tools evidence, then reviews structure, parity, action labels, quality, risk, and Worker executability. Reject missing or unverifiable evidence; do not use a fallback reviewer.
-- **Orchestrator** owns go coordination, live-file checkboxes/status, project gates, Git, push, and CI. **Worker** edits only its declared source/test scope and never changes plan files or commits.
-
-For foreground authoring, call `diffpi_modes_set({agent: "planner"})` using the shared inline id (never `plan:planner`); on the next model turn call `diffpi_modes_status` and stop if the switch or evidence is unavailable. For foreground `go`, call `diffpi_modes_set({agent: "orchestrator"})` and verify its status on the next turn. `--bg` launches exactly one named same-session child with `Agent` (Planner for `init/new/update/finalize`, Orchestrator for `go`), passing the exact verb, target, cwd, mode, and `background: true`; remove `--bg`. The child never redispatches, asks questions, or falls back inline.
-
-## Live-file contract
-
-Plans live under the initiating nested Git root in one flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory. The date and slug are parts of ONE directory name, never nested `date/slug` directories. Resolve collisions before writing. Use ordinary `read`/`write`/`edit` calls, read every file back, and preserve intent, IDs, completed evidence, order, dependencies, scopes, and constraints. Document phase constraints in each phase's `PLAN.md` entry (use `None` if empty). Each brief puts its sole action-labeled, fenced `text` file tree under `## Files Affected` immediately after `## Objective` (never a bullet list); `## Implementation Constraints` is free-form with optional subheadings. Edit only live plan files; never managed records, plugin source, tests, or profiles. `INCOMPLETE` is a visible marker inside an open `DRAFT`, not a status enum.
-
-`new` and `update` run the stateless read-only `plan_verify` on the current files, then review the complete current draft with one reviewer profile. Repair actionable findings, rerun mechanical verification after each repair, and invoke the same named reviewer again in a fresh `Agent` call (never resume a finished child) within bounded attempts. They remain `DRAFT` after a successful review. Require the child to complete with an attested explicit PASS; partial, steered, stopped, missing, and BLOCKING reports never count. `finalize` and draft `go` write `READY` only after both a passing `plan_verify` on current files and that completed reviewer PASS; do not dispatch Workers or write ready after repairing a failed review without a new completed review. An already-ready plan is reread and mechanically verified too. `plan_verify` does not judge quality, change status, freeze files, or replace the reviewer. No retired managed-plan tools.
-
-## Execution
-
-`go --mode no-commit|commit|push` defaults to `no-commit`. The Orchestrator is the only writer of plan status/checkboxes and coordinates Workers. A draft gets one mechanical `plan_verify` check and one reviewer per pass; both must pass on current files before ready. Schedule a phase only after all prerequisites complete; derive each bounded Worker's task scope from its steps and the phase's sole Files Affected tree. Serialize tasks with overlapping or uncertain derived scopes; independent tasks may run concurrently only when scopes are unambiguously disjoint and prerequisites are satisfied. Run project format, lint, test, and CI checks via `bash`/`ctx_execute` as appropriate. On any failure, preserve the exact command/output, attempts, and affected role and block.
-
-With `commit`, after gates pass make one phase commit. With `push`, push it and call `watch_ci` for that exact SHA; do not push the next phase until settled. `--bg` has one child only and that child does not redispatch. No stateful plan tools.
-
-Read: [init](references/workflows/init.md), [new](references/workflows/new.md), [update](references/workflows/update.md), [annotate](references/workflows/annotate.md), [finalize](references/workflows/finalize.md), [go](references/workflows/go.md), [help](references/workflows/help.md).
+Follow the selected workflow. `new`, `update`, and `go` do not auto-validate; `finalize` validates before readiness, and `validate` is explicit and memory-only. For `init`, DRAFT `validate`, `finalize`, or `go` when no native subagents are available, follow [the explicit inline exception](references/workflows/inline-fallback.md) only after the caller obtains confirmation; never silently fall back.

package/skills/plan/references/design-quality.md

@@ -11,7 +11,7 @@ Build from repository evidence. Keep the result compact and useful to a Worker.
 
 ## Implementation brief
 
-- Give tasks ordered implementation steps. Add nested `Verify` bullets under the relevant task; verification is part of the task, not a separate task.
+- Give tasks ordered implementation steps. Add nested `Verify` bullets under the relevant task; verification is part of the task, not a separate task. Every Verify command must be executable when that task finishes: do not require a test file, build artifact, dependency, or command created only by a later task. Use an inline smoke check or move the test creation earlier when needed.
 - Put `## Files Affected` immediately after `## Objective` and before `## Tasks`. It is the sole phase-level file scope: include exactly one fenced `text` file tree with a directory root and branches whose file leaves start with `[ADD]`, `[MODIFY]`, `[REMOVE]`, `[MOVE from: old/path]`, or `[VERIFY]`. Do not replace the tree with Markdown bullets or add per-task file scopes. Include acceptance criteria for every task.
 - Write `## Implementation Constraints` as useful free-form implementation guidance. Add `### Required Libraries & Technology Choices`, `### Key Algorithm Specifications`, or `### Core Invariants` only when useful; do not require any of them. Do not restate or paraphrase the phase-wide guardrails in `PLAN.md` here; refer to the phase ID when a connection is needed.
 - Read back each file after writing it. Normal successive write/edit calls are intentional: incomplete drafts remain visible until the plan is ready.
@@ -20,9 +20,9 @@ Build from repository evidence. Keep the result compact and useful to a Worker.
 
 Template metadata such as managed revisions or snapshots is not part of the live-file contract. Leave historical plan files untouched; current plans use the direct-file format.
 
-After writing the current `PLAN.md` and all numbered briefs, independently invoke exactly one VERIFIED frontier/high-thinking `diffpi-plan-reviewer` in read-only mode. The reviewer checks structure and parity, action labels, whole-plan quality, consistency and risk, and whether every task is executable by a lightweight Worker without guessing, in one pass. Do not replace this with cheap separate reviewers or tiered checks.
+After writing the current `PLAN.md` and all numbered briefs, perform observed read-only structural verification, then invoke the independent `diffpi-plan-reviewer` exactly once per authoring cycle over the complete snapshot. Require the actual completed independent `diffpi-plan-reviewer` result, record its verdict and findings, and compare plan hashes and Git state around it; a reviewer mutation invalidates the round. The reviewer is instructed not to mutate but inherits ambient capabilities, so read-only behavior is a policy, not a sandbox.
 
-The Planner repairs actionable findings and reruns the same reviewer within bounded attempts. A passing review does not prove that source code implements the plan. `annotate` is optional human review; it does not replace the automated reviewer.
+The Planner documents each actionable finding and its disposition, repairs it, rereads changed files, and reruns only observed read-only structural verification. Do not automatically rerun the reviewer. Keep the plan DRAFT until explicit finalize/go checks completed review evidence and dispositions. A BLOCKING verdict remains BLOCKING even when repaired; a passing review does not prove source implementation. Human review is optional and is not a replacement for the automated round.
 
 ## Contracts and consequences
 

package/skills/plan/references/workflows/finalize.md

@@ -1,10 +1,14 @@
 # `/plan finalize`
 
-**Owner/tier:** Planner, frontier/high. **Tools:** read/write/edit, `diffpi_modes_set`, `diffpi_modes_status`, `plan_verify`, Agent, get_subagent_result, steer_subagent. **Child:** exactly one independent `diffpi-plan-reviewer`, frontier/high, read/search-only.
+## Parse arguments
 
-1. Select the shared inline profile with `diffpi_modes_set({agent: "planner"})` (not `plan:planner`) and verify `diffpi_modes_status` on the next turn; stop on unavailable switch or unverifiable evidence.
-2. Select one live plan. Reread `PLAN.md` and all numbered briefs.
-3. Run read-only `plan_verify` and repair any structural issues. Invoke exactly one reviewer for structure/parity, action labels, quality/risk, consistency, and Worker executability. Verify its attestation before trusting the report.
-4. If findings are actionable, repair the live files, rerun `plan_verify`, and invoke the same named reviewer profile again with a fresh `Agent` call (not `resume`) within bounded attempts. Only after a current mechanical PASS and a completed attested reviewer PASS, write `READY` to `PLAN.md`.
+Syntax: `finalize <slug>` (optional `--plan <plan-path>` or `--target <plan-path>`).
 
-**Effects:** only direct plan repairs and the `READY` marker change. Do not execute or freeze files. **Failure:** preserve evidence and remain `DRAFT`; report exact reviewer/preflight/error details. No fallback, redispatch, background questions, or retired plan tools.
+1. Infer readiness intent and unique target from explicit args/flags first, then natural language and repository context. Do not require an inferable slug. Ask `ask_user_question` in the caller for material ambiguity; send insufficient intent to [help](help.md).
+
+## Steps
+
+If DRAFT and no native subagents are available, ask for explicit confirmation in the caller and follow [the inline exception](inline-fallback.md); a passing inline structural and review/disposition validation under that recorded exception permits READY. Otherwise stop with a blocker. Finalize is the only automatic validation entry point.
+
+1. Resolve the initiating Git root, absolute PLAN.md and numbered briefs. If DRAFT, invoke [validate](validate.md) through its **one** separate frontier/high `diffpi-planner` background child with the resolved path, filling the self-contained fenced `text` prompt in validate.md before launch and collecting the completed result. Do not launch a second child or another reviewer. If validation is incomplete or blocked, leave DRAFT and report the blocker.
+2. The **calling agent** (not the child) checks the completed validation result against the current files, then makes the short DRAFT → READY transition and reads it back. If the plan is already READY, read it back without revalidation. Do not execute tasks. Report status and memory-only proof or exact blocker.

package/skills/plan/references/workflows/go.md

@@ -1,11 +1,31 @@
 # `/plan go`
 
-**Owner/tier:** Orchestrator, medium. **Tools:** read/write/edit, `diffpi_modes_set`, `diffpi_modes_status`, `plan_verify`, Agent, get_subagent_result, steer_subagent, bash, ctx_execute, ctx_execute_file, watch_ci. **Children:** one same-session Orchestrator for `--bg`; thereafter one bounded low-thinking Worker per eligible task; one frontier/high reviewer only when the plan is draft.
+## Parse arguments
 
-1. Parse `--mode no-commit|commit|push`; default is `no-commit`. Select the shared inline profile with `diffpi_modes_set({agent: "orchestrator"})` and verify `diffpi_modes_status` on the next turn. If switching or evidence fails, stop with the exact error. Git/project tasks and gates run through `bash` (or `ctx_execute` for large output); there are no `task`, `format`, `lint`, `test`, `ci`, `git`, or `push` tools.
-2. Select and reread the current live `PLAN.md` and all numbered briefs. Run `plan_verify` on that exact plan directory; if it reports issues, stop in its current state and repair through Planner before trying again. If `DRAFT`, invoke exactly one named `diffpi-plan-reviewer` per pass with `Agent(run_in_background:false)`; do not impose a short turn limit. Independently verify runtime attestation and require a **completed** child result with an explicit PASS and no BLOCKING findings. A `steered`, partial, stopped, missing, or failed result is NOT a pass. On findings, hand repairs to Planner, reread live files, rerun `plan_verify`, then invoke the same named reviewer profile in a fresh `Agent` call (not `resume`) within bounded attempts. Write `READY` and dispatch Workers ONLY after a current mechanical PASS and a completed attested reviewer PASS; otherwise leave `DRAFT` and stop with exact evidence. Do not launch a duplicate background child or recursively dispatch. If already `READY`, reread and verify current files as-is.
-3. The Orchestrator alone writes live plan checkboxes/status. Schedule a phase only after every prerequisite is complete. Derive a bounded Worker scope per task from that phase brief's sole fenced Files Affected tree and the task's steps; never invent separate per-task scope fields. Serialize when task-to-file ownership is uncertain or scopes overlap. Dispatch disjoint Workers concurrently only when prerequisites are complete and ownership is unambiguous. The Worker never edits plan files, commits, redispatches, asks questions, or falls back inline.
-4. Run the declared project format, lint, test, and CI gates through `bash`/`ctx_execute`. On Worker, gate, preflight, reviewer, or command failure, block; preserve the exact command/output, attempts, and affected role.
-5. In `no-commit`, continue only with verified gates. In `commit`, after all phase gates pass, make exactly one commit for that phase. In `push`, push that phase commit, obtain its exact SHA, and call `watch_ci` for that SHA; do not push or schedule the next phase until CI settles successfully.
+Syntax: `go <slug> [--mode no-commit|commit|push]` (optional `--plan <plan-path>` or `--target <plan-path>`).
 
-**Effects:** declared source/test changes plus serialized live-file status/checkboxes. Never edit plugin source or managed plan records. `--bg` launches one child only; it never redispatches.
+1. Infer execution intent, unique target and mode from explicit args/flags first, then natural language and repository context. Default mode to `no-commit`; never infer commit or push authorization from silence. Do not require an inferable slug. Ask `ask_user_question` in the caller for material ambiguity; send insufficient intent to [help](help.md).
+
+## Steps
+
+If no native subagents are available, ask for explicit confirmation in the caller and follow [the inline exception](inline-fallback.md) for DRAFT readiness and/or READY execution; otherwise stop with a blocker. Never silently execute inline. `/plan go` never invokes validation or a reviewer.
+
+1. Resolve the initiating Git root, the unique absolute PLAN.md and all numbered briefs. Scan shared plans for active or blocked canonical-worktree bindings before changing status; ask the caller to resolve an ambiguous target, another worktree's ownership, rebind, restart, or abandonment. If DRAFT, change only `**Status:** DRAFT` to `**Status:** READY`, reread it, and begin execution without `/plan validate`, structural checks, or a reviewer. If already READY, **skip validate** and skip readiness checks; a separate `finalize` is not required. Reread status. Bind the selected READY plan to the canonical worktree before dispatch. Do not send DRAFT to the orchestrator. Take `<plan-id>` from the selected PLAN.md parent directory, not from old log references in its text. Derive the relative filename `.diffpi/plan/<plan-id>/logs.jsonl`. Confirm that `realpath(<repo-root>/.diffpi/plan/<plan-id>)` equals `realpath(dirname(<absolute PLAN.md>))`, even if PLAN.md was selected through the shared store path; block if they differ. This makes the filename relative to the canonical Git root and places `logs.jsonl` directly beside PLAN.md. Do not create a `logs/` directory.
+2. Fill every placeholder with actual request, paths, derived log filename, and chosen mode before launch (no literal placeholders). Launch a medium `diffpi-orchestrator` background agent with ambient capabilities and this prompt:
+
+```text
+Execute this READY live plan under the user-approved policy. Do not run a plan reviewer or revalidate READY for readiness.
+- Exact request: {exact-request}
+- Initiating Git root: {repo-root}
+- Absolute READY PLAN.md path: {plan-path}
+- Absolute numbered brief paths: {brief-paths}
+- Relative log filename: {derived-log-filename} (the `logs.jsonl` sibling of the selected PLAN.md, relative to the canonical Git root)
+- Mode: {mode} (no-commit|commit|push)
+- Read PLAN.md and every brief; require READY. Own execution metadata and lifecycle, schedule phases after prerequisites, and persist actual results before more work.
+- Derive bounded task scopes from steps and each brief's sole action-labeled fenced `text` Files Affected tree; serialize uncertain/overlapping scopes, while disjoint source tasks may run concurrently. Targeted task-line edits are not atomic. Delegate each Worker the absolute PLAN.md path, exact unchecked task line and task ID/title, canonical execution root, and the exact derived relative `logs.jsonl` filename. Require `diffpi_log` calls with `cwd` set to the canonical execution root and `filename` set to that supplied relative path at start, meaningful milestones, verification, and completed/failed/partial return, using `label: progress` by default and `label: deviation` only for an actual departure. Never write new plan events under `logs/` or `.diffpi/logs/`; leave historical logs untouched. Workers edit only assigned source/test files plus their one exact task line; they must search for exactly one literal unchecked line, replace only that line after focused checks pass, reread it, and report a discrepancy for missing, duplicated, changed, or already-checked lines. Failed or partial work remains unchecked.
+- After each Worker, and at every phase barrier, reread PLAN.md, validate source and check evidence, and restore only supported completion marks lost to concurrent last-writer-wins edits. Logs and checkboxes alone never advance a phase.
+- Run project format, lint and tests after phase work; preserve failures, warnings and attempts; block on failed gates. In no-commit, do not commit or push. In commit, create exactly one phase commit after gates, do not push. In push, commit and push, then wait for settled CI on the exact observed SHA before the next phase. Block on unavailable exact-SHA monitoring, timeout, partial or failed CI. Local gates cannot be replaced by CI.
+- Return actual completed results or precise blockers, without background questions.
+```
+
+3. Report the job ID and actual completed result or precise background-capability blocker.

package/skills/plan/references/workflows/help.md

@@ -1,7 +1,23 @@
 # `/plan help`
 
-**Owner/tier:** User, read-only. **Tools:** read/grep/find only. **Children:** none.
+## Parse arguments
 
-Explain the verbs and ownership: `init` creates an `INCOMPLETE` live draft; `new` creates a complete plan; `update` edits one selected plan; `annotate` is optional human tuicr/direct-file review; `finalize` reviews and marks `READY`; `go` reviews drafts then orchestrates execution; `help` does nothing. Explain `--bg` launches exactly one named same-session Planner or Orchestrator child with the exact verb/target/cwd/commitMode, without redispatch or questions.
+Syntax: `help` (no flags or positional arguments required).
 
-**Effects:** none. **Failure:** unknown or missing input returns this help; no files, reviewer, dispatch, or managed plan calls.
+1. Match `help`, a missing/unrecognizable verb, or genuinely insufficient intent. Fuzzy-match recognizable natural-language plan requests to their verb before showing help. Do not treat an inferable missing positional argument as insufficient; give explicit arguments/flags precedence over request/repository inference, then safe defaults.
+
+## Steps
+
+1. Show the complete usage below for explicit help or truly unrecognizable/insufficient intent. Identify any invalid argument in the error context without losing the original request.
+
+```text
+/plan init <slug> [--branch <branch>]
+/plan new <slug> <request>
+/plan update <slug> <request>
+/plan validate <slug> [--plan <plan-path>]
+/plan finalize <slug>
+/plan go <slug> [--mode no-commit|commit|push]
+/plan help
+```
+
+2. Describe these argument shapes as guidance rather than rigid gates; send a recognizable request to its verb for inference. Include examples: “update the existing API plan with this feedback” and “apply review notes to PLAN.md” route to `update` when the target is unique. Explain that metadata and examples improve discovery but cannot guarantee host routing; use `/skill:diffpi-plan update <slug> <request>` when exact routing is needed. Make no plan changes.

package/skills/plan/references/workflows/init.md

@@ -1,10 +1,27 @@
 # `/plan init`
 
-**Owner/tier:** Planner, frontier/high. **Tools:** read/write/edit/find/grep, `diffpi_modes_set`, `diffpi_modes_status`. **Children:** none.
+## Parse arguments
 
-1. Select the shared inline profile with `diffpi_modes_set({agent: "planner"})` (not `plan:planner`); on the next turn verify `diffpi_modes_status`. If either call or evidence is unavailable, stop with the exact error.
-2. Resolve the initiating nested Git root and unique flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory (one date-prefixed name, not `date/slug`). Inspect collisions before creating anything; on collision, stop without overwriting.
-3. Successively create the live directory, `PLAN.md`, and phase scaffolds with ordinary writes. Put `INCOMPLETE` in the visible `DRAFT` document; it is a marker, not a status enum.
-4. Read every created file back and report paths.
+Syntax: `init <slug> [--branch <branch>]` (optional target/issue inferred from request).
 
-**Effects:** only live plan files change. **Failure:** preserve partial files and report the exact path, command, and error; do not dispatch or ask questions in background. Foreground may ask one material goal question before writing.
+1. Infer scaffold intent, slug, branch and issue from explicit args/flags first, then natural language and the initiating Git root, then safe defaults. A positional slug is not required when inferable. Ask `ask_user_question` in the caller only for material ambiguity; send insufficient intent to [help](help.md).
+
+## Steps
+
+If no native subagents are available, ask for explicit confirmation in the caller and follow [the inline exception](inline-fallback.md); otherwise stop with a blocker. Do not silently scaffold inline. The scaffold may include sibling `revisions/`, but must not create a `logs/` directory. `/plan go` creates `logs.jsonl` beside PLAN.md on its first log append.
+
+1. Resolve the unique initiating Git root and absolute PLAN.md target. Replace every placeholder below with actual values (use `none` for absent issue/branch); never pass literal placeholders. Launch a low `diffpi-worker` background agent with this bounded prompt and ambient capabilities:
+
+```text
+Scaffold an incomplete live plan, and do nothing else.
+- Exact request: {exact-request}
+- Initiating Git root: {repo-root}
+- Absolute PLAN.md target: {plan-path}
+- Branch and issue: {branch-and-issue}
+- Check collisions before writing. Use one flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory, never `date/slug`.
+- Create PLAN.md and phase scaffolds with ordinary writes, DRAFT and a visible INCOMPLETE marker (not a status). Do not create a `logs/` directory or an empty log file; execution later appends to `logs.jsonl` beside PLAN.md. This init-only exception permits plan-file creation, but not status transitions beyond the initial DRAFT scaffold, source edits, execution or review.
+- Reread created files. Do not validate or launch a reviewer for the incomplete scaffold.
+- Return created paths or the exact failed operation/path/error; return unresolved decisions as blockers without interactive questions.
+```
+
+2. Report the job ID and actual completed result or precise background-capability blocker. Do not scaffold in the caller.

package/skills/plan/references/workflows/inline-fallback.md

@@ -0,0 +1,9 @@
+# Explicit inline exception when no native subagents exist
+
+Apply this policy only to `init`, `new`, `update`, DRAFT `validate`, `finalize`, or `go` when **no native subagent mechanism is available** to the initiating conversation. Try any available attached subagent dispatch/completion transport before treating native subagents as unavailable; a missing named tool alone is not proof. A failed reviewer, gate, implementation, structural check, CI check, or unavailable particular model is **not** an excuse to switch inline. Do not silently fall back after a child is queued, stopped, incomplete, or fails; return its actual blocker.
+
+Before substantive inline work, the **calling agent** must ask `ask_user_question` and receive explicit confirmation for the inline exception. State that this is a last resort with reduced isolation/model-tier guarantees and that review in the same thread is **not independent**. Offer a choice to proceed inline or stop; a declined, abandoned, or unavailable questionnaire (including in a background child or noninteractive eval) means **stop and report the blocker to the initiating thread**. Do not infer consent from the request, a prior unrelated approval, or silence. Record the confirmation and its scope with the authoring-cycle evidence; one confirmation can cover the named operation and its required steps, but a later user-initiated update requires confirmation again. Noninteractive evals still require an actual completed child; they cannot opt into inline fallback.
+
+After confirmation, perform the **same selected workflow** in the caller, with the same paths, collision checks, statuses, role boundaries, snapshots, Git evidence, findings, repairs, one-round budget, gates, CI and commit/push authorization. For `init`, create only an incomplete DRAFT scaffold. For `new` and `update`, make requested draft edits without automatic validation; `update` must preserve completed work and earlier evidence. For DRAFT `validate`, first run a working read-only structural check and repair structural defects as in the normal workflow. Capture every plan path/hash and Git HEAD, porcelain status, diff and untracked inventory before the review and again immediately afterward. Perform **one distinct read-only inline Plan Reviewer checklist pass** on the whole draft per authoring cycle, checking structure and parity, phase prerequisites/constraints, tree placement, ordered steps and temporally runnable Verify commands, intent/design consistency, risks and Worker executability. Keep provenance as **INLINE reviewer (same thread, not independent)**, the actual verdict and line-specific BLOCKING/CONSIDER/NOTE findings (or explicit empty list), reviewed and post-review snapshots, Git evidence, and concrete dispositions in the validation response/memory only; never write validation proof into PLAN.md or another durable plan artifact. Never fabricate a child ID, completed subagent, independent verdict or independent PASS. Reuse a valid completed round from the cycle rather than automatically reviewing a second time. Reviewer pass is read-only: if the pass mutates files or evidence changes unexplained, invalidate it. Repair actionable findings outside that pass, preserve an original BLOCKING verdict, reread and rerun **only** the structural check; do not call repaired content reviewer-approved. Failed structural checks, unresolved BLOCKING findings or unexplained changes block readiness.
+
+For `finalize`, after **passing inline structural verification and inline review/disposition validation under the recorded approved exception**, the caller may mark DRAFT → READY and reread it. This exception does not waive any failed check. For DRAFT `go`, mark only DRAFT → READY and reread it before execution; do not run validation, structural readiness checks, or a reviewer. Already-READY `go` skips readiness validation too. If no native subagents remain for execution, the confirmed caller performs Orchestrator and bounded Worker steps inline with serialized uncertain/overlapping scopes and the same phase gates, no-commit/commit/push policy and exact-SHA CI requirements. Derive `.diffpi/plan/<plan-id>/logs.jsonl` from the selected PLAN.md parent directory; confirm that `realpath(<root>/.diffpi/plan/<plan-id>)` equals `realpath(dirname(<absolute PLAN.md>))`, so the file is its sibling through the managed `.diffpi` link. Call `diffpi_log` with `cwd` set to the canonical execution root and `filename` set to this relative path at each required milestone. Do not write new events under a `logs/` directory, even if old plan text names one. Do not claim inline work was delegated or independently reviewed. If the user declines or cannot be asked, return the blocker rather than modifying the plan or executing work.

package/skills/plan/references/workflows/new.md

@@ -1,11 +1,26 @@
 # `/plan new`
 
-**Owner/tier:** Planner, frontier/high. **Tools:** read/write/edit/find/grep, `diffpi_modes_set`, `diffpi_modes_status`, `plan_verify`, Agent, get_subagent_result, steer_subagent. **Child:** exactly one independent `diffpi-plan-reviewer`, frontier/high, read/search-only.
+## Parse arguments
 
-1. Select the shared inline profile with `diffpi_modes_set({agent: "planner"})` (not `plan:planner`) and verify `diffpi_modes_status` on the next turn; stop on unavailable switch or unverifiable evidence.
-2. Resolve the initiating nested Git root and a flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory (one date-prefixed directory, not `date/slug`). Check collisions and stop before writing an existing match. Research only after selection.
-3. Successively write `PLAN.md` and one numbered brief per phase. Document each phase's high-level constraints in `PLAN.md` (use `None` if empty) without copying implementation details there. Do not repeat or paraphrase those phase constraints in a brief; reference the phase ID instead. Give each brief a `## Files Affected` section immediately after `## Objective` and before `## Tasks`, containing exactly one fenced `text` action-labeled file tree rather than Markdown bullets, with free-form `## Implementation Constraints` after tasks; optional implementation subheadings are not mandatory. Preserve phase/task parity, dependencies, scopes, and acceptance criteria; read every file back.
-4. Run read-only `plan_verify` against the live directory and repair structural issues before invoking exactly one reviewer. Verify its attestation and review the complete current draft. Repair actionable findings, rerun `plan_verify`, then invoke the same named reviewer profile in a fresh `Agent` call (not `resume`) within bounded attempts.
-5. Leave the plan marked `DRAFT` after a successful review. Do not write `READY`; only `/plan finalize` or draft `/plan go` may do that.
+Syntax: `new <slug> <request>` (optional `--target <plan-path>`, `--issue <id>`, `--issue-url <url>`).
 
-**Failure:** preserve visible files and exact evidence; block on collision, failed/unverifiable review, or exhausted repairs. Background never asks questions or redispatches.
+1. Infer creation intent, slug, target, branch, issue and requested outcome from explicit args/flags first, then natural language and repository context, then safe defaults. Do not require inferable positionals. Ask `ask_user_question` in the caller for material ambiguity; send insufficient intent to [help](help.md).
+
+## Steps
+
+If no native subagents are available, ask for explicit confirmation in the caller and follow [the inline exception](inline-fallback.md); otherwise stop with a blocker. Never silently draft inline. The draft may include sibling `revisions/`, but must not create a `logs/` directory. `/plan go` creates `logs.jsonl` beside PLAN.md on its first log append.
+
+1. Resolve the initiating Git root and unique absolute PLAN.md target. Fill every placeholder with actual values before launch (use `none` for absent context). Launch a frontier/high `diffpi-planner` background agent with ambient capabilities:
+
+```text
+Draft a complete live plan; do not dispatch a reviewer or mark READY.
+- Exact request: {exact-request}
+- Initiating Git root: {repo-root}
+- Absolute PLAN.md target, branch and issue: {plan-path-and-context}
+- Reject collisions; use a flat `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` directory.
+- Inspect the repository and resolve design questions. Write PLAN.md with intent, requirements, design, references, stable phase/task IDs, phase prerequisites and constraints (or None), and flat task checkboxes.
+- Write every numbered brief. Put exactly one action-labeled fenced `text` Files Affected tree immediately after Objective. Include ordered task steps, Verify commands runnable before later tasks, acceptance criteria and free-form Implementation Constraints. Do not create `logs/` or an empty log file; execution later appends to `logs.jsonl` beside PLAN.md.
+- Reread all files. Leave DRAFT. Return paths and completed result or exact blocker; do not ask background questions.
+```
+
+2. Collect the completed draft result. Do not run structural validation or dispatch a reviewer automatically. Leave DRAFT and report the created paths and actual result; the user may request [validate](validate.md) or [finalize](finalize.md) explicitly.

package/skills/plan/references/workflows/update.md

@@ -1,10 +1,28 @@
 # `/plan update`
 
-**Owner/tier:** Planner, frontier/high. **Tools:** read/write/edit/find/grep, `diffpi_modes_set`, `diffpi_modes_status`, `plan_verify`, Agent, get_subagent_result, steer_subagent. **Child:** exactly one independent `diffpi-plan-reviewer`, frontier/high, read/search-only.
+## Parse arguments
 
-1. Select the shared inline profile with `diffpi_modes_set({agent: "planner"})` (not `plan:planner`) and verify `diffpi_modes_status` on the next turn; stop on unavailable switch or unverifiable evidence.
-2. Select exactly one plan by repository-root path. Read current `PLAN.md`, every numbered brief, and the request. Preserve intent, IDs, completed evidence, ownership, dependencies, and order.
-3. Research affected code, then successively edit/write authoritative live files and read each back. Keep the marker `DRAFT` (and any `INCOMPLETE` marker) until explicit finalize or go.
-4. Run read-only `plan_verify` against the current plan directory and repair structural issues. Invoke exactly one reviewer over the complete current plan. Verify actual model, thinking, and tools evidence. Repair actionable findings, rerun `plan_verify`, and reinvoke that named reviewer profile with a fresh `Agent` call (not `resume`) within bounded attempts.
+Syntax: `update <slug> <request>` (optional `--plan <plan-path>` or `--target <plan-path>`).
 
-**Failure:** preserve visible edits and report exact evidence; block on ambiguity, unavailable role/reviewer evidence, failed review, or exhausted repair. No fallback reviewer, redispatch, or background questions.
+1. Infer revision intent, unique target and requested edits from explicit args/flags first, then natural language and repository context. Recognize requests such as “update the existing plan with this feedback”, “revise PLAN.md”, and “apply these review notes to the cache plan” as update intent. Resolve a unique plan by slug, explicit path, branch, or repository context; do not require inferable positionals. Treat metadata and natural-language examples as routing guidance, not a guarantee. Ask `ask_user_question` in the caller for material ambiguity; send insufficient intent to [help](help.md).
+
+## Steps
+
+When the request names an existing plan but omits a slug, inspect repository plan directories and use the only unambiguous match. Do not silently choose among multiple plans; ask the caller to select one.
+
+If no native subagents are available, ask for explicit confirmation in the caller **before edits** and follow [the inline exception](inline-fallback.md); otherwise stop with a blocker. Never silently revise inline.
+
+1. Resolve the initiating Git root, absolute PLAN.md and numbered brief paths. Fill all placeholders with actual values before launch. Before substantive edits, the planner must append the exact supplied feedback under `### Feedback`, reread PLAN.md, and archive the complete feedback-bearing PLAN.md plus every numbered brief under `.diffpi/plan/<plan-id>/revisions/rev-NNNN/`. The archive is create-only inside the live plan directory: reuse an existing directory only after byte-for-byte verification of PLAN.md and the complete brief set; otherwise stop for reconciliation. Never overwrite an archive. Launch `diffpi-planner` on its configured frontier model with explicit **low** thinking and `inherit_context: true` (fork the parent conversation at launch), in the background with ambient capabilities:
+
+```text
+Revise only the requested unfinished plan work in a new user-initiated authoring cycle. Do not validate or dispatch a reviewer.
+- Exact requested edits: {exact-request}
+- Initiating Git root: {repo-root}
+- Absolute PLAN.md path: {plan-path}
+- Absolute numbered brief paths: {brief-paths}
+- Read PLAN.md and all briefs. Preserve stable IDs, dependencies, completed work, prior reviewed snapshots, verdicts, dispositions and execution history. Amend only draft/pending/blocked work; preserve INCOMPLETE if still incomplete.
+- Research affected code and make only requested changes. Keep phase prerequisites/constraints (or None), flat task checkboxes and exactly one action-labeled fenced `text` Files Affected tree immediately after Objective in each brief. Keep ordered steps, acceptance criteria, temporally runnable Verify commands and free-form Implementation Constraints.
+- Reread files, leave DRAFT, return changed paths and exact result or blocker. Do not ask background questions.
+```
+
+2. Collect the completed edit result. Do not launch validation or a reviewer automatically. Leave DRAFT and report changed paths and the exact result; the user may request [validate](validate.md) or [finalize](finalize.md) explicitly. Do not discard earlier evidence.

package/skills/plan/references/workflows/validate.md

@@ -0,0 +1,31 @@
+# `/plan validate`
+
+## Parse arguments
+
+Syntax: `validate <slug>` (optional `--plan <plan-path>` or `--target <plan-path>`).
+
+1. Infer validation intent and a unique target from explicit args/flags first, then natural language and repository context. Do not require an inferable slug. Ask `ask_user_question` in the caller for material ambiguity; send insufficient intent to [help](help.md).
+
+## Steps
+
+If DRAFT and no native subagents are available, ask for explicit confirmation in the caller and follow [the inline exception](inline-fallback.md), including a distinct read-only inline Plan Reviewer pass; otherwise stop with a blocker. Never claim an independent review for inline work.
+
+1. Resolve the initiating Git root, absolute PLAN.md and every numbered brief path. If the plan is inactive READY, perform the manual validation below; do not return early. READY does not require revalidation for go. For DRAFT, fill all placeholders with real values before launch (use `none` where appropriate). Validation is explicit and memory-only. Do not write validation proof, snapshots, findings, dispositions, or verdicts to PLAN.md or any plan artifact. Launch a separate frontier/high `diffpi-planner` background agent with ambient capabilities:
+
+```text
+Validate this DRAFT without marking it READY or executing tasks.
+- Exact request: {exact-request}
+- Initiating Git root: {repo-root}
+- Absolute PLAN.md path: {plan-path}
+- Absolute numbered brief paths: {brief-paths}
+- Read PLAN.md and all numbered briefs. Run a working read-only structural check of the whole current draft; name the capability used or block if none works. Check task ID/title parity, prerequisites/constraints, sole action-labeled fenced `text` Files Affected tree immediately after Objective, ordered tasks and temporally runnable Verify commands. Repair structural errors only within the plan and rerun the structural check.
+- Identify this authoring cycle. If one independent completed whole-plan diffpi-plan-reviewer round already exists for the cycle with valid before/after memory-only proof, reuse it; never dispatch a second reviewer on repeated validate or after repairs. Otherwise capture every plan file path/hash plus Git HEAD, porcelain status, diff and untracked inventory in memory, then launch at most ONE independent frontier/high diffpi-plan-reviewer background agent. Fill its prompt with the actual absolute plan/brief paths, hashes and Git evidence before dispatch:
+
+  Reviewer task: Read PLAN.md and every numbered brief at {reviewed-plan-paths-and-hashes} with Git evidence {git-head-status-diff-untracked}. Make no mutations. Review structure, parity, phase prerequisites/constraints, Files Affected tree placement, ordered steps, temporally runnable Verify commands, intent/design consistency, risks and lightweight Worker executability. Return completed verdict and findings; each finding includes file, line, BLOCKING/CONSIDER/NOTE severity, reason and concrete fix. Return an explicit empty findings list for PASS. Do not claim source implementation is verified.
+
+- Require the reviewer's actual completed result, not queued/partial/stopped output or self-reported identity. Compare plan hashes and Git HEAD/status/diff/untracked inventory immediately after review. Invalidate the round on reviewer mutation, incomplete evidence or unexplained change. Use any real available dispatch/completion implementation, not one named tool prerequisite.
+- Keep the reviewed snapshot, Git evidence, completed verdict, findings and dispositions in the validation result's response/memory only. Keep proof in memory only; do not write it into PLAN.md, References, revisions, or logs. Repair actionable findings only when explicitly requested by the validation workflow, reread changed files and rerun ONLY the read-only structural check. Preserve the original BLOCKING verdict; never claim reviewer PASS for repaired content. A later user-initiated change starts a new authoring cycle, but repeated validation does not.
+- Return validation PASS only when structural checks pass, the one completed review round and memory-only proof are valid, every BLOCKING finding has a resolved disposition, and all post-review changes are explained. Otherwise return precise blockers. Leave DRAFT; no background questions.
+```
+
+2. Collect the actual completed result, not only a job ID. Report validation verdict, reviewed and current snapshots, dispositions or blockers. Do not mark READY.

package/skills/review/SKILL.md

@@ -1,15 +1,23 @@
 ---
-name: review
-description: Create, edit, review, address, publish, complete, and merge GitHub/GitLab or local tuicr reviews.
-allowed-tools: read ask_user_question Agent get_subagent_result steer_subagent bash review_context review_status review_new review_open review_edit review_diff review_gates review_submit review_add_comment review_comments review_respond review_publish review_complete review_merge review_launch_ui diffpi_template
+name: diffpi-review
+description: Create, edit, review, address, publish, complete, and merge GitHub/GitLab or local Markdown reviews.
 ---
 
 # Review
 
-Parse the first non-flag argument as the verb; preserve remaining arguments. Aliases: `create`/`draft` → `new`, `launch` → `auto`, `ready` → `publish`, `close` → `complete`, `land` → `merge`. Unknown or empty verbs show [help](references/workflows/help.md). `--local` selects tuicr working-tree state and must be preserved; otherwise use the selected forge. `--bg` removes itself and launches exactly one named same-session background Orchestrator with verb, arguments, cwd, exact target/backend, and `background: true`; it must not redispatch or ask questions. Foreground execution stays in this turn and never changes inline mode.
+Local reviews are ordinary Markdown files. For local work, read [the packaged template](templates/REVIEW.md) and [review conventions](references/review-standards.md), then use the native `read`, `write`, `edit`, and shell operations. Resolve a unique plan or ticket, ask on ambiguity, inspect existing files before best-effort numbering, and preserve existing finding IDs, replies, and checkbox state. Remote reviews use forge-backed tools and templates. Do not introduce a parser, backend, allocator, lock, sidecar, or database.
 
-Read the selected reference before acting. Every target-bearing workflow calls `review_context` FIRST, then uses the same target, backend, `local` value, and cwd for every call; help is informational and may run without a target or repository. Tools own target selection, lifecycle, templates, comments, replies, publication, and forge calls. Do not reimplement them or invent tools. Report failed and skipped gates as such. Keep remote findings/comments pending until publish; local work remains tuicr state until promotion or completion. Do not publish, complete, merge, or resolve threads from auto/address.
+Infer the verb from the request. Route it with its arguments to the selected workflow:
 
-The foreground high-tier Reviewer owns only auto judgment and address classification/replies; lifecycle coordination belongs to the coordinator, which owns new/open/status/edit/publish/complete/merge and does not delegate these to a Reviewer child. In background mode the Orchestrator retains lifecycle coordination and delegates exactly one bounded high-tier Reviewer judgment child for auto/address only; the child does not edit source or recurse. `address` lets the Reviewer classify threads and delegate bounded, non-overlapping source edits to low-thinking Workers. Workers never commit, reply, publish, complete, merge, or resolve. Remote code changes are committed by the coordinator through the upstream `/git commit --no-push` workflow after checks and before replies (use `--atomic` for separate logical commits); local changes remain uncommitted. Address replies always use `review_respond(resolve:false)`; local thread resolution remains user-owned.
+| Command                                                                         | Reference                                    |
+| ------------------------------------------------------------------------------- | -------------------------------------------- |
+| `new [title] [--intent text] [--base branch] [--local]`                         | [new](references/workflows/new.md)           |
+| `auto [target] [--local]`                                                       | [auto](references/workflows/auto.md)         |
+| `address [target] [--local]`                                                    | [address](references/workflows/address.md)   |
+| `publish [target] [--local] [--comment\|--approve\|--request-changes\|--close]` | [publish](references/workflows/publish.md)   |
+| `complete [target] [--local\|--approve\|--reject\|--close]`                     | [complete](references/workflows/complete.md) |
+| `merge [target]`                                                                | [merge](references/workflows/merge.md)       |
+| `edit [target] [--local]`                                                       | [edit](references/workflows/edit.md)         |
+| `help`                                                                          | [help](references/workflows/help.md)         |
 
-References: [auto](references/workflows/auto.md), [new](references/workflows/new.md), [open](references/workflows/open.md), [status](references/workflows/status.md), [edit](references/workflows/edit.md), [address](references/workflows/address.md), [publish](references/workflows/publish.md), [complete](references/workflows/complete.md), [merge](references/workflows/merge.md), [help](references/workflows/help.md). `review_merge` is GitHub-only; approval by the current user is not required.
+Map `create`/`draft` → `new`, `launch` → `auto`, `ready` → `publish`, `close` → `complete`, `land` → `merge`. Local `publish` and `complete` are unsupported; reject them explicitly. Remote edit reports the URL and never launches a browser. Route missing or unrecognizable intent → [help](references/workflows/help.md). For substantive work without native subagents, use the selected workflow's [foreground fallback](references/workflows/foreground-fallback.md) only after explicit confirmation.

package/skills/review/references/review-standards.md

@@ -1,6 +1,14 @@
 # Review standards
 
-Use these rules for review and address workflows.
+Use these rules for review and address workflows. Local reviews use the packaged `templates/REVIEW.md` file as a starting point and remain human-readable Markdown; remote reviews continue to use forge-backed tools.
+
+## Local Markdown conventions
+
+- Create or select one `.diffpi/review/YYMMDD-{slug}/REVIEW-{n}.md` file after inspecting existing files. Numbering is best effort, not an atomic allocator; ask when the plan or ticket match is ambiguous.
+- Keep the plain `Status` field and stable finding IDs (`F-001`, `F-002`, ...). Use `[ ]` for open findings and `[x]` only after focused verification proves the resolution.
+- Record pasted review text directly in the file. Preserve existing replies, evidence, IDs, and finding state. Add replies instead of rewriting history.
+- Leave blocked or partial findings open and explain the blocker in `Status Notes`. Local publish and complete are unsupported.
+- Do not claim that static tests prove agent execution semantics; use a manual temporary-directory exercise when a workflow needs behavioral confirmation.
 
 ## Operational workflow rules
 

package/skills/review/references/workflows/address.md

@@ -1,10 +1,17 @@
 # address
 
-**Owner/tier:** foreground high-tier Reviewer-coordinator; background Orchestrator coordinates and delegates bounded low-thinking Workers. Reviewer classifies threads; Workers may edit source only.
+## Parse arguments
 
-1. Call `review_context` first with exact target/backend/local, then `review_comments` with the same values.
-2. Reviewer classifies every thread and groups only bounded, non-overlapping requested source changes. Delegate those edits to Workers. Workers never commit, reply, publish, complete, merge, resolve, or recurse. Questions remain open. Report unmatched threads and blockers.
-3. Run `review_gates` after edits and report failures/skips. For remote code changes, coordinator invokes upstream `/git commit --no-push` after checks and before replies (`--atomic` for separate logical commits). Local changes stay uncommitted.
-4. Coordinator calls `review_respond` for every outcome with `resolve:false`; never resolve or delete threads. With local state, optionally call `review_launch_ui` after replies. Do not publish, complete, or merge.
+Accept `address [target] [--local]`. Resolve one unaddressed local file by explicit path or unique plan/ticket match; ask `ask_user_question` when matching is ambiguous. If no file exists but review text is pasted, create a file from `templates/REVIEW.md` and immediately address its findings.
 
-Report fixed, committed, answered, unresolved, skipped, and failed counts; resolved is always zero.
+## Local steps
+
+Launch a background `diffpi-reviewer` for classification when native subagents are available; it delegates bounded source edits to `diffpi-worker` and keeps lifecycle state untouched.
+
+1. Read the selected REVIEW.md and preserve existing replies, IDs, evidence, and checkbox state.
+2. For each finding, inspect the source and run focused verification. Mark `[x]` only when verified; leave blocked or partial findings `[ ]` and explain the blocker in `Status Notes`.
+3. Append an explicit reply/outcome and evidence to the Markdown file. Do not resolve or delete findings, publish, complete, invoke a backend, or use a parser.
+
+## Remote steps
+
+Call `review_context`, delegate review judgment to `diffpi-reviewer`, then use existing remote comments and gates. Keep threads open and do not publish, complete, merge, or resolve.

package/skills/review/references/workflows/auto.md

@@ -1,9 +1,17 @@
 # auto
 
-**Owner/tier:** foreground high-tier Reviewer-coordinator; background Orchestrator coordinates and delegates one high-tier Reviewer child. No source edits.
+## Parse arguments
 
-1. Parse target and `--local` (and let the skill handle `--bg` before this file). Call `review_context` first, then keep exact target/backend/local/cwd.
-2. Call `review_new`; if the review already exists, call `review_edit`. Call `review_gates`, then `review_diff`.
-3. Reviewer judges intent, correctness, edge cases, quality, minimality, docs, and duplicate findings. Report every gate failure or skip. Submit only grounded findings with `review_submit`; remote findings remain pending. Do not call publish, complete, merge, or resolve threads.
+Accept `auto [target] [--local]`. Resolve the target explicitly; ask when local plan/ticket matches are ambiguous.
 
-On missing target/backend, unsupported forge, failed creation, or failed gates, preserve state, report exact evidence, and stop or continue only with clearly reported skipped checks. Return artifact, backend, gate results, and finding count.
+## Local steps
+
+Launch a background `diffpi-reviewer` for judgment when native subagents are available; it edits only the selected local Markdown file and never changes lifecycle state.
+
+1. Inspect existing `.diffpi/review/**/REVIEW-*.md` files and select the matching file without fuzzy merging. If none exists, create one using the `new --local` procedure and `templates/REVIEW.md`.
+2. Read the diff and review standards. Write findings directly into the selected Markdown file with stable IDs and `[ ]` checkboxes. Preserve existing findings, replies, evidence, and state; never overwrite history or merge similar findings automatically.
+3. Record skipped gates and blockers honestly, then report the exact file path. Local review files remain uncommitted unless the caller requests otherwise.
+
+## Remote steps
+
+Call `review_context`, use `review_new` or `review_edit` as appropriate, run gates and diff review, and stage findings through the existing remote review tools. Do not use local file behavior for a remote target.