@syntax-syllogism/aloop 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -5,6 +5,49 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0/).
 
+## [0.6.0] - 2026-09-14
+
+### Added
+
+- **Publish attestation.** The loop records the exact reviewer-approved commit
+  SHA and refuses to publish until a gate-backed review approval covers the tree
+  being shipped. Any mutation that lands after approval is re-gated, and the
+  approval is preserved across a resumed publish/PR phase.
+- **Driver-owned publishing.** The driver, not the agent, performs the push and
+  pull-request/publish step. Publishing is bound to the configured remote,
+  retries are bounded, and PR descriptions are validated before use.
+- **GitLab publish backend.** Publishing can target GitLab in addition to
+  GitHub, selected through the publish backend configuration.
+- **Operational run commands.** `list`, `status`, `inspect`, `metrics`,
+  `cancel`, `clean`, and `doctor` inspect, cancel, clean up, and diagnose
+  persisted runs, each with `--json` output for scripting.
+- **Run budgets.** Optional `budget` ceilings (`tokens`, `usd`, `wallClockMs`)
+  are enforced cumulatively across a run, including review rounds and repairs.
+  The runner stalls at the next phase or repair boundary when a limit is
+  reached and records the usage in the manifest; budget stalls are resumable.
+- **Per-phase least privilege.** Phases declare a permission kind
+  (`read-only`, `write-worktree`, `publish`). Read-only phases run against
+  isolated source snapshots with artifact-only writes scoped to the run
+  directory.
+- **Opt-in hermetic phase execution** to isolate a phase from ambient
+  environment and network state.
+- **POSIX command shell configuration and Windows (Git Bash) support**, so runs
+  work across POSIX shells and on Windows.
+
+### Changed
+
+- Renamed the `git` phase and its prompt to `pr-description`, reflecting its
+  narrowed responsibility now that publishing is driver-owned.
+- Configuration now lints the phase order and rejects orderings that would
+  break the publish attestation boundary.
+
+### Fixed
+
+- Make the config-import cache-buster collision-proof.
+- Sync the work-item preset's verdict schema rules with the runner.
+- Handle a failed Windows timeout teardown and isolate POSIX tests from
+  Windows CI.
+
 ## [0.5.0] - 2026-09-12
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 `@syntax-syllogism/aloop` is an engine-agnostic agentic loop runner. It drives
 a task through file-based implementation, deterministic checks, review, repair,
-documentation, and git phases. The driver owns control flow; configured agent
+documentation, and publishing phases. The driver owns control flow; configured agent
 CLIs provide judgment in fresh processes.
 
 ## Install
@@ -16,6 +16,16 @@ npx @syntax-syllogism/aloop --help
 The package is published to the public npm registry and needs no private
 registry configuration.
 
+## Platform support
+
+Linux and macOS are supported. Windows is supported when aloop is launched
+from Git Bash (Git for Windows), which provides the POSIX `sh` used for setup
+and gate commands. Install Git for Windows, ensure `sh.exe` is on `PATH`, and
+run aloop from a Git Bash terminal. WSL works as Linux.
+
+Interactive confirmations use the Git Bash/Windows console when available. Use
+`--yes` for unattended or piped runs when no console input is available.
+
 ## Quick start
 
 From a git repository with a `loop.config.mjs` (or with the defaults):
@@ -28,25 +38,32 @@ aloop --task-file plan.md
 Inspect the rendered plan first with `aloop --task "..." --name example
 --dry-run`. A terminal run asks for confirmation before each phase. Use `-y`
 only after the configured engines and workflow have been proven for the task
