@difflab/pi 0.7.0 → 0.7.1-rc.202609290811.4ccd593

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

@@ -1,7 +1,20 @@
 # complete
 
-1. Parse an optional PR/MR id or URL, `--local`, and exactly one remote action: `--approve`, `--reject`, or `--abandon`. The skill-owned `close` alias follows this workflow. Skill-owned `--bg` dispatch has already occurred; a background child must not redispatch or ask questions. If a remote action is missing in foreground mode, ask the user with `header: "Action"`; all question headers must be 16 characters or fewer. In background mode, stop with a blocker instead of guessing.
-2. Call `review_context` first with the same target and `local: true` when `--local` is present, otherwise `local: false`.
-3. With `--local`, call `review_complete` with `local: true`. It archives the reply overlay to `.diffpi/reviews/<session-slug>.md`, then deletes the exact persisted tuicr session. This is destructive and prevents its comments from appearing in future tuicr sessions.
-4. Without `--local`, map `--approve`, `--reject`, or `--abandon` to the `review_complete` action `approve`, `reject`, or `abandon`. The tool applies the remote lifecycle action but does not merge.
-5. Report the archive path or remote result. Do not call `review_merge`.
+## 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.
+
+## 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.
+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,7 +1,11 @@
 # edit
 
-1. Parse an optional PR/MR number, URL, or branch target and `--local`. Skill-owned background dispatch has already occurred; a background child follows these steps without redispatch.
-2. Call `review_context` first with the same target and `local: true` when `--local` is present, otherwise `local: false`.
-3. Call `review_edit` with the same target and backend. With `--local`, it opens an existing local tuicr session. Without `--local`, it opens an existing PR/MR in tuicr, including a non-draft PR/MR for continued work on its comments.
-4. If no matching local session or remote PR/MR exists, report the error and direct the user to `new`. Do not create a review, generate findings, publish, complete, or merge.
-5. Report whether tuicr opened in a mux, prepared a Zed task, or returned a command.
+## 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.
+
+## 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.

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,36 +1,24 @@
 # help
 
-Print the following help text:
+## Parse arguments
 
-```text
-Workflows for PRs and local review. Use:
+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.
 
-Create a review and generate findings:
-  /review auto [pr-or-branch] [--local] [--bg]
+## Steps
 
-Create a local review or remote draft PR/MR:
-  /review new [title] [--intent text] [--base branch] [--local] [--bg]
+1. Show the complete subcommand list:
 
-Open an existing remote PR/MR in the system browser (never creates one):
-  /review open [pr-number|pr-url|branch] [--local]
+   ```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
+   ```
 
-Show review and worktree lifecycle status:
-  /review status [pr-number|pr-url|branch] [--local]
-
-Open an existing review in tuicr without generating findings:
-  /review edit [pr-number|pr-url|branch] [--local] [--bg]
-
-Address review comments:
-  /review address [pr-number|pr-url|branch] [--local] [--bg]
-
-Publish comments and a review status:
-  /review publish [pr-number|pr-url|branch] [--local] [--comment|--approve|--request-changes|--close] [--bg]
-
-Complete a review without merging:
-  /review complete [pr-number|pr-url|branch] [--local|--approve|--reject|--abandon] [--bg]
-
-Merge an approved remote review:
-  /review merge [pr-number|pr-url|branch] [--bg]
-```
-
-`--local` selects the working-tree tuicr backend. Otherwise, a target is a PR/MR number, URL, or branch; no target means the current branch. `--bg` launches a tracked background Orchestrator and leaves the current chat mode unchanged. `new` creates a review. `open` opens an existing remote URL in the system browser, or directs to `new`; with `--local` it creates/opens the local working-tree review. `status` reports local and remote state without requiring a forge or tuicr binary. `edit` only opens an existing local session or remote PR/MR in tuicr. `auto` creates a review, then delegates findings to the reviewer agent. `create` and `draft` alias `new`; `launch` aliases `auto`; `close` aliases `complete`. `publish` publishes remote draft PR/MR review comments and status or promotes local comments. `complete` makes a lifecycle decision without merging, or archives the local overlay and deletes its tuicr session.
+2. Show aliases: `create`/`draft` → `new`, `launch` → `auto`, `ready` → `publish`, `close` → `complete`, `land` → `merge`.

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

@@ -1,6 +1,20 @@
 # merge
 
