harness-everything 0.2.2 → 0.3.6

package/fable-mode/execution-guardrails/SKILL.md

@@ -1,87 +1,43 @@
----
-name: execution-guardrails
-description: >
-  Always-on operational guardrails, model-independent. Apply on EVERY task and
-  EVERY model (Opus, Sonnet, Haiku, and any future tier) whether or not
-  fable-mode's staged loop is running. Three rules: (1) verify-before-flag —
-  never raise a warning about a problem that hasn't been confirmed present by a
-  direct check; (2) warning batching — accumulate minor concerns and surface
-  them together at a threshold instead of interrupting piecemeal; (3)
-  find-and-replace safety — word-boundary anchoring on sed/substring edits plus
-  a corruption grep afterward. Trigger whenever a response would flag a
-  problem, raise a warning, or edit files with search-and-replace. These are
-  behavioral contracts with the user, not capability aids — they do not depend
-  on model strength.
----
-
-# Execution Guardrails
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | Any turn about to flag a problem, raise a warning, or perform a search-and-replace file edit — regardless of tier or model, whether `fable-mode`'s staged loop is running or not. |
-| **Expected Output** | Warnings issued only for confirmed (grepped/diffed/run) problems; minor concerns batched and surfaced together at a 3-item threshold instead of one at a time; sed/substring edits anchored on word boundaries with a post-edit corruption grep. |
-| **State Mutations** | None of its own — governs how other file-editing actions in the same turn are performed. |
-| **Enforcement Gate** | An unverified flag (no grep/diff/run backing it) **MUST NOT** be surfaced. Any find-and-replace pass **MUST** be followed by a corruption grep before the result is presented. |
-
-Three rules extracted from fable-mode's operational section so they apply everywhere,
-not only inside the staged loop. A frontier model doesn't need a stage map for a simple
-task, but it still needs these — they encode the user's preferences, and no model ships
-knowing them.
-
-## 1. Verify before flag
-
-Before flagging any problem — verify it actually exists. Grep, diff, run it, or check
-the source directly. Never report a problem that hasn't been confirmed present.
-
-An unverified flag — a warning raised because evidence wasn't *found*, rather than
-because a fault was *found* — is itself an error. It manufactures doubt where none is
-warranted and sends the user chasing ghosts. Absence of evidence is not the finding.
-Confirm, then flag.
-
-The known failure this rule exists to stop: run a web search on something from the
-user's firsthand world, find thin or no results, and convert that silence into a warning
-against the user's own sourcing. Web silence is never grounds for a warning. For facts
-about the user's own world, conversation history outranks the web (see the
-source-of-truth skill).
-
-A capability flag follows the same standard. "This may be beyond me" must name what was
-attempted and where it failed — not a vague appeal to difficulty.
-
-## 2. Warning threshold
-
-Across any run, minor concerns accumulate that aren't worth halting on individually.
-Keep a running count. At the threshold — **default three, tunable if the user sets a
-different number** — stop and surface all of them to the user at once before continuing.
-
-Rationale: three small things pointing the same direction usually mean one real problem
-worth a decision. Below threshold, keep working; a drip of trivial caveats is noise.
-At threshold, batch them — one interruption with full context beats three fragmentary
-ones.
-
-A concern that independently meets the verify-before-flag bar and is material on its own
-does not wait for the threshold. The threshold governs minor concerns only.
-
-## 3. Find-and-replace safety
-
-When editing files with sed (or any substring replace), always anchor on word boundaries
-to avoid corrupting compound words — a bare `edge` replace will mangle `Ledger` into
-garbage. Use `\bword\b`, not bare `word`.
-
-After any sed pass on a file, grep for glued or malformed compound words before
-presenting the result. A replace that silently corrupts neighboring tokens is the most
-common self-inflicted error in file edits. The check is cheap; the silent corruption is
-not.
-
-Preferred order of tools: targeted string-replace on a unique anchor > word-boundary
-sed > bare sed (never). If the string to replace isn't unique in the file, widen the
-anchor until it is — do not replace-all and hope.
-
-## Relationship to fable-mode
-
-fable-mode's staged loop is optional and gated on task size. These guardrails are not
-optional and not gated. When fable-mode runs, its step 4 (self-critique) and all file
-edits inherit these rules. When fable-mode doesn't run, these rules apply anyway. In v3
-the per-model runners route to frontmatter-defined agents (`agents/*.md`) whose system
-prompts carry these rules inline, because spawned agents cannot see this skill.
+---
+name: execution-guardrails
+description: >-
+  Always-on guardrails: verify findings before flagging warnings, batch
+  minor caveats, and anchor search-and-replace edits with post-write checks.
+  Use when raising warnings or performing search-and-replace file edits.
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.5
+---
+
+# Execution Guardrails
+
+**USE FOR**: Raising warnings or flagging problems, search-and-replace/regex file edits, batching minor caveats, reporting capability limits.
+
+| Component | Spec |
+| :--- | :--- |
+| **Trigger / Input** | Turn raising a warning or performing search-and-replace edits. |
+| **Expected Output** | Verified warnings; batched caveats (3-item threshold); corruption-checked edits. |
+| **State Mutations** | None — governs execution quality for file-editing turns. |
+| **Enforcement Gate** | Verify before flagging; validate edits post-write. |
+
+## USE FOR:
+- Raising a warning or flagging a suspected problem
+- Search-and-replace or regex file edits
+- Batching multiple minor caveats during a run
+- Reporting capability limits ("this may be beyond me")
+
+## DO NOT USE FOR:
+- Task planning, staging, or fable-mode's staged loop itself
+- Git history rewriting (see `rewrite-commits`)
+- Skills that never raise warnings or edit files
+
+## Core Rules
+
+1. **Verify before flag** — Confirm a problem exists before reporting it. Never convert absence of evidence into a warning.
+2. **Warning threshold** — Batch minor concerns; surface them together at three (default). Material concerns do not wait.
+3. **Find-and-replace safety** — Prefer structured edit tools over shell `sed`; anchor with unique context or `\bword\b` boundaries; verify file integrity post-edit. Never replace-all blindly.
+
+These rules are always-on, even when `fable-mode`'s staged loop is not running.
+
+Deep dive: references/guardrail-rules.md

