@syntax-syllogism/aloop 0.7.0 → 0.8.2

package/CHANGELOG.md

@@ -5,7 +5,27 @@ 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/).
 
-## [Unreleased]
+## [0.8.0] - 2026-09-20
+
+### Added
+
+- Eval harness for running code across multiple models
+- JSDoc type checking for validation
+- Live TUI renderer for interactive aloop runs
+- aloop init command for project initialization
+- Guided resume capability to repair failing gates
+
+### Changed
+
+- TUI renderer now runs even with --yes flag
+
+### Fixed
+
+- JSDoc type contracts bound to production boundaries
+- Fixed TUI rendering performance with diff-stat caching
+- Resume repair and downstream attestation restored
+
+## [0.7.0] - 2026-09-18
 
 ### Added
 
@@ -17,11 +37,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   Gemini has no reasoning-effort flag, so a configured `effort` is ignored for
   it.
 
-## [0.7.0] - 2026-09-18
+## [0.6.2] - 2026-09-16
 
-### Added
+### Fixed
 
-- Gemini is now available as a built-in engine
+- Resolve Windows executables to correct on-disk casing
 
 ## [0.6.0] - 2026-09-14
 
@@ -66,6 +86,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Handle a failed Windows timeout teardown and isolate POSIX tests from
   Windows CI.
 
+## [0.5.2] - 2026-09-13
+
+### Changed
+
+- Internal maintenance and tooling updates
+
+## [0.5.1] - 2026-09-13
+
+### Changed
+
+- Internal maintenance and tooling updates
+
 ## [0.5.0] - 2026-09-12
 
 ### Added
@@ -88,15 +120,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 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
@@ -200,22 +229,3 @@ History from before the standalone extraction (changesets format), preserved for
     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.
-
-## [0.6.2] - 2026-09-16
-
-### Fixed
-
-- Resolve Windows executables to correct on-disk casing
-
-## [0.5.2] - 2026-09-13
-
-### Changed
-
-- Internal maintenance and tooling updates
-
-## [0.5.1] - 2026-09-13
-
-### Changed
-
-- Internal maintenance and tooling updates
-

package/README.md

@@ -28,7 +28,13 @@ Interactive confirmations use the Git Bash/Windows console when available. Use
 
 ## Quick start
 