-shapes you intend to automate.
+shapes you intend to automate. Required phases cannot be skipped interactively:
+declining one asks you to run it or quit. `docs` is optional by default; see
+[`docs/loop.md`](docs/loop.md#phases) for custom-phase rules and the full phase
+reference.
 
 ## How the loop works
 
 The default pipeline is:
 
 1. `implement` — make the requested change in an isolated git worktree.
-2. `gate` — run deterministic commands such as `npm test`.
-3. `review` — write a machine-readable verdict JSON file.
-4. `address` — repair blocking findings, then repeat the gate and review up to
+2. `docs` — update documentation when the implementation requires it.
+3. `gate` — run deterministic commands such as `npm test`.
+4. `review` — write a machine-readable verdict JSON file.
+5. `address` — repair blocking findings, then repeat the gate and review up to
    the configured round limit.
-5. `docs` — update documentation when the implementation requires it.
-6. `git` — verify the tree and prepare the branch for an open pull request.
+6. `pr-description` — author the title and body in the run directory.
+7. `publish` — push and verify the attested branch, then create or update a
+   draft pull request.
 
 Phases communicate through files rather than shared agent sessions. A review
 verdict has the shape `{ verdict, summary, blocking, nits }`; malformed verdicts
 fail closed. The runner never merges a branch and never treats an agent's prose
-as a deterministic test result. See [`docs/loop.md`](docs/loop.md) for the
-complete guide and verdict contract.
+as a deterministic test result. Each real run also records the repository SHAs,
+rendered prompt and configuration hashes, gate receipts, verdict binding, and
+phase artifacts in its run manifest. See [`docs/loop.md`](docs/loop.md) for the
+complete guide, manifest schema, and verdict contract.
 
 ## Configuration
 
@@ -59,8 +76,10 @@ export default {
     default: { name: 'claude', effort: 'high' },
     review: { name: 'codex', effort: 'high' },
   },
-  phases: ['implement', 'gate', 'review', 'address', 'docs', 'git'],
+  phases: ['implement', 'docs', 'gate', 'review', 'address', 'pr-description', 'publish'],
   gate: ['npm test'],
+  shell: 'sh',
+  publish: { backend: 'github', draft: true },
   setup: ['npm ci'],
   maxRounds: 3,
 };
@@ -72,14 +91,29 @@ an engine-specific `model` and `effort`. `--config` selects a configuration
 file outside the current repository; command-line phase and round options take
 precedence.
 
+GitLab publishing is also bundled: set `publish: { backend: 'gitlab', draft:
+true }` to use the authenticated `glab` CLI. For a REST or MCP integration,
+import `gitlabBackend` and inject the small GitLab-native transport port:
+
+```js
+import { gitlabBackend } from '@syntax-syllogism/aloop';
+
+const myMcpTransport = { checkAuth, getMergeRequest, createMergeRequest, updateMergeRequest };
+export default { publish: { backend: gitlabBackend({ transport: myMcpTransport }), draft: true } };
+```
+
 ### Bring your own engine
 
 Register an adapter under `adapters` when another CLI should run a phase. Its
