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

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

@@ -1,7 +1,20 @@
 # complete
 
-**Owner/tier:** lifecycle coordinator; no Reviewer or Worker.
+## Parse arguments
 
-1. Parse target, `--local`, or exactly one remote action: approve, reject, abandon. Call `review_context` first with the same values. If a remote action is missing, ask with `ask_user_question`; background mode must stop rather than guess.
-2. Call `review_complete` with local true for local archive or the mapped remote action. Local completion archives the overlay and removes the matching tuicr session; remote completion does not merge.
-3. Report archive/result and any failure. Never publish or call `review_merge`.
+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 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
+   Inspect completion readiness without changing review state.
+   - Repository: {absolute repo cwd}; exact request: {exact request}.
+   - Resolved target: {target}; backend: {backend}; local: {local}; issue URL: {issue URL or none}; approved remote action: {action or none for local}.
+   - Call review_context first; reuse its target/backend/local/cwd. Inspect only the matching review/session and report outstanding findings, status and material decisions. Do not switch backend.
+   - Return actual completed evidence and a go/no-go recommendation or precise blocker. Do not complete, publish, merge or resolve threads.
+   ```
+
+3. If no native subagents are available for step 2, follow [foreground fallback](foreground-fallback.md) before inspection; only after explicit confirmation inspect inline and report actual evidence without claiming an Orchestrator result. Otherwise require the completed result, not a queued job or claim. Resolve material decisions with the user before calling `review_complete` in the initiating thread if approval still applies.

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

@@ -1,5 +1,13 @@
 # edit
 
-**Owner/tier:** lifecycle coordinator; no findings judgment.
+## Parse arguments
 
-Call `review_context` first, then `review_edit` with the same target/backend/local. It opens an existing local session or remote PR/MR in tuicr without generating findings. Report missing sessions, unsupported targets, and launch failures. Do not create, publish, complete, merge, or resolve.
+Accept `edit [target] [--local]`. Resolve the existing local review by explicit path or unique plan/ticket match; ask on ambiguity.
+
+## Local steps
+
+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/foreground-fallback.md

@@ -0,0 +1,7 @@
+# Foreground fallback (review only)
+
+Use this policy only when **no native subagents are available** for the required background `diffpi-worker`, `diffpi-reviewer`, or `diffpi-orchestrator` work. This is not a recovery path for a failed launch, child/tool error, unavailable result, authentication failure, failed checks, or a reviewer's BLOCKING findings. Do not substitute a shell process or claim a child launched or completed.
+
+After `review_context` resolves the target/backend/local, but **before substantive creation, diff analysis, thread classification, source edits, or lifecycle-readiness inspection**, call `ask_user_question` in the initiating conversation. State that the named background agent is unavailable and that running the work here loses the intended model tier and agent isolation. Offer `Stop and report blocker` (no substantive work; report missing native agents) and `Run inline` (continue in this conversation without the intended model tier or isolation) as options; a custom response must clearly authorize inline work. Do not interpret a previous lifecycle approval or absence of a refusal as consent. If the user declines, the question tool is unavailable, or this is a background child unable to ask, stop and return a precise blocker to the initiating conversation. Never silently continue inline.
+
+On explicit confirmation only, the calling agent performs the selected workflow's substantive steps inline, using the same resolved target/backend/local/cwd and the child prompt's constraints, tools, checks, and evidence requirements. For `address`, perform the needed source/test edits directly without inventing Worker results; keep `review_respond(resolve:false)` and user-owned thread resolution. For `publish`, `complete`, or `merge`, inline inspection is read-only; the lifecycle call remains in the initiating conversation only after its existing approval and readiness requirements are satisfied. Report actual inline actions and outcomes as **foreground fallback**, not as a completed child. The ordinary short, explicitly approved lifecycle calls, `status`, `open`, `edit`, and `help` do not need this fallback.

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

@@ -1,15 +1,16 @@
 # help
 
+Show:
+
 ```text
