@osolmaz/pi-workflows 0.11.1 → 0.12.0

package/skills/autoimplement/SKILL.md

@@ -1,10 +1,57 @@
 ---
 name: autoimplement
-description: Use when the user asks to implement a plan end-to-end, test it, run Pi Reviewer against the base branch in a loop until no P0/P1 issues remain, and make sure CI/CD is green before finishing.
+description: Use when the user asks to implement a plan end-to-end, test it, run pi-reviewer against the base branch in a loop until no P0/P1 issues remain, and make sure CI/CD is green before finishing.
 compatibility: Requires Pi Workflows and the built-in autoimplement workflow.
 ---
 
-Use the built-in `autoimplement` Pi Workflow when it is available. At top level, list workflows, then start `autoimplement` once with the task, existing plan, repository, scope, constraints, base branch, and merge policy from the conversation. Set `merge: true` only when the user explicitly requested merge or an applicable standing instruction authorizes it. Otherwise set it to false. Do not manually duplicate stages already owned by the workflow.
+# Autoimplement
+
+## Start the workflow
+
+Use the built-in `autoimplement` workflow when it is available. At top level, list workflows, build the complete input, and start `autoimplement` once. Do not start with a partial input and repair it in later turns.
+
+Build the input as follows:
+
+- `task`: Preserve the user's requested end state.
+- `plan`: Pass the selected plan or the full contents of its canonical plan document. Do not devise a new initial plan.
+- `repository`: Use the absolute path of the repository that owns the work.
+- `scope`: Always include a concrete authority statement. Name every allowed repository and the allowed edit, test, commit, push, pull-request, merge, and release actions. Carry forward exclusions from the conversation. A repository path alone is not a scope.
+- `constraints`: Include all applicable user and repository constraints. Use an empty array when none apply.
+- `baseBranch`: Use the requested base or the repository default branch.
+- `merge`: Set `true` only when the user explicitly requested merge or an applicable standing instruction authorizes it. Otherwise set `false`.
+- `documents`: Include known canonical plan or specification paths. Use an empty array when none are known.
+- `concurrency`: Include it only when the conversation gives explicit limits.
+
+When one repository is clearly named, derive the scope without asking the user to restate it. A safe derived scope permits only work needed for the task in that repository, including local verification and normal branch and pull-request publication. It excludes unrelated repositories, merge, release, deployment, credentials, and policy changes unless those actions are explicitly authorized.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "autoimplement",
+  "input": {
+    "task": "Implement the selected timeout fallback plan end to end.",
+    "plan": {
+      "canonicalDocument": "docs/plans/timeout-fallback-plan.md",
+      "summary": "Add a bounded timeout fallback.",
+      "requirements": [
+        "Route supported timeouts to one read-only fallback.",
+        "Keep cancellation terminal."
+      ],
+      "verification": ["npm run check", "npm run test:e2e"]
+    },
+    "repository": "/absolute/path/to/repository",
+    "scope": "Only /absolute/path/to/repository. May edit and test task-related files, create commits, push the task branch, and open or update its pull request. Must not modify other repositories, merge, release, deploy, change credentials, or change repository policy.",
+    "constraints": ["Preserve immediate cancellation.", "Keep deferred-turn work separate."],
+    "baseBranch": "main",
+    "merge": false,
+    "documents": ["docs/plans/timeout-fallback-plan.md"]
+  }
+}
+```
+
+Do not manually duplicate stages already owned by the workflow. Autoimplement runs independent pi-reviewer commands, pending CI watches, and local verification commands from separate repositories in bounded batches. It keeps model turns, fixes, pushes, comment changes, merges, and releases ordered. One repository uses the same batch path with concurrency one.
 
 When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract with the available tools.
 
@@ -21,29 +68,36 @@ Outside Pi, or when the workflow is unavailable, do the following in the order t
 
 2. Once you finish implementing, make sure to test it.
    - This will depend on the nature of the problem. If needed, run local smoke tests, spin up dev servers, make requests and such.
+   - Run commands from independent repositories in a bounded batch only when their working directories are distinct and local resources can support the overlap.
+   - Keep one repository's dependent checks in order. Do not batch shell wrappers, remote mutations, package publication, or commands with unclear side effects.
    - Try to test as much as possible, without merging.
    - State explicitly what could not be tested locally and what still needs staging or production verification.
    - Do not put mutation testing on the critical path unless repository policy explicitly requires it; keep the mutation test scripts available.
 
 3. Push your latest commits before running review so the review is always against the current PR head.
-   - Run Pi Reviewer with its configured defaults against the base branch: `pi-reviewer --base <branch_name>`. The model and thinking level come from the reviewer's own config, not from this skill.
-   - Use a 10 minute timeout on the tool call available to the model, not the shell `timeout` program. If Pi Reviewer takes more than 10 minutes, kill it.
-   - Do not silently fall back to `codex review` when Pi Reviewer is unavailable; stop and report the missing command or configuration.
-   - Record every review round with separate P0, P1, P2, and lower findings.
-   - Run Pi Reviewer in a loop and address any P0 or P1 issues until there are none left.
-   - If a round reports only P2 or lower findings, address valid proportionate P2 findings, verify and push them, then move to the next stage without running Pi Reviewer again solely because of that P2 work.
+   - Run pi-reviewer with its configured defaults against the base branch: `pi-reviewer --base <branch_name>`. The model and thinking level come from the reviewer's own config, not from this skill.
+   - Run reviewer commands for independent repositories in one bounded batch. Keep each result tied to its repository, base branch, pushed head, and relevant dependency fingerprint.
+   - In later rounds, rerun only repositories whose pushed head or relevant dependency fingerprint changed.
+   - Use a 10 minute timeout for each reviewer item, not the shell `timeout` program. If pi-reviewer takes more than 10 minutes, stop that item.
+   - Do not silently fall back to `codex review` when pi-reviewer is unavailable; stop and report the missing command or configuration for that repository.
+   - Treat truncated reviewer output as an invalid review, never a clean result.
+   - Record every review round with separate P0, P1, P2, and lower findings for each repository.
+   - Run pi-reviewer in a loop and address any P0 or P1 issues until there are none left.
+   - If a round reports only P2 or lower findings, address valid proportionate P2 findings, verify and push them, then move to the next stage without running pi-reviewer again solely because of that P2 work.
    - Ignore issues about supporting legacy behavior unless the plan requires compatibility.
-   - Look at CI only after Pi Reviewer passes, meaning the last completed run found no issues or only P2 or lower issues.
+   - Look at CI only after pi-reviewer passes, meaning the last completed run found no issues or only P2 or lower issues.
 
-4. Pi Reviewer reports findings locally and does not post them to the pull request.
+4. pi-reviewer reports findings locally and does not post them to the pull request.
    - Separately check existing inline review comments and PR issue comments, and address valid comments.
    - Ignore irrelevant comments and stale comments from before the latest commit unless they still apply.
    - Reply to and resolve each comment either way.
    - Do not wait a fixed five minutes; wait only when a required review is known to be pending, and keep that wait bounded.
 
 5. In the final step, make sure that CI/CD is green.
-   - Inspect CI once before deciding to wait. If waiting is useful, state and run the exact `gh` tracking command.
-   - Bound one CI watch to five minutes. If CI is still pending, use the next model turn for additional useful local tests or smoke tests instead of waiting. Then inspect CI again.
+   - Inspect every pull request once before deciding to wait. If waiting is useful, state the exact `gh` tracking command for each pending pull request.
+   - Run supported pending CI watches in one bounded batch. Keep every result tied to its pull request and current head.
+   - Bound each CI watch to five minutes. If CI is still pending, use the next model turn for additional useful local tests or smoke tests instead of waiting. Then inspect CI again.
+   - Do not invent an ETA when the CI provider does not supply one.
    - Ignore the fails unrelated to your changes, others break stuff sometimes and don't fix it.
    - Make sure whatever changes you did don't break anything.
    - If CI/CD is not fully green, state explicitly which failures are unrelated and why.

package/skills/autoplan/SKILL.md

@@ -1,12 +1,36 @@
 ---
 name: autoplan
 description: Use when the user asks to devise, choose, or plan the most elegant long-term production-ready solution, compare it with the ideal end state, and produce the best practical in-scope implementation plan without asking the user to resolve the gap.
-compatibility: Requires Pi Workflows and the built-in autoplan workflow.
+compatibility: Requires pi-workflows and the built-in autoplan workflow.
 ---
 
 # Autoplan
 
-Use the built-in `autoplan` Pi Workflow when it is available. At top level, list workflows, then start `autoplan` once with the problem, authorized scope, constraints, previous plan, and new evidence from the conversation.
+## Start the workflow
+
+Use the built-in `autoplan` workflow when it is available. At top level, list workflows, build the complete input, and start `autoplan` once.
+
+Build the input as follows:
+
+- `problem`: State the decision or implementation-planning problem and its observable end state.
+- `scope`: Name the repositories, systems, and interfaces that may change. State important exclusions. Derive an unambiguous repository-local scope without asking the user to restate it.
+- `constraints`: Preserve all user, repository, safety, compatibility, cost, and authority limits. Use an empty array when none apply.
+- `previousPlan`: Include it only when revising an existing plan.
+- `newEvidence`: Include it only when evidence caused the revision request.
+
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "autoplan",
+  "input": {
+    "problem": "Choose a production-ready timeout fallback and write its implementation plan.",
+    "scope": "Only /absolute/path/to/repository. Plan changes to its public workflow API, built-in workflow, tests, and documentation. Exclude Pi core, external services, credentials, releases, and unrelated repositories.",
+    "constraints": ["Keep cancellation terminal.", "Use only documented public interfaces."]
+  }
+}
+```
 
 When this skill is loaded inside an active workflow step, do not start another workflow. Complete the current step contract.
 

