@sublang/slc 0.4.0 → 0.6.0

package/README.md

@@ -19,17 +19,18 @@ through it. Why compile prose instead of prompting with it:
   stop — the control flow becomes an inspectable
   [XState](https://xstate.js.org) machine, not prompt improvisation.
   LLM judgment is confined to the work *inside* each state.
-- **Auditable at every stage.** The intermediates are first-class files
-  you can read and edit: the normalized text, one testable "shall" item
-  per behavior (in the GEARS spec grammar the SubLang stack shares), and
-  the state machine itself. The compiler also emits verification tests
-  binding its output to the source spec.
+- **Auditable at every stage.** Every intermediate is a file you can
+  read and edit: the normalized text, one testable "shall" item per
+  behavior, the state machine itself. The compiler also emits tests
+  binding its output back to the spec.
 - **Cheaper and safer by optimization.** Steps that need no judgment are
   rewritten at compile time into plain shell commands — no LLM call, no
-  hallucination, verifiable before anything runs.
+  hallucination.
 - **Your agents, per role.** Compilation and execution run through the
   agent CLIs you already use — Claude Code, Codex, Gemini, OpenCode —
-  selectable per role.
+  selectable per role, with an optional
+  [second agent reviewing](#reviewed-compilation-two-agents) every
+  compile step.
 
 The flagship pipeline is `playbook` (the name of both the pipeline and
 the sibling [playbook](https://github.com/sublang-ai/playbook) project
@@ -41,9 +42,9 @@ a linked module the `playbook` CLI runs.
 The [demo](demo/README.md) compiles a one-paragraph description into a
 two-agent code-review loop, then lets it loose on a buggy C file: the
 coder and reviewer commit, review, and debate inside a real Git
-repository until the review comes back clean. Precompiled reference
-artifacts are included, so you can watch a run — or just read every
-compile stage — without waiting on a compile.
+repository until the review comes back clean. Precompiled artifacts are
+included, so you can watch a run — or read every compile stage —
+without waiting on a compile.
 
 ## Install
 
@@ -53,60 +54,42 @@ npm install -g @anthropic-ai/claude-agent-sdk @openai/codex-sdk
 slc --version
 ```
 
-The second line supplies the agent SDKs for the default Claude and Codex
-lineup. Playbook 4 installs none itself — which versions work is
-`@sublang/cligent`'s to enforce at load — so name the SDKs your own
-configuration needs. If one is missing, the compile stops before any
-agent call and names the package to install; if one is too old, it
-names the installed and required versions along with the exact version
-to install.
-
-Compiled artifacts import the Playbook engine from their own directory;
-when that import does not resolve, `playbook run` (3.1+) links its own
-engine beside the artifact and says so (`--no-provision` opts out).
-Working inside an npm project instead? Install the same set there — the
-compiler, the engine, and the SDKs your lineup uses — and prefix the
-commands with `npx`. A project's own install is always authoritative,
-and a globally installed SDK is invisible to a project's nested
-`@sublang/cligent`, so the SDKs belong in the same tree
-([RELEASE-11](specs/dev/release.md#release-11) has the full rules).
-
 Requirements:
 
-- A POSIX platform — macOS or Linux; on Windows, use WSL (or Git
-  Bash). Compiled script steps execute through `sh`, so native Windows
-  is not supported.
-- Node.js >= 23.6 (compiled phase artifacts are imported as native
-  TypeScript at runtime).
+- A POSIX platform — macOS or Linux; on Windows, use WSL (or Git Bash).
+  Compiled script steps execute through `sh`.
+- Node.js >= 23.6 (compiled artifacts are imported as native TypeScript).
 - One supported coding-agent CLI, installed and authenticated:
   [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview),
   [Codex CLI](https://github.com/openai/codex),
   [Gemini CLI](https://github.com/google-gemini/gemini-cli), or
   [OpenCode](https://opencode.ai).
 
+The second install line supplies the agent SDKs for the default Claude
+and Codex lineup; name the SDKs your own lineup needs instead. A missing
+or too-old SDK stops the compile before any agent call and names the
+exact package and version to install.
+
+Compiled artifacts import the Playbook engine from their own directory;
+when that import does not resolve, `playbook run` (3.1+) links its own
+engine beside the artifact and says so (`--no-provision` opts out).
+Working inside an npm project? Install the same set there and prefix the
+commands with `npx`: a project-local install is authoritative wherever it
+resolves, a project manifest declaring `@sublang/playbook` must install
+it itself, and a global SDK is invisible to a project's nested
+`@sublang/cligent`
+([[release-11](specs/packages/release.md#release-11)] has the full rules).
+
 ## Quick start
 
-In any directory, write a prose workflow as a `.md` or plain `.txt`
-file — [`demo/workflow.txt`](demo/workflow.txt) is a complete
-one-paragraph example — and compile it:
+Write a prose workflow as a `.md` or `.txt` file —
+[`demo/workflow.txt`](demo/workflow.txt) is a complete one-paragraph
+example — and compile it from any directory:
 
 ```bash
 slc playbook my-workflow.md
 ```
 
-`slc` finds the `playbook` pipeline inside its own `@sublang/playbook`
-dependency, so it compiles in any directory — no clone, no project
-setup. Compilation drives your configured coding agent — the first run
-seeds `~/.config/slc/config.yaml` with `agent: claude-code`; set
-`SLC_AGENT` (or edit that file) to use another agent CLI. Expect it to
-take a while: duration is agent- and workload-dependent, and measured
-compiles of a five-line workflow have run from tens of minutes to more
-than two hours, with the first intermediate typically landing within
-about five minutes. Plain-text input (`.txt`) works too; it is
-normalized first. The pipeline's optimization pass, which rewrites
-judgment-free steps into plain script, runs by default
-(`--no-optimize` skips it).
-
 Artifacts land in your working directory: `my-workflow.playbook/` holds
 the intermediates — `my-workflow.gears.md`, the XState machine
 `my-workflow.fsm.ts`, the linked runtime module, and its verification
@@ -116,105 +99,91 @@ tests — and `my-workflow.ts` is the runnable entry. Run it:
 playbook run ./my-workflow.ts "<your task>"
 ```
 
-Intermediates are first-class: edit one and re-run a single phase
-(`slc playbook.gears2fsm …`) and it lands in the same place.
-`slc --help` shows all invocation forms.
+Compilation drives your configured coding agent, so **expect it to take
+a while**: measured compiles of a five-line workflow have run from tens
+of minutes to more than two hours, with the first intermediate typically
+landing within about five minutes. Meanwhile `slc` reports each phase,
+each artifact with its elapsed time, and a heartbeat at least every 30
+seconds on stderr; an agent call that goes silent for `stallTimeout`
+seconds fails that phase instead of hanging. Success prints the artifact
+paths and exits 0; a failure prints diagnostics naming the failing phase
+and exits non-zero.
+
+Intermediates are first-class: edit one, re-run a single phase
+(`slc playbook.gears2fsm …`), and it lands in the same place.
+`slc --help` shows all invocation forms and flags, including
+`--no-optimize` to skip the optimization pass.
 
 ### Incremental recompiles
 
-Canonical full and full-link runs of ordinary pipelines remember successful
-builds under `<artifact-dir>/.slc/`. Each numbered, private snapshot contains
-one manifest plus verbatim copies of the source and every accepted phase
-output. The active marker is committed last. If that build is missing,
-deleted, or corrupt in any part, `slc` treats the whole snapshot as absent and
-compiles ordinarily.
-
-On a re-run, `slc` walks the phases in order and chooses one mode for each:
-
-- **Reuse** when every input is byte-identical and the live target is readable:
-  no agent runs, and the on-disk output stays exactly as it is, including manual
-  refinements.
-- **Update** when a compile phase's inputs changed and its prior input and live
-  output are available: the ordinary executor also receives the recorded old
-  input, a bounded best-effort diff, and one instruction to update the complete
-  artifact while preserving unaffected work.
-- **Ordinary** when no usable record exists, for a changed link phase, or when
-  `--rebuild` is given.
-
-Update is only a hint to the usual executor. The phase definition remains the
-sole authority, needs no update section, and uses the same acceptance rules as
-a fresh compile. A run that only reuses reports `up to date` and records
-nothing new. Before the first executor in an eligible run may write, `slc`
-removes the active marker; only a wholly successful run, including required
-deterministic post-processing, publishes a new marker. Once the marker is
-removed, a failed or interrupted run therefore leaves the next run to compile
-ordinarily. `--rebuild` forces every phase through Ordinary mode and records a
-fresh successful build while retaining older numbered snapshots.
-
-History selection and publication do not apply to `-o`, the reserved `slc`
-meta-pipeline, single-phase or standalone-pass runs, or direct-link runs. If one
-of those excluded forms is about to overwrite an artifact named by a usable
-active build, `slc` clears that marker first so it cannot describe the new
-bytes.
-
-`.slc/` sits inside the artifact bundle and holds verbatim copies of your
-source and every accepted phase output, so treat it as no less private than
-the source, and add `.slc/` to your `.gitignore` if you commit the bundle.
-Deleting it is always safe — the next run simply compiles ordinarily — and
-old numbered builds under `.slc/builds/` can be pruned at any time. An upgrade
-that changes a recorded definition or input invalidates only the affected
-steps: an eligible compile step can use Update while link steps run ordinarily.
-Pass `--rebuild` after an upgrade when you want every phase to compile from
-scratch instead.
-
-While a compile runs, `slc` reports progress on stderr: each phase as it
-starts, each artifact as it lands with the elapsed time, the compiled
-runtime's own state transitions, and a heartbeat so the terminal is
-never silent for more than 30 seconds. An agent call that goes quiet for
-`stallTimeout` seconds (default 600, `0` disables) is aborted and
-reported as a failed phase rather than hanging indefinitely.
-
-Success prints the written artifact paths to stdout and exits 0 — or
-just `up to date` when incremental selection recompiled nothing, in which
-case the paths the previous run reported are still current; a failure
-prints diagnostics to stderr — naming the failing phase when one is at
-fault — and exits non-zero.
+A successful full compile is snapshotted under `<artifact-dir>/.slc/`,
+so a re-run only redoes what changed. Per phase, `slc` picks:
+
+- **Reuse** — inputs are byte-identical: no agent call, and the artifact
+  on disk is left exactly as it is, manual refinements included.
+- **Update** — inputs changed: the phase runs ordinarily and also
+  receives its prior input and a diff, as a hint to update the artifact
+  rather than rewrite it from scratch.
+- **Ordinary** — no usable record, a changed link phase, or `--rebuild`.
+
+A run that reuses everything prints `up to date` instead of paths.
+History is success-only, so an interrupted or failed run simply leaves
+the next one to compile ordinarily. `.slc/` holds verbatim copies of
+your source and outputs — treat it as no less private, gitignore it if
+you commit the bundle, and delete it freely. Excluded invocation forms
+and the full rules are in the
+[incremental spec](specs/packages/incremental-compilation.md).
 
 ## Configuration
 
-`slc` reads its agent and pipeline settings from an optional YAML config file,
-overridden per key by environment variables. A blank or unset environment value
-falls through to the file. When no config file exists anywhere, the first run
-seeds `~/.config/slc/config.yaml` with `agent: claude-code`, so a fresh
-machine needs no setup; `model` falls through to the agent CLI's own default
-and `pipelinePath` to the working directory.
+The first run seeds `~/.config/slc/config.yaml` with
+`agent: claude-code`, so a fresh machine needs no setup. A
+`slc.config.yaml` in the working directory wins over the user config,
+and `SLC_AGENT`, `SLC_MODEL`, and the other `SLC_*` variables override
+either, per key.
 
 ```yaml
 # slc.config.yaml
 agent: claude-code # claude-code | codex | gemini | opencode
 model: claude-opus-4-8 # optional; omit to use the agent CLI's default
+effort: high # optional adapter-scoped reasoning effort
+reviewerAgent: codex # optional; enables reviewed compilation
+reviewerModel: gpt-5.3-codex # optional reviewer model
+reviewerEffort: xhigh # optional reviewer reasoning effort
 stallTimeout: 600 # seconds of agent silence before a stalled call fails
 pipelinePath: # search roots for <pipeline> references; defaults to the cwd
   - ./pipelines
 ```
 
-A `slc.config.yaml` in the working directory wins over the user config;
-`SLC_AGENT`, `SLC_MODEL`, `SLC_STALL_TIMEOUT`, and `SLC_PIPELINE_PATH`
-override either per key. Discovery order, `--config`, and validation
-rules live in the [CLI spec](specs/user/cli.md); `slc --help` prints the
-summary.
+Discovery order, `--config`, and validation rules live in the
+[CLI spec](specs/packages/cli.md); `slc --help` prints the summary.
+
+### Reviewed compilation (two agents)
+
+Set `reviewerAgent` to compile with two independent agents. Your `agent`
+selection is the Coder that writes each artifact; the Reviewer then
+inspects that work read-only and reports only material correctness or
+spec defects, and the Coder answers every finding with evidence and a
+minimal fix. Up to three review rounds — if the third still reports
+findings, the phase fails closed and names them rather than shipping a
+questionable artifact.
+
+It costs at least one extra agent call per transformation that runs.
+Reuse performs no transformation and so makes no calls; Update,
+Ordinary, and `--rebuild` use the loop automatically
+([DR-022](specs/decisions/022-two-agent-reviewed-compilation.md)).
 
 ## How pipelines work
 
 A pipeline is a directory of phase definitions named
 `<source-format>2<target-format>.md`, each declaring its formats in a
-`## Formats` table, plus an optional `link.md` defining the terminal
-link phase. `slc` infers phase order by chaining formats — no
-manifest — and refuses incomplete, branching, or cyclic chains. Adding
-a phase means writing a definition, never changing the compiler: `slc`
-itself performs only the generic mechanics of chaining, validation, and
-artifact placement. The bundled `playbook` pipeline chains `text2gears`
-and `gears2fsm`, with `link` emitting the runnable runtime.
+`## Formats` table, plus an optional `link.md` for the terminal link
+phase. `slc` infers phase order by chaining formats — no manifest — and
+refuses incomplete, branching, or cyclic chains. Adding a phase means
+writing a definition, never changing the compiler: `slc` itself performs
+only the generic mechanics of chaining, validation, and artifact
+placement. The bundled `playbook` pipeline chains `text2gears` and
+`gears2fsm`, with `link` emitting the runnable runtime.
 
 Every phase runs through a coding agent, one of two ways:
 
@@ -222,11 +191,11 @@ Every phase runs through a coding agent, one of two ways:
   performs it. This is how an npm-installed `slc` runs the `playbook`
   pipeline, using the definitions shipped inside `@sublang/playbook`.
 - **Compiled** — the phase's own compiled playbook artifact drives the
-  agent through audited state-machine steps. This repository's checkout
-  runs its bundled phases this way: `slc` is self-hosting, its phase
-  definitions compiled, reviewed, and sha256-pinned under
+  agent through audited state-machine steps. This repository runs its
+  bundled phases this way: `slc` is self-hosting, its phase definitions
+  compiled, reviewed, and sha256-pinned under
   [`pipelines/playbook/`](pipelines/playbook), failing closed on drift
-  ([self-hosting spec](specs/user/self-hosting.md)).
+  ([self-hosting spec](specs/packages/self-hosting.md)).
 
 Specs are the source of truth — start at the
 [spec map](specs/map.md).

package/dist/app.d.ts

@@ -11,11 +11,11 @@ export type DepsBuilder = (io: {
     env: Record<string, string | undefined>;
     cwd: string;
     signal: AbortSignal;
-    /** Explicit `--config <path>`, when given (CLI-20). */
+    /** Explicit `--config <path>`, when given (cli-20). */
     configPath?: string;
-    /** Sink for host notes such as first-run config seeding (DR-015, CLI-30). */
+    /** Sink for host notes such as first-run config seeding (DR-015, cli-30). */
     note?: (text: string) => void;
-    /** The run's progress sink, rendered to stderr by the bin (DR-019, CLI-35). */
+    /** The run's progress sink, rendered to stderr by the bin (DR-019, cli-35). */
     progress?: ProgressSink;
 }) => SlcDeps | Promise<SlcDeps>;
 /** Injectable IO and configuration for {@link run}; all fields default to the process. */
@@ -24,9 +24,9 @@ export interface RunOptions {
     cwd?: string;
     stdout?: (text: string) => void;
     stderr?: (text: string) => void;
-    /** Cancellation signal passed into `runSlc` (CLI-10). */
+    /** Cancellation signal passed into `runSlc` (cli-10). */
     signal?: AbortSignal;
-    /** Overrides production dependency construction (CLI-6, CLI-7). */
+    /** Overrides production dependency construction (cli-6, cli-7). */
     buildDeps?: DepsBuilder;
 }
 /** The executor factory {@link buildSlcDeps} uses; injected in tests. */
@@ -35,19 +35,19 @@ export type ExecutorFactory = typeof createConfiguredExecutor;
 export type CompiledFactoryBuilder = typeof createConfiguredCompiledFactory;
 /**
  * Builds the production {@link SlcDeps}: a pipeline resolver over the resolved
- * search roots (CLI-6) — with the reserved `slc` reference routed to the
- * meta-pipeline definitions `@sublang/playbook` provides (SELFHOST-2) — an
- * interpreted executor for the resolved agent/model (CLI-7), and the
- * compiled-execution factory a current pinned phase selects (CLI-8, PHEXEC-27).
- * Configuration is loaded from the config file (DR-006, CLI-20) and
+ * search roots (cli-6) — with the reserved `slc` reference routed to the
+ * meta-pipeline definitions `@sublang/playbook` provides (self-hosting-2) — an
+ * interpreted executor for the resolved agent/model (cli-7), and the
+ * compiled-execution factory a current pinned phase selects (cli-8, phase-execution-27).
+ * Configuration is loaded from the config file (DR-006, cli-20) and
  * then overridden per key by a non-blank environment variable, so existing
  * env-only runs are unchanged and the file fills any key the environment leaves
  * unset.
  *
  * @throws {import('./config-file.js').ConfigFileError} when an explicit
- *   `--config` path is absent or the file is malformed or invalid (CLI-21).
+ *   `--config` path is absent or the file is malformed or invalid (cli-21).
  * @throws {import('./config.js').ConfigError} when neither source supplies an
- *   agent, or the resolved agent is unsupported (CLI-12).
+ *   agent, or the resolved agent is unsupported (cli-12).
  */
 export declare function buildSlcDeps({ env, cwd, signal, configPath, note, progress }: Parameters<DepsBuilder>[0], createExecutor?: ExecutorFactory, createCompiled?: CompiledFactoryBuilder): Promise<SlcDeps>;
 /** The cligent-invocation selection after merging environment over file (DR-006). */
@@ -55,34 +55,34 @@ export interface RunConfig {
     selection: AgentSelection;
     /** Search-root source: an `SLC_PIPELINE_PATH` string, the file's sequence, or undefined. */
     pipelinePath: string | string[] | undefined;
-    /** Agent-stall watchdog window in milliseconds; `0` disables (DR-019, CLI-34). */
+    /** Agent-stall watchdog window in milliseconds; `0` disables (DR-019, cli-34). */
     stallTimeoutMs: number;
 }
-/** Default agent-stall watchdog window in seconds (DR-019, CLI-34). */
+/** Default agent-stall watchdog window in seconds (DR-019, cli-34). */
 export declare const DEFAULT_STALL_TIMEOUT_SECONDS = 600;
 /**
- * Merges the environment over config-file values per key (DR-006, CLI-20): for
+ * Merges the environment over config-file values per key (DR-006, cli-20): for
  * each key a non-blank environment variable wins, otherwise the file value,
  * otherwise the built-in default. The agent and model go through
  * {@link resolveAgentSelection} so the supported-agent check stays single-sourced
- * (CLI-7, CLI-12); the stall timeout defaults to
+ * (cli-7, cli-12); the stall timeout defaults to
  * {@link DEFAULT_STALL_TIMEOUT_SECONDS} with `0` disabling the watchdog
- * (DR-019, CLI-34).
+ * (DR-019, cli-34).
  *
  * @throws {Error} when `SLC_STALL_TIMEOUT` is not a non-negative number.
  */
 export declare function resolveRunConfig(env: Record<string, string | undefined>, file: FileConfig): RunConfig;
-/** Usage text naming the documented invocation forms and configuration (CLI-2). */
+/** Usage text naming the documented invocation forms and configuration (cli-2). */
 export declare function usageText(): string;
 /**
- * Runs the `slc` command line and returns a process exit code (CLI package).
+ * Runs the `slc` command line and returns a process exit code (`cli` package).
  * Never rejects: configuration refusals and run failures are reported and
  * mapped to a non-zero code.
  */
 export declare function run(argv: readonly string[], options?: RunOptions): Promise<number>;
 /**
  * Wires `SIGINT`/`SIGTERM` on `emitter` to abort a fresh controller, returning
- * its cancellation signal and a disposer that removes the listeners (CLI-10).
+ * its cancellation signal and a disposer that removes the listeners (cli-10).
  * The `cli.ts` shim passes `process`; tests pass a fake emitter so the
  * interrupt-to-abort wiring is exercised without real signals.
  */

package/dist/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"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"}

package/dist/app.js

@@ -1,17 +1,17 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 /**
- * The `slc` bin orchestrator (CLI package).
+ * The `slc` bin orchestrator (`cli` package).
  *
  * `run` is the testable command-line entry: it short-circuits `--version` and
- * `--help` before touching any pipeline or agent (CLI-1, CLI-2, CLI-9), builds
- * the run dependencies from environment configuration (CLI-6, CLI-7, CLI-12),
- * invokes the injectable `runSlc` core under a cancellation signal (CLI-10), and
+ * `--help` before touching any pipeline or agent (cli-1, cli-2, cli-9), builds
+ * the run dependencies from environment configuration (cli-6, cli-7, cli-12),
+ * invokes the injectable `runSlc` core under a cancellation signal (cli-10), and
  * maps the result onto process streams and an exit code — produced artifact
- * paths to stdout on success, the failure report to stderr otherwise (CLI-3,
- * CLI-4, CLI-11). Every IO seam is injectable so the bin is integration-testable
+ * paths to stdout on success, the failure report to stderr otherwise (cli-3,
+ * cli-4, cli-11). Every IO seam is injectable so the bin is integration-testable
  * without a real agent; the `cli.ts` shim supplies the process-backed defaults
- * and signal wiring. See specs/dev/cli.md and specs/user/cli.md.
+ * and signal wiring. See specs/packages/cli.md.
  */
 import { createRequire } from 'node:module';
 import { messageOf } from './errors.js';
@@ -33,19 +33,19 @@ export function version() {
 }
 /**
  * Builds the production {@link SlcDeps}: a pipeline resolver over the resolved
- * search roots (CLI-6) — with the reserved `slc` reference routed to the
- * meta-pipeline definitions `@sublang/playbook` provides (SELFHOST-2) — an
- * interpreted executor for the resolved agent/model (CLI-7), and the
- * compiled-execution factory a current pinned phase selects (CLI-8, PHEXEC-27).
- * Configuration is loaded from the config file (DR-006, CLI-20) and
+ * search roots (cli-6) — with the reserved `slc` reference routed to the
+ * meta-pipeline definitions `@sublang/playbook` provides (self-hosting-2) — an
+ * interpreted executor for the resolved agent/model (cli-7), and the
+ * compiled-execution factory a current pinned phase selects (cli-8, phase-execution-27).
+ * Configuration is loaded from the config file (DR-006, cli-20) and
  * then overridden per key by a non-blank environment variable, so existing
  * env-only runs are unchanged and the file fills any key the environment leaves
  * unset.
  *
  * @throws {import('./config-file.js').ConfigFileError} when an explicit
- *   `--config` path is absent or the file is malformed or invalid (CLI-21).
+ *   `--config` path is absent or the file is malformed or invalid (cli-21).
  * @throws {import('./config.js').ConfigError} when neither source supplies an
- *   agent, or the resolved agent is unsupported (CLI-12).
+ *   agent, or the resolved agent is unsupported (cli-12).
  */
 export async function buildSlcDeps({ env, cwd, signal, configPath, note, progress }, 
 // Injectable so a test can capture the executor options — notably the
@@ -65,7 +65,7 @@ createExecutor = createConfiguredExecutor, createCompiled = createConfiguredComp
     // Auto-accept the agents' file operations so a non-interactive `slc` run can
     // write its target artifact; the DR-003 generic checks still guard the
     // protected inputs (DR-004). The stall watchdog rides every constructed
-    // transport (DR-019, CLI-35).
+    // transport (DR-019, cli-35).
     const agentOpts = {
         cwd,
         permissions: { mode: 'auto' },
@@ -73,7 +73,7 @@ createExecutor = createConfiguredExecutor, createCompiled = createConfiguredComp
     };
     const executor = createExecutor(selection, agentOpts);
     // Compiled-runtime status streams to the same reporter as phase progress
-    // (PHEXEC-25, CLI-32).
+    // (phase-execution-25, cli-32).
     const compiled = createCompiled(selection, {
         ...agentOpts,
         onStatus: progress === undefined
@@ -82,16 +82,16 @@ createExecutor = createConfiguredExecutor, createCompiled = createConfiguredComp
     });
     return { resolver, executor, compiled, cwd, signal, progress };
 }
-/** Default agent-stall watchdog window in seconds (DR-019, CLI-34). */
+/** Default agent-stall watchdog window in seconds (DR-019, cli-34). */
 export const DEFAULT_STALL_TIMEOUT_SECONDS = 600;
 /**
- * Merges the environment over config-file values per key (DR-006, CLI-20): for
+ * Merges the environment over config-file values per key (DR-006, cli-20): for
  * each key a non-blank environment variable wins, otherwise the file value,
  * otherwise the built-in default. The agent and model go through
  * {@link resolveAgentSelection} so the supported-agent check stays single-sourced
- * (CLI-7, CLI-12); the stall timeout defaults to
+ * (cli-7, cli-12); the stall timeout defaults to
  * {@link DEFAULT_STALL_TIMEOUT_SECONDS} with `0` disabling the watchdog
- * (DR-019, CLI-34).
+ * (DR-019, cli-34).
  *
  * @throws {Error} when `SLC_STALL_TIMEOUT` is not a non-negative number.
  */
@@ -100,6 +100,9 @@ export function resolveRunConfig(env, file) {
         SLC_AGENT: nonBlank(env.SLC_AGENT) ?? file.agent,
         SLC_MODEL: nonBlank(env.SLC_MODEL) ?? file.model,
         SLC_EFFORT: nonBlank(env.SLC_EFFORT) ?? file.effort,
+        SLC_REVIEWER_AGENT: nonBlank(env.SLC_REVIEWER_AGENT) ?? file.reviewerAgent,
+        SLC_REVIEWER_MODEL: nonBlank(env.SLC_REVIEWER_MODEL) ?? file.reviewerModel,
+        SLC_REVIEWER_EFFORT: nonBlank(env.SLC_REVIEWER_EFFORT) ?? file.reviewerEffort,
     });
     const pipelinePath = nonBlank(env.SLC_PIPELINE_PATH) ?? file.pipelinePath;
     const stallSeconds = parseStallTimeout(nonBlank(env.SLC_STALL_TIMEOUT)) ??
@@ -125,7 +128,7 @@ function parseStallTimeout(value) {
 function nonBlank(value) {
     return value !== undefined && value.trim() !== '' ? value : undefined;
 }
-/** Usage text naming the documented invocation forms and configuration (CLI-2). */
+/** Usage text naming the documented invocation forms and configuration (cli-2). */
 export function usageText() {
     return [
         'Usage:',
@@ -155,11 +158,15 @@ export function usageText() {
         '  environment variable below:',
         '    ./slc.config.yaml',
         '    ${XDG_CONFIG_HOME:-~/.config}/slc/config.yaml',
-        '  Keys: agent, model, effort, pipelinePath, stallTimeout.',
+        '  Keys: agent, model, effort, reviewerAgent, reviewerModel,',
+        '        reviewerEffort, pipelinePath, stallTimeout.',
         '',
         '  SLC_AGENT          agent CLI: claude-code | codex | gemini | opencode',
         '  SLC_MODEL          optional model for the agent CLI',
         '  SLC_EFFORT         optional adapter-scoped reasoning effort (e.g. xhigh)',
+        '  SLC_REVIEWER_AGENT optional independent reviewer; enables reviewed compilation',
+        '  SLC_REVIEWER_MODEL optional model for the reviewer agent CLI',
+        '  SLC_REVIEWER_EFFORT optional adapter-scoped reviewer reasoning effort',
         '  SLC_PIPELINE_PATH  search roots for <pipeline> references (default: cwd)',
         '  SLC_STALL_TIMEOUT  seconds of agent inactivity before a stalled call',
         '                     fails the run (default: 600; 0 disables)',
@@ -168,7 +175,7 @@ export function usageText() {
 }
 /**
  * Splits `--config <path>` out of argv, returning the path and the remaining
- * arguments for `runSlc` (CLI-20). `--config` is a bin-level flag, so it is
+ * arguments for `runSlc` (cli-20). `--config` is a bin-level flag, so it is
  * removed before the grammar parser, which rejects unknown options.
  *
  * @throws {Error} when `--config` is given without a following value.
@@ -191,14 +198,14 @@ function extractConfigFlag(argv) {
     return { configPath, rest };
 }
 /**
- * Runs the `slc` command line and returns a process exit code (CLI package).
+ * Runs the `slc` command line and returns a process exit code (`cli` package).
  * Never rejects: configuration refusals and run failures are reported and
  * mapped to a non-zero code.
  */
 export async function run(argv, options = {}) {
     const stdout = options.stdout ?? ((text) => void process.stdout.write(text));
     const stderr = options.stderr ?? ((text) => void process.stderr.write(text));
-    // Conveniences short-circuit before any pipeline or agent work (CLI-1, CLI-2, CLI-9).
+    // Conveniences short-circuit before any pipeline or agent work (cli-1, cli-2, cli-9).
     if (hasFlag(argv, '--version', '-v')) {
         stdout(`${name} ${version()}\n`);
         return 0;
@@ -211,13 +218,13 @@ export async function run(argv, options = {}) {
     const cwd = options.cwd ?? process.cwd();
     const signal = options.signal ?? new AbortController().signal;
     // In-run progress renders on stderr as it happens, with the silence-bounded
-    // heartbeat (DR-019, CLI-32, CLI-33, CLI-35).
+    // heartbeat (DR-019, cli-32, cli-33, cli-35).
     const reporter = createProgressReporter(stderr);
     let deps;
     let rest;
     try {
         // `--config <path>` is a bin-level flag: strip it before runSlc, whose
-        // grammar (parseInvocation) rejects unknown options (CLI-20).
+        // grammar (parseInvocation) rejects unknown options (cli-20).
         const extracted = extractConfigFlag(argv);
         rest = extracted.rest;
         deps = await (options.buildDeps ?? buildSlcDeps)({
@@ -231,7 +238,7 @@ export async function run(argv, options = {}) {
     }
     catch (error) {
         // Configuration refusals — a bad `--config`, an invalid config file
-        // (CLI-21), or an unset/unsupported agent (CLI-12) — fail the run.
+        // (cli-21), or an unset/unsupported agent (cli-12) — fail the run.
         reporter.dispose();
         stderr(`${name}: ${messageOf(error)}\n`);
         return 1;
@@ -248,7 +255,7 @@ export async function run(argv, options = {}) {
             stdout('up to date\n');
         else if (result.outputs.length > 0)
             stdout(`${result.outputs.join('\n')}\n`);
-        // Surface any ambiguity the agent resolved without polluting the path output.
+        // Surface benign ambiguity resolved during the run without polluting paths.
         if (result.diagnostics.length > 0)
             stderr(`${result.diagnostics.join('\n')}\n`);
         return 0;
@@ -259,7 +266,7 @@ export async function run(argv, options = {}) {
 }
 /**
  * Wires `SIGINT`/`SIGTERM` on `emitter` to abort a fresh controller, returning
- * its cancellation signal and a disposer that removes the listeners (CLI-10).
+ * its cancellation signal and a disposer that removes the listeners (cli-10).
  * The `cli.ts` shim passes `process`; tests pass a fake emitter so the
  * interrupt-to-abort wiring is exercised without real signals.
  */