-1. Parse an optional PR number, URL, or branch. This workflow is remote-only; reject `--local`. The skill has already handled `--bg`; a background child must not redispatch. Call `review_context` first with the target and `local: false`. Do not query the forge through MCP or duplicate merge-readiness checks: `review_merge` uses the GitHub CLI to confirm the PR is open, non-draft, clean, and its checks are settled before merging. Do not require approval from the current user; authors cannot approve their own PRs. GitHub branch protection remains authoritative.
-2. If a conventional squash subject is required and the subject is unclear, use `ask_user_question`.
-3. Call `review_merge` with the chosen subject. Treat its CLI-backed readiness result as authoritative.
-4. Report the merge result.
+## Parse arguments
+
+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,19 +1,21 @@
 # new
 
-## Arguments
+## Parse arguments
 
-```text
-/review new [title] [--intent text] [--base branch] [--local] [--bg]
-```
+Accept `new [title] [--intent text] [--base branch] [--local]` and a target named in the request. Fuzzy-match draft intent. Prefer explicit arguments/flags, then safe natural-language or repository title/intent/target/base/backend, then available 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.
 
-- `title` is the optional first positional argument; quote a title containing spaces.
-- `--intent` and `--base` each consume the following value. `--local` is a boolean backend flag; the skill handles `--bg` before this workflow.
-- Flags may appear in any order. Reject unknown or duplicate flags, missing flag values, and extra positional arguments. Stating this grammar before the procedure is intentional: an explicit argument contract is the best practice for making workflow behavior predictable and preventing ambiguous execution.
+## Steps
 
-## Workflow
+1. Resolve the concrete target/backend/local and base with `review_context`. Substitute actual values for every placeholder, including the exact request and issue URL if applicable; never send raw `{placeholders}`. When native subagents are available, launch a lightweight/low `diffpi-worker` background subagent for this bounded draft-creation task. Pass the following self-contained prompt with ambient capabilities:
 
-1. Parse the arguments using the grammar above after skill-owned background dispatch. A background child follows these steps directly and must not redispatch. A remote target is the current branch; `new` creates a new review rather than opening an existing one.
-2. Call `review_context` first with `local: true` when `--local` is present, otherwise `local: false`.
-3. Call `review_new` with the parsed title, intent, base branch, and the same explicit backend selection (`local: true` for `--local`, otherwise `local: false`). With `--local`, it creates and opens a local tuicr working-tree review. Without `--local`, it requires a clean, pushed branch, creates a draft PR/MR, and opens that PR/MR in tuicr.
-4. If a local session or remote PR/MR already exists, direct the user to `edit` instead.
-5. Report the PR/MR URL and whether tuicr opened in a mux, prepared a Zed task, or returned a command. Do not generate findings, publish, complete, or merge.
+   ```text
+   Create a review draft.
+   - Repository: {absolute repo cwd}; exact request: {exact request}.
+   - Resolved target: {target}; backend: {backend}; local: {local}; title: {title}; intent: {intent}; base: {base}; issue URL: {issue URL or none}; approved policy: {policy}.
+   - This explicitly assigned review-draft creation is the only review lifecycle mutation authorized here. Call review_context first. Reuse its target/backend/local/cwd for all subsequent calls; never switch backend silently.
+   - Reject unsupported forge, dirty remote branch or unavailable local base/default with exact evidence.
+   - Call review_new to create the local tuicr review or remote draft PR/MR. Call review_launch_ui only if needed; report a returned launch command if automatic launch fails.
+   - Verify and report the actual created target and draft state or exact failure. Do not stage findings, publish, complete or merge.
+   ```
+
+2. If no native subagents are available, follow [foreground fallback](foreground-fallback.md) before creation. Only after explicit confirmation, perform the draft-creation steps above inline and verify with `review_status`; do not claim a Worker result. Otherwise require the completed child result and verify the created target/draft with `review_status`. Stop on failure; report the actual result, not merely a queued ID or claim. Do not assign the Worker publication, merge, findings judgment or substantive inspection.

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

@@ -1,3 +1,11 @@
 # open
 
-Call `review_context` first. Without `--local`, call `review_open` to resolve an existing PR/MR and open its URL in the system browser. It must never create a PR/MR; if none exists, direct the user to `/review new`. If browser launch fails, show the plain URL. With `--local`, call `review_new` with `local=true` to preserve local working-tree behavior.
+## Parse arguments
+
+Accept `open [target] [--local]`. Fuzzy-match the existing PR/MR or tuicr 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.
+
+## 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_open` for an existing remote PR/MR in the browser. For `--local`, call `review_edit` to open only the matching existing tuicr session.
+3. Report the opened target or exact missing-session/browser/launch failure. Do not create a review, generate findings or mutate review state.

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