package/skills/monitor/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: monitor
 description: Use when the user asks to monitor, watch, track, or periodically check a running command, remote Job, CI run, deployment, publication, or other long-running objective. Starts the built-in Pi monitor workflow immediately in the current session and drives the objective autonomously, including routine recovery, until verified completion or a material blocker.
-compatibility: Requires Pi Workflows and the built-in monitor workflow.
+compatibility: Requires pi-workflows and the built-in monitor workflow.
 ---
 
 # Monitor
@@ -10,9 +10,9 @@ Use the built-in Pi `monitor` workflow as an autopilot for the requested objecti
 
 A monitor request authorizes routine, bounded work needed to preserve and finish the stated objective, subject to the conversation and repository approval boundaries. Apply other skills as safety and operating instructions. Do not turn their normal checks into new approval requests when the monitored objective and an existing approval already cover the action. Monitoring does not authorize changing the objective, method, model, data source, production selection, or other consequential contract.
 
-## Prepare and start without delay
+## Start the workflow without delay
 
-As soon as the user invokes this skill:
+Build the complete input and start the workflow in the same turn. As soon as the user invokes this skill:
 
 1. Read the current conversation, active plan, repository instructions, and applicable compute, runtime, credential, deployment, or publication skills.
 2. Preserve the exact objective, immutable execution contract, current identifiers, durable progress, cost already spent, approval ceilings, finish criteria, and known recovery rules in the workflow input. Write or update a durable plan or incident note first only when the work needs one for safe continuation.