package/fable-mode/execution-guardrails/references/guardrail-rules.md

@@ -0,0 +1,56 @@
+# Guardrail Rules — Full Detail
+
+Three rules extracted from fable-mode's operational section so they apply everywhere,
+not only inside the staged loop. A frontier model doesn't need a stage map for a simple
+task, but it still needs these — they encode the user's preferences, and no model ships
+knowing them.
+
+## 1. Verify before flag
+
+Before flagging any problem — verify it actually exists. Grep, diff, run it, or check
+the source directly. Never report a problem that hasn't been confirmed present.
+
+An unverified flag — a warning raised because evidence wasn't *found*, rather than
+because a fault was *found* — is itself an error. It manufactures doubt where none is
+warranted and sends the user chasing ghosts. Absence of evidence is not the finding.
+Confirm, then flag.
+
+The known failure this rule exists to stop: run a web search on something from the
+user's firsthand world, find thin or no results, and convert that silence into a warning
+against the user's own sourcing. Web silence is never grounds for a warning. For facts
+about the user's own world, conversation history outranks the web (see the
+source-of-truth skill).
+
+A capability flag follows the same standard. "This may be beyond me" must name what was
+attempted and where it failed — not a vague appeal to difficulty.
+
+## 2. Warning threshold
+
+Across any run, minor concerns accumulate that aren't worth halting on individually.
+Keep a running count. At the threshold — **default three, tunable if the user sets a
+different number** — stop and surface all of them to the user at once before continuing.
+
+Rationale: three small things pointing the same direction usually mean one real problem
+worth a decision. Below threshold, keep working; a drip of trivial caveats is noise.
+At threshold, batch them — one interruption with full context beats three fragmentary
+ones.
+
+A concern that independently meets the verify-before-flag bar and is material on its own
+does not wait for the threshold. The threshold governs minor concerns only.
+
+## 3. Find-and-replace safety
+
+When editing files via substring or regex replacement:
+- **Prefer IDE/Harness Native Tools**: Use specialized file edit tools (e.g., `replace_string_in_file`) or language-native scripts (Node.js/Python) rather than shell `sed`. Raw `sed` invocations behave inconsistently across platforms (macOS BSD sed vs Linux GNU sed vs Windows lack of native sed) and risk subtle file corruption.
+- **Context Anchoring**: Always anchor replacement strings with unique surrounding code/context or word boundaries (`\bword\b`) to avoid corrupting compound words — a bare `edge` replace will mangle `Ledger` into garbage.
+- **Post-Edit Integrity Check**: After any find-and-replace pass, verify the file structure or syntax (e.g. via linter/compiler or targeted search) before presenting the result.
+
+Preferred order of tools: IDE native structured replace tool (`replace_string_in_file`) with 3+ lines of context > word-boundary anchored script > raw regexreplace (use with caution). If the string to replace isn't unique in the file, widen the surrounding context until it is — NEVER replace-all blindly.
+
+## Relationship to fable-mode
+
+fable-mode's staged loop is optional and gated on task size. These guardrails are not
+optional and not gated. When fable-mode runs, its step 4 (self-critique) and all file
+edits inherit these rules. When fable-mode doesn't run, these rules apply anyway. In v3
+the per-model runners route to frontmatter-defined agents (`agents/*.md`) whose system
+prompts carry these rules inline, because spawned agents cannot see this skill.

