implannotator 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## 0.2.0 - Unreleased
+
+- Move the canonical npm package from `@yoseph_23/implannotator` to the unscoped `implannotator` name.
+- Support the shorter installation command: `pi install npm:implannotator`.
+- Add Pi extension and skill discovery keywords for the package gallery.
+
+## 0.1.1 - 2026-07-15
+
+- Reuse `@plannotator/pi-extension` as a separately installed companion package.
+- Stop bundling and statically loading a second Plannotator extension, preventing duplicate tool, command, and `--plan` flag conflicts.
+- Detect companion availability at session startup and retain text approval fallback when it is missing.
+- Reduce the published package size substantially.
+
+## 0.1.0 - 2026-07-15
+
+- Initial independent Implannotator Pi package.
+- Approval-gated planning, adaptive QA, Plannotator code review, bounded repair loops, resumable audit records, and complete namespaced design guidance.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yoseph_23
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,76 @@
+# Implannotator
+
+`implannotator` is a cross-platform Pi package for production-grade frontend work with mandatory plan approval, adaptive browser QA, Plannotator code review, bounded repairs, and resumable audit records.
+
+## Installation
+
+Plannotator is a companion Pi package. Install it once, then install Implannotator:
+
+```bash
+pi install npm:@plannotator/pi-extension
+pi install npm:implannotator
+```
+
+Implannotator reuses the active companion through Plannotator's public event API; it does not bundle or register a second Plannotator extension. If the companion is unavailable, mandatory text approval remains available.
+
+For local development:
+
+```bash
+cd <path-to-repository>/implannotator
+npm install
+pi install npm:@plannotator/pi-extension
+pi install .
+```
+
+Restart Pi or run `/reload`, then use:
+
+```text
+/implannotator
+/implannotator craft <target>
+/implannotator audit <target>
+/implannotator status
+/implannotator resume
+/implannotator review
+/implannotator verify
+/implannotator config
+/implannotator update-check
+```
+
+The skill may also be selected automatically for frontend design and implementation requests.
+
+## Workflow
+
+1. Inspect the project without mutation.
+2. Draft a complete plan.
+3. Approve it in Plannotator or through the text fallback.
+4. Implement as the sole writer.
+5. Run adaptive Quick, Standard, or Full QA.
+6. Open the initial code review.
+7. Repair up to three times without reopening intermediate browser tabs.
+8. Open one final review.
+9. Complete only after approval or an explicit warned override.
+
+Audit records are written to `.implannotator/runs/<run-id>/`. The package never automatically stashes, resets, commits, or pushes.
+
+## Configuration
+
+Configuration merges in this order:
+
+1. Built-in defaults
+2. `~/.pi/agent/implannotator.json`
+3. `<project>/.pi/implannotator.json`
+
+Low-risk automatic approval is disabled by default. See [docs/configuration.md](docs/configuration.md).
+
+## Development
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run test:compat
+npm run verify:snapshot
+npm run pack:check
+```
+
+See [docs/installation.md](docs/installation.md), [docs/architecture.md](docs/architecture.md), [docs/workflow.md](docs/workflow.md), [docs/qa.md](docs/qa.md), and [docs/security.md](docs/security.md).

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,9 @@
+# Third-party notices
+
+## Plannotator
+
+Implannotator interoperates with the separately installed `@plannotator/pi-extension` companion package, licensed under MIT OR Apache-2.0. See <https://github.com/backnotprop/plannotator>.
+
+## Implannotator design-guidance snapshot
+
+The files under `skills/implannotator/` were adapted from the locally installed Impeccable skill version 3.7.1. The source snapshot did not include license or repository metadata. **Do not publish this npm package publicly until redistribution rights and required attribution have been confirmed.** `scripts/assert-publish-ready.mjs` enforces an explicit acknowledgement.

package/docs/architecture.md

@@ -0,0 +1,12 @@
+# Architecture
+
+One Pi package exposes two resources:
+
+- `skills/implannotator/`: the complete namespaced design skill and mandatory workflow contract.
+- `extensions/index.ts`: commands, control tool, approval gate, state machine, audit storage, QA contracts, and Plannotator adapter.
+
+The package reuses a separately installed `@plannotator/pi-extension` companion and communicates only through its documented `plannotator:request` event channel. It neither bundles nor statically loads a second Plannotator extension, and it does not import private browser/server modules. Session startup detects the companion's public tool/command registration; when absent, the workflow uses mandatory text approval fallback.
+
+State is persisted atomically under `.implannotator/runs/<run-id>/`. The workflow is resumable and illegal state transitions are rejected.
+
+The extension enforces pre-approval mutation blocking for built-in write/edit/shell tools. The skill requires the main agent to be the sole writer; optional subagents are read-only reviewers.

package/docs/compatibility.md

@@ -0,0 +1,9 @@
+# Compatibility
+
+- Node.js 20 or newer
+- Pi 0.80.7 or newer (security baseline)
+- Companion Pi package `@plannotator/pi-extension` compatible with `^0.23.1`
+
+`npm run test:compat` checks the installed Plannotator public event contract. `npm run update-check` reports newer releases without modifying dependencies. CI tests supported Node versions on Linux, macOS, and Windows.
+
+Install the companion once with `pi install npm:@plannotator/pi-extension`. Implannotator does not bundle or register another copy, so it can coexist with the standalone extension without duplicate tools, commands, flags, listeners, or tabs. If the companion is disabled or missing, Implannotator reports that state and uses text approval fallback.

package/docs/configuration.md

@@ -0,0 +1,25 @@
+# Configuration
+
+Create `~/.pi/agent/implannotator.json` for global defaults or `.pi/implannotator.json` in a project for overrides.
+
+```json
+{
+  "schemaVersion": 1,
+  "approval": {
+    "required": true,
+    "allowLowRiskAutoApprove": false,
+    "proceedRequiresSecondConfirmation": true,
+    "browserTimeoutMs": 1800000
+  },
+  "repairs": {
+    "maxAttempts": 3,
+    "reopenOnlyForFinalReview": true
+  },
+  "qa": {
+    "defaultProfile": "adaptive",
+    "requireEvidence": true
+  }
+}
+```
+
+Mandatory approval, second-confirmation overrides, safe Git behavior, the three-repair ceiling, final-only tab reopening, read-only subagents, and sole-writer behavior cannot be weakened by configuration.

package/docs/installation.md

@@ -0,0 +1,30 @@
+# Installation
+
+Implannotator and Plannotator are separate Pi packages that cooperate through Plannotator's public event API.
+
+```bash
+pi install npm:@plannotator/pi-extension
+pi install npm:implannotator
+```
+
+Restart Pi or run `/reload`. Use `/implannotator` to begin.
+
+## Why two packages?
+
+Pi loads separately installed packages from independent module roots. Bundling and statically loading Plannotator inside Implannotator while also installing Plannotator directly registers the same tools, commands, and `--plan` flag twice. Implannotator reuses the one active companion and never loads a duplicate.
+
+## Without Plannotator
+
+Implannotator remains usable with mandatory text approval. It shows a session warning and status indicator until the companion is installed or enabled.
+
+## Migrate from the scoped package
+
+The original releases used `@yoseph_23/implannotator`. Version-pinned Pi packages do not update automatically, and npm treats the unscoped name as a separate package. Remove the scoped installation and install the canonical unscoped package:
+
+```bash
+pi remove npm:@yoseph_23/implannotator@0.1.1
+pi install npm:@plannotator/pi-extension
+pi install npm:implannotator
+```
+
+If a different scoped version is installed, use the exact source shown by `pi list` in the remove command.

package/docs/qa.md

@@ -0,0 +1,5 @@
+# QA profiles
+
+Quick covers targeted checks for tiny isolated changes. Standard adds multi-viewport, state, theme, motion, touch, overflow, and content-resilience checks. Full adds reference comparison, Core Web Vitals, cross-browser coverage when available, internationalization, full user flows, and independent read-only review.
+
+Each check is recorded as passed, failed, unavailable, or not-applicable. Unavailable tooling is never reported as passed. Every failure links to command, screenshot, URL/viewport, or observation evidence.

package/docs/security.md

@@ -0,0 +1,10 @@
+# Security and work preservation
+
+- Pi packages execute with the user's permissions; inspect package source before installation.
+- Project mutation is blocked until plan approval during an active run.
+- Writes outside the project are blocked during active runs.
+- Automatic Git stash, reset, clean, restore, checkout, switch, commit, merge, rebase, and push are blocked.
+- Existing dirty work is preserved and reported.
+- Audit records and screenshots may contain private product information. They use restrictive local file permissions where supported and should not be committed unless deliberately reviewed.
+- `allowLowRiskAutoApprove` is opt-in and applies only when interactive approval is unavailable.
+- Public npm publishing is blocked until third-party redistribution rights are acknowledged explicitly.

package/docs/troubleshooting.md

@@ -0,0 +1,17 @@
+# Troubleshooting
+
+## Browser review unavailable
+
+Implannotator returns a text-review request. Present the plan or diff evidence in chat and record the explicit decision. Low-risk continuation is not automatic unless enabled.
+
+## Plannotator companion not active
+
+Install or enable the companion with `pi install npm:@plannotator/pi-extension`, then restart Pi or run `/reload`. The canonical unscoped `implannotator` package and scoped `@yoseph_23/implannotator` 0.1.1 do not bundle a second copy. Scoped version 0.1.0 should be removed because it can register duplicate tools and flags.
+
+## Run interrupted
+
+Use `/implannotator status` then `/implannotator resume`. Inspect `.implannotator/runs/<run-id>/run.json` and do not repeat completed mutations.
+
+## Mutation blocked
+
+The plan has not been approved, the path is outside the active project, or the command is unsafe Git automation. Complete the approval step or perform the action manually outside the workflow after reviewing the risk.

package/docs/workflow.md

@@ -0,0 +1,12 @@
+# Workflow
+
+The durable state machine is:
+
+```text
+inspecting -> planning -> awaiting plan review -> approved -> implementing
+-> QA -> initial review -> repair/QA (up to 3) -> final review -> complete
+```
+
+Rejection or close offers Revise, Proceed anyway, or Stop. Proceed anyway requires a second warning and creates a durable override decision. Browser-unavailable sessions use text approval; conservative low-risk auto-approval is disabled by default.
+
+Review cadence is fixed: one plan tab, one initial code-review tab, no intermediate repair tabs, and one final code-review tab.

package/extensions/commands/register.ts

@@ -0,0 +1,39 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { Orchestrator } from "../workflow/orchestrator.js";
+
+const MANAGEMENT = new Set(["status", "resume", "review", "verify", "config", "update-check"]);
+
+export function registerCommands(pi: ExtensionAPI, getOrchestrator: (cwd: string) => Orchestrator): void {
+  pi.registerCommand("implannotator", {
+    description: "Approval-gated frontend design and implementation: /implannotator [command] [target]",
+    handler: async (args, ctx) => handle(args.trim(), pi, ctx, getOrchestrator),
+  });
+}
+
+async function handle(args: string, pi: ExtensionAPI, ctx: ExtensionCommandContext, getOrchestrator: (cwd: string) => Orchestrator): Promise<void> {
+  const [first = "", ...rest] = splitArgs(args);
+  const workflow = getOrchestrator(ctx.cwd);
+  if (first === "status") {
+    const run = workflow.active();
+    ctx.ui.notify(run ? `Implannotator ${run.id}: ${run.phase}, repairs ${run.repairCount}/3, QA ${run.qaProfile}` : "No Implannotator run exists here.", "info");
+    return;
+  }
+  if (first === "config") {
+    ctx.ui.notify("Config precedence: built-in defaults, ~/.pi/agent/implannotator.json, then <project>/.pi/implannotator.json.", "info");
+    return;
+  }
+  const instruction = !args
+    ? "Use the implannotator skill. Inspect this frontend project and recommend the 2-3 highest-value commands, but do not implement until I choose and approve a plan."
+    : MANAGEMENT.has(first)
+      ? `Use the implannotator skill and ${first}${rest.length ? ` ${rest.join(" ")}` : ""} the active workflow.`
+      : `Use the implannotator skill. Start or continue an approval-gated run for command: ${first}${rest.length ? `; target: ${rest.join(" ")}` : ""}.`;
+  pi.sendUserMessage(instruction);
+}
+
+export function splitArgs(input: string): string[] {
+  const result: string[] = [];
+  const pattern = /"([^"]*)"|'([^']*)'|([^\s]+)/g;
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(input))) result.push(match[1] ?? match[2] ?? match[3] ?? "");
+  return result;
+}

package/extensions/config/defaults.ts

@@ -0,0 +1,16 @@
+import type { ImplannotatorConfig } from "../domain/types.js";
+
+export const DEFAULT_CONFIG: ImplannotatorConfig = {
+  schemaVersion: 1,
+  approval: {
+    required: true,
+    allowLowRiskAutoApprove: false,
+    proceedRequiresSecondConfirmation: true,
+    browserTimeoutMs: 30 * 60 * 1000,
+  },
+  repairs: { maxAttempts: 3, reopenOnlyForFinalReview: true },
+  qa: { defaultProfile: "adaptive", requireEvidence: true },
+  audit: { directory: ".implannotator/runs", retentionDays: 90, redactSensitiveValues: true },
+  git: { allowAutomaticCommit: false, allowAutomaticStash: false, preserveExistingChanges: true },
+  subagents: { enabled: true, readOnly: true, mainAgentSoleWriter: true },
+};

package/extensions/config/loader.ts

@@ -0,0 +1,84 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+import { DEFAULT_CONFIG } from "./defaults.js";
+import type { ImplannotatorConfig } from "../domain/types.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+
+function merge<T>(base: T, override: unknown): T {
+  if (!isRecord(base) || !isRecord(override)) return (override === undefined ? base : override) as T;
+  const result: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(override)) {
+    result[key] = isRecord(value) && isRecord(result[key]) ? merge(result[key], value) : value;
+  }
+  return result as T;
+}
+
+function readJson(path: string): unknown {
+  if (!existsSync(path)) return undefined;
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    throw new Error(`Invalid Implannotator configuration at ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+const CONFIG_KEYS: Record<string, readonly string[]> = {
+  root: ["schemaVersion", "approval", "repairs", "qa", "audit", "git", "subagents"],
+  approval: ["required", "allowLowRiskAutoApprove", "proceedRequiresSecondConfirmation", "browserTimeoutMs"],
+  repairs: ["maxAttempts", "reopenOnlyForFinalReview"],
+  qa: ["defaultProfile", "requireEvidence"],
+  audit: ["directory", "retentionDays", "redactSensitiveValues"],
+  git: ["allowAutomaticCommit", "allowAutomaticStash", "preserveExistingChanges"],
+  subagents: ["enabled", "readOnly", "mainAgentSoleWriter"],
+};
+
+function assertKnownConfig(value: unknown, source: string): void {
+  if (value === undefined) return;
+  if (!isRecord(value)) throw new Error(`Implannotator configuration at ${source} must be an object.`);
+  for (const key of Object.keys(value)) {
+    if (!CONFIG_KEYS.root!.includes(key)) throw new Error(`Unknown Implannotator setting ${key} in ${source}.`);
+    if (key !== "schemaVersion" && value[key] !== undefined) {
+      if (!isRecord(value[key])) throw new Error(`Implannotator setting ${key} in ${source} must be an object.`);
+      for (const nested of Object.keys(value[key])) {
+        if (!CONFIG_KEYS[key]!.includes(nested)) throw new Error(`Unknown Implannotator setting ${key}.${nested} in ${source}.`);
+      }
+    }
+  }
+}
+
+export function validateConfig(config: ImplannotatorConfig): ImplannotatorConfig {
+  if (config.schemaVersion !== 1) throw new Error("Unsupported Implannotator config schemaVersion.");
+  if (config.approval.required !== true) throw new Error("approval.required cannot be disabled.");
+  if (config.approval.proceedRequiresSecondConfirmation !== true) throw new Error("Proceed confirmation cannot be disabled.");
+  if (!Number.isInteger(config.approval.browserTimeoutMs) || config.approval.browserTimeoutMs < 1_000) throw new Error("approval.browserTimeoutMs must be at least 1000.");
+  if (!Number.isInteger(config.repairs.maxAttempts) || config.repairs.maxAttempts < 0 || config.repairs.maxAttempts > 3) {
+    throw new Error("repairs.maxAttempts must be an integer from 0 through 3.");
+  }
+  if (config.repairs.reopenOnlyForFinalReview !== true) throw new Error("Intermediate repair review tabs cannot be enabled.");
+  if (!['adaptive', 'quick', 'standard', 'full'].includes(config.qa.defaultProfile)) throw new Error("qa.defaultProfile is invalid.");
+  if (isAbsolute(config.audit.directory) || config.audit.directory.split(/[\\/]+/).includes("..")) throw new Error("audit.directory must stay inside the project.");
+  if (!Number.isInteger(config.audit.retentionDays) || config.audit.retentionDays < 1) throw new Error("audit.retentionDays must be a positive integer.");
+  if (!config.audit.redactSensitiveValues) throw new Error("Audit redaction cannot be disabled.");
+  if (config.git.allowAutomaticCommit || config.git.allowAutomaticStash || !config.git.preserveExistingChanges) {
+    throw new Error("Unsafe Git automation settings are not supported.");
+  }
+  if (!config.subagents.readOnly || !config.subagents.mainAgentSoleWriter) {
+    throw new Error("Subagents must remain read-only and the main agent must be the sole writer.");
+  }
+  return config;
+}
+
+export function loadConfig(cwd: string): ImplannotatorConfig {
+  const globalPath = join(homedir(), ".pi", "agent", "implannotator.json");
+  const projectPath = join(cwd, ".pi", "implannotator.json");
+  const globalConfig = readJson(globalPath);
+  const projectConfig = readJson(projectPath);
+  assertKnownConfig(globalConfig, globalPath);
+  assertKnownConfig(projectConfig, projectPath);
+  const config = merge(merge(DEFAULT_CONFIG, globalConfig), projectConfig);
+  return validateConfig(config);
+}