-/review auto [target] [--local] [--bg]
-/review new [title] [--intent text] [--base branch] [--local] [--bg]
-/review open [target] [--local]
-/review status [target] [--local]
-/review edit [target] [--local] [--bg]
-/review address [target] [--local] [--bg]
-/review publish [target] [--local] [--comment|--approve|--request-changes|--close] [--bg]
-/review complete [target] [--local|--approve|--reject|--abandon] [--bg]
-/review merge [target] [--bg]
+/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
 ```
 
-Every target-bearing workflow calls `review_context` first; help is informational and may run without a target or repository. `--local` selects working-tree tuicr state and is preserved; otherwise use the forge. `--bg` launches one named same-session Orchestrator child without redispatch or mode changes. `auto` reviews and stages grounded findings; `new` creates a draft; `open` opens an existing target; `status` is read-only; `edit` opens without findings; `address` fixes and replies without resolving; `publish` publishes/promotes pending work; `complete` approves/rejects/abandons or archives local state without merging; `merge` is GitHub-only and requires clean settled readiness. Aliases: create/draft=new, launch=auto, ready=publish, close=complete, land=merge. Unknown verbs show this help.
+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`.

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

@@ -1,5 +1,20 @@
 # merge
 
-**Owner/tier:** lifecycle coordinator; remote GitHub-only, no Reviewer or Worker.
+## Parse arguments
 