-From a git repository with a `loop.config.mjs` (or with the defaults):
+From a git repository, create the editable configuration and prompt overrides:
+
+```sh
+aloop init
+```
+
+Review the generated `loop.config.mjs`, then start a task:
 
 ```sh
 aloop --task "Add request tracing" --name request-tracing
@@ -67,7 +73,8 @@ complete guide, manifest schema, and verdict contract.
 
 ## Configuration
 
-Create `loop.config.mjs` in the repository being operated on:
+`aloop init` creates a commented `loop.config.mjs` in the repository being
+operated on. Adjust it as needed; for example, a configuration can be:
 
 ```js
 export default {
@@ -125,12 +132,13 @@ 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/
+aloop init --preset work-item
 ```
 
-The preset includes prompts and a sample configuration. Adapt it to the
-repository's branches and gates before use.
+This creates the preset's sample configuration and prompt overrides. Adapt its
+branches and gates before use. `aloop init` also copies the default prompts, so
+you can edit any `.loop/prompts/<phase>.md` immediately; see
+[`docs/loop.md`](docs/loop.md#getting-started) for overwrite and preset details.
 
 ## Building up to unattended runs
 
@@ -141,6 +149,13 @@ Use this progression:
 3. Exercise the review loop with `--max-rounds 2`.
 4. Add `-y` only for task shapes whose behavior is already understood.
 
+## Evaluation harness
+
+`aloop-eval <spec.mjs>` runs a task corpus across a model/config matrix, each
+cell in its own throwaway repository, and reports completion, escaped
+defects, convergence, and cost per cell and per config. See
+[`docs/eval.md`](docs/eval.md) for the spec file shape and reported fields.
+
 ## Development
 
 ```sh

package/bin/eval.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { isMainEntrypoint } from '../src/entrypoint.mjs';
+import { formatEvalSummaryTable, formatEvalTable, runEval, summarizeEval } from '../src/eval.mjs';
+
+export function usage() {
+  return [
+    'Usage: aloop-eval <spec.mjs> [options]',
+    '',
+    'Runs the task corpus and model/config matrix exported by <spec.mjs>',
+    '(a default export, or named `corpus` and `matrix` exports) through the',
+    'loop and reports completion, escaped defects, convergence, cost, and time.',
+    '',
+    'Options:',
+    '      --json    Emit machine-readable JSON instead of tables',
+  ].join('\n');
+}
+
+export async function runEvalCli(argv, { cwd = process.cwd(), output = console } = {}) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: { json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' } },
+    allowPositionals: true,
+    strict: true,
+  });
+  if (values.help || !positionals.length) {
+    output.log(usage());
+    return null;
+  }
+  const [specPath] = positionals;
+  const spec = await import(pathToFileURL(resolve(cwd, specPath)).href);
+  const { corpus, matrix } = spec.default ?? spec;
+  if (!Array.isArray(corpus) || !Array.isArray(matrix)) {
+    throw new Error(`${specPath} must export a task \`corpus\` array and a config \`matrix\` array.`);
+  }
+  const results = await runEval({ corpus, matrix });
+  const summaries = summarizeEval(results);
+  if (values.json) {
+    output.log(JSON.stringify({ results, summaries }, null, 2));
+  } else {
+    output.log(formatEvalTable(results));
+    output.log('');
+    output.log(formatEvalSummaryTable(summaries));
+  }
+  return { results, summaries };
+}
+
+if (isMainEntrypoint(import.meta.url)) {
+  try {
+    await runEvalCli(process.argv.slice(2));
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/bin/loop.mjs

@@ -10,6 +10,7 @@ import {
   doctor,
   getAggregateMetrics,
   getRun,
+  init,
   inspectRun,
   listRuns,
   resolveRunsDir,
@@ -17,7 +18,7 @@ import {
 import { computeRunMetrics } from '../src/metrics.mjs';
 import { runLoop } from '../src/pipeline.mjs';
 
-const commands = new Set(['run', 'list', 'status', 'inspect', 'cancel', 'clean', 'doctor', 'metrics']);
+const commands = new Set(['run', 'list', 'status', 'inspect', 'cancel', 'clean', 'doctor', 'metrics', 'init']);
 
 export function parseLoopArgs(argv) {
   const command = commands.has(argv[0]) ? argv[0] : 'run';
@@ -37,12 +38,17 @@ export function parseLoopArgs(argv) {
       'max-rounds': { type: 'string' },
       from: { type: 'string' },
       resume: { type: 'boolean' },
+      note: { type: 'string' },
+      'note-file': { type: 'string' },
       yes: { type: 'boolean', short: 'y' },
       'no-worktree': { type: 'boolean' },
+      'no-tui': { type: 'boolean' },
       'dry-run': { type: 'boolean' },
       json: { type: 'boolean' },
       metrics: { type: 'boolean' },
       'older-than': { type: 'string' },
+      preset: { type: 'string' },
+      force: { type: 'boolean' },
       help: { type: 'boolean', short: 'h' },
     },
     allowPositionals: true,
@@ -79,12 +85,17 @@ export function parseLoopArgs(argv) {
     maxRounds,
     from: values.from,
     resume: values.resume,
+    note: values.note,
+    noteFile: values['note-file'],
     yes: values.yes,
     noWorktree: values['no-worktree'],
+    noTui: values['no-tui'],
     dryRun: values['dry-run'],
     json: values.json,
     metrics: values.metrics,
     olderThanDays,
+    preset: values.preset,
+    force: values.force,
   };
 }
 
@@ -100,6 +111,7 @@ export function usage() {
     '  cancel <name>           Stop a run and release its lock',
     '  clean                   Preview/remove completed runs older than 30 days',
     '  doctor                  Check configuration and local tooling',
+    '  init                    Scaffold loop.config.mjs and .loop/prompts',
     '  run                     Start or resume a run (the default)',
     '',
     'Operational options:',
@@ -109,6 +121,10 @@ export function usage() {
     '  -y, --yes               Confirm destructive clean operations',
     '      --dry-run           Preview clean operations without changing files',
     '',
+    'Init options:',
+    '      --preset <name>     Seed init from a bundled preset (e.g. work-item)',
+    '      --force             Overwrite existing scaffold files',
+    '',
     'Run options:',
     '  -t, --task <text>       Inline task description',
     '  -f, --task-file <path>  Path to a task/plan/spec file',
@@ -122,7 +138,10 @@ export function usage() {
     '      --max-rounds <n>    Cap on review/repair rounds',
     '      --from <phase>      Start at this phase',
     '      --resume            Skip phases already recorded complete',
+    '      --note <text>       Give the resumed phase an authoritative instruction',
+    '      --note-file <path>  Read the instruction from a file (--note wins)',
     '      --no-worktree       Work in the current checkout instead of a worktree',
+    '      --no-tui            Force plain streaming output (TUI is on by default on a TTY)',
     '  -y, --yes               Run unattended (no per-phase confirmation; required without a terminal)',
     '      --dry-run           Print the plan and rendered prompts, run nothing',
   ].join('\n');
@@ -258,6 +277,16 @@ export async function runOperationalCommand(args, { cwd = process.cwd(), output
     }
     return result;
   }
+  if (args.command === 'init') {
+    const result = await init({ cwd, preset: args.preset, force: args.force });
+    if (args.json) output.log(JSON.stringify(result, null, 2));
+    else {
+      for (const file of result.created) output.log(`  create  ${file}`);
+      for (const file of result.skipped) output.log(`  skip    ${file} (exists)`);
+      output.log(result.preset ? `Initialized aloop with preset "${result.preset}".` : 'Initialized aloop.');
+    }
+    return result;
+  }
   throw new Error(`Unknown command: ${args.command}`);
 }
 
@@ -270,7 +299,7 @@ if (isMainEntrypoint(import.meta.url)) {
       await runLoop({ args });
     } else {
       const result = await runOperationalCommand(args);
-      if (args.command === 'doctor' && !result.ok) process.exitCode = 1;
+      if (args.command === 'doctor' && !(/** @type {any} */ (result)).ok) process.exitCode = 1;
     }
   } catch (error) {
     console.error(error.message);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syntax-syllogism/aloop",
-  "version": "0.7.0",
+  "version": "0.8.2",
   "description": "Syntax & Syllogism agentic loop runner.",
   "type": "module",
   "exports": {
@@ -13,7 +13,8 @@
     "node": ">=22"
   },
   "bin": {
-    "aloop": "bin/loop.mjs"
+    "aloop": "bin/loop.mjs",
+    "aloop-eval": "bin/eval.mjs"
   },
   "files": [
     "bin",
@@ -48,6 +49,11 @@
     "access": "public"
   },
   "scripts": {
-    "test": "node --test"
+    "test": "node --test",
+    "typecheck": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.4",
+    "typescript": "^5.9.3"
   }
 }

package/presets/work-item/README.md

@@ -18,14 +18,16 @@ 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:
+Install the package, then initialize the project with the preset:
 
 ```sh
-mkdir -p .loop/prompts
-cp -r node_modules/@syntax-syllogism/aloop/presets/work-item/prompts/. .loop/prompts/
+aloop init --preset work-item
 ```
 
-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.
+This writes the sample config and preset prompts into your project, with the
+packaged defaults filling any prompts the preset does not provide. The runner
+loads project prompt overrides before its packaged defaults.
+
+If you prefer to wire it up by hand, create `.loop/prompts/` and copy the
+contents of `node_modules/@syntax-syllogism/aloop/presets/work-item/prompts/`
+there; copy `loop.config.mjs` separately if its settings match your repository.

package/prompts/fix-gate.md

@@ -0,0 +1,17 @@
+{{TASK_CONTEXT}}
+
+The deterministic gate is failing. Work in `{{REPO}}` on branch `{{BRANCH}}`
+and make the gate pass by fixing the underlying implementation.
+
+## Gate status
+
+{{GATE_STATUS}}
+
+## Gate commands
+
+{{GATE_COMMANDS}}
+
+Do not delete, skip, or weaken tests or gate commands to make the gate pass.
+Make only the changes needed to correct the failure, run the relevant tests and
+the gate commands, then commit the repair with a conventional commit message.
+Keep the worktree clean for the re-check.

package/src/adapters.mjs

@@ -1,3 +1,7 @@
+/** @typedef {import('./types.js').Adapter} Adapter */
+/** @typedef {import('./types.js').Config} Config */
+/** @typedef {import('./types.js').Engine} Engine */
+
 /**
  * Engine adapters.
  *
@@ -305,15 +309,17 @@ export function createJsonlRenderer(renderEvent) {
 }
 
 /** A renderer for engines whose stdout is already meant to be read. */
+/** @returns {import('./types.js').Renderer} */
 export function passthroughRenderer() {
   return { write: (text) => text, end: () => '' };
 }
 
+/** @type {Adapter} */
 const claudeAdapter = {
   name: 'claude',
   version: cliVersion('claude'),
   efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
-  command({ prompt, addDirs, permissions, artifactOnly = false, agent = {} }) {
+  command({ prompt, addDirs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
     // `auto`, not `acceptEdits`, is used for worktree-writing and
     // artifact-only phases: under acceptEdits a non-interactive `-p` run
     // auto-denies every Bash call, because there is no one to answer the
@@ -334,11 +340,12 @@ const claudeAdapter = {
   createRenderer: () => createJsonlRenderer(renderClaudeEvent),
 };
 
+/** @type {Adapter} */
 const codexAdapter = {
   name: 'codex',
   version: cliVersion('codex'),
   efforts: ['low', 'medium', 'high', 'xhigh', 'max'],
-  command({ prompt, cwd, addDirs, permissions, artifactOnly = false, agent = {} }) {
+  command({ prompt, cwd, addDirs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
     const canWrite = permissionLevel(permissions) === PERMISSIONS.WRITE_WORKTREE || artifactOnly;
     const sandbox = canWrite ? 'workspace-write' : 'read-only';
     const args = ['exec', prompt, '--sandbox', sandbox, '--cd', cwd];
@@ -349,11 +356,12 @@ const codexAdapter = {
   },
 };
 
+/** @type {Adapter} */
 const agyAdapter = {
   name: 'agy',
   version: cliVersion('agy'),
   efforts: ['low', 'medium', 'high'],
-  command({ prompt, addDirs, timeoutMs, permissions, artifactOnly = false, agent = {} }) {
+  command({ prompt, addDirs, timeoutMs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
     // `--dangerously-skip-permissions`, not bare `accept-edits`: in headless
     // `--print` mode agy cannot prompt for the `command` permission its Bash-
     // style tools need, so it auto-denies the first one and exits 0 having done
@@ -382,12 +390,13 @@ const agyAdapter = {
   createRenderer: () => createJsonlRenderer(renderAgyEvent),
 };
 
+/** @type {Adapter} */
 const geminiAdapter = {
   name: 'gemini',
   version: cliVersion('gemini'),
   // Gemini CLI exposes no reasoning-effort flag, so this adapter declares no
   // `efforts`: a configured effort is simply not passed through (see docs).
-  command({ prompt, addDirs, permissions, artifactOnly = false, agent = {} }) {
+  command({ prompt, addDirs, permissions, artifactOnly = false, agent = /** @type {import('./types.js').Agent} */ ({}) }) {
     // `yolo`, not `plan`/`auto_edit`: in headless `--prompt` mode Gemini cannot
     // interactively approve the shell tools a worktree-writing phase needs to
     // build, test, and commit. `plan` is read-only and `auto_edit` auto-approves
@@ -436,6 +445,7 @@ function validateConfiguredAdapter(name, adapter) {
   return adapter;
 }
 
+/** @returns {Adapter} */
 export function adapterFor(engine, customAdapters = {}) {
   const configuredNames = customAdapters && typeof customAdapters === 'object' ? Object.keys(customAdapters) : [];
   const hasConfiguredAdapter = customAdapters && typeof customAdapters === 'object'
@@ -448,6 +458,7 @@ export function adapterFor(engine, customAdapters = {}) {
   return adapter;
 }
 
+/** @param {Engine} agent @returns {Engine} */
 export function validateAgent(agent, customAdapters = {}) {
   const adapter = adapterFor(agent.name, customAdapters);
   if (agent.effort && adapter.efforts && !adapter.efforts.includes(agent.effort)) {
@@ -457,11 +468,13 @@ export function validateAgent(agent, customAdapters = {}) {
 }
 
 /** Resolve an agent descriptor: per-phase override, else the default. */
+/** @param {Config} config @returns {Engine} */
 export function agentForPhase(config, phaseName) {
   return config.engines[phaseName] ?? config.engines.default;
 }
 
 /** Resolve which executable runs a phase. Retained for string-based callers. */
+/** @param {Config} config */
 export function engineForPhase(config, phaseName) {
   return agentForPhase(config, phaseName).name;
 }

package/src/backends/gitlab.mjs

@@ -83,7 +83,8 @@ function errorText(error) {
  * The default GitLab transport. `glab` is intentionally an external runtime
  * requirement, so consumers can replace this transport with REST or MCP code.
  */
-export function glabTransport({ cwd, runner = runCommand, env } = {}) {
+export function glabTransport(options = {}) {
+  const { cwd, runner = runCommand, env } = /** @type {any} */ (options);
   async function run(args) {
     try {
       return await runner('glab', args, { cwd, ...(env ? { env } : {}) });
@@ -153,9 +154,10 @@ export function glabTransport({ cwd, runner = runCommand, env } = {}) {
 /**
  * Adapt GitLab-native merge request data to aloop's verified pull-request port.
  *
- * @param {{ cwd: string, git?: GitFacade, transport?: GitLabTransport, env?: object }} options
+ * @param {any} options
  */
-export function gitlabBackend({ cwd, git = new GitFacade(cwd), transport, env } = {}) {
+export function gitlabBackend(options = {}) {
+  let { cwd, git = new GitFacade(cwd), transport, env } = options;
   transport ??= glabTransport({ cwd, env });
   const repositories = new Map();
 

package/src/command.mjs

@@ -2,11 +2,8 @@ import { spawn } from 'node:child_process';
 import { existsSync, realpathSync, unlinkSync, writeFileSync } from 'node:fs';
 import { win32 as windowsPath } from 'node:path';
 
-export function signalProcessGroup(pid, signal, {
-  platform = process.platform,
-  spawnImpl = spawn,
-  onFailure,
-} = {}) {
+export function signalProcessGroup(pid, signal, options = {}) {
+  const { platform = process.platform, spawnImpl = spawn, onFailure } = /** @type {any} */ (options);
   if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) return false;
   if (platform === 'win32') {
     const handleFailure = onFailure ?? (() => {
@@ -63,10 +60,8 @@ function environmentValue(env, name) {
   return key ? env[key] : undefined;
 }
 
-export function resolveWindowsExecutable(command, env = process.env, {
-  fileExists = existsSync,
-  realPath = realpathSync.native,
-} = {}) {
+export function resolveWindowsExecutable(command, env = process.env, options = {}) {
+  const { fileExists = existsSync, realPath = realpathSync.native } = /** @type {any} */ (options);
   const pathEntries = (environmentValue(env, 'PATH') ?? '').split(';').filter(Boolean);
   const pathExtensions = (environmentValue(env, 'PATHEXT') ?? WINDOWS_EXECUTABLE_EXTENSIONS.join(';'))
     .split(';')
@@ -144,7 +139,7 @@ export async function runCommand(command, args = [], options = {}) {
     platform = process.platform,
     spawnImpl = spawn,
     resolveExecutable = resolveWindowsExecutable,
-  } = options;
+  } = /** @type {any} */ (options);
   return new Promise((resolve, reject) => {
     const spawnSpec = platform === 'win32' ? windowsSpawnSpec(command, args, env, resolveExecutable) : { command, args };
     const child = spawnImpl(spawnSpec.command, spawnSpec.args, {

package/src/config.mjs

@@ -1,3 +1,6 @@
+/** @typedef {import('./types.js').Config} Config */
+/** @typedef {import('./types.js').PhaseDescriptor} PhaseDescriptor */
+
 import { access } from 'node:fs/promises';
 import { constants } from 'node:fs';
 import { join, resolve } from 'node:path';
@@ -184,6 +187,7 @@ function toPhase(entry, index) {
  * A custom verdict phase must declare its own `repair` list; merely placing a
  * repair phase after it no longer changes control flow.
  */
+/** @returns {PhaseDescriptor[]} */
 export function normalizePhases(entries, { maxRounds }) {
   const list = entries.map(toPhase);
   const phaseIndexes = new Map();
@@ -215,7 +219,7 @@ export function normalizePhases(entries, { maxRounds }) {
 
   for (let index = 0; index < list.length; index += 1) {
     const phase = list[index];
-    if (!phase.verdict) continue;
+    if (!phase.verdict && !(phase.kind === 'gate' && phase.repair)) continue;
     const repair = phase.repair ?? [];
     if (!Array.isArray(repair)) {
       throw new Error(`Phase "${phase.name}" has an invalid repair transition; expected an array.`);
@@ -233,7 +237,7 @@ export function normalizePhases(entries, { maxRounds }) {
   for (let index = 0; index < list.length; index += 1) {
     const phase = list[index];
     if (phase.role === 'repair' && !consumedRepairs.has(index)) {
-      throw new Error(`Phase "${phase.name}" is a repair phase and must be declared by a phase that emits a verdict.`);
+      throw new Error(`Phase "${phase.name}" is a repair phase and must be declared by a phase that emits a verdict or gate repair transition.`);
     }
     if (!consumedRepairs.has(index)) result.push(phase);
   }
@@ -356,6 +360,7 @@ export async function loadRunsDir(cwd, configPath) {
   return runsDir;
 }
 
+/** @returns {Promise<Config>} */
 export async function loadConfig(cwd, overrides = {}, configPath) {
   const configured = await importConfigFile(cwd, configPath);
   const merged = {