package/extensions/domain/types.ts

@@ -0,0 +1,94 @@
+export const PHASES = [
+  "inspecting",
+  "planning",
+  "awaiting-plan-review",
+  "awaiting-text-approval",
+  "approved",
+  "implementing",
+  "qa",
+  "initial-review",
+  "repairing",
+  "final-review",
+  "complete",
+  "stopped",
+  "failed",
+] as const;
+
+export type RunPhase = (typeof PHASES)[number];
+export type QaProfile = "quick" | "standard" | "full";
+export type RiskLevel = "low" | "medium" | "high";
+export type ReviewStage = "plan" | "initial" | "final";
+export type EvidenceStatus = "passed" | "failed" | "unavailable" | "not-applicable";
+
+export interface ImplannotatorConfig {
+  schemaVersion: 1;
+  approval: {
+    required: true;
+    allowLowRiskAutoApprove: boolean;
+    proceedRequiresSecondConfirmation: true;
+    browserTimeoutMs: number;
+  };
+  repairs: { maxAttempts: number; reopenOnlyForFinalReview: true };
+  qa: { defaultProfile: "adaptive" | QaProfile; requireEvidence: boolean };
+  audit: { directory: string; retentionDays: number; redactSensitiveValues: boolean };
+  git: { allowAutomaticCommit: false; allowAutomaticStash: false; preserveExistingChanges: true };
+  subagents: { enabled: boolean; readOnly: true; mainAgentSoleWriter: true };
+}
+
+export interface DecisionRecord {
+  at: string;
+  kind: string;
+  actor: "user" | "agent" | "system";
+  decision: string;
+  reason?: string;
+  warned?: boolean;
+}
+
+export interface QaCheck {
+  id: string;
+  label: string;
+  status: EvidenceStatus;
+  evidence?: string[];
+  notes?: string;
+}
+
+export interface QaReport {
+  schemaVersion: 1;
+  profile: QaProfile;
+  createdAt: string;
+  checks: QaCheck[];
+  blockingFailures: string[];
+}
+
+export interface ReviewRecord {
+  stage: ReviewStage;
+  at: string;
+  approved: boolean;
+  feedback?: string;
+  annotations?: unknown[];
+  fallback?: "text";
+}
+
+export interface RunRecord {
+  schemaVersion: 1;
+  id: string;
+  cwd: string;
+  command: string;
+  target?: string;
+  risk: RiskLevel;
+  phase: RunPhase;
+  resumePhase?: Exclude<RunPhase, "complete" | "stopped" | "failed" | "implementing" | "repairing">;
+  createdAt: string;
+  updatedAt: string;
+  plan?: string;
+  planReviewId?: string;
+  pendingTextReview?: ReviewStage;
+  repairCount: number;
+  qaProfile: QaProfile;
+  changedFiles: string[];
+  baselineFiles?: Record<string, string>;
+  decisions: DecisionRecord[];
+  reviews: ReviewRecord[];
+  lastError?: string;
+  completionOverride?: boolean;
+}