@@ -31,6 +31,36 @@ Derive the workflow input from the full conversation:
 - `stopWhen`: Infer verified completion from the full conversation. Describe completion of the complete objective, not only the end of one physical process. Also name material blockers that require human intervention.
 - `repair`: Include this object only when the request or an existing approval authorizes mutation. Set `authorized: true` and record the repository, scope, base branch, merge policy, and constraints that apply. Omit it for observation-only work.
 
+Replace the example values below with facts from the conversation, then make one start call:
+
+```json
+{
+  "action": "start",
+  "workflow": "monitor",
+  "input": {
+    "task": "Monitor GitHub Actions run 123456 in owner/repository. Inspect the run and its artifacts, retry only transient status reads, and report each check. Do not change code or repository state.",
+    "everyMinutes": 5,
+    "stopWhen": "Stop when run 123456 completes and its required artifacts are verified, or when a material external blocker prevents truthful verification.",
+    "checkTimeoutMinutes": 10
+  }
+}
+```
+
+For authorized repair, add a complete `repair` object instead of leaving mutation authority implicit:
+
+```json
+{
+  "repair": {
+    "authorized": true,
+    "repository": "/absolute/path/to/repository",
+    "scope": "Only /absolute/path/to/repository. May diagnose and fix failures related to the monitored objective, test, commit, push, and update its pull request. Must not modify other repositories, merge, release, deploy, change credentials, or change repository policy.",
+    "constraints": ["Keep the monitored objective and method unchanged."],
+    "baseBranch": "main",
+    "merge": false
+  }
+}
+```
+
 When the conversation gives no clear finish criterion, set `stopWhen` to `Stop only when the user explicitly asks to stop.` Do not use that fallback when a broader implementation, repair, publication, or deployment objective is clear from context.
 
 Do not invent a finite check count. Omit `maxChecks` unless the user explicitly requests one. The workflow host can apply its own safety upper bound. Disclose that bound if it appears.
