@syntax-syllogism/aloop 0.5.0

package/CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+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.5.0] - 2026-09-12
+
+### Added
+
+- Config-registered engine adapters for customizing loop execution environments
+- Worktree setup with automatic no-op detection
+- Lean prompts and work-item preset templates
+- Optional task input parameter to decouple from work-item operations
+- Complete configuration overrides for flexible behavior customization
+- Audited resume engine overrides for workflow control
+- Configurable base branch support for multi-branch operations
+- Per-phase commits with configurable AI model and effort levels
+
+### Fixed
+
+- Standalone public package history export
+- Task context inclusion in AI review prompts
+- Piped input safety with explicit confirmation requirements
+- Worktree stability on dirty git states
+- Wiki commit preservation with cron scheduling
+- Output streaming for long-running phases to prevent false hang detection
+
+## [Unreleased]
+
+---
+
+## Pre-extraction history
+
+History from before the standalone extraction (changesets format), preserved for reference.
+
+
+## 0.4.6
+
+### Patch Changes
+
+- 1eac189: Fix the `agy` engine adapter so it works in the loop's headless runs. Pass
+  `--dangerously-skip-permissions` — agy has no non-interactive `auto` permission
+  mode, so without it agy auto-denies the first command tool and exits 0 having
+  done nothing, and the phase is wrongly marked complete. Also switch agy to
+  `--output-format stream-json` with a renderer for its `init`/`step_update`/
+  `result` events, so a multi-minute phase streams readable progress instead of
+  buffering every byte until exit and looking like a hang.
+
+## 0.4.5
+
+### Patch Changes
+
+- 35b961b: Stall the git phase deterministically when the worktree is dirty.
+
+  The `git` phase pushes and opens a PR and is forbidden from committing, yet it ran as an unbounded agent. When an earlier phase left the tree dirty, the agent — told the tree was already clean — improvised an uncommittable "fix" and spun until its per-command timeout. The runner now asserts a clean worktree before any phase flagged `requiresCleanTree` (the built-in `git` phase) and stalls with the offending paths instead, and the git prompt tells the agent to stop and report rather than reconcile a dirty tree. The check is worktree cleanliness only: unresolved review findings deliberately do not block, so a clean tree with open findings can still be resumed through `docs` and `git`.
+
+## 0.4.4
+
+### Patch Changes
+
+- c522a34: Allow `aloop --config <path>` to load an external loop configuration,
+  including as a complete configuration override when resuming a run.
+- c88fce3: Stop asking agents to commit wiki work items, move new work items to `IN PROGRESS`
+  at the start of implementation, and constrain loop status instructions to the
+  supported `TODO`, `IN PROGRESS`, `UNDER REVIEW`, and `DONE` values.
+
+## 0.4.3
+
+### Patch Changes
+
+- a5540e2: Allow `aloop --config <path>` to load an external loop configuration,
+  including as a complete configuration override when resuming a run.
+- 0b74814: Checkpoint the owed repair when a review hits the round cap.
+
+  Previously, a `CHANGES_REQUESTED` verdict on the final allowed round was not recorded as a pending repair, so the last review's findings were left unaddressed with no checkpoint. Resuming with a raised `--max-rounds` then started with a fresh review of the identical tree instead of running the `address` phase, burning a review round re-discovering the same findings. The repair is now checkpointed at the cap, so a resume runs the owed `address` phase before re-reviewing. Resuming without raising the cap stays a clean no-op.
+
+- 4800fb5: Add an explicit `--override-engine` option to move a resumed run to a different
+  agent executable while recording the change in run state and phase logs.
+
+## 0.4.2
+
+### Patch Changes
+
+- 97de439: Checkpoint the owed repair when a review hits the round cap.
+
+  Previously, a `CHANGES_REQUESTED` verdict on the final allowed round was not recorded as a pending repair, so the last review's findings were left unaddressed with no checkpoint. Resuming with a raised `--max-rounds` then started with a fresh review of the identical tree instead of running the `address` phase, burning a review round re-discovering the same findings. The repair is now checkpointed at the cap, so a resume runs the owed `address` phase before re-reviewing. Resuming without raising the cap stays a clean no-op.
+
+## 0.4.1
+
+### Patch Changes
+
+- a091002: Stop Claude phases from stalling silently.
+
+  - Run the Claude engine in `auto` permission mode instead of `acceptEdits`. A non-interactive `claude -p` run has nobody to answer a permission prompt, so under `acceptEdits` every Bash call was denied and the implement, gate-repair, docs, and git phases could not build, test, or commit.
+  - Ask Claude for `stream-json` output and render it to readable progress lines. `--output-format text` withheld every byte until the process exited, so a phase that ran for half an hour was indistinguishable from one that had hung.
+  - Raise the default per-command timeout from 30 to 60 minutes; a real implement phase routinely runs past the old cap and was killed mid-edit.
+
+## 0.4.0
+
+### Minor Changes
+
+- 8f2421f: Add `--base-branch` to build and PR a run on top of another branch, for stacked PRs.
+
+## 0.3.0
+
+### Minor Changes
+
+- 903d17c: Allow loop engine configuration to select an optional model and reasoning effort
+  per phase, preserve those effective settings when a run resumes, and display
+  them in dry-run output and phase logs. Existing string-based engine settings
+  remain supported.
+- 903d17c: Commit implementation, repair, and documentation phases independently and use
+  review commit SHAs to resume incremental verdict rounds.
+
+## 0.2.0
+
+### Minor Changes
+
+- 3eb19c2: Add `@syntax-syllogism/aloop`, an engine-agnostic agentic loop runner.
+
+  `aloop` drives a work item through implementation, a deterministic gate, a
+  capped review/repair loop, a documentation pass, and the git workflow, stopping
+  at an open pull request. Control flow, iteration caps, and exit conditions live
+  in the driver; agents only supply judgment.
+
+  - Engine adapters for `claude`, `codex`, and `agy`, selectable per phase, so the
+    reviewer can run on a different model family than the implementer.
+  - Phases are declared as a flat list and folded into a loop: a verdict phase
+    absorbs the repair phases after it and the gate before it.
+  - The review phase emits a machine-readable verdict. Parsing fails closed, and
+    the loop will not exit on approval while the gate re-check is red.
+  - Runs are isolated in a `git worktree`, with logs, verdicts, and resumable
+    state under `.loop/runs/<slug>/`.
+  - Only the `git` phase commits; earlier phases leave work uncommitted in the
+    worktree, so the reviewer reads the working tree rather than a branch range.
+  - `remote` selects the push target and is validated before the run starts,
+    rather than assuming `origin` in repos with several remotes.
+  - Prompts ship with the package and are overridable per phase from
+    `.loop/prompts/` in the consuming project.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jacob Richter
+
+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,128 @@
+# aloop
+
+`@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
+CLIs provide judgment in fresh processes.
+
+## Install
+
+```sh
+npm install --global @syntax-syllogism/aloop
+# or run without a global install
+npx @syntax-syllogism/aloop --help
+```
+
+The package is published to the public npm registry and needs no private
+registry configuration.
+
+## Quick start
+
+From a git repository with a `loop.config.mjs` (or with the defaults):
+
+```sh
+aloop --task "Add request tracing" --name request-tracing
+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.
+
+## 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
+   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.
+
+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.
+
+## Configuration
+
+Create `loop.config.mjs` in the repository being operated on:
+
+```js
+export default {
+  remote: 'origin',
+  engines: {
+    default: { name: 'claude', effort: 'high' },
+    review: { name: 'codex', effort: 'high' },
+  },
+  phases: ['implement', 'gate', 'review', 'address', 'docs', 'git'],
+  gate: ['npm test'],
+  setup: ['npm ci'],
+  maxRounds: 3,
+};
+```
+
+Supported built-in engines are `claude`, `codex`, and `agy`. The corresponding
+CLI must already be installed and authenticated. Engine descriptors may include
+an engine-specific `model` and `effort`. `--config` selects a configuration
+file outside the current repository; command-line phase and round options take
+precedence.
+
+### 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.
+
+## Prompt overrides and the work-item preset
+
+Copy a phase prompt to `.loop/prompts/<phase>.md` to override only that phase.
+Templates use the variables documented in `docs/loop.md` and fail if a
+placeholder is unresolved.
+
+For repositories using Markdown work items, install the bundled preset:
+
+```sh
+mkdir -p .loop/prompts
+cp -r node_modules/@syntax-syllogism/aloop/presets/work-item/prompts/. .loop/prompts/
+```
+
+The preset includes prompts and a sample configuration. Adapt it to the
+repository's branches and gates before use.
+
+## Building up to unattended runs
+
+Use this progression:
+
+1. Render prompts with `--dry-run`.
+2. Watch one representative task through every phase.
+3. Exercise the review loop with `--max-rounds 2`.
+4. Add `-y` only for task shapes whose behavior is already understood.
+
+## Development
+
+```sh
+npm ci
+npm test
+npm pack --dry-run
+```
+
+## Contributing
+
+Issues and contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) and
+the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for how to report vulnerabilities.
+
+## License
+
+[MIT](LICENSE) © Jacob Richter