-Reject `--local`. Call `review_context` first with `local:false`, then `review_merge`; the tool checks open, non-draft, clean PR and settled checks and uses branch protection as authoritative. Approval by the current user is not required. Ask only when a conventional squash subject is materially unclear. Report merge or readiness failure. Merge never publishes or completes review state.
+Accept `merge [target]` and an optional conventional squash subject in the request. Fuzzy-match GitHub PR target from the request and repository. Prefer explicit target/subject, then safe inference, then current PR. Reject `--local`; do not infer it. Call `ask_user_question` only for material target or subject ambiguity before launch; return a precise blocker if a new decision arises later.
+
+## Steps
+
+1. Call `review_context` first with `local:false` and the selected target. Reject non-GitHub or local reviews without switching backend. For a short, explicitly approved merge requiring no substantive analysis, call `review_merge` directly with its resolved target and conventional squash subject if needed. The tool rechecks open, ready, clean PR status and settled CI; branch protection is authoritative, and current-user approval is not required unless protection requires it. Report the actual merge or exact readiness/CI/subject failure. Do not publish or complete in its place.
+2. If merge-readiness requires substantive inspection or judgment beyond the tool's checks, 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
+   Inspect GitHub PR merge readiness without merging.
+   - Repository: {absolute repo cwd}; exact request: {exact request}.
+   - Resolved target: {target}; backend: remote GitHub; local: false; issue URL: {issue URL or none}; proposed conventional squash subject: {subject or none}.
+   - Call review_context first with local:false; reuse its target/backend/cwd. Inspect PR readiness, subject and settled CI using review_status and available checks. Treat branch protection as authoritative; do not demand current-user approval unless protection requires it.
+   - Return completed evidence and a go/no-go recommendation or precise blocker. Do not merge, publish, complete or resolve threads.
+   ```
+
+3. If no native subagents are available for step 2, follow [foreground fallback](foreground-fallback.md) before inspection; only after explicit confirmation inspect inline and report actual evidence without claiming an Orchestrator result. Otherwise require the completed result, not a queued job or claim. Resolve material decisions with the user, then call `review_merge` in the initiating thread only if approval still applies. Report the actual result.

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

@@ -1,9 +1,22 @@
 # new
 
-**Owner/tier:** foreground or background lifecycle coordinator; no Reviewer or Worker required.
+## Parse arguments
 
-1. Parse title, intent, base, target, and `--local`. Call `review_context` first with the exact selection.
-2. Call `review_new` with the same target/backend/local values. This creates a local tuicr review or remote draft PR/MR and opens it; use `review_launch_ui` only when needed.
-3. Report the created target and draft state. Do not run findings, publish, complete, or merge.
+Accept `new [title] [--intent text] [--base branch] [--local]`. Resolve explicit target, plan/ticket, title, and backend first. For local work, ask `ask_user_question` when multiple plans or tickets match; do not guess.
 
-Missing title/base, unsupported forge, dirty remote branch, or creation failure is an explicit error; never silently switch backend. `--bg` is one named child only.
+## Local steps
+
+Use a background `diffpi-worker` when native subagents are available; otherwise follow the foreground fallback after confirmation. The worker performs only direct-file creation.
+
+1. Inspect `.diffpi/review/` and the matching plan/ticket directory before choosing a number. Derive `YYMMDD-{slug}` from the unique matching plan after stripping its date prefix, otherwise the ticket ID, otherwise a descriptive slug.
+2. Create `.diffpi/review/YYMMDD-{slug}/REVIEW-{n}.md` by reading `templates/REVIEW.md` and writing a copy. Numbering is best effort, not atomic; preserve existing files.
+3. Fill every known title, intent, target, base, and status field. If review text was pasted in the request, record it directly in the file and assign stable `F-001`-style IDs. Preserve replies and checkbox state on later edits.
+4. Report the exact path. Do not call `review_new`, create a backend, or claim atomic allocation.
+
+## Remote steps
+
+Call `review_context`, then launch a `diffpi-worker` only for draft creation. Give the worker the resolved repository, branch, base, issue URL (if any), and exact request. The worker must:
+
+1. Read the packaged PR template at `../../templates/review/draft-pr.md` relative to the review skill directory. Inspect the actual branch changes against the selected base and any completed checks; do not invent validation results.
+2. Fill **every** template section: distinct intent and concrete changes, checks actually run (or `Not run (draft)`), the issue URL (or `No linked issue`), and known further work (or `Not yet assessed`). Remove all `{{...}}` markers and HTML comments. Pass the fully rendered Markdown as `body` to the existing `review_new` tool, with the resolved title/base/issue URL. The tool rejects missing or incomplete bodies before calling the forge.
+3. Report the actual PR/MR URL and draft state or the precise failure. Do not publish, complete, merge, or stage findings.

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

@@ -1,7 +1,20 @@
 # publish
 
-**Owner/tier:** lifecycle coordinator; no Reviewer or Worker.
+## Parse arguments
 
-1. Parse target, `--local`, and one status: comment (default), approve, request-changes, or close. Call `review_context` first and preserve the selected backend. A local promotion may be used only when context identifies the matching local session; never silently switch.
-2. Call `review_publish` with the same target/backend/local. It promotes/stages pending local work where applicable and publishes the selected status; remote comments remain pending until this call. Comment/approve/request-changes mark remote drafts ready; close publishes comment then closes. GitLab may reject request-changes.
-3. Report promoted bodies/comments/replies, status, and final state. Publish never merges. Unsupported target, unmatched response, or forge failure is explicit.
+Accept `publish [target] [--comment|--approve|--request-changes|--close]`. Local publish is unsupported; reject stale `--local` or working-tree selectors. Fuzzy-match target/backend/status from the request and repository. Prefer explicit arguments/flags, then safe inference, then current-review target and comment status. 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 remote target/backend and `local:false`. For a short, explicitly approved publication with no substantive inspection, call `review_publish` directly using its resolved values and selected status (`COMMENT` by default, `APPROVE`, `REQUEST_CHANGES`, or `CLOSE`). Remote findings and replies stay pending until this call. Reject stale local or working-tree selectors; never promote local drafts. Report unmatched promotion, GitLab request-changes rejection, and exact failures; verify the final status. Do not merge or resolve threads.
+2. If the request instead needs substantive inspection or judgment before publication, 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
+   Inspect publication readiness without publishing.
+   - Repository: {absolute repo cwd}; exact request: {exact request}.
+   - Resolved target: {target}; backend: {backend}; local: {local}; selected status: {status}; issue URL: {issue URL or none}; approved policy: {policy}.
+   - Call review_context first; reuse its target/backend/local/cwd. Inspect the matching session and pending findings/replies; identify unmatched drafts, failed checks and material decisions. Do not silently switch backends.
+   - Return actual completed evidence and a go/no-go recommendation or precise blocker. Do not publish, complete, merge or resolve threads.
+   ```
+
+3. If no native subagents are available for step 2, follow [foreground fallback](foreground-fallback.md) before inspection; only after explicit confirmation inspect inline and report actual evidence without claiming an Orchestrator result. Otherwise require the completed inspection result, not a queued job or claim. Resolve material decisions with the user, then call `review_publish` in the initiating thread only if approval still applies. Report the actual published or blocked outcome.

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

@@ -1,5 +1,10 @@
 # status
 
-**Owner/tier:** lifecycle coordinator, read-only.
+## Parse arguments
 
-Call `review_context` first with the exact target/backend/local, then `review_status` with the same values. Report branch, worktree, forge/local review, URLs, and tuicr state. Missing or unsupported targets are errors; status never creates, publishes, completes, merges, or changes comments.
+Accept `status [target] [--local]`. Fuzzy-match the status target/backend 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.
+
+## 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_status` with those same values. Report branch, worktree, local or remote review, URLs, pending/draft state and exact errors. Do not create a review or mutate source, comments or lifecycle state.

package/skills/review/templates/REVIEW.md