package/fable-mode/fable-haiku/SKILL.md

@@ -1,48 +1,36 @@
----
-name: fable-haiku
-description: >
-  Run fable-mode execution discipline on Claude Haiku. Routes the task to the
-  @fable-worker-haiku agent, whose definition carries the staged loop with
-  tightened verification (no bare "unverified" allowed) and an
-  escalate-don't-improvise rule. Trigger when the user explicitly asks for
-  thorough/systematic handling run cheaply or fast ("fable on haiku", "deep work
-  mode but cheap", "stage this on haiku"). For bulk mechanical work. Do NOT use
-  for tasks needing synthesis — benchmark note: at n=1 the skill's effect on
-  Haiku swung both directions (+25 / −17); route quality-critical work to
-  fable-sonnet instead.
----
-
-# Fable Mode — Haiku (v3, agent-routed)
-
-## 📋 Skill Contract
-
-| Component | Specification |
-| :--- | :--- |
-| **Trigger / Input** | User explicitly asks for staged/thorough execution run cheaply or fast on Haiku ("fable on haiku", "stage this on haiku") for bulk mechanical work. |
-| **Expected Output** | Task delegated to the `fable-worker-haiku` agent (or an inline fallback carrying the same rules verbatim), optionally fanned out across multiple concurrent workers, followed by a `fable-verifier` pass before any unsupervised delivery. |
-| **State Mutations** | None directly — spawns/manages Task-tool subagents and whatever file edits they perform. |
-| **Enforcement Gate** | Every worker brief **MUST** name the pass condition explicitly (no benefit of the doubt on verification for Haiku). A worker that escalates "needs synthesis" **MUST** be re-routed to `fable-worker-sonnet`, never retried on Haiku with a louder prompt. |
-
-v3 change: the worker is a real agent definition (`agents/fable-worker-haiku.md`)
-invoked by name. Its system prompt carries the loop, the tightened verification
-rule, and the operational rules; this skill only routes.
-
-If a task has one obvious correct approach and fits in a single pass, skip this
-loop and do it directly.
-
-## How to run it
-
-1. Confirm `fable-worker-haiku` appears in the available agent types. If not,
-   fall back to inline: spawn a general-purpose Haiku agent and pass it the
-   rules verbatim from `agents/fable-worker-haiku.md`.
-2. Spawn **@fable-worker-haiku** via the Task tool (`subagent_type:
-   "fable-worker-haiku"`). Brief it with: the task, the exact output path(s),
-   and the pass condition — name the check explicitly; Haiku gets no benefit of
-   the doubt on verification.
-3. Haiku is cheap: for independent sub-parts, fan out one worker per part and
-   merge. Set a ceiling on concurrent workers.
-4. Follow with **@fable-verifier** (a second Haiku is cheap; fresh eyes can't
-   inherit the worker's blind spots) for anything that will be delivered
-   without human review.
-5. If a worker escalates ("needs synthesis"), re-route that part to
-   fable-worker-sonnet rather than retrying Haiku with a louder prompt.
+---
+name: fable-haiku
+description: "Run staged fable work on Haiku for bulk mechanical tasks with explicit pass conditions, visible fallback handling, and a cold verifier pass."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.5
+---
+
+# Fable Mode — Haiku
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Explicit `fable on haiku` for bulk mechanical or format work. |
+| **Expected Output** | A bounded worker artifact, audit record, and verifier result. |
+| **State Mutations** | Native host TODO tracker or Markdown checklist. |
+| **Enforcement Gate** | Worker pass condition plus `fable-verifier`; unsupported runtime must be visible. |
+
+## USE FOR:
+- File processing, format conversion, boilerplate, and structured extraction
+- Cheap parallel stages with independently verifiable artifacts
+
+## DO NOT USE FOR:
+- Synthesis-heavy or high-stakes architecture decisions
+- Delivery without a named pass condition and verifier result
+
+## Run it
+
+1. Resolve `haiku` through `../scripts/model-selector.js`.
+2. Spawn `fable-worker-haiku` when available; otherwise use an inline fallback only when the audit record says so.
+3. Brief one bounded output path and a named check; workers do not spawn workers.
+4. Route synthesis blockers to Sonnet/Opus and cold-review unsupervised delivery with `fable-verifier`.
+
+Use `../references/model-matrix.md` for the audit fields and fallback policy.

package/fable-mode/fable-haiku/references/routing-notes.md

@@ -0,0 +1,26 @@
+# Fable Haiku — v3 Routing Notes
+
+Details moved from SKILL.md.
+
+## v3 change: agent-routed
+
+The worker is a real agent definition (`../agents/fable-worker-haiku.md`)
+invoked by name. Its system prompt carries the loop, the tightened verification
+rule, and the operational rules; this skill only routes.
+
+## Full run procedure
+
+1. Confirm `fable-worker-haiku` appears in the available agent types. If not,
+   fall back to inline: spawn a general-purpose Haiku agent and pass it the
+   rules verbatim from `../agents/fable-worker-haiku.md`.
+2. Spawn **@fable-worker-haiku** via the Task tool (`subagent_type:
+   "fable-worker-haiku"`). Brief it with: the task, the exact output path(s),
+   and the pass condition — name the check explicitly; Haiku gets no benefit of
+   the doubt on verification.
+3. Haiku is cheap: for independent sub-parts, fan out one worker per part and
+   merge. Set a ceiling on concurrent workers.
+4. Follow with **@fable-verifier** (a second Haiku is cheap; fresh eyes can't
+   inherit the worker's blind spots) for anything that will be delivered
+   without human review.
+5. If a worker escalates ("needs synthesis"), re-route that part to
+   the main Orchestrator model context rather than retrying Haiku with a louder prompt.

package/fable-mode/fable-opus/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: fable-opus
+description: "Run staged fable orchestration on Opus for cross-stage synthesis, high-stakes architecture, and final decisions with named workers, cold verification, and visible fallback handling."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.5
+---
+
+# Fable Mode — Opus
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Explicit `fable on opus` for macro orchestration or high-stakes decisions. |
+| **Expected Output** | A staged orchestration record, worker artifacts, and cold-verifier results. |
+| **State Mutations** | Native host TODO tracker or Markdown checklist; stage contracts remain auditable. |
+| **Enforcement Gate** | `fable-orchestrator`, named worker checks, `fable-verifier`, and visible blocker/escalation status. |
+
+## USE FOR:
+- Cross-stage synthesis, architecture decisions, and final macro-task review
+- Tasks that need the Write-less orchestrator to delegate artifact production
+
+## DO NOT USE FOR:
+- One obvious single-pass task
+- Bulk mechanical work (use `fable-haiku`) or bounded reasoning (use `fable-sonnet`)
+
+## Run it
+
+1. Resolve `opus` through `../scripts/model-selector.js`.
+2. Spawn `fable-orchestrator` when the runtime exposes it; otherwise report the inline fallback explicitly.
+3. The orchestrator owns scope lock, at most two replans, stage contracts, named worker delegation, and escalation; it never produces artifacts itself.
+4. Cold-review high-stakes deliverables with `fable-verifier`; report every unverified stage.
+
+Use `../references/model-matrix.md` for the audit fields and fallback policy.

package/fable-mode/fable-sonnet/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: fable-sonnet
+description: "Run staged fable work on Sonnet for non-trivial implementation, research synthesis, or bounded reasoning with explicit pass conditions and visible fallback handling."
+license: Apache-2.0
+metadata:
+  author: Miya Daniel
+  version: 0.3.5
+---
+
+# Fable Mode — Sonnet
+
+## Skill Contract
+
+| Component | Specification |
+| :--- | :--- |
+| **Trigger / Input** | Explicit `fable on sonnet` or the accepted typo `fable on sonnect`. |
+| **Expected Output** | A bounded reasoning artifact, audit record, and verifier result. |
+| **State Mutations** | Native host TODO tracker or Markdown checklist. |
+| **Enforcement Gate** | Named pass condition, actual verification command, and visible unsupported-model handling. |
+
+## USE FOR:
+- Non-trivial implementation, analysis, document drafting, and research synthesis
+- Bounded stages that need stronger reasoning than bulk processing
+
+## DO NOT USE FOR:
+- One obvious single-pass task
+- Macro orchestration or final high-stakes decisions (use `fable-opus`)
+
+## Run it
+
+1. Resolve `sonnet` through `../scripts/model-selector.js`; normalize `sonnect` to Sonnet.
+2. Spawn `fable-worker-sonnet` when available, otherwise use a visible inline fallback.
+3. Brief the exact artifact path, context, and pass condition; workers do not spawn workers.
+4. Send high-stakes artifacts to `fable-verifier` and escalate contradictions instead of guessing.
+
+Use `../references/model-matrix.md` for the audit fields and fallback policy.

package/fable-mode/model-matrix.json

@@ -0,0 +1,32 @@
+{
+  "schemaVersion": 1,
+  "modes": {
+    "haiku": {
+      "role": "bulk mechanical / format conversion",
+      "agent": "fable-worker-haiku",
+      "aliases": ["haiku"]
+    },
+    "sonnet": {
+      "role": "non-trivial implementation / research synthesis / bounded stage reasoning",
+      "agent": "fable-worker-sonnet",
+      "aliases": ["sonnet", "sonnect"]
+    },
+    "opus": {
+      "role": "macro orchestration / cross-stage synthesis / high-stakes architecture and final decision",
+      "agent": "fable-orchestrator",
+      "aliases": ["opus"]
+    }
+  },
+  "fallbacks": {
+    "inline": {
+      "status": "fallback",
+      "effectiveModel": "host-model",
+      "reason": "requested model is unavailable; run inline on the declared host model"
+    },
+    "stop": {
+      "status": "blocked",
+      "effectiveModel": null,
+      "reason": "requested model is unavailable and inline fallback was not authorized"
+    }
+  }
+}

package/fable-mode/references/execution-phases.md

@@ -0,0 +1,37 @@
+# Fable Mode — Execution Phases
+
+```mermaid
+flowchart TD
+  Start[Qualifying Tier 3 task] --> Discover[Discover sources, runtime, and authorized scope]
+  Discover --> Plan[Write stage map and pass conditions]
+  Plan --> Select[Resolve requested model and write audit record]
+  Select --> Delegate[Delegate to named agent or visible inline fallback]
+  Delegate --> Contract[Write stage contract]
+  Contract --> Verify[Run the named failable check]
+  Verify --> Review[Cold-review high-stakes deliverables]
+  Review --> Done[Record result or escalate blocker]
+```
+
+## Discovery and planning
+
+Read the relevant files and sources before producing an artifact. Lock the
+authorized write scope in the handoff. Number the stages, assign one artifact
+and one pass condition to each, and allow no more than two full replans.
+
+## Delegation
+
+Use `fable-orchestrator` for Opus macro work, `fable-worker-sonnet` for
+reasoning and synthesis, and `fable-worker-haiku` for mechanical work. Brief
+each worker with its exact output path, context, audit record, and check.
+Workers do not spawn workers. If the named agent is unavailable, choose the
+explicit inline fallback or stop and escalate; do not silently change models.
+
+## Verification and handoff
+
+Before each spot-check, create `.claude/harness-everything/state/contracts/<stage>.json`
+using `CONTRACT-FORMAT.md`, then run the exact command in that contract. A
+stage is not complete until the command passes and the audit record contains
+the verifier result. Use `fable-verifier` with only the spec and artifact for
+high-stakes or unsupervised delivery. Review scope-guard output before merging.
+
+When macro scaffolding ends, transition to `tdd` for focused implementation.

package/fable-mode/references/model-matrix.md

@@ -0,0 +1,39 @@
+# Fable model matrix and execution audit
+
+Issue #27 defines three explicit execution modes. The mode selector is the
+machine-readable gate; this document is the human-facing contract.
+
+| Mode | Use for | Named agent |
+|---|---|---|
+| Haiku | Bulk mechanical work and format conversion | `fable-worker-haiku` |
+| Sonnet | Non-trivial implementation, research synthesis, bounded reasoning | `fable-worker-sonnet` |
+| Opus | Macro orchestration, cross-stage synthesis, high-stakes architecture and final decisions | `fable-orchestrator` |
+
+Use the explicit entrypoints `fable-haiku`, `fable-sonnet`, and `fable-opus`.
+The accepted input `sonnect` normalizes to Sonnet. A normal Tier 2 prompt does
+not select a fable model.
+
+## Deterministic selection
+
+Before each stage, run `fable-mode/scripts/model-selector.js` with the requested
+mode, the runtime's available modes, the host model, and the stage contract:
+
+```text
+node fable-mode/scripts/model-selector.js --requested opus --available opus,sonnet,haiku --available-agents fable-orchestrator,fable-worker-sonnet,fable-worker-haiku --fallback stop --host-model opus --stage-brief "Synthesize the architecture" --pass-condition "ADR and dependency map exist" --verification-command "npm test" --verifier-result pending
+```
+
+The JSON result always records `requestedModel`, `effectiveModel`,
+`fallbackReason`, `stageBrief`, `passCondition`, `verificationCommand`, and
+`verifierResult`, plus available agents, status, agent, and escalation state. The
+CLI appends the same record as one JSON line to
+`.claude/harness-everything/state/fable-mode/audit.jsonl` (or the path supplied by
+`--audit-file`).
+
+If the requested model is unavailable, `--fallback inline` records the declared
+host model and a visible reason. `--fallback stop` emits `status: blocked`, a
+null effective model, and exit code 2. Neither path silently downgrades.
+
+The orchestrator still owns scope lock, at most two full replans, stage
+contracts, worker non-recursion, cold verification, and escalation. The native
+host TODO tracker or a Markdown checklist records stage progress; no CLI TODO
+state machine is part of this contract.

package/fable-mode/scripts/model-selector.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const MATRIX_PATH = path.join(__dirname, '..', 'model-matrix.json');
+const REQUIRED = ['stageBrief', 'passCondition', 'verificationCommand', 'verifierResult'];
+const VALID_VERIFIER_RESULTS = new Set(['pending', 'pass', 'fail', 'not-run', 'blocked']);
+
+function loadMatrix() {
+  return JSON.parse(fs.readFileSync(MATRIX_PATH, 'utf8'));
+}
+
+function normalizeModel(value, matrix) {
+  const input = String(value || '').trim().toLowerCase();
+  for (const [model, definition] of Object.entries(matrix.modes)) {
+    if (definition.aliases.includes(input)) return model;
+  }
+  return null;
+}
+
+function parseArgs(argv) {
+  const args = {};
+  for (let i = 0; i < argv.length; i += 1) {
+    const token = argv[i];
+    if (token === '--help' || token === '-h') return { help: true };
+    if (!token.startsWith('--')) throw new Error(`unknown argument: ${token}`);
+    const key = token.slice(2).replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+    const value = argv[i + 1];
+    if (typeof value === 'undefined' || value.startsWith('--')) throw new Error(`missing value for --${key}`);
+    args[key] = value;
+    i += 1;
+  }
+  return args;
+}
+
+function resolveMode(input, matrix = loadMatrix()) {
+  const requestedModel = normalizeModel(input.requested, matrix);
+  if (!requestedModel) throw new Error('requested model must be one of haiku, sonnet, sonnect, or opus');
+
+  const availableModels = String(input.available || '')
+    .split(/[\s,]+/)
+    .map(model => normalizeModel(model, matrix))
+    .filter(Boolean);
+  const availableAgents = String(input.availableAgents || '')
+    .split(/[\s,]+/)
+    .map(agent => agent.trim())
+    .filter(Boolean);
+  const fallback = input.fallback || 'stop';
+  if (!Object.prototype.hasOwnProperty.call(matrix.fallbacks, fallback)) {
+    throw new Error('fallback must be inline or stop');
+  }
+
+  for (const field of REQUIRED) {
+    if (!String(input[field] || '').trim()) throw new Error(`${field} is required for an auditable stage`);
+  }
+  if (!VALID_VERIFIER_RESULTS.has(input.verifierResult)) {
+    throw new Error(`verifierResult must be one of ${[...VALID_VERIFIER_RESULTS].join(', ')}`);
+  }
+
+  const requestedAgent = matrix.modes[requestedModel].agent;
+  const modelAvailable = availableModels.includes(requestedModel);
+  const agentAvailable = availableAgents.includes(requestedAgent);
+  const selected = modelAvailable && agentAvailable;
+  const hostModel = String(input.hostModel || 'current-host').trim();
+  const fallbackDefinition = matrix.fallbacks[fallback];
+  const status = selected ? 'selected' : fallbackDefinition.status;
+  const effectiveModel = selected
+    ? requestedModel
+    : fallback === 'inline'
+      ? hostModel
+      : fallbackDefinition.effectiveModel;
+  const missing = [];
+  if (!modelAvailable) missing.push(`${requestedModel} is not in availableModels`);
+  if (!agentAvailable) missing.push(`${requestedAgent} is not in availableAgents`);
+  const fallbackReason = selected
+    ? 'none'
+    : `${fallbackDefinition.reason}: ${missing.join('; ')}`;
+
+  return {
+    schemaVersion: matrix.schemaVersion,
+    status,
+    requestedModel,
+    requestedInput: String(input.requested).trim(),
+    effectiveModel,
+    availableModels: [...new Set(availableModels)],
+    availableAgents: [...new Set(availableAgents)],
+    fallbackPolicy: fallback,
+    fallbackReason,
+    agent: selected ? requestedAgent : null,
+    modelRole: matrix.modes[requestedModel].role,
+    stageBrief: String(input.stageBrief).trim(),
+    passCondition: String(input.passCondition).trim(),
+    verificationCommand: String(input.verificationCommand).trim(),
+    verifierResult: input.verifierResult,
+    escalationRequired: status === 'blocked'
+  };
+}
+
+function printHelp() {
+  console.log('Usage: node fable-mode/scripts/model-selector.js --requested <haiku|sonnet|sonnect|opus> --available <models> --available-agents <agent names> --stage-brief <text> --pass-condition <text> --verification-command <command> --verifier-result <pending|pass|fail|not-run|blocked> [--fallback <inline|stop>] [--host-model <model>] [--audit-file <path>]');
+}
+
+function appendAuditRecord(record, auditFile) {
+  const target = auditFile || process.env.FABLE_AUDIT_FILE || path.join(process.cwd(), '.claude', 'harness-everything', 'state', 'fable-mode', 'audit.jsonl');
+  fs.mkdirSync(path.dirname(path.resolve(target)), { recursive: true });
+  fs.appendFileSync(target, `${JSON.stringify(record)}\n`, 'utf8');
+}
+
+function main(argv = process.argv.slice(2)) {
+  try {
+    const input = parseArgs(argv);
+    if (input.help) {
+      printHelp();
+      return 0;
+    }
+    const record = resolveMode(input);
+    appendAuditRecord(record, input.auditFile);
+    console.log(JSON.stringify(record, null, 2));
+    return record.status === 'blocked' ? 2 : 0;
+  } catch (error) {
+    console.error(`[fable-mode/model-selector] ${error.message}`);
+    return 2;
+  }
+}
+
+if (require.main === module) process.exitCode = main();
+
+module.exports = { loadMatrix, normalizeModel, parseArgs, resolveMode, main };