@@ -60,23 +90,7 @@ When the paid action remains within the approved method, hardware, concurrency,
 
 The monitor may use a credential only when the conversation or repository has already authorized that credential's source, destination, and purpose. It may reuse that authorization for retries and replacement attempts under the same objective. It must not discover unrelated credentials, broaden scopes, copy credentials to a new store, or print secret values.
 
-## Start the workflow
-
-Start the built-in workflow in the current session with this shape:
-
-```text
-workflow({
-  action: "start",
-  workflow: "monitor",
-  input: {
-    task: "<complete objective, contract, recovery authority, and verification task>",
-    everyMinutes: 30,
-    stopWhen: "<derived finish criterion or explicit-user-stop fallback>"
-  }
-})
-```
-
-Use the user-supplied interval instead of `30` when present. Add `maxChecks` only when the user explicitly supplies that limit. Do not send `reportWhen`; the current monitor reports every accepted check.
+Use the user-supplied interval instead of the example value when present. Add `maxChecks` only when the user explicitly supplies that limit. Do not send `reportWhen`; the current monitor reports every accepted check.
 
 Do not start a second monitor for the same objective while one is active. Update or replace the run only when the objective or contract changes. A replacement must preserve the previous accepted observation and durable recovery state.
 
@@ -115,7 +129,7 @@ Submit observed facts. The workflow computes rates, confidence, remaining work,
 
 For several concurrent processes, publish one stable track per process. The Pi widget and viewers show them separately and keep each ETA independent.
 
-Keep the monitored target independent of Pi Workflows. Do not require a target Job or application to import Pi Workflows, emit a Pi schema, write a Pi progress file, expose a Pi endpoint, create a progress store, or add a progress reader command solely for monitoring. Do not add provider-specific clients or credentials to Pi Workflows. Target-specific observation belongs in the check task and is performed by the regular Pi model with already authorized tools.
+Keep the monitored target independent of pi-workflows. Do not require a target Job or application to import pi-workflows, emit a Pi schema, write a Pi progress file, expose a Pi endpoint, create a progress store, or add a progress reader command solely for monitoring. Do not add provider-specific clients or credentials to pi-workflows. Target-specific observation belongs in the check task and is performed by the regular Pi model with already authorized tools.
 
 Before proposing a new progress API, transport, schema, or persistence layer, prove that the model cannot observe the needed facts and publish them through the existing `workflow update` and `submit` path. If the target does not expose enough facts for ETA, report `ETA unavailable`. Application telemetry changes require separate scope and should expose normal operational facts rather than a Pi-specific protocol.
 