package/extensions/index.ts

@@ -0,0 +1,44 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerCommands } from "./commands/register.js";
+import { loadConfig } from "./config/loader.js";
+import { registerMutationGate } from "./policy/mutation-gate.js";
+import { getPlannotatorAvailability } from "./plannotator/availability.js";
+import { registerControlTool } from "./tools/control-tool.js";
+import { Orchestrator } from "./workflow/orchestrator.js";
+
+export default function implannotator(pi: ExtensionAPI): void {
+  const workflows = new Map<string, Orchestrator>();
+  const getOrchestrator = (cwd: string) => {
+    let workflow = workflows.get(cwd);
+    if (!workflow) {
+      workflow = new Orchestrator(pi, cwd, loadConfig(cwd));
+      workflows.set(cwd, workflow);
+    }
+    return workflow;
+  };
+
+  registerControlTool(pi, getOrchestrator);
+  registerCommands(pi, getOrchestrator);
+  registerMutationGate(pi, (cwd) => getOrchestrator(cwd).active());
+
+  pi.on("session_start", (_event, ctx) => {
+    const plannotator = getPlannotatorAvailability(pi);
+    if (plannotator.available) {
+      ctx.ui.setStatus("implannotator-plannotator", undefined);
+    } else {
+      ctx.ui.setStatus("implannotator-plannotator", "Implannotator: text approval fallback");
+      ctx.ui.notify(
+        "Implannotator: Plannotator companion is not active. Install npm:@plannotator/pi-extension for browser reviews; text approval fallback remains available.",
+        "warning",
+      );
+    }
+
+    const run = getOrchestrator(ctx.cwd).active();
+    if (run && !["complete", "stopped", "failed"].includes(run.phase)) {
+      ctx.ui.setStatus("implannotator", `Implannotator: ${run.phase}`);
+      ctx.ui.notify(`Resumable Implannotator run ${run.id} is in ${run.phase}. Use /implannotator resume.`, "info");
+    } else {
+      ctx.ui.setStatus("implannotator", undefined);
+    }
+  });
+}