package/bin/loop.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import { isMainEntrypoint } from '../src/entrypoint.mjs';
+import { runLoop } from '../src/pipeline.mjs';
+
+export function parseLoopArgs(argv) {
+  const { values } = parseArgs({
+    args: argv,
+    options: {
+      task: { type: 'string', short: 't' },
+      'task-file': { type: 'string', short: 'f' },
+      name: { type: 'string', short: 'n' },
+      branch: { type: 'string', short: 'b' },
+      'base-branch': { type: 'string' },
+      engine: { type: 'string', short: 'e' },
+      'override-engine': { type: 'boolean' },
+      config: { type: 'string' },
+      phases: { type: 'string' },
+      'max-rounds': { type: 'string' },
+      from: { type: 'string' },
+      resume: { type: 'boolean' },
+      yes: { type: 'boolean', short: 'y' },
+      'no-worktree': { type: 'boolean' },
+      'dry-run': { type: 'boolean' },
+      help: { type: 'boolean', short: 'h' },
+    },
+    allowPositionals: false,
+    strict: true,
+  });
+  if (values.help) return { 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');
+  }
+  return {
+    task: values.task,
+    taskFile: values['task-file'],
+    name: values.name,
+    branch: values.branch,
+    baseBranch: values['base-branch'],
+    engine: values.engine,
+    overrideEngine: values['override-engine'],
+    config: values.config,
+    phases: values.phases ? values.phases.split(',').map((phase) => phase.trim()).filter(Boolean) : undefined,
+    maxRounds,
+    from: values.from,
+    resume: values.resume,
+    yes: values.yes,
+    noWorktree: values['no-worktree'],
+    dryRun: values['dry-run'],
+  };
+}
+
+export function usage() {
+  return [
+    'Usage: aloop [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',
+    '  -b, --branch <name>     Branch to build on (default: <branchPrefix><name>)',
+    '      --base-branch <branch>  Base to branch from and PR against (default: baseBranch config)',
+    '  -e, --engine <name>     Default engine: claude | codex | agy',
+    '      --override-engine   With --resume and --engine, replace saved agent executables',
+    '      --config <path>     Load loop configuration from this file (also overrides saved config on resume)',
+    '      --phases a,b,c      Override the configured phase list',
+    '      --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',
+    '      --dry-run           Print the plan and rendered prompts, run nothing',
+  ].join('\n');
+}
+
+if (isMainEntrypoint(import.meta.url)) {
+  try {
+    const args = parseLoopArgs(process.argv.slice(2));
+    if (args.help) {
+      console.log(usage());
+    } else {
+      await runLoop({ args });
+    }
+  } catch (error) {
+    console.error(error.message);
+    if (!error.command) console.error(usage());
+    process.exitCode = 1;
+  }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@syntax-syllogism/aloop",
+  "version": "0.5.0",
+  "description": "Syntax & Syllogism agentic loop runner.",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "bin": {
+    "aloop": "bin/loop.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "prompts",
+    "presets",
+    "CHANGELOG.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "agentic",
+    "loop",
+    "code-review",
+    "claude",
+    "codex",
+    "antigravity",
+    "opencode",
+    "cli"
+  ],
+  "homepage": "https://github.com/Syntax-Syllogism/aloop#readme",
+  "bugs": {
+    "url": "https://github.com/Syntax-Syllogism/aloop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Syntax-Syllogism/aloop.git"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/presets/work-item/README.md

@@ -0,0 +1,31 @@
+# Work-item preset
+
+The default loop prompts are task-oriented and do not require a particular
+document layout. This preset is for repositories that use the Syntax &
+Syllogism work-item workflow.
+
+## Assumptions
+
+The preset expects:
+
+- a Markdown task file with status frontmatter and `## Changelog` and
+  `## Code Review` sections;
+- a separate repository for those task files; and
+- a separate job or cron workflow that commits task-file changes.
+
+The preset also includes an example `loop.config.mjs` with the owner's standard
+branches, engines, phases, and `npm test` gate. Adjust it for your repository.
+
+## Installation
+
+Install the package, create `.loop/prompts/`, and copy the preset prompts into
+the project override directory:
+
+```sh
+mkdir -p .loop/prompts
+cp -r node_modules/@syntax-syllogism/aloop/presets/work-item/prompts/. .loop/prompts/
+```
+
+The runner loads project prompt overrides before its packaged defaults. Keep the
+sample config as a starting point for `loop.config.mjs` if its settings match
+your repository.

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

@@ -0,0 +1,13 @@
+export default {
+  baseBranch: 'master',
+  branchPrefix: 'feat/',
+  remote: 'origin',
+  engines: {
+    default: { name: 'claude', effort: 'high' },
+    review: { name: 'codex', effort: 'high' },
+  },
+  phases: ['implement', 'gate', 'review', 'address', 'docs', 'git'],
+  gate: ['npm test'],
+  maxRounds: 3,
+  timeoutMs: 30 * 60 * 1000,
+};

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

@@ -0,0 +1,57 @@
+A code review has been appended for task `{{TASK_NAME}}`. Please
+address all findings, and if a task file is present (`{{TASK_FILE}}`), update its changelog.
+
+The work is in the worktree at `{{REPO}}` on branch `{{BRANCH}}`; prior phases
+have committed their changes.
+
+This is round {{ROUND}} of at most {{MAX_ROUNDS}}. If the findings are not
+resolved by round {{MAX_ROUNDS}} the run stops and a human picks it up, so fix
+causes rather than symptoms.
+
+## Blocking findings
+
+{{FINDINGS}}
+
+The structured verdict is in `{{VERDICT_FILE}}`; the full review, including
+non-blocking notes, is in the task file's `## Code Review` section if a task file
+is present.
+
+## Deterministic gate
+
+{{GATE_STATUS}}
+
+If the gate is failing, that is your first priority — the review cannot clear
+while it is red.
+
+## How to respond
+
+Address every blocking finding. For each one, either fix it or — if you believe
+the reviewer is wrong — leave the code as it is and record a short rebuttal under a
+`#### Response — Round {{ROUND}}` heading (in the task file's `## Code Review`
+section if a task file is present, or in your final summary), naming the finding and
+your reasoning. A disagreement recorded in writing is a legitimate outcome;
+silently ignoring a finding is not.
+
+Do not:
+
+- Delete, skip, or weaken a test to make a finding or a gate go away. If a test
+  is genuinely wrong, fix the test and say so in the rebuttal.
+- Fix anything the reviewer did not raise. Unrelated changes make the next
+  review round harder and can introduce new findings.
+
+Scope and token discipline from the implementation phase still apply: work from
+the files the findings name, keep command output short, and summarize before editing.
+
+## Verification
+
+Run the targeted tests for what you changed, then the gate commands:
+
+```
+{{GATE_COMMANDS}}
+```
+
+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.

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

@@ -0,0 +1,31 @@
+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.
+
+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
+references.
+
+Audit the final as-built state and update durable documentation only where
+needed:
+
+Keep AGENTS.md light. It should orient coding agents and point them to the right
+project documentation; it should not become the full documentation body.
+Put substantive documentation for each major functionality area in docs/, split
+by topic when that keeps files focused.
+Ensure AGENTS.md references the relevant docs/ files so future agents know where
+to find the information they need without loading everything.
+Do not touch CLAUDE.md. It should already reference AGENTS.md and should remain
+unchanged.
+If docs are already accurate and appropriately structured, make no changes.
+
+After the pass, run the smallest meaningful verification checks for
+documentation changes, such as checking links/paths by inspection and
+`git diff AGENTS.md` or `git diff docs` when applicable.
+
+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
+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.

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

@@ -0,0 +1,44 @@
+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 pushing.
+- 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.
+
+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.
+
+## The task file
+
+If a task file is present (`{{TASK_FILE}}`), update it without committing it:
+
+- Set the frontmatter `status` to `UNDER REVIEW`.
+- Append a `## Changelog` entry listing the code commits (short SHA + subject)
+  and the PR URL once you have it.
+- Use only `TODO`, `IN PROGRESS`, `UNDER REVIEW`, or `DONE` as statuses.
+
+A separate job or workflow commits task file changes if needed. Do not commit the
+task file or make any other commits in its repository.
+
+## 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 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.
+
+The separate task-file workflow and cron process own updates to that repository;
+keep code and task-file commits separate.

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

@@ -0,0 +1,50 @@
+{{TASK_CONTEXT}} The worktree at
+`{{REPO}}` is already checked out to a new branch `{{BRANCH}}` off
+`{{BASE_BRANCH}}` — work there, and do not create or switch branches.
+
+Skip any steps that require manual human intervention. Implement the rest from
+start to finish.
+
+If a task file is present (`{{TASK_FILE}}`), update its frontmatter status to
+`IN PROGRESS` before doing anything else in this first turn. The only allowed
+statuses are `TODO`, `IN PROGRESS`, `UNDER REVIEW`, and `DONE`.
+
+This run is unattended, so you cannot ask clarifying questions. Where you would
+have asked, choose the reading most consistent with the task and the
+surrounding code, and record the question and the assumption you made under
+`## Changelog` in the task file (if present). If a step genuinely cannot proceed
+without a human, implement everything else and record what you skipped and why.
+
+Scope:
+
+- Start with the files referenced in the task.
+- Do _not_ scan or explore the whole repo.
+- Only read additional files if they are imported or referenced in the task.
+
+Token discipline:
+
+- Keep command output short.
+- Summarize findings before editing.
+
+Verification:
+
+- Add or update targeted tests.
+- Run only the relevant test file first.
+- Run broader tests after the targeted test passes.
+- These commands gate the work and will be run against your changes, so run
+  them yourself before finishing:
+
+```
+{{GATE_COMMANDS}}
+```
+
+- Judge them by process exit code on unfiltered output. A wrapper that
+  summarizes output can report a failure the tool never produced, and a cached
+  build can report success without compiling anything.
+- At the end of the phase, commit the implementation and its targeted tests in
+  a conventional commit. Keep the worktree clean for the next phase.
+- If a task file is present (`{{TASK_FILE}}`), keep it current by adding updates
+  to the `## Changelog` and updating status in the frontmatter when applicable.
+  Use only `TODO`, `IN PROGRESS`, `UNDER REVIEW`, or `DONE` as statuses.
+- End your turn with a summary and next steps if applicable. The loop runs the
+  code review next, so you do not need to ask for one.