package/skills/pi-workflows/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: pi-workflows
-description: Use when creating, reviewing, debugging, starting, inspecting, or controlling Pi Workflows; authoring .workflow.ts files; using the workflow tool; handling workflow step contracts, checkpoints, updates, or progress; or deciding how a task should compose workflow primitives.
-compatibility: Requires the Pi Workflows extension.
+description: Use when creating, reviewing, debugging, starting, inspecting, or controlling pi-workflows; authoring .workflow.ts files; using the workflow tool; handling workflow step contracts, checkpoints, updates, or progress; or deciding how a task should compose workflow primitives.
+compatibility: Requires the pi-workflows extension.
 ---
 
-# Pi Workflows
+# pi-workflows
 
-Use Pi Workflows for durable multi-step work that needs explicit routing, retries, checkpoints, scheduled waits, or progress. Keep simple one-turn work outside a workflow.
+Use pi-workflows for durable multi-step work that needs explicit routing, retries, checkpoints, scheduled waits, or progress. Keep simple one-turn work outside a workflow.
 
 The `workflow` tool schema is the authority for call shapes. A workflow step message is the authority for its current step id, attempt id, and expected output. Do not guess these values from an earlier attempt.
 
@@ -22,7 +22,21 @@ Use the smallest applicable action:
 - `update` publishes a non-completing durable update for the active step attempt.
 - `submit` completes the active agent step with its required output.
 
-Use `start` only once for one requested run. Do not build a manual polling loop around a workflow that already schedules its own work. Use the `monitor` skill for monitoring requests.
+Use `start` only once for one requested run. Before starting, load the matching workflow skill when one exists and build its complete input. Include scope, authority, constraints, identifiers, and finish criteria required by that skill. Do not start with placeholders that still need user or model repair.
+
+For a workflow without a specialized skill, inspect its input contract and make one complete call. For example:
+
+```json
+{
+  "action": "start",
+  "workflow": "examples/workflows/echo.workflow.ts",
+  "input": {
+    "task": "Summarize this repository in one sentence."
+  }
+}
+```
+
+Do not build a manual polling loop around a workflow that already schedules its own work. Use the `monitor` skill for monitoring requests.
 
 ## Complete agent steps
 

package/src/builtins/autoimplement-command-batches.ts