@@ -1,8 +1,20 @@
 # publish
 
-1. Parse an optional PR/MR id or URL, `--local`, and one status: `--comment`, `--approve`, `--request-changes`, or `--close`. The default is comment. The skill has already handled `--bg`; a background child follows these steps without redispatch.
-2. Call `review_context` first with the target and `local: true` so the exact tuicr PR session can be inspected. If no matching local session exists, continue with `local: false` only for forge-native pending review work. If that session exists and has drafts, publish through the local promotion path even when the user omitted `--local`. Use `local: false` only when no matching tuicr session exists or when the target has forge-native pending review work.
-3. The local promotion path reads the exact tuicr session. A local line comment on the same file and line as an existing remote thread is treated as a response, not a new comment. A leading `[REOPEN]`, `[RESOLVE]`, or `[DELETE]` changes the thread state; the marker is removed from the response body. `[DELETE]` deletes the matched remote thread when the forge supports it. Other unpublished line comments become new review comments. The tool follows the stored local overlay path, posts unpublished replies to their remote threads, and then publishes the selected status. Question replies remain open. The tool does not post an overall review comment.
-4. For a forge-native review without a matching tuicr session, call `review_publish` without `local`. Existing pending forge comments already contain provenance, so the tool only publishes them with the selected status and no overall comment.
-5. Comment, approve, and request-changes mark a draft PR/MR ready before publication. Close publishes pending work as comment status and then closes the PR/MR. GitLab rejects request-changes because it has no equivalent review state.
-6. Report promoted comment and reply counts, the public status, and the final PR/MR state. Publishing never merges. If a response cannot be matched by file and line, report it as a new comment rather than silently attaching it to the wrong thread.
+## Parse arguments
+
+Accept `publish [target] [--local] [--comment|--approve|--request-changes|--close]`. 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 target/backend/local. 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. Promote only drafts matching the remote PR/MR; preserve `local:true` for a working-tree session. 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,3 +1,10 @@
 # status
 
-Call `review_context` first, then `review_status` with the same target and local setting. Report branch, worktree counts, local and remote review state, URLs, and remote tuicr state. Status must remain useful when no forge or tuicr binary is installed.
+## Parse arguments
+
+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, tuicr session, pending/draft state and exact errors. Do not create a review or mutate source, comments or lifecycle state.

package/templates/plan/PLAN.md

@@ -1,13 +1,10 @@
-<!-- diffpi-plan: {"schemaVersion":1,"id":"{{id}}","revision":0,"branch":"{{branch}}","issueId":"{{issue_id}}","issueUrl":"{{issue_url}}","status":"draft","createdAt":"{{created_at}}","updatedAt":"{{updated_at}}"} -->
-
 # {{title}}
 
 - **Plan ID:** {{id}}
 - **Branch:** {{branch}}
+- **Status:** draft
 - **Issue:** {{issue_id}}
 - **Issue URL:** {{issue_url}}
-- **Status:** draft
-- **Revision:** 0
 
 ## Intent
 
@@ -15,26 +12,36 @@
 
 ## Requirements
 
-<!-- Add requirements. -->
+<!-- Add concrete requirements. -->
 
 ## Design
 
 ### Big Ideas
 
-<!-- Describe the main approach. -->
+<!-- Describe the outcome-oriented design. -->
 
 ### Key API Addition/Updates
 
-<!-- Describe public API changes. -->
+<!-- Describe public or internal contract changes. -->
 
 ### Consequences
 
-<!-- Describe trade-offs and limitations. -->
+<!-- Describe before/after behavior, risks, and trade-offs. -->
+
+## Phases
+
+<!-- Use numbered phases. State prerequisites on the phase only; do not add task dependencies here. -->
+
+### Phase 1: <!-- phase title -->
 
-## Implementation
+- **Phase ID:** <!-- assign a stable phase ID -->
+- **Prerequisites:** <!-- list phase IDs, or “None” -->
+- **Objective:** <!-- state the outcome -->
+- **Constraints:** <!-- phase guardrails or None; do not repeat them in briefs -->
 
