orchestrator-workflow 0.41.0 → 0.43.1

package/dist/routing.d.ts

@@ -4,11 +4,13 @@ export interface ModelSelection {
     model: string;
     effort: Tier;
 }
+export type CodexModelAlias = "small" | "balanced" | "strong";
 /**
  * A sparse harness-specific model-routing patch. Later layers supplied to
  * mergeRouting replace a selection leaf while preserving unrelated entries.
  */
 export type HarnessRouting = Partial<Record<Harness, Partial<Record<Role, Partial<Record<Tier, ModelSelection>>>>>>;
+export declare function parseCodexModels(value: unknown): Partial<Record<CodexModelAlias, string>>;
 /**
  * Parses one strict, sparse routing layer. It deliberately never drops
  * unrecognised data: a typo in a harness, role, tier, or selection is an
@@ -17,80 +19,44 @@ export type HarnessRouting = Partial<Record<Harness, Partial<Record<Role, Partia
 export declare function parseRouting(value: unknown): HarnessRouting;
 /** Deeply merges sparse routing layers without mutating any input layer. */
 export declare function mergeRouting(...layers: (HarnessRouting | undefined)[]): HarnessRouting;
-declare const CODEX_DEFAULTS: {
+declare const CODEX_DEFAULT_ALIASES: {
     explorer: {
-        low: {
-            model: string;
-            effort: "low";
-        };
-        medium: {
-            model: string;
-            effort: "medium";
-        };
-        high: {
-            model: string;
-            effort: "high";
-        };
+        low: "small";
+        medium: "balanced";
+        high: "balanced";
     };
     "task-slicer": {
-        low: {
-            model: string;
-            effort: "low";
-        };
-        medium: {
-            model: string;
-            effort: "medium";
-        };
-        high: {
-            model: string;
-            effort: "high";
-        };
+        low: "balanced";
+        medium: "balanced";
+        high: "balanced";
     };
     implementer: {
-        low: {
-            model: string;
-            effort: "low";
-        };
-        medium: {
-            model: string;
-            effort: "medium";
-        };
-        high: {
-            model: string;
-            effort: "high";
-        };
-        xhigh: {
-            model: string;
-            effort: "xhigh";
-        };
+        low: "small";
+        medium: "balanced";
+        high: "balanced";
+        xhigh: "strong";
     };
     reviewer: {
-        medium: {
-            model: string;
-            effort: "medium";
-        };
-        high: {
-            model: string;
-            effort: "high";
-        };
-        xhigh: {
-            model: string;
-            effort: "xhigh";
-        };
+        medium: "balanced";
+        high: "strong";
+        xhigh: "strong";
     };
     advisor: {
-        high: {
-            model: string;
-            effort: "high";
-        };
-        xhigh: {
-            model: string;
-            effort: "xhigh";
-        };
+        high: "strong";
+        xhigh: "strong";
     };
 };
+export declare function codexModelsRoutingPatch(value: unknown): HarnessRouting;
+type CodexDefaultRoleRouting<AliasRouting extends Partial<Record<Tier, CodexModelAlias>>> = {
+    [TierName in keyof AliasRouting]: TierName extends Tier ? {
+        model: string;
+        effort: TierName;
+    } : never;
+};
 export type CodexDefaultRouting = HarnessRouting & {
-    codex: typeof CODEX_DEFAULTS;
+    codex: {
+        [RoleName in Role]: CodexDefaultRoleRouting<(typeof CODEX_DEFAULT_ALIASES)[RoleName]>;
+    };
 };
 /** Returns a fresh complete Codex routing layer, including each default tier. */
 export declare function defaultCodexRouting(): CodexDefaultRouting;

package/dist/routing.js

@@ -1,5 +1,11 @@
 import { HARNESSES } from "./detect.js";
+import { readAsset } from "./assets.js";
 import { ROLE_TIERS, ROLES } from "./models.js";
+const CODEX_MODEL_ALIASES = [
+    "small",
+    "balanced",
+    "strong",
+];
 const TIERS = ["low", "medium", "high", "xhigh"];
 const DANGEROUS_KEYS = new Set(["__proto__", "prototype", "constructor"]);
 const CLAUDE_ALIASES = new Set(["sonnet", "opus", "haiku"]);
@@ -58,6 +64,50 @@ function assertModelId(model, harness, location) {
     }
     return model;
 }
