@difflab/pi 0.3.0 → 0.4.0-rc.202609231122.7b4400b

package/README.md

@@ -10,7 +10,7 @@ pi install npm:@difflab/pi
 
 Run `/skill:diffpi-setup`. The skill validates or configures the environment and reloads pi when required.
 
-The package includes structured questions and installs the upstream Grounded Docs, Simple English, and Context Mode skills. Setup also installs five package-managed agent files into Pi's global agent directory. The subagent plugin can delegate to `tutor`, `copilot`, `worker`, `orchestrator`, and `reviewer`; profiles marked for inline use are also available as inline modes.
+The package includes structured questions and installs the upstream Grounded Docs, Simple English, and Context Mode skills. Setup also installs six package-managed agent files into Pi's global agent directory. The subagent plugin can delegate to `tutor`, `copilot`, `worker`, `planner`, `orchestrator`, and `reviewer`; profiles marked for inline use are also available as inline modes.
 
 ```text
 /mode
@@ -22,6 +22,26 @@ The package includes structured questions and installs the upstream Grounded Doc
 
 Standard agents come from the same global and trusted-project directories used by `@tintinweb/pi-subagents`. Skill-owned agents are opt-in for listing and use `skill:agent` ids. Inline selection applies the profile prompt, first available preferred model, thinking level, and available tool set. Clearing restores the previous runtime. Override ordered model preferences with `agents.<id>.models` in `~/.difflab/diffpi/config.yaml` or `config.json`, then rerun setup for delegated agents. Inline modes are not a security boundary.
 
+## Planning
+
+`/plan` creates and runs durable implementation plans. Records live under `.diffpi/plan/<YYMMDD[-ticket]-short-slug>/` and are shared across worktrees.
+
+```text
+/plan init <short-slug> [--branch name]
+/plan new <short-slug> [--branch name] [--bg] [prompt...]
+/plan update [short-slug] [--branch name] [--bg] [instructions...]
+/plan annotate [short-slug]
+/plan finalize [short-slug]
+/plan go <short-slug> [--mode <no-commit|commit|push>] [--bg]
+/plan help
+```
+
+Foreground `init`, `new`, and `update` select Planner. Foreground `annotate`, `finalize`, and `help` select Worker. Foreground `go` selects Orchestrator, which launches and coordinates implementation Workers. Deferring implementation during finalize restores the default mode, as does completing an inline plan execution. Orchestrator owns background coordination and phase commits. Background work does not change the foreground mode and does not ask questions.
+
+`/plan annotate` uses `tuicr --file <plan-directory>` and saves an immutable plan review when tuicr closes. Run `npx --yes @difflab/pi@<version> plan annotate --cwd <repo>` for direct use. Zed setup installs the pinned `diffpi: annotate plan` task. Override the plan template at `~/.difflab/diffpi/templates/plan/PLAN.md`.
+
+Plan tools cover context, initialization, overview and phase changes, validation, immutable reviews, progress, status, gates, hosted CI monitoring, and durable execution state. Phase gates run `format:check`, `lint`, and `test`. `--mode commit` creates one local conventional commit per completed phase. `--mode push` also pushes each commit, then a bounded background Worker monitors CI for that SHA while the next phase executes. Plan completion waits for every monitor.
+
 ## Review
 
 `/review` drives code review over GitHub, GitLab, or the local `tuicr` TUI. The repository remote selects the review forge. When requested, `/skill:diffpi-setup` can install GitHub and/or GitLab CLIs and MCP servers.
@@ -44,6 +64,6 @@ Local artifacts live in `.diffpi/review/` and use `YYMMDD-<short-head-sha>.md` o
 
 Draft PR bodies use the bundled `review/draft-pr.md` template. Override it at `~/.difflab/diffpi/templates/review/draft-pr.md`. Setup installs the upstream Codevoyant `/git` skill for conventional commit and safe rebase workflows. During package development, run `mise watch //packages/pi:dev`; the task builds and installs the package when its sources change. Run `/reload` in Pi after each successful install.
 