-<!-- Add phases with one complete plan_apply_revision request. -->
+- [ ] <!-- assign a stable task ID --> Task title
+- [ ] <!-- assign a stable task ID --> Another task title
 
 ## References
 
-<!-- Add references. -->
+<!-- Add repository or external references. Record one completed Plan Reviewer round per authoring cycle: reviewed file hashes, Git state, verdict and findings; each finding's disposition; post-fix structural verification and current snapshot. A repaired BLOCKING verdict is not a reviewer PASS. Keep DRAFT until explicit finalize/go. -->

package/templates/plan/implementation.md

@@ -1,30 +1,41 @@
-<!-- diffpi-implementation: {"schemaVersion":1,"planRevision":{{plan_revision}},"ordinal":{{phase_ordinal}},"phaseId":"{{phase_id}}"} -->
-
 # Phase {{phase_ordinal}}: {{phase_title}}
 
 - **Phase ID:** {{phase_id}}
-- **Plan Revision:** {{plan_revision}}
-
-## Summary
-
-{{phase_summary}}
+- **Prerequisites:** {{phase_prerequisites}}
 
 ## Objective
 
 {{phase_objective}}
 
-## Tasks
+## Files Affected
 
-{{phase_tasks}}
+<!-- This is the sole file scope for this phase. Use one fenced text tree; label each file leaf [ADD], [MODIFY], [REMOVE], [MOVE from: path], or [VERIFY]. Do not repeat file scopes in tasks or PLAN.md. -->
 
-## API Changes
+```text
+Phase {{phase_ordinal}}/
+├── [MODIFY] <!-- exact/path/to/implementation-file -->
+└── [VERIFY] <!-- exact/path/to/test-or-check -->
+{{phase_files_affected}}
+```
 
-{{phase_api}}
+## Tasks
+
+<!-- Keep tasks flat and in phase order. Repeat this shape for each task. -->
 
-## Libraries and Algorithms
+### 1. <!-- task title -->
 
-{{phase_libraries}}
+- **Task ID:** <!-- stable task ID -->
+- **Steps:**
+  1. <!-- ordered implementation action -->
+  2. <!-- ordered implementation action -->
+- **Verify:**
+  - <!-- command or inspection that proves this task -->
+- **Acceptance:** <!-- observable result -->
+
+{{phase_tasks}}
 
 ## Implementation Constraints
 
-{{phase_constraints}}
+<!-- Free-form implementation details, not a restatement of PLAN.md phase constraints. Add only useful optional headings: Required Libraries & Technology Choices, Key Algorithm Specifications, Core Invariants. Refer to the PLAN.md phase ID instead of repeating a phase guardrail. -->
+
+{{phase_implementation_constraints}}

package/dist/commands/mode.d.ts

@@ -1,5 +0,0 @@
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import type { ModeController } from '../modes';
-/** Register the inline agent mode command. */
-export declare function registerModeCommand(pi: ExtensionAPI, modes: ModeController): void;
-//# sourceMappingURL=mode.d.ts.map

package/dist/commands/mode.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"mode.d.ts","sourceRoot":"","sources":["../../src/commands/mode.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAoB,MAAM,iCAAiC,CAAC;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAK/C,8CAA8C;AAC9C,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,cAAc,GAAG,IAAI,CAKjF"}

package/dist/modes.d.ts