+function assertConcreteCodexModelId(model, location) {
+    const value = assertModelId(model, "codex", location);
+    if (CODEX_MODEL_ALIASES.includes(value)) {
+        throw new Error(`${location}.model must not use an internal Codex alias`);
+    }
+    return value;
+}
+function loadBundledCodexModels() {
+    let value;
+    try {
+        value = JSON.parse(readAsset("codex-models.json"));
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read bundled Codex model aliases: ${reason}`);
+    }
+    if (!isRecord(value)) {
+        throw new Error("Bundled Codex model aliases must be an object");
+    }
+    assertSafeKeys(value, "bundled Codex model aliases");
+    const result = {};
+    for (const alias of CODEX_MODEL_ALIASES) {
+        if (!(alias in value)) {
+            throw new Error(`Bundled Codex model aliases must contain "${alias}"`);
+        }
+        result[alias] = assertConcreteCodexModelId(value[alias], `bundled Codex model alias "${alias}"`);
+    }
+    for (const key of Object.keys(value)) {
+        assertKnownKey(key, CODEX_MODEL_ALIASES, "bundled Codex model alias");
+    }
+    return result;
+}
+export function parseCodexModels(value) {
+    if (!isRecord(value)) {
+        throw new Error("Codex model aliases must be an object");
+    }
+    assertSafeKeys(value, "Codex model aliases");
+    const result = {};
+    for (const [alias, model] of Object.entries(value)) {
+        assertKnownKey(alias, CODEX_MODEL_ALIASES, "Codex model alias");
+        result[alias] = assertConcreteCodexModelId(model, `Codex model alias "${alias}"`);
+    }
+    return result;
+}
 function parseSelection(value, harness, location) {
     if (!isRecord(value)) {
         throw new Error(`${location} must be a selection object`);
@@ -144,36 +194,55 @@ export function mergeRouting(...layers) {
     }
     return result;
 }
-const CODEX_DEFAULTS = {
+const CODEX_DEFAULT_ALIASES = {
     explorer: {
-        low: { model: "gpt-5.6-luna", effort: "low" },
-        medium: { model: "gpt-5.6-sol", effort: "medium" },
-        high: { model: "gpt-5.6-sol", effort: "high" },
+        low: "small",
+        medium: "balanced",
+        high: "balanced",
     },
     "task-slicer": {
-        low: { model: "gpt-5.6-luna", effort: "low" },
-        medium: { model: "gpt-5.6-sol", effort: "medium" },
-        high: { model: "gpt-5.6-sol", effort: "high" },
+        low: "balanced",
+        medium: "balanced",
+        high: "balanced",
     },
     implementer: {
-        low: { model: "gpt-5.6-luna", effort: "low" },
-        medium: { model: "gpt-5.6-terra", effort: "medium" },
-        high: { model: "gpt-5.6-terra", effort: "high" },
-        xhigh: { model: "gpt-6-astra", effort: "xhigh" },
+        low: "small",
+        medium: "balanced",
+        high: "balanced",
+        xhigh: "strong",
     },
     reviewer: {
-        medium: { model: "gpt-5.6-terra", effort: "medium" },
-        high: { model: "gpt-6-astra", effort: "high" },
-        xhigh: { model: "gpt-6-astra", effort: "xhigh" },
+        medium: "balanced",
+        high: "strong",
+        xhigh: "strong",
     },
     advisor: {
-        high: { model: "gpt-6-astra", effort: "high" },
-        xhigh: { model: "gpt-6-astra", effort: "xhigh" },
+        high: "strong",
+        xhigh: "strong",
     },
 };
+function codexRoutingForAliases(models) {
+    const routing = { codex: {} };
+    for (const role of ROLES) {
+        for (const tier of ROLE_TIERS[role]) {
+            const alias = CODEX_DEFAULT_ALIASES[role][tier];
+            if (alias === undefined)
+                continue;
+            const model = models[alias];
+            if (model === undefined)
+                continue;
+            routing.codex[role] ??= {};
+            routing.codex[role][tier] = { model, effort: tier };
+        }
+    }
+    return routing;
+}
+export function codexModelsRoutingPatch(value) {
+    return codexRoutingForAliases(parseCodexModels(value));
+}
 /** Returns a fresh complete Codex routing layer, including each default tier. */
 export function defaultCodexRouting() {
-    return mergeRouting({ codex: CODEX_DEFAULTS });
+    return codexRoutingForAliases(loadBundledCodexModels());
 }
 function normalizeCodexCatalog(catalog) {
     const modelsValue = Array.isArray(catalog)

package/docs/architecture.md

@@ -0,0 +1,44 @@
+# Architecture: why this shape
+
+The orchestrator/subagent loop `orchestrator-workflow` installs, and the
+reasoning behind it. See the [package README](../README.md) for installation
+and day-to-day usage.
+
+```text
+                 Operator
+             goal |    ^ handoff: what changed, how verified,
+                  v    | what remains open
+  explorer  -->  Orchestrator  . . . . .  .ai/runs/<date>-<slug>/
+  optional,      session model             00-goal       04-implementation-summary
+  read-only      plans, validates slices,  01-plan       05-review-findings
+  terrain map    decides acceptance        02-tasks      06-handoff
+                      |                     03-decisions
+     narrow           |    ^ structured     (state lives in files,
+     contracts        v    | YAML evidence   not in chat history)
+        +-------------+-------------+
+        |             |             |
+    task-slicer   implementer   reviewer
+      sonnet        sonnet        opus
+    small,        one narrow    skeptical, severity-rated
+    testable      task, plus    findings, no rewrites
+    slices        tests
+```
+
+Two effects fall out of this shape:
+
+- **Token efficiency.** The orchestrator's context stays small: subagents
+  receive narrow task contracts instead of the whole conversation, return
+  structured YAML evidence instead of transcripts, and durable state lives
+  in run files that survive context compaction. The cheap models do the
+  volume work; the strongest model is spent only on orchestration decisions
+  and the skeptical review. The ceremony scales to the task: a trivial change
+  is done directly, the full flow is for non-trivial work, and a read-only
+  explorer maps the terrain first only when the solution is unclear. When
+  available, the explorer prefers each of a repo's configured knowledge
+  bundles (`knowledge` in `.ai/workflow/manifest.json`; default `docs/okf/`)
+  or a connected semantic code-search tool over hand-mapping terrain with
+  grep.
+- **Quality through structure.** Writing and reviewing are separated by
+  role and model, task slices are validated before any implementation
+  starts, acceptance is decided on evidence (tests executed, findings
+  addressed), and every run leaves an auditable trail in `.ai/runs/`.

package/docs/harnesses.md

@@ -0,0 +1,38 @@
+# Harnesses: installed files and read-only posture
+
+See the [package README](../README.md) for install commands and the rest of
+the CLI surface.
+
+Each installed skill includes the compact `SKILL.md` entrypoint and every
+regular Markdown file from its adjacent `references/` directory. The entrypoint
+routes run-state/harness, contracts, evidence/probes, and review/recovery work
+to those files; references are part of the installed skill, not optional docs.
+
+| Harness | Files | Notes |
+|---|---|---|
+| Claude Code | `.claude/skills/orchestrator-workflow/{SKILL.md,references/*.md}`, `.claude/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md`, `CLAUDE.md` | Claude Code reads `CLAUDE.md`, not `AGENTS.md`; the installer adds an additive `@AGENTS.md` import. Subagent models go into the `model:` frontmatter; the read-only explorer, reviewer, and advisor also get `disallowedTools: Edit, Write, NotebookEdit`. |
+| OpenAI Codex | `.agents/skills/orchestrator-workflow/{SKILL.md,references/*.md}`, `.codex/agents/{explorer,task-slicer,implementer,reviewer,advisor}.toml` | Codex reads `AGENTS.md` natively. Native custom-agent files carry the canonical role instructions plus `model` and `model_reasoning_effort`. Explorer and advisor request a read-only sandbox; reviewer inherits the caller's sandbox so it can run temporary/build checks, while its prompt prohibits source edits. |
+| opencode | `.opencode/skills/orchestrator-workflow/{SKILL.md,references/*.md}`, `.opencode/agents/{explorer,task-slicer,implementer,reviewer,advisor}.md` | opencode reads `AGENTS.md` natively. Subagents get `mode: subagent`; the read-only explorer, reviewer, and advisor also get `permission: edit: deny`. Model resolution is described in [Model routing reference](model-routing-reference.md). |
+
+**Read-only posture, honestly stated.** Claude Code disables file-mutation
+tools for explorer, reviewer, and advisor; opencode denies edits for those
+roles. Codex requests a read-only sandbox for explorer and advisor. Its
+reviewer inherits the caller's sandbox so temporary/build checks remain
+possible, while its prompt prohibits source edits. In inherited or otherwise
+write-enabled sandboxes, shell-level mutation (`git checkout`,
+`git restore`, `git clean`, `git stash`, `git reset`, `sed -i`, redirecting
+output into a file, which the reviewer may do only inside its write boundary below) is guarded by instruction only: the agent prompts forbid
+it explicitly, but the role definition itself does not prevent it. A native
+read-only sandbox can block those writes. This residual has bitten in practice (a
+reviewer ran `git checkout` and discarded uncommitted work), which is why the
+prompts now name the forbidden commands instead of just saying "read-only".
+The reviewer's own write boundary is narrower than "read-only": it may write
+to its own scratchpad (a scratch copy or replay of the repository) and to
+the run directory's `evidence/`, and nowhere else. It never writes into the
+reviewed tree, its index, its refs, or its object store: no `git fetch`, no
+`git merge-tree --write-tree`, no `git update-ref`, no `git gc`, on top of
+the working-tree and index mutations already forbidden above. A write a
+declared check or the probe runner's own isolation leaves behind is expected
+wherever that tool places it, not an exception to this rule.
+Marker- or verdict-style enforcement of the Bash residual (sandboxing,
+PreToolUse hooks) is harness territory and out of this kit's scope.

package/docs/install-reference.md

@@ -0,0 +1,95 @@
+# Install reference
+
+Details behind the install commands in the [package README](../README.md):
+what the agent-led installer's conflict check does, the exact rules for
+`--harness none` (templates-only mode) on a re-run, the optional
+`knowledge` manifest field for a repository whose bundle is not at the
+default location, and the file-ownership rules a re-run follows.
+
+## Agent-led installation: bundle and conflict handling
+
+The compact skill entrypoint and its routed references form one installed
+bundle. On a reinstall, the installer checks the core and every required
+reference for local conflicts before activating a new core; it leaves the
+current coherent bundle intact unless an explicitly authorized `--force` run
+replaces the affected files.
+
+## Templates-only mode (`--harness none`)
+
+`--harness none` (the literal word `none`, on its own) installs only
+`.ai/workflow/**` and `.ai/runs/.gitkeep`: no `AGENTS.md`, no `CLAUDE.md`, no
+harness-specific directory, and a manifest recording `harnesses: []`. Use it
+for a repo that wants the run-state templates and the workflow itself, but no
+per-harness subagent files yet (e.g. no harness has been chosen, or the files
+were dropped by hand). `none` combined with a real harness name
+(`--harness none,claude`) is rejected as ambiguous rather than silently
+picking one. A plain **non-interactive** re-run (no `--harness` flag) after a
+templates-only install stays templates-only, for `init` and `apply` alike,
+even when `apply`'s own operator-defaults name a harness or the target has
+harness files on disk from something else; add a harness back with an
+explicit `--harness <list>` on a later run, the same explicit-flag-wins rule
+`--profile`/`--models`/`--tiers` use, applied to the no-harness case. An
+**interactive** re-run is different: it still prompts, with nothing forced
+pre-selected, instead of silently skipping straight back to templates-only
+without asking; deselect every checkbox to stay templates-only. `init` and
+`apply` both pre-check nothing at all on this prompt, and both still
+annotate what is detected on disk with a " (detected)" label; select a
+harness to install it.
+
+```bash
+npx orchestrator-workflow init --harness none --yes
+```
+
+## The `knowledge` manifest field
+
+`manifest.json` may also carry a `knowledge` list of `{ path, repoRoot }`
+entries, for a repo whose knowledge bundle is not at the default location (a
+workspace-level bundle with sources in a sub-repo, a bundle elsewhere, or
+several bundles). `path` is the bundle directory and `repoRoot` (default
+`"."`) the root of the repository the bundle's sources live in. Each is a
+relative path resolved against the worktree top level on its own (`path` is
+not nested under `repoRoot`), so a workspace bundle for a sub-repo's sources
+reads `{ "path": "kb/app", "repoRoot": "app" }`. Entries are stored
+normalised (`./kb/app/` becomes `kb/app`); an empty or absolute path
+(POSIX, or a Windows form such as `C:/x`), any other path starting with a
+Windows drive letter (the drive-relative `C:x` or `C:..`), a `path` of `.`, a
+path escaping the worktree top level, and any path containing a backslash are
+invalid (use `/` as the separator on every platform). The absolute, drive and
+escape rules apply both as written and to the normalised value that is stored,
+so `./C:x` and `docs/../C:/x` are invalid too. The CLI has no flag for the
+field: edit it in the manifest by hand, and every re-install preserves its
+valid entries (the programmatic `runInit` option `knowledge` writes it and
+refuses an invalid entry). A hand-edited invalid entry is ignored on read
+and reported by `doctor`; a re-install that rewrites the manifest removes it
+from disk and prints a note naming its index and reason. The field carries
+no check argv; the concrete bundle-check command still lives in the
+repository-bound verification set (see the package README's
+"Verification sets" section), so there is one source of argv truth. When
+`knowledge` in `.ai/workflow/manifest.json` is absent or an empty list, the
+default `docs/okf/` applies, today's behaviour. `doctor` prints a
+`knowledge:` detail line (the `knowledgeWarnings` key in `--json`) for a
+configured `path` or `repoRoot` that is not a directory, for each ignored
+invalid
+entry, and when a non-empty list omits an existing default bundle directory.
+These warnings never change the status or the exit code.
+
+## Ownership and re-runs
+
+`init` is idempotent: a second run changes nothing. `apply` installs
+through that same `runInit` path and is subject to the same
+conflict/`--force`/ownership rules; on the repository side it changes
+nothing either, but it refreshes this target's entry in the operator
+manifest on every run. The rules:
+
+- `AGENTS.md` and `CLAUDE.md` belong to you. The installer only appends its
+  fenced section or the import line, and on re-run replaces only the content
+  between its own markers. A broken or duplicated marker fence is reported as
+  a conflict and left alone.
+- Templates, skills, and subagent definitions are kit-owned. The manifest
+  records a hash of each file as installed, so a re-run after a kit upgrade
+  updates files you never touched and reports files you edited as conflicts
+  instead of overwriting them; `--force` overwrites those too.
+- `.ai/workflow/manifest.json` is the kit's state file. It records the applied
+  version, harnesses, role profile, models, the `--tiers` flag, the optional
+  kit-version pin, and file hashes, and is rewritten whenever that state
+  changes; do not edit it by hand.