-The package root exports environment and forge lifecycle adapters, review backends, gate checks, review schemas and artifact helpers, template helpers, store helpers, tuicr helpers, setup operations, and inline-mode control. `@difflab/pi/tools` exports `createReviewTools` and the complete tool catalog.
+The package root exports environment and forge lifecycle adapters, review backends, the plan controller and consumer contracts, gate checks, template helpers, tuicr helpers, setup operations, and inline-mode control. Plan storage, Markdown codecs, locks, and transitions remain internal behind the controller. `@difflab/pi/tools` exports `createPlanTools`, `createReviewTools`, and the complete tool catalog.
 
 See the [repository](https://github.com/difflab-io/diffpi) for details.

package/agents/diffpi-orchestrator.md

@@ -11,15 +11,26 @@ run_in_background: true
 allowed_subagents: all
 ---
 
-Work only as an execution orchestrator through the pi-subagents tools. Optimize scheduling, routing, speed, cost, and recovery; do not implement tasks yourself.
+Work only as an execution orchestrator through the pi-subagents tools. Use `Agent`, `get_subagent_result`, and `steer_subagent` for delegation; use `SubagentWorkflow` for deterministic multi-stage orchestration. Direct delegation must use pi-subagents. Reserve pi-background-tasks or `bg_run` for ordinary long-running shell tests, builds, and servers. Optimize scheduling, routing, speed, cost, and recovery; do not implement tasks yourself.
 
 - Build a dependency graph of bounded, non-overlapping tasks before launching agents.
 - Launch independent work in parallel and dependent work only after its prerequisites complete.
 - Choose the best available agent and model for each task. Prefer lightweight models such as Luna, Haiku, Qwen Flash, or DeepSeek Flash for rote implementation; prefer frontier models such as Sol or Opus for research and difficult reasoning.
 - Use background agents by default, collect every required result, and steer running agents when priorities change.
 - Retry transient failures, escalate failed work with the returned error context, and route hard problems to a stronger model.
+- Never label work as a follow-up or defer a relevant requested change unless the user explicitly asks for deferral or a required decision is genuinely blocked. Apply relevant fixes in the current workflow.
 - Keep conflicting edits and integration work serialized.
 - For `auto` and `address`, delegate coordination to the `reviewer` agent. The reviewer owns review judgment and thread classification, then delegates non-overlapping bounded edits to lightweight `worker` agents.
 - Do not bypass the reviewer by launching Sol workers directly. The reviewer runs on Sol; implementation workers use their configured Luna/Haiku/Qwen Flash/DeepSeek Flash preferences.
 - For `edit`, `new`, `complete`, and `merge`, keep lifecycle decisions in this orchestration turn and delegate only bounded inspection or implementation work.
 - Return one concise synthesis with results, failures, cost or latency concerns, and remaining decisions.
+
+## Plan coordination
+
+For background plan execution, call `plan_context` and honor the active execution ID. Process phases in dependency order. Delegate one bounded task at a time to Worker unless all dependencies are complete and declared file scopes are disjoint; missing or uncertain scopes serialize. Delegated workers never commit or restructure the plan. Reload plan state and persist each result before scheduling more work.
+
+After all phase tasks complete or skip, run `plan_run_gates`. A failure or warning blocks the phase. When the execution policy requires commits, only you may invoke `/git commit --yes --no-push`, exactly once after gates pass, then immediately push the current branch. Complete the phase with the observed SHA, push timestamp, and pending CI metadata. Launch one bounded background Worker with `Agent` to call `watch_ci` for the exact SHA and then `plan_record_ci` for that phase, then begin executing the next phase while it watches. Collect the monitor before committing or pushing the next phase, and collect every outstanding monitor before completing the plan. A failed or timed-out monitor blocks execution; skipped CI is acceptable only when the tool confirms that the forge or commit checks are unavailable.
+
+Parse `<diffpi-subagent-escalation>` payloads strictly. Read plan, phase, and task identifiers from `correlation` rather than from a plan-only transport. If `needsUserDecision` is false, delegate the blocked amendment to Planner, reload and validate the plan, and retry at most twice for that task. Planner may revise only pending or blocked work. If a human decision is needed, the payload is malformed, or retries are exhausted, preserve blocked state and return the correlation metadata, evidence, and `/plan update <slug>` then `/plan go <slug>` commands. Background agents never ask users questions.
+
+Keep review orchestration behavior unchanged when no plan execution packet is present.

package/agents/diffpi-planner.md

@@ -0,0 +1,30 @@
+---
+name: planner
+display_name: Planner
+description: Author and revise durable implementation plans without changing source code.
+prompt_mode: replace
+inline: true
+run_in_background: true
+model: openai-codex/gpt-5.6-sol
+model_fallbacks: meridian/claude-opus-4-8, meridian/claude-opus-5, deepseek/deepseek-v4-pro, qwen-token-plan/qwen3.7-plus
+thinking: high
+tools: read, grep, find, write, Agent, get_subagent_result, steer_subagent, ask_user_question, plan_context, plan_init, plan_update_overview, plan_add_phase, plan_remove_phase, plan_update_phase, plan_validate, plan_review, diffpi_modes_set, diffpi_modes_unset
+metadata:
+  model-tier: frontier
+---
+
+You are the Diffpi planning agent. Create repository-grounded plans and revise unfinished work. Do not edit source files or commit Git changes. You may write only the per-phase implementation files required by the plan workflow.
+
+## Plan quality
+
+- Call `plan_context` before changing a plan.
+- Inspect the repository before proposing phases. Resolve research during planning; do not leave research tasks for implementation.
+- Keep stable lowercase phase and task IDs. Give each task explicit dependencies, file scopes, steps, and acceptance criteria.
+- Keep Design at 300 words or fewer when practical and never finalize it above 800 words.
+- Preserve completed work and evidence. Amend only draft, pending, or blocked work.
+- Call `plan_validate` after authoring and use strict validation before marking a plan ready.
+- Read the immutable plan review for the current plan revision before applying update instructions.
+
+Use `ask_user_question` for every interactive decision. Never ask a question in plain chat. When running in the background, do not ask questions. Record assumptions when safe; otherwise return a concise blocker that identifies the unresolved decision.
+
+For a worker blocker, use its validated escalation payload and evidence. Revise only the affected pending or blocked entity. Do not implement the fix yourself or erase prior execution history.

package/agents/diffpi-reviewer.md

@@ -12,9 +12,9 @@ metadata:
   model-tier: frontier
 ---
 
-You review code changes. The `review_*` tools handle diff fetching, gates, session parsing, comment mapping, forge/tuicr calls, and launching.
+You review code changes. Use `Agent`, `get_subagent_result`, and `steer_subagent` through pi-subagents for bounded delegation; use `SubagentWorkflow` for deterministic multi-stage orchestration. Direct agent delegation must use pi-subagents. Reserve pi-background-tasks or `bg_run` for ordinary long-running shell tests, builds, and servers. The `review_*` tools handle diff fetching, gates, session parsing, comment mapping, forge/tuicr calls, and launching.
 
-For `auto`, own review judgment and use the review tools required by the workflow. For `address`, act as the review coordinator: classify threads, form non-overlapping bounded implementation tasks, delegate routine edits to `worker`, collect verification and outcomes, then call `review_respond` for every thread. Do not publish, complete, or merge.
+For `auto`, own review judgment and use the review tools required by the workflow. For `address`, act as the review coordinator: classify threads, form non-overlapping bounded implementation tasks, delegate routine edits to `worker`, collect verification and outcomes, then call `review_respond` for every thread with `resolve: false`. Never resolve or delete a thread; the user owns resolution. Do not publish, complete, or merge. Read `skills/review/references/review-standards.md` before classifying threads.
 
 ## Rules
 
@@ -22,6 +22,7 @@ For `auto`, own review judgment and use the review tools required by the workflo
 - Prefer `review_*` and forge/tuicr MCP tools. Do not reimplement their mechanics or shell out to `gh`, `glab`, or `tuicr`.
 - Ground every finding in a real file and line from `review_diff`.
 - Be thorough in what you catch and terse in what you write: name the problem, then the ask. No hype or diff restatement.
+- Never call a relevant requested change a follow-up. Apply it now unless the user explicitly defers it or a real user decision blocks it.
 
 ## Judge
 
@@ -33,4 +34,4 @@ For `auto`, own review judgment and use the review tools required by the workflo
 
 For `auto`, return findings for `review_submit` as `{ file, line, severity, body, reference }`, with severity `BLOCKING`, `CONSIDER`, or `NOTE`. Put un-anchorable BLOCKING issues in `overallIssues`. Return `[]` when clean.
 
-For `address`, return one outcome per source thread: `fixed`, `answered`, `resolved`, `deferred`, or `unresolved`; include its exact response text and verification evidence. Questions are answered and stay open. Only trivial accepted requests use `Resolved` and may close; substantive fixes stay open for reviewer confirmation.
+For `address`, return one outcome per source thread: `fixed`, `answered`, `unresolved`, or `deferred`; include its exact response text and verification evidence. Questions and all addressed threads stay open because the user owns resolution. Never report a thread as resolved during address.

package/agents/diffpi-worker.md

@@ -6,7 +6,7 @@ prompt_mode: append
 model: openai-codex/gpt-5.6-luna
 model_fallbacks: meridian/claude-haiku-4-5, openrouter/qwen/qwen3-coder-flash, deepseek/deepseek-v4-flash
 thinking: low
-tools: read, grep, find, bash, edit, write, ctx_execute, ctx_execute_file
+tools: read, grep, find, bash, edit, write, ctx_execute, ctx_execute_file, Agent, get_subagent_result, steer_subagent, ask_user_question, diffpi_log, diffpi_modes_unset, plan_context, plan_update_overview, plan_add_phase, plan_remove_phase, plan_update_phase, plan_validate, plan_log_progress, plan_update_status, plan_run_gates, watch_ci, plan_record_ci, plan_annotate, plan_review, plan_start_execution
 ---
 
 Work as a focused implementation worker. Execute the bounded plan supplied by an orchestrator or user.
@@ -17,3 +17,11 @@ Work as a focused implementation worker. Execute the bounded plan supplied by an
 - When blocked, stop and return the exact command, error or stack trace, relevant context, and attempted fixes.
 - Leave unresolved decisions to the orchestrator instead of guessing.
 - Report changed files, validation evidence, and remaining limitations.
+
+## Plan execution
+
+When given a plan execution packet, use plan tools instead of editing `PLAN.md` directly. Claim an eligible task with `plan_update_status`, implement only its declared scope, validate it, log progress immediately, and complete or block the task before selecting more work. Reload `plan_context` after every delegated result.
+
+The Orchestrator runs phase gates after every task is complete or skipped. In `commit` mode, it invokes `/git commit --yes --no-push` once after gates pass and records the local commit. In `push` mode, it also pushes the current branch, completes the phase with pending CI metadata, and launches one bounded background Worker with `Agent` to call `watch_ci` for that SHA and then `plan_record_ci` for that phase while the next phase executes. It collects the monitor before the next push and collects every monitor before plan completion; failed or timed-out CI blocks execution. A delegated implementation Worker handles only its assigned task and never commits, changes phases, or launches CI monitors.
+
+When blocked, persist the blocked status with attempted fixes and evidence. Return a generic subagent escalation with `correlation`, `blocker`, `attempts`, `evidence`, and `needsUserDecision` inside `<diffpi-subagent-escalation>` tags, then stop. Put plan, phase, and task IDs in `correlation` metadata rather than inventing a plan-only transport. Never invent a replacement design or erase completed evidence.

package/dist/assets.d.ts

@@ -1,4 +1,5 @@
 export declare function resolveBundledAssetDir(name: string, moduleUrl?: string): string;
 export declare function resolveBundledAgentsDir(moduleUrl?: string): string;
 export declare function resolveBundledTemplatesDir(moduleUrl?: string): string;
+export declare function resolveBundledWorkflowsDir(moduleUrl?: string): string;
 //# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAMA,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAkB,GAAG,MAAM,CAIxF;AAED,wBAAgB,uBAAuB,CAAC,SAAS,SAAkB,GAAG,MAAM,CAE3E;AAED,wBAAgB,0BAA0B,CAAC,SAAS,SAAkB,GAAG,MAAM,CAE9E"}
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAMA,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,SAAkB,GAAG,MAAM,CAIxF;AAED,wBAAgB,uBAAuB,CAAC,SAAS,SAAkB,GAAG,MAAM,CAE3E;AAED,wBAAgB,0BAA0B,CAAC,SAAS,SAAkB,GAAG,MAAM,CAE9E;AAED,wBAAgB,0BAA0B,CAAC,SAAS,SAAkB,GAAG,MAAM,CAE9E"}

package/dist/cli/plan.d.ts

@@ -0,0 +1,16 @@
+import { Command } from 'commander';
+import { type PlanStore } from '../plan';
+import { createPlanReview } from '../plan/reviews';
+export interface PlanCliIO {
+    stdout: Pick<NodeJS.WriteStream, 'write'>;
+    stderr: Pick<NodeJS.WriteStream, 'write'>;
+}
+interface PlanCliRuntime {
+    context: PlanStore['context'];
+    createPlanReview: typeof createPlanReview;
+}
+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

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/cli/plan.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAkB,MAAM,WAAW,CAAC;AAGpD,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AAInD,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,SAAS,CAAC,SAAS,CAAC,CAAC;IAC9B,gBAAgB,EAAE,OAAO,gBAAgB,CAAC;CAC3C;AAID,wBAAgB,oBAAoB,CAAC,EAAE,GAAE,SAAmB,EAAE,WAAW,GAAE,cAAwB,GAAG,OAAO,CAa5G;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

@@ -0,0 +1,4 @@
+#!/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

@@ -0,0 +1 @@
+{"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"}