-`command({ prompt, cwd, addDirs, agent })` function returns `{ command, args }`.
-It may also provide `efforts` validation and `createRenderer()` for streaming
-output. Because adapters run commands with write access, non-interactive or
-auto-approve flags can allow an agent to change files without asking. Review
-the adapter and its permissions before enabling unattended runs.
+`command({ prompt, cwd, addDirs, readOnlyDirs, permissions, artifactOnly, agent })` function returns `{ command, args }`. For a read-only phase,
+`cwd` is always the run directory and `addDirs` contains only artifact roots;
+`readOnlyDirs` is an optional source-inspection input for adapters that can
+honor it. The runner supplies a permission level and restricts `addDirs`
+accordingly; the adapter must translate `permissions` into its own read-only
+or write-capable invocation flags. It may also provide `efforts`
+validation and `createRenderer()` for streaming output. Custom adapter flags
+are vendor-specific and are not verified by aloop. See the [phase permission
+contract](docs/loop.md#phase-permissions) before enabling unattended runs.
 
 ## Prompt overrides and the work-item preset
 

package/bin/loop.mjs

@@ -1,12 +1,29 @@
 #!/usr/bin/env node
 
 import { parseArgs } from 'node:util';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
 import { isMainEntrypoint } from '../src/entrypoint.mjs';
+import {
+  cancelRun,
+  cleanRuns,
+  doctor,
+  getAggregateMetrics,
+  getRun,
+  inspectRun,
+  listRuns,
+  resolveRunsDir,
+} from '../src/operations.mjs';
+import { computeRunMetrics } from '../src/metrics.mjs';
 import { runLoop } from '../src/pipeline.mjs';
 
+const commands = new Set(['run', 'list', 'status', 'inspect', 'cancel', 'clean', 'doctor', 'metrics']);
+
 export function parseLoopArgs(argv) {
-  const { values } = parseArgs({
-    args: argv,
+  const command = commands.has(argv[0]) ? argv[0] : 'run';
+  const commandArgv = command === 'run' && argv[0] !== 'run' ? argv : argv.slice(1);
+  const { values, positionals } = parseArgs({
+    args: commandArgv,
     options: {
       task: { type: 'string', short: 't' },
       'task-file': { type: 'string', short: 'f' },
@@ -23,17 +40,33 @@ export function parseLoopArgs(argv) {
       yes: { type: 'boolean', short: 'y' },
       'no-worktree': { type: 'boolean' },
       'dry-run': { type: 'boolean' },
+      json: { type: 'boolean' },
+      metrics: { type: 'boolean' },
+      'older-than': { type: 'string' },
       help: { type: 'boolean', short: 'h' },
     },
-    allowPositionals: false,
+    allowPositionals: true,
     strict: true,
   });
-  if (values.help) return { help: true };
+  if (values.help) return { command, help: true };
   const maxRounds = values['max-rounds'] ? Number(values['max-rounds']) : undefined;
   if (maxRounds !== undefined && (!Number.isInteger(maxRounds) || maxRounds < 1)) {
     throw new Error('--max-rounds must be a positive integer');
   }
+  const olderThanDays = values['older-than'] === undefined ? undefined : Number(values['older-than']);
+  if (olderThanDays !== undefined && (!Number.isFinite(olderThanDays) || olderThanDays < 0)) {
+    throw new Error('--older-than must be a non-negative number of days');
+  }
+  const [runName] = positionals;
+  if (positionals.length > 1 || (['status', 'inspect', 'cancel'].includes(command) && !runName)) {
+    throw new Error(`${command} requires exactly one run name`);
+  }
+  if (command !== 'run' && !['status', 'inspect', 'cancel'].includes(command) && positionals.length) {
+    throw new Error(`${command} does not accept positional arguments`);
+  }
   return {
+    command,
+    runName,
     task: values.task,
     taskFile: values['task-file'],
     name: values.name,
@@ -49,13 +82,34 @@ export function parseLoopArgs(argv) {
     yes: values.yes,
     noWorktree: values['no-worktree'],
     dryRun: values['dry-run'],
+    json: values.json,
+    metrics: values.metrics,
+    olderThanDays,
   };
 }
 
 export function usage() {
   return [
-    'Usage: aloop [options]',
+    'Usage: aloop [command] [options]',
+    '',
+    'Commands:',
+    '  list                    List persisted runs',
+    '  status <name>           Show current phase, verdict, and metrics',
+    '  inspect <name>          Show manifest, phase evidence, and metrics',
+    '  metrics                 Show aggregate metrics across runs',
+    '  cancel <name>           Stop a run and release its lock',
+    '  clean                   Preview/remove completed runs older than 30 days',
+    '  doctor                  Check configuration and local tooling',
+    '  run                     Start or resume a run (the default)',
+    '',
+    'Operational options:',
+    '      --json              Emit machine-readable JSON',
+    '      --metrics           Include per-run metrics in list output',
+    '      --older-than <n>    Clean completed runs older than n days',
+    '  -y, --yes               Confirm destructive clean operations',
+    '      --dry-run           Preview clean operations without changing files',
     '',
+    'Run options:',
     '  -t, --task <text>       Inline task description',
     '  -f, --task-file <path>  Path to a task/plan/spec file',
     '  -n, --name <slug>       Explicit run identity/slug',
@@ -68,19 +122,155 @@ export function usage() {
     '      --max-rounds <n>    Cap on review/repair rounds',
     '      --from <phase>      Start at this phase',
     '      --resume            Skip phases already recorded complete',
-    '  -y, --yes               Run unattended (no per-phase confirmation; required without a terminal)',
     '      --no-worktree       Work in the current checkout instead of a worktree',
+    '  -y, --yes               Run unattended (no per-phase confirmation; required without a terminal)',
     '      --dry-run           Print the plan and rendered prompts, run nothing',
   ].join('\n');
 }
 
+function formatMetric(value) {
+  return value === null || value === undefined ? '?' : String(value);
+}
+
+async function metricsForRun(run) {
+  try {
+    const manifest = JSON.parse(await readFile(join(run.runDir, 'manifest.json'), 'utf8'));
+    return computeRunMetrics(manifest);
+  } catch {
+    return computeRunMetrics({ phases: [] });
+  }
+}
+
+function printList(runs, output = console, includeMetrics = false) {
+  if (!runs.length) return output.log('No runs found.');
+  const header = ['NAME', 'STATUS', 'PHASE', 'BRANCH', 'UPDATED', 'PR'];
+  if (includeMetrics) header.push('DURATION', 'TOKENS', 'COST');
+  output.log(header.join('\t'));
+  for (const run of runs) {
+    const row = [run.name, run.status, run.currentPhase ?? '-', run.branch ?? '-', run.updatedAt ?? run.startedAt ?? '-', run.prUrl ?? '-'];
+    if (includeMetrics && run.metrics) {
+      row.push(`${run.metrics.total.durationMs}ms`, formatMetric(run.metrics.total.tokens), formatMetric(run.metrics.total.cost));
+    }
+    output.log(row.join('\t'));
+  }
+}
+
+function printMetricsLines(metrics, output = console) {
+  output.log(`duration : ${metrics.total.durationMs}ms`);
+  output.log(`tokens   : ${formatMetric(metrics.total.tokens)}`);
+  output.log(`cost     : ${formatMetric(metrics.total.cost)}`);
+  output.log(`catch    : ${formatMetric(metrics.reviewer.catchRate)}`);
+}
+
+function printStatus(run, output = console, metrics = null) {
+  output.log(`run      : ${run.name}`);
+  output.log(`status   : ${run.status}`);
+  output.log(`phase    : ${run.currentPhase ?? '-'}`);
+  output.log(`verdict  : ${run.verdict ?? '-'}`);
+  output.log(`gate     : ${run.gateStatus ?? '-'}`);
+  output.log(`branch   : ${run.branch ?? '-'}`);
+  output.log(`updated  : ${run.updatedAt ?? run.startedAt ?? '-'}`);
+  output.log(`PR       : ${run.prUrl ?? '-'}`);
+  if (metrics) printMetricsLines(metrics, output);
+}
+
+function printAggregate(metrics, output = console) {
+  output.log(`runs        : ${metrics.runs}`);
+  output.log(`duration    : ${metrics.total.durationMs}ms`);
+  output.log(`tokens      : ${formatMetric(metrics.total.tokens)}`);
+  output.log(`cost        : ${formatMetric(metrics.total.cost)}`);
+  output.log(`convergence : ${formatMetric(metrics.convergence.convergenceRate)}`);
+  output.log(`catch       : ${formatMetric(metrics.reviewer.catchRate)}`);
+}
+
+function printInspect(run, output = console, metrics = null) {
+  printStatus(run, output, metrics);
+  output.log(`run dir  : ${run.runDir}`);
+  for (const phase of run.phases) {
+    output.log(`\n[${phase.phase}] ${phase.status}`);
+    for (const field of ['inputSha', 'outputSha', 'promptHash', 'configHash', 'engine', 'verdict', 'gateReceipts', 'artifacts']) {
+      if (phase[field] !== undefined && phase[field] !== null) output.log(`${field} : ${JSON.stringify(phase[field])}`);
+    }
+  }
+}
+
+export async function runOperationalCommand(args, { cwd = process.cwd(), output = console } = {}) {
+  const options = { cwd, configPath: args.config };
+  if (args.command === 'list') {
+    const result = await listRuns(options);
+    if (args.metrics) {
+      for (const run of result) run.metrics = await metricsForRun(run);
+    }
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else printList(result, output, args.metrics);
+    return result;
+  }
+  if (args.command === 'status') {
+    const run = await getRun(args.runName, options);
+    const metrics = computeRunMetrics(run.manifest);
+    const result = { ...run.summary, metrics };
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else printStatus(run.summary, output, metrics);
+    return result;
+  }
+  if (args.command === 'inspect') {
+    const result = await inspectRun(args.runName, options);
+    const metrics = computeRunMetrics(result.manifest ?? { phases: result.phases });
+    if (args.json) output.log(JSON.stringify({ ...result, metrics }, null, 2));
+    else printInspect(result, output, metrics);
+    return result;
+  }
+  if (args.command === 'metrics') {
+    const { runsDir } = await resolveRunsDir(cwd, args.config);
+    const result = await getAggregateMetrics(runsDir);
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else printAggregate(result, output);
+    return result;
+  }
+  if (args.command === 'cancel') {
+    const result = await cancelRun(args.runName, options);
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else printStatus(result, output);
+    return result;
+  }
+  if (args.command === 'clean') {
+    const result = await cleanRuns({
+      ...options,
+      olderThanDays: args.olderThanDays ?? 30,
+      dryRun: args.dryRun,
+      yes: args.yes,
+    });
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else {
+      output.log(`${result.dryRun ? 'Would remove' : 'Removed'} ${result.dryRun ? result.candidates.length : result.removed.length} run(s).`);
+      for (const run of result.candidates) output.log(`  ${run.name} (${run.updatedAt ?? run.startedAt ?? 'unknown date'})`);
+      if (!args.yes && !args.dryRun && result.candidates.length) output.log('Preview only: rerun with --yes to remove these runs.');
+      for (const error of result.errors) output.error?.(`  ${error.name}: ${error.error}`);
+    }
+    return result;
+  }
+  if (args.command === 'doctor') {
+    const result = await doctor(options);
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else {
+      for (const check of result.checks) output.log(`${check.ok ? '✓' : '✗'} ${check.name}: ${check.detail}`);
+      output.log(result.ok ? 'Doctor: OK' : 'Doctor: problems found');
+    }
+    return result;
+  }
+  throw new Error(`Unknown command: ${args.command}`);
+}
+
 if (isMainEntrypoint(import.meta.url)) {
   try {
     const args = parseLoopArgs(process.argv.slice(2));
     if (args.help) {
       console.log(usage());
-    } else {
+    } else if (args.command === 'run') {
       await runLoop({ args });
+    } else {
+      const result = await runOperationalCommand(args);
+      if (args.command === 'doctor' && !result.ok) process.exitCode = 1;
     }
   } catch (error) {
     console.error(error.message);

package/package.json

@@ -1,8 +1,14 @@
 {
   "name": "@syntax-syllogism/aloop",
-  "version": "0.5.3",
+  "version": "0.6.0",
   "description": "Syntax & Syllogism agentic loop runner.",
   "type": "module",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./backends/github": "./src/publish.mjs",
+    "./backends/gitlab": "./src/backends/gitlab.mjs",
+    "./src/*": "./src/*"
+  },
   "engines": {
     "node": ">=22"
   },

package/presets/work-item/loop.config.mjs

@@ -6,7 +6,7 @@ export default {
     default: { name: 'claude', effort: 'high' },
     review: { name: 'codex', effort: 'high' },
   },
-  phases: ['implement', 'gate', 'review', 'address', 'docs', 'git'],
+  phases: ['implement', 'docs', 'gate', 'review', 'address', 'pr-description', 'publish'],
   gate: ['npm test'],
   maxRounds: 3,
   timeoutMs: 30 * 60 * 1000,

package/presets/work-item/prompts/docs.md

@@ -1,6 +1,7 @@
-Do a documentation-as-built pass with the committed work in the current
-branch `{{BRANCH}}`, in the worktree at `{{REPO}}`. The work implements
-`{{TASK_NAME}}` and has passed code review.
+Do a documentation-as-built pass with the committed implementation in the
+current branch `{{BRANCH}}`, in the worktree at `{{REPO}}`. This phase runs
+before the gate and review phases, so its commit is part of the artifact they
+inspect. The work implements `{{TASK_NAME}}`.
 
 This is a docs/agent-guidance reconciliation pass only. Do not make code changes
 unless they are strictly necessary to correct documentation generation or broken
@@ -28,4 +29,5 @@ commit. Keep the worktree clean for the next phase. If the documentation is
 already accurate, make no changes and leave the worktree clean.
 
 If you find a bug while reading, note it in your final summary (and under `## Changelog` in the task file if present)
-rather than fixing it; a code change at this point would go out unreviewed.
+rather than fixing it. Later `address` rounds may revise documentation as part
+of their reviewed fixes.

package/presets/work-item/prompts/pr-description.md

@@ -0,0 +1,27 @@
+The code-producing phases have already committed their work in `{{REPO}}`, on
+branch `{{BRANCH}}`. Verify the worktree is clean and do not create any code
+commits in this phase.
+
+- Inspect the full worktree and recent branch history before writing the
+  description.
+- Do _NOT_ include notes about co-author / author.
+- Report the existing code commit hashes and messages, validation performed,
+  and whether the worktree is clean.
+- Write `{{RUN_DIR}}/pr.md` with `Title: <one-line title>` on the first line,
+  a blank line, and a body of fewer than 250 words.
+
+The PR body should cover what changed and why, a summary of the task, the
+review outcome (how many rounds, plus any recorded disagreements from the task file's
+`## Code Review` section if present), and anything deliberately left out of scope.
+
+## Boundaries
+
+- If the worktree is **not** clean — `git status --porcelain` reports anything —
+  do **not** edit files, tests, or configuration to make it clean, and do not
+  create commits. A dirty tree at this phase is a pipeline error: stop
+  immediately and report the offending paths. Reconciling it is out of scope
+  here, and the earlier phase that left the work uncommitted must be resumed
+  instead.
+- Do not push, create, edit, merge, or enable auto-merge on a pull request. The
+  driver performs and verifies those operations after this phase.
+- Do not modify the worktree or create commits.

package/presets/work-item/prompts/review.md

@@ -10,7 +10,9 @@ section, creating the section at the end of the file if it is absent. Start with
 AND Time as there may be multiple rounds of code reviews. Provide a summary of your
 review and note any gaps in completion of the task.
 
-The implementation, repair, and documentation phases commit their work. The
+The implementation and documentation phases have already committed their work,
+so documentation is included in the reviewed diff. The repair phase may revise
+documentation while committing fixes or may record a written rebuttal. The
 worktree should be clean; confirm that with `git status`. Review the complete
 cumulative branch diff with `git diff {{BASE_BRANCH}}...HEAD`, including all
 new files. Review all of it, not a sample.
@@ -68,6 +70,9 @@ In addition to your notes in the task file (if present), write this JSON to
 Rules the loop enforces — violating them stalls the run:
 
 - `blocking` holds every 🔴 and 🟡 finding. `nits` holds 🟢 and 💬.
+- `blocking` and `nits` must be arrays when supplied. Each finding must be an
+  object with a non-empty `issue` or `summary` string; `file`, when included,
+  must be a string and `line`, when included, must be a number.
 - `CHANGES_REQUESTED` requires at least one entry in `blocking`.
 - `APPROVED` requires `blocking` to be empty.
 - Approve only if you would merge this as-is. If the gate status above is

package/prompts/address.md

@@ -56,4 +56,5 @@ Judge them by process exit code on unfiltered output.
 At the end of the phase, commit the fixes and their tests in a conventional
 commit whose message names the review findings addressed. Keep the worktree
 clean for the next phase. If there is nothing to commit, leave the worktree
-clean.
+clean. When blocking findings exist, that is valid only if you recorded a
+rebuttal in the response file; otherwise the phase stalls.

package/prompts/docs.md

@@ -1,7 +1,8 @@
 {{TASK_CONTEXT}}
 
-Do a documentation-as-built pass for the committed work on branch `{{BRANCH}}`,
-in the worktree at `{{REPO}}`.
+Do a documentation-as-built pass for the committed implementation on branch
+`{{BRANCH}}`, in the worktree at `{{REPO}}`. This phase runs before the gate and
+review phases, so its commit is part of the artifact they inspect.
 
 This is a documentation reconciliation pass only. Do not make code changes
 unless they are strictly necessary to correct documentation generation or a
@@ -16,7 +17,8 @@ documentation changes, such as checking links and paths by inspection and
 reviewing the documentation diff.
 
 If you find a bug while reading, note it in your final summary rather than
-fixing it; a code change at this point would go out unreviewed.
+fixing it. Code changes are outside this documentation-only pass. Later
+`address` rounds may revise documentation as part of their reviewed fixes.
 
 At the end of the phase, commit documentation changes in a `docs:` conventional
 commit. Keep the worktree clean for the next phase. If the documentation is

package/prompts/{git.md → pr-description.md}

@@ -5,12 +5,17 @@ branch `{{BRANCH}}`.
 
 Verify the worktree is clean and do not create any code commits in this phase.
 
-- Inspect the full worktree and recent branch history before pushing.
+- Inspect the full worktree and recent branch history before writing the
+  description.
 - Do _NOT_ include notes about co-author / author.
 - Report the existing code commit hashes and messages, validation performed,
   and whether the worktree is clean.
-- Push to `{{REMOTE}}` and create a PR to `{{BASE_BRANCH}}` on the same repo. PR
-  body should be < 250 words.
+- Write `{{RUN_DIR}}/pr.md` with this exact format. The first line is a
+  one-line title, followed by a blank line and a body of fewer than 250 words:
+
+  Title: <pull request title>
+
+  <pull request body>
 
 The PR body should cover what changed and why, a summary of the task, the review
 outcome (how many rounds, plus any recorded disagreements), and anything
@@ -22,8 +27,6 @@ deliberately left out of scope.
   do **not** edit files, tests, or configuration to make it clean, and do not
   create commits. A dirty tree at this phase is a pipeline error: stop
   immediately and report the offending paths. Reconciling it is out of scope.
-- **Do not merge the pull request**, and do not enable auto-merge. A human
-  decides; an open PR is the correct end state for this run.
-- Never force-push, and never rewrite commits that already exist on `{{REMOTE}}`.
-- If the push is rejected because the branch moved, stop and report it rather
-  than forcing anything.
+- Do not push, create, edit, merge, or enable auto-merge on a pull request. The
+  driver performs and verifies those operations after this phase.
+- Do not modify the worktree or create commits.

package/prompts/review.md

@@ -6,10 +6,12 @@ in the worktree at `{{REPO}}` for bugs, quality, and alignment with the task.
 Write your prose review to `{{RUN_DIR}}/review-round-{{ROUND}}.md`. Include a
 summary of the review and any gaps in completion of the task.
 
-The implementation, repair, and documentation phases commit their work. The
-worktree should be clean; confirm that with `git status`. Review the complete
-cumulative branch diff with `git diff {{BASE_BRANCH}}...HEAD`, including all
-new files. Review all of it, not a sample.
+The implementation and documentation phases have already committed their work,
+so documentation is included in the reviewed diff. The repair phase may revise
+documentation while committing fixes or may record a written rebuttal in the
+run directory. The worktree should be clean; confirm that with `git status`.
+Review the complete cumulative branch diff with `git diff {{BASE_BRANCH}}...HEAD`,
+including all new files. Review all of it, not a sample.
 
 This is review round {{ROUND}} of at most {{MAX_ROUNDS}}.
 
@@ -65,6 +67,9 @@ prose or your stdout.
 Rules the loop enforces — violating them stalls the run:
 
 - `blocking` holds every 🔴 and 🟡 finding. `nits` holds 🟢 and 💬.
+- `blocking` and `nits` must be arrays when supplied. Each finding must be an
+  object with a non-empty `issue` or `summary` string; `file`, when included,
+  must be a string and `line`, when included, must be a number.
 - `CHANGES_REQUESTED` requires at least one entry in `blocking`.
 - `APPROVED` requires `blocking` to be empty.
 - Approve only if you would merge this as-is. If the gate status above is