@difflab/pi 0.8.0 → 0.9.0

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.8.0",
+  "version": "0.9.0",
   "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,7 +54,6 @@
   },
   "dependencies": {
     "@juicesharp/rpiv-ask-user-question": "^2.10.1",
-    "commander": "^14.0.0",
     "mdast-builder": "1.1.1",
     "pi-mcp-adapter": "^2.38.0",
     "remark-stringify": "11.0.0",

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. The agents run through the subagent plugin; no inline profile selection is required for plan or review workflows.

package/skills/plan/SKILL.md

@@ -1,21 +1,20 @@
 ---
 name: diffpi-plan
-description: Create, revise, review, finalize, and execute live Diffpi plans with direct files and one verified plan reviewer.
+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
 
-Route the verb and remaining request to its workflow. Fuzzy-match recognizable natural language; treat argument shapes as hints, not rigid gates.
+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.
 
 | 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)     |
-| `annotate <plan-path>`                       | [annotate](references/workflows/annotate.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)         |
 
-Follow the selected workflow. For `init`, `new`, `update`, 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.
+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

@@ -22,7 +22,7 @@ Template metadata such as managed revisions or snapshots is not part of the live
 
 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 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. `annotate` is optional human review, not a replacement for the automated round.
+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

@@ -8,7 +8,7 @@ Syntax: `finalize <slug>` (optional `--plan <plan-path>` or `--target <plan-path
 
 ## 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.
+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 and durable evidence 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 evidence or exact 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

@@ -8,10 +8,10 @@ Syntax: `go <slug> [--mode no-commit|commit|push]` (optional `--plan <plan-path>
 
 ## 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.
+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, absolute PLAN.md and all numbered briefs. An explicit `go` authorizes readiness after passing validation: DRAFT alone is not a blocker and a separate `finalize` is not required. If DRAFT, launch [validate](validate.md) through its separate frontier/high `diffpi-planner` background child with resolved paths and collect actual completion; do not require any retired mode tool. On failed/incomplete validation leave DRAFT and stop. On PASS the calling agent checks current evidence, changes only `**Status:** DRAFT` to `**Status:** READY` in PLAN.md using ordinary file editing, and reads the status back before execution. If already READY, **skip validate**, reviewer and structural revalidation; read status and proceed. Do not send DRAFT to the orchestrator.
-2. Fill every placeholder with actual request, paths and chosen mode before launch (no literal placeholders). Launch a medium `diffpi-orchestrator` background agent with ambient capabilities and this prompt:
+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.
@@ -19,9 +19,11 @@ Execute this READY live plan under the user-approved policy. Do not run a plan r
 - 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 status and checkboxes, 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. Delegate disjoint tasks to lightweight `diffpi-worker` background agents with concrete scopes, acceptance checks and ambient capabilities. Collect completed results, escalate blocked work and route bounded fixes; reload plan state before rescheduling. Workers edit only assigned source/test files, never plan lifecycle or commits.
+- 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.
 ```

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

@@ -14,11 +14,10 @@ Syntax: `help` (no flags or positional arguments required).
 /plan init <slug> [--branch <branch>]
 /plan new <slug> <request>
 /plan update <slug> <request>
-/plan annotate <plan-path>
 /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. Make no plan changes.
+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

@@ -8,7 +8,7 @@ Syntax: `init <slug> [--branch <branch>]` (optional target/issue inferred from r
 
 ## 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.
+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:
 
@@ -19,7 +19,7 @@ Scaffold an incomplete live plan, and do nothing else.
 - 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). This init-only exception permits plan-file creation, but not status transitions beyond the initial DRAFT scaffold, source edits, execution or review.
+- 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.
 ```

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

@@ -2,8 +2,8 @@
 
 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 chained validation/readiness/execution steps, but a later user-initiated update requires confirmation again. Noninteractive evals still require an actual completed child; they cannot opt into inline fallback.
+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, then validate; `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. Record 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 References or a linked durable 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.
+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` or DRAFT `go`, after **passing inline structural verification and inline review/disposition validation under the recorded approved exception**, the caller may mark DRAFT → READY, reread it, and continue the selected workflow. This exception does not waive any failed check. Already-READY `go` still skips readiness validation. 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. 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.
+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

@@ -8,7 +8,7 @@ Syntax: `new <slug> <request>` (optional `--target <plan-path>`, `--issue <id>`,
 
 ## Steps
 
-If no native subagents are available, ask for explicit confirmation in the caller and follow [the inline exception](inline-fallback.md), including chained validation; otherwise stop with a blocker. Never silently draft inline.
+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:
 
@@ -19,8 +19,8 @@ Draft a complete live plan; do not dispatch a reviewer or mark READY.
 - 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.
+- 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. On success run [validate](validate.md) once in this authoring cycle, using the resolved plan path; its own child owns the independent review round. Leave DRAFT even on validation PASS. Report actual result and blockers, not just the job ID.
+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

@@ -4,13 +4,15 @@
 
 Syntax: `update <slug> <request>` (optional `--plan <plan-path>` or `--target <plan-path>`).
 
-1. Infer revision intent, unique target and requested edits from explicit args/flags first, then natural language and repository context. Do not require inferable positionals. Ask `ask_user_question` in the caller for material ambiguity; send insufficient intent to [help](help.md).
+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
 
-If no native subagents are available, ask for explicit confirmation in the caller **before edits** and follow [the inline exception](inline-fallback.md), including chained validation; otherwise stop with a blocker. Never silently revise inline.
+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.
 
-1. Resolve the initiating Git root, absolute PLAN.md and numbered brief paths. Fill all placeholders with actual values before launch. 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:
+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.
@@ -23,4 +25,4 @@ Revise only the requested unfinished plan work in a new user-initiated authoring
 - Reread files, leave DRAFT, return changed paths and exact result or blocker. Do not ask background questions.
 ```
 
-2. Collect the completed edit result. On success the caller launches the separate [validate](validate.md) child for this new authoring cycle (one independent review round maximum) and reports its result; leave DRAFT. Do not put review inside the edit child or discard earlier evidence.
+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

@@ -10,7 +10,7 @@ Syntax: `validate <slug>` (optional `--plan <plan-path>` or `--target <plan-path
 
 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 READY, return its status; READY does not require revalidation for go. For DRAFT, fill all placeholders with real values before launch (use `none` where appropriate). Launch a separate frontier/high `diffpi-planner` background agent with ambient capabilities:
+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.
@@ -18,14 +18,14 @@ Validate this DRAFT without marking it READY or executing tasks.
 - Initiating Git root: {repo-root}
 - Absolute PLAN.md path: {plan-path}
 - Absolute numbered brief paths: {brief-paths}
-- Read PLAN.md, all numbered briefs and durable review evidence. 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 snapshot evidence, 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, 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:
+- 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.
-- Record the reviewed snapshot, Git evidence, completed verdict, findings and concrete disposition of each finding under References or a linked durable artifact. Repair actionable findings, reread changed files and rerun ONLY the read-only structural check. Record post-fix snapshot separately. 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 evidence 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.
+- 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,10 +1,12 @@
 ---
 name: diffpi-review
-description: Create, edit, review, address, publish, complete, and merge GitHub/GitLab or local tuicr reviews.
+description: Create, edit, review, address, publish, complete, and merge GitHub/GitLab or local Markdown reviews.
 ---
 
 # Review
 
+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.
+
 Infer the verb from the request. Route it with its arguments to the selected workflow:
 
 | Command                                                                         | Reference                                    |
@@ -13,11 +15,9 @@ Infer the verb from the request. Route it with its arguments to the selected wor
 | `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\|--abandon]`                   | [complete](references/workflows/complete.md) |
+| `complete [target] [--local\|--approve\|--reject\|--close]`                     | [complete](references/workflows/complete.md) |
 | `merge [target]`                                                                | [merge](references/workflows/merge.md)       |
-| `status [target] [--local]`                                                     | [status](references/workflows/status.md)     |
-| `open [target] [--local]`                                                       | [open](references/workflows/open.md)         |
 | `edit [target] [--local]`                                                       | [edit](references/workflows/edit.md)         |
 | `help`                                                                          | [help](references/workflows/help.md)         |
 
-Map `create`/`draft` → `new`, `launch` → `auto`, `ready` → `publish`, `close` → `complete`, `land` → `merge`. 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.
+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

@@ -2,22 +2,16 @@
 
 ## Parse arguments
 
-Accept `address [target] [--local]`. Fuzzy-match the review target/backend from the request and repository. Prefer explicit target/`--local`, then safe inference, then the current-review default. Select local for an explicit working-tree request. Infer commit approval only from an actual user instruction. Call `ask_user_question` only for material ambiguity before launch; return a precise blocker if a new decision arises later.
+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.
 
-## Steps
+## Local steps
 
-1. Resolve the concrete target/backend/local and review scope with `review_context` without classifying threads. Read [review standards](../review-standards.md). Substitute actual values for every placeholder, including the exact request, resolved review-context target, review scope, issue URL if applicable, and standards; never send raw `{placeholders}`. When native subagents are available, launch a frontier/high `diffpi-reviewer` background subagent with the following self-contained prompt and ambient capabilities:
+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.
 
-   ```text
-   Address every thread on this review.
-   - Repository: {absolute repo cwd}; exact request: {exact request}.
-   - Resolved review-context target: {target}; backend: {backend}; local: {local}; review scope: {review scope}; issue URL: {issue URL or none}; approved commit policy: {policy}.
-   - Review standards: {standards}.
-   - Call review_context first; reuse its target/backend/local/cwd. Call review_comments; classify every thread, preserve IDs and report unmatched threads. Apply every relevant requested change now unless explicitly deferred by the user or concretely blocked.
-   - Delegate independent, bounded non-overlapping source/test edits to lightweight/low diffpi-worker agents with ambient capabilities. Each self-contained fenced text task prompt must supply the actual repository, target/backend/local, thread IDs and exact requests, assigned file scope, acceptance checks and no-lifecycle-mutation policy; fill real values before launch, never raw placeholders. Serialize uncertain or overlapping scopes. Keep your source review read-only. Collect completed worker results, inspect actual edits and verification; escalate hard or ambiguous work instead of silently deferring it. Workers must not commit, reply, publish, complete, merge, resolve or mutate review state.
-   - Run review_gates after edits; record failed and skipped checks. For remote source changes, commit after checks and before replies through the user-approved upstream /git commit --no-push workflow (--atomic for separate logical commits). Do not commit without approval. Leave local source edits uncommitted.
-   - Call review_respond for every thread with resolve:false, explicit fixed/answered/unresolved outcome and verification evidence. Do not claim blocked work was delivered. Keep questions and all threads open for user resolution. Optionally call review_launch_ui for local replies.
-   - Never delete or resolve threads, publish, complete or merge. Report fixed, committed, answered, unresolved, skipped and failed counts, unmatched replies, gate evidence and blockers; resolved count is zero. Preserve local replies and thread state between runs.
-   ```
+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.
 
-2. If no native subagents are available, follow [foreground fallback](foreground-fallback.md) before classifying threads or editing. Only after explicit confirmation, perform the address steps above inline, including source/test edits directly where needed (do not invent Worker results), checks, approved commit policy, and `review_respond(resolve:false)` for every thread; report unresolved and blocked work honestly. Otherwise verify the attached launch. Stop on failure; report the actual completed child outcome, not merely its queued ID or claim of success.
+## 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

@@ -2,24 +2,16 @@
 
 ## Parse arguments
 
-Accept `auto [target] [--local]`. Fuzzy-match review intent and infer the current branch, PR/MR or working-tree target/backend from the request and repository. Prefer explicit arguments/flags, then safe inference, then current-review defaults. Select local for an explicit working-tree request. Call `ask_user_question` only for material ambiguity before launch; return a precise blocker if a new decision arises later.
+Accept `auto [target] [--local]`. Resolve the target explicitly; ask when local plan/ticket matches are ambiguous.
 
-## Steps
+## Local steps
 
-1. Resolve the concrete target/backend/local and diff scope with `review_context` without analyzing the diff. Read [review standards](../review-standards.md). Substitute actual values for every placeholder, including the exact request, resolved review-context target, diff scope, issue URL if applicable, and standards; never send raw `{placeholders}`. When native subagents are available, launch a frontier/high `diffpi-reviewer` background subagent with the following self-contained prompt and ambient capabilities:
+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.
 
-   ```text
-   Review this change without editing source.
-   - Repository: {absolute repo cwd}; exact request: {exact request}.
-   - Resolved review-context target: {target}; backend: {backend}; local: {local}; diff scope: {diff scope}; issue URL: {issue URL or none}; approved policy: {policy}.
-   - Review standards: {standards}.
-   - Call review_context first; reuse its target/backend/local/cwd. Reject unsupported forge, missing integration or unavailable local base without switching backend.
-   - Use review_status if needed to distinguish an existing review. Call review_new for a new local session or remote draft PR/MR; call review_edit for an existing review.
-   - Run review_gates, then review_diff. Judge intent, correctness, negative/security paths, scope and duplicate findings. Record failed and skipped format/lint/test/subject/CI checks; stop with evidence if the diff is unavailable.
-   - Stage changed-file-and-line-grounded BLOCKING, CONSIDER or NOTE findings with review_submit; submit [] if clean. Include overall issues and not-verified checks where needed. Keep remote findings pending and local findings in draft.
-   - Do not edit source, publish, complete, merge or resolve threads.
-   - Delegate bounded independent checks when useful, with self-contained task prompts and ambient capabilities. The plan's exactly-one independent review limit does not apply to PR/MR code review.
-   - Verify and report artifact, backend, gates, finding count and blockers.
-   ```
+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.
 
-2. If no native subagents are available, follow [foreground fallback](foreground-fallback.md) before analysis or creation. Only after explicit confirmation, execute the review steps above inline without source edits, following the same standards and staging findings via `review_submit`; label the result foreground fallback. Otherwise verify the attached launch. Stop on failure; report the actual completed child outcome, not merely its queued ID or claim of success.
+## 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.

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

@@ -2,11 +2,11 @@
 
 ## Parse arguments
 
-Accept `complete [target] [--local|--approve|--reject|--abandon]`. Fuzzy-match target/backend/action from the request and repository. Prefer explicit arguments/flags, then safe inference, then current-review target; do not invent a remote action. Call `ask_user_question` only for material ambiguity before launch; return a precise blocker if a new decision arises later.
+Accept `complete [target] [--approve|--reject|--close]`. Local complete is unsupported; reject stale `--local` or working-tree selectors. Fuzzy-match target/backend/action from the request and repository. Prefer explicit arguments/flags, then safe inference, then current-review target; do not invent a remote action. Call `ask_user_question` only for material ambiguity before launch; return a precise blocker if a new decision arises later.
 
 ## Steps
 
-1. Call `review_context` first with the selected target/backend/local. For a short, explicitly approved completion with no substantive inspection, call `review_complete` directly using its resolved values: `local:true` archives only the matching local review and removes its tuicr session; a remote review needs an explicit `approve`, `reject`, or `abandon` action. Verify and report the actual result or exact failure. Do not publish pending comments, merge or resolve threads.
+1. Call `review_context` first with the selected remote target/backend and `local:false`. For a short, explicitly approved completion with no substantive inspection, call `review_complete` directly using its resolved values. A remote review needs an explicit `approve`, `reject`, or `close` action. `approve` and `reject` publish their decisions; `close` closes the remote PR/MR without publishing first. Verify and report the actual result or exact failure. Do not merge or resolve threads.
 2. If substantive inspection or judgment is required, when native subagents are available, delegate only that analysis to medium `diffpi-orchestrator` in the background with ambient capabilities. Fill every field in this self-contained prompt with actual values (or `none`), including the exact request; never send raw placeholders:
 
    ```text

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

@@ -2,10 +2,12 @@
 
 ## Parse arguments
 
-Accept `edit [target] [--local]`. Fuzzy-match the existing tuicr or PR/MR session from the request and repository. Prefer explicit arguments/flags, then safe inference, then the current-review target. Select local for an explicit working-tree request. Call `ask_user_question` only for material ambiguity.
+Accept `edit [target] [--local]`. Resolve the existing local review by explicit path or unique plan/ticket match; ask on ambiguity.
 
-## Steps
+## Local steps
 
-1. Call `review_context` first with the selected target/backend/local; reuse its target/backend/local/cwd. Reject unsupported selections without switching backend.
-2. Call `review_edit` with those values to open the existing local session or remote PR/MR in tuicr without generating findings. Keep remote-session draft comments associated with that PR/MR for later promotion at publish.
-3. Report the opened session, returned launch command or exact missing-session/launch failure. Do not create, publish, complete, merge, resolve or generate findings.
+Print the selected `.diffpi/review/**/REVIEW-*.md` path. Read it before any edit, preserve all finding IDs, replies, evidence, and checkbox state, and use native `read`, `write`, `edit`, or shell operations only. Do not create a session, parser, backend, or browser launch.
+
+## Remote steps
+
+Call `review_context` and `review_edit`; report the PR/MR URL or selected local Markdown path. Never launch a browser.

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

@@ -1,24 +1,16 @@
 # help
 
-## Parse arguments
+Show:
 
-Accept `help` or a request with no recognizable review verb; no positional arguments or flags. Prefer an explicit verb, then safely inferred natural-language intent, then help. Ask only if a material ambiguity prevents routing to a workflow.
+```text
+/review new [title] [--intent text] [--base branch] [--local]
+/review auto [target] [--local]
+/review edit [target] [--local]
+/review address [target] [--local]
+/review publish [target] [--comment|--approve|--request-changes|--close]
+/review complete [target] [--approve|--reject|--close]
+/review merge [target]
+/review help
+```
 
-## Steps
-
-1. Show the complete subcommand list:
-
-   ```text
-   /review new [title] [--intent text] [--base branch] [--local]
-   /review auto [target] [--local]
-   /review open [target] [--local]
-   /review status [target] [--local]
-   /review edit [target] [--local]
-   /review address [target] [--local]
-   /review publish [target] [--local] [--comment|--approve|--request-changes|--close]
-   /review complete [target] [--local|--approve|--reject|--abandon]
-   /review merge [target]
-   /review help
-   ```
-
-2. Show aliases: `create`/`draft` → `new`, `launch` → `auto`, `ready` → `publish`, `close` → `complete`, `land` → `merge`.
+Local `publish` and `complete` are unsupported. Local workflows use direct Markdown files; remote workflows use forge-backed tools. Aliases: `create`/`draft` → `new`, `launch` → `auto`, `ready` → `publish`, `close` → `complete`, `land` → `merge`.