@@ -1,60 +0,0 @@
-import { type ExtensionAPI, type ExtensionContext } from '@earendil-works/pi-coding-agent';
-export type ModePromptStrategy = 'append' | 'replace';
-export type ModeThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
-export interface AgentMode {
-    id: string;
-    label: string;
-    description: string;
-    systemPrompt: string;
-    promptStrategy: ModePromptStrategy;
-    modelPreferences: string[];
-    thinkingLevel?: ModeThinkingLevel;
-    tools: string[];
-    source: string;
-    sourcePath: string;
-}
-export interface ModeCatalog {
-    modes: AgentMode[];
-    diagnostics: string[];
-}
-export interface ModeListOptions {
-    includeSkills?: boolean;
-}
-export interface ModeController {
-    list(ctx: ExtensionContext, options?: ModeListOptions): Promise<ModeCatalog>;
-    set(agent: string, ctx: ExtensionContext): Promise<ModeSelectionResult>;
-    unset(ctx: ExtensionContext): Promise<ModeSelectionResult>;
-    restore(ctx: ExtensionContext): Promise<void>;
-    refresh(ctx: ExtensionContext): void;
-    apply(systemPrompt: string): string;
-    getActive(): AgentMode | undefined;
-}
-export type ModeSelectionResult = {
-    ok: true;
-    active?: AgentMode;
-    message: string;
-} | {
-    ok: false;
-    message: string;
-};
-export interface ModeDiscoveryOptions extends ModeListOptions {
-    cwd: string;
-    agentDir?: string;
-    bundledAgentsDir?: string;
-    homeDir?: string;
-    projectTrusted: boolean;
-}
-export interface ModeControllerOptions {
-    agentDir?: string;
-    bundledAgentsDir?: string;
-    homeDir?: string;
-}
-type ModeRuntime = Pick<ExtensionAPI, 'appendEntry' | 'getActiveTools' | 'getAllTools' | 'getThinkingLevel' | 'setActiveTools' | 'setModel' | 'setThinkingLevel'>;
-/** Discover standard agents and, when requested, qualified skill agents. */
-export declare function discoverAgentModes(options: ModeDiscoveryOptions): Promise<ModeCatalog>;
-/** Resolve an agent id without guessing an unqualified skill-agent name. */
-export declare function resolveAgentMode(modes: readonly AgentMode[], requested: string): ModeSelectionResult;
-/** Create the session-scoped controller that applies and restores complete mode profiles. */
-export declare function createModeController(pi: ModeRuntime, options?: ModeControllerOptions): ModeController;
-export {};
-//# sourceMappingURL=modes.d.ts.map

package/dist/modes.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"modes.d.ts","sourceRoot":"","sources":["../src/modes.ts"],"names":[],"mappings":"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"}

package/dist/plan/index.d.ts

@@ -1,4 +0,0 @@
-export type { PlanCiRetry, PlanCiUpdate, PlanStatusUpdate, PlanStatusUpdateResult } from './operations';
-export { createPlanStore, type InitPlanInput, type NewPlanLogEntry, type PlanResolution, type PlanStore, type PlanStoreOptions, type ResolvePlanFilters, } from './store';
-export type * from './types';
-//# sourceMappingURL=index.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plan/index.ts"],"names":[],"mappings":"AAEA,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACxG,OAAO,EACL,eAAe,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,SAAS,EACd,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,SAAS,CAAC;AACjB,mBAAmB,SAAS,CAAC"}

package/dist/plan/markdown.d.ts

@@ -1,9 +0,0 @@
-import type { PlanDocument, PlanImplementationBrief, PlanPhase, PlanRecord, PlanValidationIssue, PlanValidationOptions } from './types';
-export declare function countDesignWords(plan: PlanDocument): number;
-export declare function validatePlanDocument(plan: PlanDocument, options?: PlanValidationOptions): PlanValidationIssue[];
-export declare function validatePlanBriefs(plan: PlanDocument, briefs: readonly PlanImplementationBrief[]): PlanValidationIssue[];
-export declare function validatePlanRecord(record: PlanRecord, options?: PlanValidationOptions): Promise<PlanValidationIssue[]>;
-export declare function renderImplementationBrief(planRevision: number, ordinal: number, phase: PlanPhase, brief: PlanImplementationBrief): string;
-export declare function renderPlanDocument(plan: PlanDocument, previousSource?: string): string;
-export declare function parsePlanDocument(source: string, ref?: string): PlanDocument;
-//# sourceMappingURL=markdown.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"markdown.d.ts","sourceRoot":"","sources":["../../src/plan/markdown.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,YAAY,EACZ,uBAAuB,EACvB,SAAS,EACT,UAAU,EAGV,mBAAmB,EACnB,qBAAqB,EACtB,MAAM,SAAS,CAAC;AAgDjB,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAM3D;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,GAAE,qBAA0B,GAAG,mBAAmB,EAAE,CAuDnH;AAED,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,YAAY,EAClB,MAAM,EAAE,SAAS,uBAAuB,EAAE,GACzC,mBAAmB,EAAE,CAqDvB;AAED,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAMhC;AAED,wBAAgB,yBAAyB,CACvC,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,SAAS,EAChB,KAAK,EAAE,uBAAuB,GAC7B,MAAM,CAsDR;AAED,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,YAAY,EAAE,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAgEtF;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,SAAY,GAAG,YAAY,CA6B/E"}