package/extensions/plannotator/availability.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+export interface PlannotatorAvailability {
+  available: boolean;
+  tool: boolean;
+  command: boolean;
+}
+
+export function getPlannotatorAvailability(pi: ExtensionAPI): PlannotatorAvailability {
+  const tool = pi.getAllTools().some((candidate) => candidate.name === "plannotator_submit_plan");
+  const command = pi.getCommands().some((candidate) => candidate.name === "plannotator");
+  return { available: tool || command, tool, command };
+}

package/extensions/plannotator/client.ts

@@ -0,0 +1,54 @@
+import { randomUUID } from "node:crypto";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { CodeReviewResult, PlanReviewStarted, PlannotatorAction, PlannotatorResponse, ReviewStatus } from "./contracts.js";
+
+const REQUEST_CHANNEL = "plannotator:request";
+
+function delay(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => { clearTimeout(timer); reject(signal.reason ?? new Error("Aborted")); }, { once: true });
+  });
+}
+
+export class PlannotatorClient {
+  constructor(private readonly pi: ExtensionAPI, private readonly responseTimeoutMs = 5_000) {}
+
+  request<T>(action: PlannotatorAction, payload: Record<string, unknown>, signal?: AbortSignal): Promise<PlannotatorResponse<T>> {
+    return new Promise((resolve) => {
+      let settled = false;
+      const finish = (response: PlannotatorResponse<T>) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve(response);
+      };
+      const timer = setTimeout(() => finish({ status: "unavailable", error: `Plannotator did not handle ${action} within ${this.responseTimeoutMs}ms.` }), this.responseTimeoutMs);
+      signal?.addEventListener("abort", () => finish({ status: "error", error: "Plannotator request aborted." }), { once: true });
+      this.pi.events.emit(REQUEST_CHANNEL, { requestId: randomUUID(), action, payload, respond: finish });
+    });
+  }
+
+  async startPlanReview(planContent: string, signal?: AbortSignal): Promise<PlannotatorResponse<PlanReviewStarted>> {
+    return this.request("plan-review", { planContent, origin: "implannotator" }, signal);
+  }
+
+  async reviewStatus(reviewId: string, signal?: AbortSignal): Promise<PlannotatorResponse<ReviewStatus>> {
+    return this.request("review-status", { reviewId }, signal);
+  }
+
+  async waitForPlanDecision(reviewId: string, timeoutMs: number, signal?: AbortSignal): Promise<ReviewStatus> {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const response = await this.reviewStatus(reviewId, signal);
+      if (response.status !== "handled") throw new Error(response.error ?? "Plannotator review status unavailable.");
+      if (response.result.status !== "pending") return response.result;
+      await delay(500, signal);
+    }
+    throw new Error("Timed out waiting for plan approval.");
+  }
+
+  async codeReview(cwd: string, signal?: AbortSignal): Promise<PlannotatorResponse<CodeReviewResult>> {
+    return this.request("code-review", { cwd, diffType: "uncommitted", useLocal: true }, signal);
+  }
+}