@@ -0,0 +1,364 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import {
+  MAX_COMMAND_BATCH_ITEMS,
+  validateCommandBatchRequest,
+  type CommandBatchItem,
+} from "../workflows/command-batch.js";
+
+export const REVIEW_TIMEOUT_MS = 10 * 60_000;
+export const CI_WATCH_TIMEOUT_MS = 5 * 60_000;
+export const VERIFICATION_TIMEOUT_MS = 45 * 60_000;
+export const AUTOIMPLEMENT_BATCH_MAX_OUTPUT_CHARS = 1_000_000;
+export const AUTOIMPLEMENT_MAX_CONCURRENCY = 8;
+
+export type AutoimplementConcurrency = {
+  reviewer: number;
+  ciWatch: number;
+  verification: number;
+};
+
+export type PublishedRepository = {
+  id: string;
+  repository: string;
+  branch: string;
+  baseBranch: string;
+  headRevision: string;
+  pr: string;
+  dependencyFingerprint?: string;
+};
+
+export type PublishedRepositories = {
+  repositories: PublishedRepository[];
+};
+
+export type VerificationCommandPlan = {
+  commands: CommandBatchItem[];
+  untested: string[];
+};
+
+export type CiTargetInspection = {
+  id: string;
+  repository: string;
+  headRevision: string;
+  pr: string;
+  route: "green" | "failed" | "pending" | "unavailable";
+  reason: string;
+  relatedFailures: string[];
+  unrelatedFailures: string[];
+  trackingCommand?: CommandBatchItem;
+};
+
+export type CiInspectionBatch = {
+  route: "green" | "failed" | "pending" | "unavailable";
+  reason: string;
+  relatedFailures: string[];
+  unrelatedFailures: string[];
+  targets: CiTargetInspection[];
+};
+
+export function parseAutoimplementConcurrency(value: unknown): AutoimplementConcurrency {
+  if (value === undefined) return { reviewer: 4, ciWatch: 4, verification: 2 };
+  const input = requireRecord(value, "autoimplement concurrency");
+  for (const key of Object.keys(input)) {
+    if (key !== "reviewer" && key !== "ciWatch" && key !== "verification") {
+      throw new Error(`autoimplement concurrency.${key} is not supported`);
+    }
+  }
+  return {
+    reviewer: concurrencyValue(input.reviewer ?? 4, "reviewer"),
+    ciWatch: concurrencyValue(input.ciWatch ?? 4, "ciWatch"),
+    verification: concurrencyValue(input.verification ?? 2, "verification"),
+  };
+}
+
+export function parsePublishedRepositories(value: unknown): PublishedRepositories {
+  const result = requireRecord(value, "publication result");
+  if (!Array.isArray(result.repositories) || result.repositories.length === 0) {
+    throw new Error("publication result repositories must be a non-empty array");
+  }
+  if (result.repositories.length > MAX_COMMAND_BATCH_ITEMS) {
+    throw new Error(
+      `publication result repositories must contain at most ${MAX_COMMAND_BATCH_ITEMS} entries`,
+    );
+  }
+  const ids = new Set<string>();
+  const repositories = result.repositories.map((entry, index) => {
+    const raw = requireRecord(entry, `publication repositories[${index}]`);
+    const repository = requireAbsolutePath(
+      raw.repository,
+      `publication repositories[${index}].repository`,
+    );
+    const id = repositoryId(repository);
+    if (ids.has(id)) throw new Error(`publication repository is duplicated: ${repository}`);
+    ids.add(id);
+    const dependencyFingerprint = optionalString(
+      raw.dependencyFingerprint,
+      `publication repositories[${index}].dependencyFingerprint`,
+    );
+    if (raw.pushed !== true) {
+      throw new Error(`publication repositories[${index}].pushed must be true`);
+    }
+    return {
+      id,
+      repository,
+      branch: requireString(raw.branch, `publication repositories[${index}].branch`),
+      baseBranch: requireString(raw.baseBranch, `publication repositories[${index}].baseBranch`),
+      headRevision: requireString(
+        raw.headRevision,
+        `publication repositories[${index}].headRevision`,
+      ),
+      pr: requireString(raw.pr, `publication repositories[${index}].pr`),
+      ...(dependencyFingerprint !== undefined ? { dependencyFingerprint } : {}),
+    };
+  });
+  return { repositories };
+}
+
+export function reviewerCommand(repository: PublishedRepository): CommandBatchItem {
+  return {
+    id: repository.id,
+    command: "pi-reviewer",
+    args: ["--base", repository.baseBranch],
+    cwd: repository.repository,
+    timeoutMs: REVIEW_TIMEOUT_MS,
+    maxOutputChars: AUTOIMPLEMENT_BATCH_MAX_OUTPUT_CHARS,
+  };
+}
+
+export function parseVerificationCommandPlan(value: unknown): VerificationCommandPlan {
+  const result = requireRecord(value, "verification command plan");
+  if (!Array.isArray(result.commands) || result.commands.length === 0) {
+    throw new Error("verification commands must be a non-empty array");
+  }
+  const directories = new Set<string>();
+  const commands = result.commands.map((entry, index) => {
+    const command = parseCommandItem(entry, `verification commands[${index}]`, {
+      maxTimeoutMs: VERIFICATION_TIMEOUT_MS,
+    });
+    if (directories.has(command.cwd)) {
+      throw new Error(
+        `verification commands must use distinct working directories: ${command.cwd}`,
+      );
+    }
+    directories.add(command.cwd);
+    validateVerificationCommand(command, index);
+    return command;
+  });
+  const validated = validateCommandBatchRequest({ items: commands, maxConcurrency: 1 });
+  return {
+    commands: validated.items,
+    untested: stringArray(result.untested ?? [], "verification untested"),
+  };
+}
+
+export function parseCiInspectionBatch(value: unknown): CiInspectionBatch {
+  const result = requireRecord(value, "CI inspection");
+  if (!Array.isArray(result.targets) || result.targets.length === 0) {
+    throw new Error("CI inspection targets must be a non-empty array");
+  }
+  if (result.targets.length > MAX_COMMAND_BATCH_ITEMS) {
+    throw new Error(
+      `CI inspection targets must contain at most ${MAX_COMMAND_BATCH_ITEMS} entries`,
+    );
+  }
+  const ids = new Set<string>();
+  const targets = result.targets.map((entry, index) => {
+    const raw = requireRecord(entry, `CI targets[${index}]`);
+    const repository = requireAbsolutePath(raw.repository, `CI targets[${index}].repository`);
+    const id = repositoryId(repository);
+    if (ids.has(id)) throw new Error(`CI target is duplicated: ${repository}`);
+    ids.add(id);
+    if (
+      raw.route !== "green" &&
+      raw.route !== "failed" &&
+      raw.route !== "pending" &&
+      raw.route !== "unavailable"
+    ) {
+      throw new Error(`CI targets[${index}].route is invalid`);
+    }
+    const pr = requireString(raw.pr, `CI targets[${index}].pr`);
+    const target: CiTargetInspection = {
+      id,
+      repository,
+      headRevision: requireString(raw.headRevision, `CI targets[${index}].headRevision`),
+      pr,
+      route: raw.route,
+      reason: requireString(raw.reason, `CI targets[${index}].reason`),
+      relatedFailures: stringArray(
+        raw.relatedFailures ?? [],
+        `CI targets[${index}].relatedFailures`,
+      ),
+      unrelatedFailures: stringArray(
+        raw.unrelatedFailures ?? [],
+        `CI targets[${index}].unrelatedFailures`,
+      ),
+    };
+    if (raw.route === "pending") {
+      target.trackingCommand = parseCiCommand(raw.trackingCommand, id, repository, pr);
+    }
+    return target;
+  });
+  const route = targets.some((target) => target.route === "failed")
+    ? "failed"
+    : targets.some((target) => target.route === "pending")
+      ? "pending"
+      : targets.some((target) => target.route === "unavailable")
+        ? "unavailable"
+        : "green";
+  return {
+    route,
+    reason: targets.map((target) => `${target.id}: ${target.reason}`).join("; "),
+    relatedFailures: targets.flatMap((target) => target.relatedFailures),
+    unrelatedFailures: targets.flatMap((target) => target.unrelatedFailures),
+    targets,
+  };
+}
+
+export function parseCiCommand(
+  value: unknown,
+  id: string,
+  repository: string,
+  pr: string,
+): CommandBatchItem {
+  const raw = requireRecord(value, "CI tracking command");
+  if (raw.id !== id) throw new Error("CI tracking command id must match the target repository");
+  const command = parseCommandItem(raw, "CI tracking command", {
+    id,
+    command: "gh",
+    cwd: repository,
+    maxTimeoutMs: CI_WATCH_TIMEOUT_MS,
+  });
+  const args = command.args;
+  const prWatch =
+    (args.length === 3 && args[0] === "pr" && args[1] === "checks" && args[2] === "--watch") ||
+    (args.length === 4 &&
+      args[0] === "pr" &&
+      args[1] === "checks" &&
+      args[2] === pr &&
+      args[3] === "--watch");
+  const runWatch =
+    args.length === 3 &&
+    args[0] === "run" &&
+    args[1] === "watch" &&
+    /^[1-9]\d*$/.test(args[2] ?? "");
+  if (!prWatch && !runWatch) {
+    throw new Error("CI tracking command args are not allowed for the target PR");
+  }
+  return { ...command, args: ["pr", "checks", pr, "--watch"] };
+}
+
+export function repositoryId(repository: string): string {
+  const canonical = path.resolve(repository);
+  return createHash("sha256").update(canonical).digest("hex").slice(0, 16);
+}
+
+function parseCommandItem(
+  value: unknown,
+  label: string,
+  options: {
+    id?: string;
+    command?: string;
+    cwd?: string;
+    maxTimeoutMs: number;
+  },
+): CommandBatchItem {
+  const raw = requireRecord(value, label);
+  const id = options.id ?? requireString(raw.id, `${label}.id`);
+  const command = options.command ?? requireString(raw.command, `${label}.command`);
+  if (options.command !== undefined && raw.command !== options.command) {
+    throw new Error(`${label}.command must be ${options.command}`);
+  }
+  if (!Array.isArray(raw.args) || raw.args.some((arg) => typeof arg !== "string")) {
+    throw new Error(`${label}.args must be an array of strings`);
+  }
+  const cwd = options.cwd ?? requireAbsolutePath(raw.cwd, `${label}.cwd`);
+  if (options.cwd !== undefined && path.resolve(String(raw.cwd)) !== options.cwd) {
+    throw new Error(`${label}.cwd must match the target repository`);
+  }
+  const timeoutMs = positiveInteger(raw.timeoutMs, `${label}.timeoutMs`, options.maxTimeoutMs);
+  const maxOutputChars = positiveInteger(
+    raw.maxOutputChars ?? AUTOIMPLEMENT_BATCH_MAX_OUTPUT_CHARS,
+    `${label}.maxOutputChars`,
+    AUTOIMPLEMENT_BATCH_MAX_OUTPUT_CHARS,
+  );
+  return { id, command, args: [...raw.args] as string[], cwd, timeoutMs, maxOutputChars };
+}
+
+function validateVerificationCommand(command: CommandBatchItem, index: number): void {
+  const forbiddenCommands = new Set([
+    "ash",
+    "bash",
+    "cmd",
+    "cmd.exe",
+    "csh",
+    "dash",
+    "fish",
+    "gh",
+    "git",
+    "ksh",
+    "powershell",
+    "powershell.exe",
+    "pwsh",
+    "pwsh.exe",
+    "rm",
+    "sh",
+    "tcsh",
+    "zsh",
+  ]);
+  const executable = path.win32.basename(path.basename(command.command)).toLowerCase();
+  if (forbiddenCommands.has(executable)) {
+    throw new Error(`verification commands[${index}].command is not allowed`);
+  }
+  const joined = command.args.join(" ").toLowerCase();
+  if (/\b(publish|release|deploy|push|merge)\b/.test(joined)) {
+    throw new Error(`verification commands[${index}] contains a mutation or publication action`);
+  }
+}
+
+function concurrencyValue(value: unknown, field: string): number {
+  return positiveInteger(
+    value,
+    `autoimplement concurrency.${field}`,
+    AUTOIMPLEMENT_MAX_CONCURRENCY,
+  );
+}
+
+function positiveInteger(value: unknown, label: string, maximum: number): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 1 || (value as number) > maximum) {
+    throw new Error(`${label} must be an integer from 1 through ${maximum}`);
+  }
+  return value as number;
+}
+
+function stringArray(value: unknown, label: string): string[] {
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`${label} must be an array of strings`);
+  }
+  return [...value] as string[];
+}
+
+function requireRecord(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+  return value as Record<string, unknown>;
+}
+
+function requireString(value: unknown, label: string): string {
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function optionalString(value: unknown, label: string): string | undefined {
+  if (value === undefined) return undefined;
+  return requireString(value, label);
+}
+
+function requireAbsolutePath(value: unknown, label: string): string {
+  const resolved = requireString(value, label);
+  if (!path.isAbsolute(resolved)) throw new Error(`${label} must be absolute`);
+  return path.resolve(resolved);
+}