@@ -0,0 +1,39 @@
+# Local Review
+
+- **Review:** <!-- descriptive title or plan/ticket slug -->
+- **Status:** OPEN
+- **Source:** <!-- pasted review text, local diff, or request -->
+- **Created:** <!-- YYYY-MM-DD -->
+- **Updated:** <!-- YYYY-MM-DD -->
+
+## Intent
+
+<!-- State what this review is checking. -->
+
+## Findings
+
+<!-- Keep findings in stable ID order. Preserve IDs, replies, and checkbox state when editing. -->
+
+### F-001 [ ] <!-- short finding title -->
+
+- **Severity:** BLOCKING | CONSIDER | NOTE
+- **Location:** `path/to/file.ts:1`
+- **Finding:** <!-- Explain the problem and its impact. -->
+- **Evidence:** <!-- Quote the relevant source or review text. -->
+- **Resolution:** <!-- Leave blank while open; record the verified fix here. -->
+
+<!-- Copy the finding shape above for F-002, F-003, and so on. -->
+
+## Replies
+
+<!-- Preserve human replies verbatim. Add dated replies below without deleting prior context. -->
+
+## Verification
+
+- [ ] Focused check run for each addressed finding
+- [ ] Remaining open findings reviewed
+- [ ] Overall status updated only after verification
+
+## Status Notes
+
+<!-- Record blockers, partial work, and decisions. Do not close a finding without evidence. -->

package/templates/plan/PLAN.md

@@ -3,8 +3,12 @@
 - **Plan ID:** {{id}}
 - **Branch:** {{branch}}
 - **Status:** draft
+- **Execution state:** inactive
+- **Execution worktree:** None
+- **Execution reason:** None
 - **Issue:** {{issue_id}}
 - **Issue URL:** {{issue_url}}
+- **Revision:** 0
 
 ## Intent
 
@@ -44,4 +48,8 @@
 
 ## References
 
-<!-- Add repository or external references. -->
+<!-- Add repository or external references before Feedback. -->
+
+### Feedback
+
+<!-- Capture pending user feedback before an update. Archive the complete plan and numbered briefs before substantive edits, then increment Revision exactly once and address or disposition the feedback. -->

package/templates/review/draft-pr.md

@@ -4,22 +4,16 @@
 
 ## Changes
 
-<!-- List the user-visible or architectural changes. -->
+{{changes}}
 
 ## Validation
 
-<!-- List the checks that were run. -->
-
-- [ ] Existing tests pass
+{{validation}}
 
 ## References
 
-<!-- Link the issue that defines this task. Add related project, epic, and public documentation links when available. -->
-
 - Issue: {{issue_url}}
 
 ## Further Work
 
-<!-- Optional: list intentionally deferred follow-up work as bullets, or remove this section. -->
-
--
+{{further_work}}

package/dist/cli/plan.d.ts

@@ -1,17 +0,0 @@
-import { Command } from 'commander';
-export interface PlanCliIO {
-    stdout: Pick<NodeJS.WriteStream, 'write'>;
-    stderr: Pick<NodeJS.WriteStream, 'write'>;
-}
-interface PlanCliRuntime {
-    execute: (command: string, args: string[], cwd: string, interactive: boolean) => Promise<{
-        code: number;
-        stdout: string;
-        stderr: string;
-    }>;
-}
-export declare function createPlanCliCommand(io?: PlanCliIO, planRuntime?: PlanCliRuntime): Command;
-export declare function runPlanCli(args: string[], io?: PlanCliIO): Promise<number>;
-export declare function planCliHelp(): string;
-export {};
-//# sourceMappingURL=plan.d.ts.map

package/dist/cli/plan.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/cli/plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAKpD,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,UAAU,cAAc;IACtB,OAAO,EAAE,CACP,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,EACX,WAAW,EAAE,OAAO,KACjB,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChE;AAMD,wBAAgB,oBAAoB,CAAC,EAAE,GAAE,SAAmB,EAAE,WAAW,GAAE,cAAwB,GAAG,OAAO,CA0B5G;AAED,wBAAsB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,GAAE,SAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CASzF;AAED,wBAAgB,WAAW,IAAI,MAAM,CAEpC"}

package/dist/cli.d.ts

@@ -1,4 +0,0 @@
-#!/usr/bin/env node
-import { type PlanCliIO } from './cli/plan';
-export declare function main(argv?: string[], io?: PlanCliIO): Promise<number>;
-//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAGA,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AAElE,wBAAsB,IAAI,CAAC,IAAI,WAAwB,EAAE,EAAE,GAAE,SAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAkBjG"}