package/extensions/plannotator/contracts.ts

@@ -0,0 +1,20 @@
+export type PlannotatorAction = "plan-mode" | "plan-review" | "review-status" | "code-review" | "annotate" | "annotate-last" | "archive";
+
+export type PlannotatorResponse<T> =
+  | { status: "handled"; result: T }
+  | { status: "unavailable"; error?: string }
+  | { status: "error"; error: string };
+
+export interface PlanReviewStarted { status: "pending"; reviewId: string }
+export type ReviewStatus =
+  | { status: "pending" }
+  | { status: "missing" }
+  | { status: "completed"; reviewId: string; approved: boolean; feedback?: string; savedPath?: string };
+
+export interface CodeReviewResult {
+  approved: boolean;
+  feedback?: string;
+  annotations?: unknown[];
+  agentSwitch?: string;
+  exit?: boolean;
+}

package/extensions/policy/change-inventory.ts

@@ -0,0 +1,23 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { diffSnapshots, snapshotFiles } from "./non-git-diff.js";
+
+export function hasGit(cwd: string): boolean {
+  return existsSync(join(cwd, ".git"));
+}
+
+export function baselineFiles(cwd: string): Record<string, string> | undefined {
+  if (hasGit(cwd)) return undefined;
+  try { return snapshotFiles(cwd); } catch { return {}; }
+}
+
+export function changedFiles(cwd: string, baseline?: Record<string, string>): string[] {
+  if (!hasGit(cwd)) return baseline ? diffSnapshots(baseline, snapshotFiles(cwd)) : [];
+  try {
+    const output = execFileSync("git", ["status", "--porcelain=v1", "-z"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return output.split("\0").filter(Boolean).map((entry) => entry.slice(3)).filter(Boolean).sort();
+  } catch {
+    return [];
+  }
+}