package/dist/plan/operations.d.ts

@@ -1,43 +0,0 @@
-import type { SubagentEscalation } from '../extensions/subagentx';
-import type { PlanStore } from './store';
-import type { PlanCiStatus, PlanCommit, PlanDocument, PlanPhaseStatus, PlanRecord, PlanStatus } from './types';
-export interface PlanStatusUpdate {
-    target: {
-        type: 'plan' | 'phase' | 'task';
-        id?: string;
-    };
-    expectedStatus: PlanStatus | PlanPhaseStatus;
-    status: PlanStatus | PlanPhaseStatus;
-    actor: string;
-    message: string;
-    executionId?: string;
-    evidence?: string[];
-    blockedReason?: string;
-    attempts?: string[];
-    needsUserDecision?: boolean;
-    commit?: PlanCommit;
-}
-export interface PlanStatusUpdateResult {
-    record: PlanRecord;
-    escalation?: SubagentEscalation;
-}
-export interface PlanCiUpdate {
-    phaseId: string;
-    sha: string;
-    status: Exclude<PlanCiStatus, 'pending'>;
-    actor: string;
-    executionId: string;
-    detail: string;
-}
-export interface PlanCiRetry {
-    phaseId: string;
-    sha: string;
-    actor: string;
-    executionId: string;
-    reason: string;
-}
-export declare function updatePlanStatus(store: PlanStore, cwd: string, query: string, input: PlanStatusUpdate): Promise<PlanStatusUpdateResult>;
-export declare function updatePlanCi(store: PlanStore, cwd: string, query: string, input: PlanCiUpdate): Promise<PlanRecord>;
-export declare function retryPlanCi(store: PlanStore, cwd: string, query: string, input: PlanCiRetry): Promise<PlanRecord>;
-export declare function assertPhasePushEligible(plan: PlanDocument, phaseId: string, executionId: string): void;
-//# sourceMappingURL=operations.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"operations.d.ts","sourceRoot":"","sources":["../../src/plan/operations.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAElE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAEV,YAAY,EACZ,UAAU,EACV,YAAY,EAEZ,eAAe,EACf,UAAU,EACV,UAAU,EAGX,MAAM,SAAS,CAAC;AAIjB,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;QAAC,EAAE,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACzD,cAAc,EAAE,UAAU,GAAG,eAAe,CAAC;IAC7C,MAAM,EAAE,UAAU,GAAG,eAAe,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,UAAU,CAAC;IACnB,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,OAAO,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IACzC,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB;AAID,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,gBAAgB,GACtB,OAAO,CAAC,sBAAsB,CAAC,CAkIjC;AAED,wBAAsB,YAAY,CAChC,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,YAAY,GAClB,OAAO,CAAC,UAAU,CAAC,CAwCrB;AAED,wBAAsB,WAAW,CAC/B,KAAK,EAAE,SAAS,EAChB,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,KAAK,EAAE,WAAW,GACjB,OAAO,CAAC,UAAU,CAAC,CAoCrB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI,CAiBtG"}

package/dist/plan/reviews.d.ts

@@ -1,28 +0,0 @@
-import type { PlanRecord } from './types';
-interface PlanReviewDump {
-    schemaVersion: 1;
-    planId: string;
-    planRevision: number;
-    source: 'tuicr';
-    sourceId: string;
-    planSource: string;
-    content: string;
-}
-interface PlanReview {
-    path: string;
-    dump: PlanReviewDump;
-}
-interface PlanReviewRuntime {
-    execute?: (command: string, args: string[], cwd: string, interactive: boolean) => Promise<{
-        code: number;
-        stdout: string;
-        stderr: string;
-    }>;
-}
-export declare function createPlanReview(record: PlanRecord, runtime?: PlanReviewRuntime): Promise<{
-    code: number;
-    review: PlanReview;
-}>;
-export declare function readPlanReview(record: PlanRecord): Promise<PlanReview | undefined>;
-export {};
-//# sourceMappingURL=reviews.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"reviews.d.ts","sourceRoot":"","sources":["../../src/plan/reviews.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAI1C,UAAU,cAAc;IACtB,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,UAAU,UAAU;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,cAAc,CAAC;CACtB;AAED,UAAU,iBAAiB;IACzB,OAAO,CAAC,EAAE,CACR,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;AAID,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,UAAU,EAClB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,CA4B/C;AAED,wBAAsB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAiBxF"}