@ikon85/agent-workflow-kit 0.33.0 → 0.34.1

package/docs/adr/0006-routing-knowledge-access-and-policy-are-separate.md

@@ -0,0 +1,91 @@
+# Routing knowledge, access, and policy are separate
+
+Status: accepted (2026-07-22, Program #197)
+
+Planning cannot safely persist a concrete recommended model. Provider catalogs
+change, model names age, effort behavior differs by model, agent surfaces expose
+different controls, and a surface may reach another provider through a plugin
+or CLI transport. A recommendation that is correct in one session can therefore
+be nonexistent, unreachable, or unenforceable in the session that implements
+the work.
+
+We decided to keep three identities separate:
+
+1. The Kit-maintained **Evidence catalog** contains all known provider models
+   and observations, whether or not the active surface can use them. Each
+   decision-grade observation retains the complete configuration identity:
+   model, effort, harness, workload, source, benchmark version, uncertainty,
+   freshness, and cost.
+2. The user-local **Access graph** records the native and cross-provider paths
+   available from each agent surface. Claude Code and Codex attest only their
+   own runtime capabilities. A detected transport is not automatically approved,
+   and neither surface claims another surface's unverified capabilities.
+3. The user-local **Routing policy** records allowed surfaces and transports,
+   switching autonomy, optimization goals, and optional advanced overrides.
+   Personal choices do not alter catalog facts.
+
+Durable plans and issues contain only a provider-neutral **Routing intent**.
+At execution time a resolver compares all evidence-backed candidates, filters
+them through the Access graph and Routing policy, and produces a one-execution
+**Route decision**. It reports the best overall route separately from the best
+currently executable route. An unreachable preference follows the user's
+explicit handoff, fallback, or block policy.
+
+Every surface adapter declares how independently it can control model and
+effort: per spawn, through a named agent definition, through a session default,
+or not at all. Environment precedence is part of the capability proof. An AFK
+subagent requires enforced model and effort selection and emits a **Dispatch
+receipt** containing the requested and applied route, enforcement method, and
+policy/evidence revisions. Silent inheritance and unverified degradation are
+not valid AFK routes.
+
+Setup keeps the technical model behind a simple user decision. It presents a
+registry-driven list of familiar agent surfaces, preselects detected entries,
+and asks whether the Kit may switch automatically, ask before switching, or use
+only the current surface. Adapters establish providers, transports, model
+selectors, and effort controls. Model preferences and optimization overrides
+remain optional advanced settings.
+
+An existing installation without a routing profile receives this choice once
+through setup or the first compatible Kit update. Later updates perform a
+read-only preflight and ask again only when the profile is missing, invalid,
+materially stale, references a removed route, or a newly detected surface makes
+a meaningful choice available. Installing Kit mechanics and changing personal
+policy are separate transactions; unattended update never invents a decision.
+
+BenchLM may populate discovery, catalog, pricing, freshness, coverage, and
+corroboration signals. Its aggregate scores are not decision-grade routing
+observations because effort and harness identity may be collapsed and missing
+evidence may be estimated. DeepSWE, Artificial Analysis, OpenHands, Arena, and
+other benchmark-owner artifacts remain authoritative for the claims they
+actually measure. Local experience may calibrate policy but does not rewrite
+public evidence.
+
+## Considered options
+
+- **Persist a concrete model and effort in every issue:** rejected because the
+  recommendation ages and may not be executable on the implementing surface.
+- **Maintain separate Claude and Codex routing tables:** rejected because it
+  duplicates evidence, hides cross-provider routes, and lets the two surfaces
+  drift.
+- **Filter the shared table during setup:** rejected because current access is
+  a user/runtime fact, not a limit on routing knowledge.
+- **Ask users to describe transports and enforcement capabilities:** rejected
+  because these are adapter facts most users cannot answer reliably.
+- **Route directly from a composite leaderboard:** rejected because benchmark,
+  harness, effort, uncertainty, and workload boundaries would be lost.
+- **Re-run the routing interview on every Kit update:** rejected because a valid
+  user-owned profile should remain stable until a material choice changes.
+
+## Consequences
+
+- Model/provider churn updates the catalog and resolver without rewriting
+  durable issues.
+- Both Claude Code and Codex read one local policy while proving their own
+  execution capabilities independently.
+- Cross-provider dispatch is expressible without pretending that every surface
+  can reach every model.
+- The Kit must maintain source adapters, schema migration, capability probes,
+  last-known-good evidence, and dispatch receipts.
+- Different machines do not share personal routing state unless the user later
+  chooses an explicit export or private synchronization mechanism.

package/docs/agents/skills/local-ci.md

@@ -0,0 +1,89 @@
+<!-- setup-workflow: state=filled -->
+# Project layer — local-ci
+
+This repo is a Node + stdlib-Python repo with no database, no dev server and no
+typecheck step, so the two generic profiles map onto a short command set. Run the
+two commands below; do not infer others.
+
+Prerequisite once per clone (worktrees inherit it):
+
+```sh
+git config core.hooksPath .githooks
+```
+
+## Fast static guards
+
+The skill/manifest lints, ~3s, no network, no DB. This is exactly what
+`.githooks/pre-commit` runs, so a normal commit already covers it:
+
+```sh
+python3 -m unittest discover -s scripts -p 'test_skill_*.py' -q
+```
+
+## Full gate
+
+Mirrors the `test` job in `.github/workflows/ci.yml` step for step. Run it from
+the branch's worktree root before opening a PR:
+
+```sh
+npm test
+npm run kit:staleness
+npm run release:guard -- --base "$(git merge-base origin/main HEAD)"
+npm pack --dry-run
+```
+
+Notes on the individual steps:
+
+- `npm test` is `test:node` (`node --test`) plus `test:python`
+  (`python3 -m unittest discover -s scripts -p 'test_*.py'`). Several negative-path
+  tests print `[FAIL] …` lines by design; only the runner's own summary and exit
+  code decide red or green.
+- CI runs `npm install --ignore-scripts` first. Locally that is only needed after
+  a dependency change.
+- `release:guard` runs in CI on `pull_request` only, against
+  `github.event.pull_request.base.sha`. `git merge-base origin/main HEAD` is the
+  local equivalent; `git fetch origin main` first if `origin/main` is stale.
+- `npm pack --dry-run` catches packaging drift (a file added outside the
+  published set) without publishing anything.
+
+## Enforcement
+
+Since #220 the host **does** enforce: the `main protection` ruleset makes the CI
+job `test` a required status check on `main`, with no bypass actor. So the
+generic skill's "When the host CAN enforce" branch applies to this repo — the
+local gate is a pre-flight that shortens the feedback loop, not the only thing
+standing between a red branch and `main`.
+
+Layered, from cheapest to strongest:
+
+| Layer | Runs | Scope |
+| --- | --- | --- |
+| `pre-commit` | automatic, every commit | fast skill/manifest lints |
+| `pre-push` | automatic, every push | full `npm test` |
+| this full gate | explicit, before a PR | `npm test` + staleness + release guard + pack |
+| CI `test` | automatic, on the PR | the same set, machine-enforced at merge |
+
+Never bypass a hook with `--no-verify`.
+
+**Drift rule.** The full gate above and `.github/workflows/ci.yml` are two copies
+of one list. Change one, change the other in the same PR — otherwise the local
+gate goes green on a set the required check does not accept.
+
+## Contention
+
+Not applicable here. This repo has no dev server and the suites are process-level
+(`node --test`, `unittest`), so the generic boot-contention false-red guidance has
+no target. A red is a real red until an isolated re-run of that one test proves
+otherwise.
+
+## On a red
+
+1. Read the failing assertion — the guards print the exact drift (`file:line`,
+   the offending token, the missing manifest key).
+2. Fix the source. A guard that legitimately cannot be satisfied yet gets a
+   documented allowlist entry with a reason; never widen a guard silently.
+3. Re-run the single failing suite, then the full gate for sign-off.
+
+`kit:staleness` red almost always means the generated kit artefacts lag the
+skill sources — run `npm run kit:build` and commit the result rather than
+editing the generated output by hand.

package/docs/agents/wave-anchor-template.md

@@ -25,7 +25,7 @@ The **candidate stub** (Stage 1) has no cluster/Wave. On **`to-issues` promotion
 - **Source:** <board-to-waves | external-prd | raw-issue | plan | grill> *(provenance-neutral — the shape is the same regardless of origin; fill the following lines where they apply, delete where they don't)*
 - **Member issues:** #<a> #<b> #<c> … *(listed; linked via `to-issues` promotion, To-Do below)*
 - **Why together (firing criteria):** Gate=<Outcome> · <B1 code proximity / B2 type homogeneity / B3 dependency / B4 verify surface, where applicable>
-- **Size + risk:** ~<N> slices · Backend: <yes/no> · Model mix: <Model [Effort], e.g. Sonnet [medium] / Opus [high] / gpt-5.5 [medium]> · Risk: <low/medium/high — reason, e.g. race/cache/forecast/migration>
+- **Size + risk:** ~<N> slices · Backend: <yes/no> · Routing-intent mix: <judgment/development/mechanical + deep/balanced/light> · Risk: <low/medium/high — reason, e.g. race/cache/forecast/migration>
 - **`grill-needed`:** <no> | <yes — this session> | <yes — own session (too big/fuzzy)>
 
 ### To-Do (maturation: grill → to-prd → to-issues) — *(Stage 1/1p only; at promotion this whole checklist collapses to ONE line: `Maturation: grill <✓/–> · to-prd ✓ · to-issues ✓ (<Date>) — Wave gate + tracking open`)*
@@ -53,7 +53,7 @@ Order (WSJF-lite): visible + low-risk first → logic/backend → cleanup. Depen
 | 1 | ⬜ | <Slice title> | #<sub> | <—/🧭/🔬/📐/📝> | <closes #x / refs #y> |
 <!-- slice-table:end -->
 
-Status legend: ⬜ open · 🔄 in progress · ✅ merged #<PR>. **Every slice = one sub-issue** (`#<sub>`). **The volatile Status column is generated by `board-sync.py anchor-sync <anchor#>` from the board** (between the `<!-- slice-table:start/end -->` markers; `wrapup` Step 5e.1 calls it on merge) — monotone (never flips a `✅`/`🔄` back), drift-free idempotent; **stable plan columns (Slice/Gate/refs) stay hand-maintained** and survive verbatim. It appends missing sub-issue rows (gen-b split). **Don't delete the markers** — without them `anchor-sync` can't locate the table (the first run locates it via the `Status`+`Sub-Issue` header row and sets the markers itself). The native "Sub-issues progress" rollup is the secondary %-view. *(Slimmed in: Branch is derivable from the `feat/<#>-<slug>` convention, the model recommendation lives in the leaf's handoff, Backend? carried no navigation value — legacy anchors that still have those columns keep working, `anchor-sync` matches columns by header name and refreshes Branch/Blocked-by only where the column exists.)*
+Status legend: ⬜ open · 🔄 in progress · ✅ merged #<PR>. **Every slice = one sub-issue** (`#<sub>`). **The volatile Status column is generated by `board-sync.py anchor-sync <anchor#>` from the board** (between the `<!-- slice-table:start/end -->` markers; `wrapup` Step 5e.1 calls it on merge) — monotone (never flips a `✅`/`🔄` back), drift-free idempotent; **stable plan columns (Slice/Gate/refs) stay hand-maintained** and survive verbatim. It appends missing sub-issue rows (gen-b split). **Don't delete the markers** — without them `anchor-sync` can't locate the table (the first run locates it via the `Status`+`Sub-Issue` header row and sets the markers itself). The native "Sub-issues progress" rollup is the secondary %-view. *(Slimmed in: Branch is derivable from the `feat/<#>-<slug>` convention, provider-neutral routing intent lives in the leaf's handoff, Backend? carried no navigation value — legacy anchors that still have those columns keep working, `anchor-sync` matches columns by header name and refreshes Branch/Blocked-by only where the column exists.)*
 
 **Gate legend (retro):** `—` AFK build (`/implement`) · 🧭 design grill (`grill-with-docs-codex`, ADR) · 🔬 verify spike (read-only fact question) · 📐 trade-off/research (read-only, below grill threshold) · 📝 review note (not a build slice). A gate slice (🧭/🔬/📐) sits **before** its dependent build slice (gate-before-build) and blocks it.
 

package/docs/methodology.html

@@ -324,7 +324,7 @@
           <span class="station st-program">grill</span><span class="arrow">→</span>
           <span class="station st-program">Program document</span><span class="arrow">→</span>
           <span class="station st-gate">preview gate</span><span class="arrow">→</span>
-          <span class="station st-wave">to-waves</span><span class="arrow">→</span>
+          <span class="station st-wave">to-issues · Program mode</span><span class="arrow">→</span>
           <span class="station st-phase">phases stamped</span><span class="arrow">+</span>
           <span class="station st-wave">Wave 1…n + slices</span>
         </div>

package/docs/methodology.svg

@@ -49,7 +49,7 @@
 
   <!-- top branch: planned top-down -->
   <rect x="350" y="350" width="260" height="40" rx="7" fill="#2E3850" stroke="B2" stroke-width="1.2"/>
-  <text x="480" y="375" font-size="12.5" fill="#8FA9C4" text-anchor="middle">scale-check → grill → to-waves</text>
+  <text x="480" y="375" font-size="12.5" fill="#8FA9C4" text-anchor="middle">scale-check → grill → to-issues</text>
   <line x1="480" y1="390" x2="553" y2="430" stroke="#8A95A6" stroke-width="1.4" marker-end="url(#arrow)"/>
 
   <!-- main spine -->

package/docs/workflow.html

@@ -181,8 +181,8 @@
       <div class="sw-track" style="--lbg: var(--plan-bg);">
         <span class="station st-plan">scale-check</span><span class="arrow">→</span>
         <span class="station st-gate">grill</span><span class="arrow">→</span>
-        <span class="station st-plan">to-waves</span>
-        <span class="decision">preview gate · zero board writes until yes</span><span class="arrow">→</span>
+        <span class="station st-plan">to-issues</span>
+        <span class="decision">Program identity · preview gate · zero writes until yes</span><span class="arrow">→</span>
         <span class="station st-exec">orchestrate-wave</span>
         <span class="decision">per wave, often AFK</span><span class="arrow">→</span>
         <span class="station st-land">wrapup</span><span class="arrow">→</span>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.33.0",
+  "version": "0.34.1",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/codex-exec.sh

@@ -4,6 +4,7 @@ set -u
 SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)
 PROC_HELPER="$SCRIPT_DIR/codex_proc.py"
 TESTED_VERSIONS=("0.137.0" "0.144.6")
+SUPPORTED_EFFORTS=("low" "medium" "high" "xhigh" "max" "ultra")
 STATE_ROOT=${CODEX_EXEC_STATE_ROOT:-${TMPDIR:-/tmp}/codex-exec-state}
 
 emit_json() {
@@ -118,10 +119,10 @@ preflight() {
 }
 
 parse_options() {
-  CODEX_BIN=codex PROFILE= MODE= SANDBOX= PROMPT= PROMPT_FILE= RUN_ID= TIMEOUT= PROBE_TIMEOUT= DEBUG_RETAIN=false
+  CODEX_BIN=codex PROFILE= MODE= SANDBOX= PROMPT= PROMPT_FILE= RUN_ID= TIMEOUT= PROBE_TIMEOUT= MODEL= EFFORT= DEBUG_RETAIN=false
   while (($#)); do
     case $1 in
-      --codex-bin|--profile|--mode|--prompt|--prompt-file|--run-id|--timeout|--probe-timeout)
+      --codex-bin|--profile|--mode|--prompt|--prompt-file|--run-id|--timeout|--probe-timeout|--model|--effort)
         (($# >= 2)) || { fail INVALID_ARGUMENT "Missing value for $1"; return 1; }
         case $1 in
           --codex-bin) CODEX_BIN=$2 ;;
@@ -132,6 +133,8 @@ parse_options() {
           --run-id) RUN_ID=$2 ;;
           --timeout) TIMEOUT=$2 ;;
           --probe-timeout) PROBE_TIMEOUT=$2 ;;
+          --model) MODEL=$2 ;;
+          --effort) EFFORT=$2 ;;
         esac
         shift 2 ;;
       --debug-retain) DEBUG_RETAIN=true; shift ;;
@@ -140,6 +143,22 @@ parse_options() {
   done
 }
 
+validate_route_controls() {
+  if [[ -z $MODEL && -z $EFFORT ]]; then
+    return 0
+  fi
+  local effort_supported=false supported
+  for supported in "${SUPPORTED_EFFORTS[@]}"; do
+    [[ $EFFORT == "$supported" ]] && effort_supported=true
+  done
+  if [[ -z $MODEL || -z $EFFORT \
+    || ! $MODEL =~ ^[A-Za-z0-9._:-]+$ \
+    || $effort_supported != true ]]; then
+    fail INVALID_ROUTE_CONTROL "Model and effort must be supplied together from the exact safe vocabulary"
+    return 1
+  fi
+}
+
 prepare_prompt() {
   local state_dir=$1
   TEMP_PROMPT="$state_dir/.prompt-input"
@@ -160,10 +179,14 @@ launch_round() {
   prepare_prompt "$state_dir" || return 1
   local command
   if [[ -z $thread_id ]]; then
-    command=("$CODEX_BIN" exec --json --sandbox "$SANDBOX" -)
+    command=("$CODEX_BIN" exec --json --sandbox "$SANDBOX")
   else
-    command=("$CODEX_BIN" exec resume "$thread_id" -c "sandbox_mode=$SANDBOX" --json -)
+    command=("$CODEX_BIN" exec resume "$thread_id" -c "sandbox_mode=$SANDBOX")
   fi
+  if [[ -n $MODEL ]]; then
+    command+=(-c "model=$MODEL" -c "model_reasoning_effort=$EFFORT")
+  fi
+  command+=(--json -)
   python3 "$PROC_HELPER" run --state-dir "$state_dir" --round "$round" \
     --profile "$PROFILE" --sandbox "$SANDBOX" --timeout "$TIMEOUT" \
     --probe-timeout "$PROBE_TIMEOUT" --prompt-file "$TEMP_PROMPT" \
@@ -252,6 +275,7 @@ PY
 
 new_run() {
   parse_options "$@" || return 1
+  validate_route_controls || return 1
   PROFILE=${PROFILE:-review}
   MODE=${MODE:-read-only}
   [[ $PROFILE == review || $PROFILE == build ]] || { fail INVALID_PROFILE "Profile must be review or build"; return 1; }
@@ -285,15 +309,18 @@ new_run() {
   state_dir=$(mktemp -d "$STATE_ROOT/codex-exec.XXXXXXXX") || return 1
   chmod 700 "$state_dir"
   run_id=${state_dir##*.}
-  printf '%s\n' "$run_id" >"$state_dir/run-id"
   printf '%s\n' "$PROFILE" >"$state_dir/profile"
   printf '%s\n' "$SANDBOX" >"$state_dir/sandbox"
+  printf '%s\n' "$MODEL" >"$state_dir/model"
+  printf '%s\n' "$EFFORT" >"$state_dir/effort"
   printf '1\n' >"$state_dir/next-round"
   chmod 600 "$state_dir"/*
   lease_token=$(acquire_lease "$state_dir") || {
     fail ACTIVE_RUN "Run state is already owned by another lifecycle action"
     return 1
   }
+  printf '%s\n' "$run_id" >"$state_dir/run-id"
+  chmod 600 "$state_dir/run-id"
   output=$(launch_round "$state_dir" 1 "$lease_token")
   rc=$?
   release_or_fail "$state_dir" "$lease_token" "$run_id" "$output" || return 1
@@ -307,16 +334,20 @@ new_run() {
 }
 
 resume_run_locked() {
-  local state_dir=$1 lease_token=$2 stored_profile stored_sandbox thread_id round
+  local state_dir=$1 lease_token=$2 stored_profile stored_sandbox stored_model stored_effort thread_id round
   [[ ! -f $state_dir/debug-retain ]] || {
     fail RUN_FINALIZED "Run was finalized with debug retention"; return 1;
   }
   [[ -f $state_dir/profile && ! -L $state_dir/profile \
-    && -f $state_dir/sandbox && ! -L $state_dir/sandbox ]] || {
-    fail INVALID_STATE "Persisted profile or sandbox state is missing or unsafe"; return 1;
+    && -f $state_dir/sandbox && ! -L $state_dir/sandbox \
+    && -f $state_dir/model && ! -L $state_dir/model \
+    && -f $state_dir/effort && ! -L $state_dir/effort ]] || {
+    fail INVALID_STATE "Persisted profile, sandbox, or route controls are missing or unsafe"; return 1;
   }
   stored_profile=$(<"$state_dir/profile")
   stored_sandbox=$(<"$state_dir/sandbox")
+  stored_model=$(<"$state_dir/model")
+  stored_effort=$(<"$state_dir/effort")
   [[ $stored_profile == review || $stored_profile == build ]] || {
     fail INVALID_STATE "Persisted profile is not in the exact allowlist"; return 1;
   }
@@ -328,6 +359,13 @@ resume_run_locked() {
     fail MODE_MISMATCH "Resume mode differs from persisted mode"
     return 1
   fi
+  if [[ -n $MODEL && $MODEL != "$stored_model" ]] || [[ -n $EFFORT && $EFFORT != "$stored_effort" ]]; then
+    fail ROUTE_CONTROL_MISMATCH "Resume model or effort differs from the persisted applied route"
+    return 1
+  fi
+  MODEL=$stored_model
+  EFFORT=$stored_effort
+  validate_route_controls || return 1
   SANDBOX=$stored_sandbox
   [[ -f $state_dir/thread-id ]] || { fail NO_THREAD "Run has no resumable thread" NO-THREAD; return 1; }
   thread_id=$(<"$state_dir/thread-id")
@@ -346,6 +384,7 @@ resume_run_locked() {
 
 resume_run() {
   parse_options "$@" || return 1
+  validate_route_controls || return 1
   [[ -n $RUN_ID ]] || { fail RUN_ID_REQUIRED "Resume requires --run-id"; return 1; }
   local state_dir lease_token rc output
   state_dir=$(find_state "$RUN_ID") || { fail RUN_NOT_FOUND "Run state does not exist"; return 1; }

package/scripts/codex-exec.test.mjs

@@ -143,6 +143,62 @@ test('invalid timeout and mode inputs fail before launch', () => {
   assert.equal(exists(fx.launchLog), false);
 });
 
+test('approved route passes explicit model and effort controls to Codex', () => {
+  const fx = fixture();
+  const result = invoke(fx, [
+    ...launchArgs(),
+    '--model', 'coding-model',
+    '--effort', 'high',
+  ]);
+  assert.equal(result.output.status, 'OK');
+  const command = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim());
+  assert.ok(command.includes('model=coding-model'));
+  assert.ok(command.includes('model_reasoning_effort=high'));
+
+  const resumed = invoke(fx, [
+    'resume', result.output.runId, '--codex-bin', fake,
+    '--prompt', 'Again', '--timeout', '2',
+  ]);
+  assert.equal(resumed.output.status, 'OK');
+  const resumeCommand = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim().split('\n').at(-1));
+  assert.ok(resumeCommand.includes('model=coding-model'));
+  assert.ok(resumeCommand.includes('model_reasoning_effort=high'));
+
+  const mismatch = invoke(fx, [
+    'resume', result.output.runId, '--codex-bin', fake,
+    '--model', 'other-model', '--effort', 'high', '--prompt', 'No',
+  ]);
+  assert.equal(mismatch.output.error, 'ROUTE_CONTROL_MISMATCH');
+});
+
+test('route controls fail closed when incomplete or unsafe', () => {
+  for (const args of [
+    [...launchArgs(), '--model', 'coding-model'],
+    [...launchArgs(), '--effort', 'high'],
+    [...launchArgs(), '--model', 'unsafe value', '--effort', 'high'],
+    [...launchArgs(), '--model', 'coding-model', '--effort', 'unknown'],
+  ]) {
+    const fx = fixture();
+    const result = invoke(fx, args);
+    assert.equal(result.output.error, 'INVALID_ROUTE_CONTROL');
+    assert.equal(exists(fx.launchLog), false);
+  }
+});
+
+test('current extended reasoning efforts are passed through explicitly', () => {
+  for (const effort of ['max', 'ultra']) {
+    const fx = fixture();
+    const result = invoke(fx, [
+      ...launchArgs(),
+      '--model', 'coding-model',
+      '--effort', effort,
+    ]);
+    assert.equal(result.output.status, 'OK', effort);
+    const command = JSON.parse(readFileSync(fx.launchLog, 'utf8').trim());
+    assert.ok(command.includes(`model_reasoning_effort=${effort}`));
+  }
+});
+
 test('finalize deletes state, debug-retain preserves diagnostics, and finalized resume fails', () => {
   const fx = fixture();
   const run = invoke(fx, launchArgs()).output;

package/scripts/kit-release.test.mjs

@@ -1,12 +1,170 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
 import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { nextVersion, prepareRelease } from './kit-release.mjs';
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
+const exec = promisify(execFile);
+
+async function releaseWorkflow() {
+  return readFile(join(REPO, '.github/workflows/release.yml'), 'utf8');
+}
+
+function workflowRunScript(workflow, stepName) {
+  const lines = workflow.split('\n');
+  const nameIndex = lines.findIndex((line) => line.trim() === `- name: ${stepName}`);
+  assert.notEqual(nameIndex, -1, `workflow step not found: ${stepName}`);
+  const runIndex = lines.findIndex(
+    (line, index) => index > nameIndex && line.trim() === 'run: |',
+  );
+  assert.notEqual(runIndex, -1, `run block not found for workflow step: ${stepName}`);
+  const indent = lines[runIndex].match(/^\s*/)[0].length + 2;
+  const body = [];
+  for (const line of lines.slice(runIndex + 1)) {
+    if (line.trim() && line.match(/^\s*/)[0].length < indent) break;
+    body.push(line.slice(indent));
+  }
+  return body.join('\n');
+}
+
+async function git(runCwd, args, options = {}) {
+  return exec('git', args, { cwd: runCwd, ...options });
+}
+
+async function releaseIntentFixture({
+  packageVersion = '1.2.3',
+  annotated = true,
+  onMain = true,
+  mainAhead = false,
+} = {}) {
+  const root = await mkdtemp(join(tmpdir(), 'kit-release-intent-'));
+  const origin = join(root, 'origin.git');
+  const repo = join(root, 'repo');
+  await git(root, ['init', '--bare', origin]);
+  await git(root, ['init', '--initial-branch=main', repo]);
+  await git(repo, ['config', 'user.name', 'Release Test']);
+  await git(repo, ['config', 'user.email', 'release-test@example.invalid']);
+  await writeFile(join(repo, 'package.json'), `${JSON.stringify({
+    name: '@ikon85/agent-workflow-kit',
+    version: packageVersion,
+  }, null, 2)}\n`);
+  await git(repo, ['add', 'package.json']);
+  await git(repo, ['commit', '-m', 'release fixture']);
+  await git(repo, ['remote', 'add', 'origin', origin]);
+  await git(repo, ['push', '-u', 'origin', 'main']);
+  if (!onMain) {
+    await git(repo, ['checkout', '-b', 'not-main']);
+    await writeFile(join(repo, 'outside-main.txt'), 'not canonical\n');
+    await git(repo, ['add', 'outside-main.txt']);
+    await git(repo, ['commit', '-m', 'outside main']);
+  }
+  const tag = 'v1.2.3';
+  await git(repo, annotated
+    ? ['tag', '-a', tag, '-m', `Release ${tag}`]
+    : ['tag', tag]);
+  if (mainAhead) {
+    await writeFile(join(repo, 'after-release.txt'), 'main moved\n');
+    await git(repo, ['add', 'after-release.txt']);
+    await git(repo, ['commit', '-m', 'move canonical main']);
+    await git(repo, ['push', 'origin', 'main']);
+  }
+  return { root, repo, tag };
+}
+
+async function validateReleaseIntent(fixture, releaseTag = fixture.tag) {
+  const workflow = await releaseWorkflow();
+  const script = workflowRunScript(workflow, 'Validate release intent');
+  const output = join(fixture.root, 'github-output');
+  try {
+    const result = await exec('bash', ['-euo', 'pipefail', '-c', script], {
+      cwd: fixture.repo,
+      env: {
+        ...process.env,
+        GITHUB_OUTPUT: output,
+        RELEASE_TAG: releaseTag,
+      },
+    });
+    return { ...result, output: await readFile(output, 'utf8') };
+  } catch (error) {
+    return { error, stderr: error.stderr ?? '', stdout: error.stdout ?? '' };
+  }
+}
+
+test('release workflow treats an annotated version tag as normal intent and merge as integration only', async () => {
+  const workflow = await releaseWorkflow();
+  assert.match(workflow, /push:\s*\n\s+tags:\s*\n\s+- ['"]v\*\.\*\.\*['"]/);
+  assert.doesNotMatch(workflow, /push:\s*\n\s+branches:\s*\[main\]/);
+  assert.match(workflow, /workflow_dispatch:\s*\n\s+inputs:\s*\n\s+tag:/);
+  assert.match(workflow, /tag:[\s\S]*?required:\s*true/);
+  assert.match(
+    workflow,
+    /group:\s*release-\$\{\{ github\.event_name == 'workflow_dispatch' && inputs\.tag \|\| github\.ref_name \}\}/,
+  );
+  assert.doesNotMatch(workflow, /git diff --name-only[\s\S]*package\.json/);
+  assert.ok(
+    workflow.indexOf('- name: Validate release intent')
+      < workflow.indexOf('node scripts/release-state.mjs'),
+    'release intent must be validated before the reconciler can publish',
+  );
+  assert.equal(workflow.match(/node scripts\/release-state\.mjs/g)?.length, 1);
+});
+
+test('the same pre-publish validator accepts a matching annotated tag', async () => {
+  const fixture = await releaseIntentFixture();
+  try {
+    const result = await validateReleaseIntent(fixture);
+    assert.equal(result.error, undefined, result.stderr);
+    assert.match(result.output, /^tag=v1\.2\.3$/m);
+    assert.match(result.output, /^commit=[0-9a-f]{40}$/m);
+  } finally {
+    await rm(fixture.root, { recursive: true, force: true });
+  }
+});
+
+for (const scenario of [
+  {
+    name: 'missing manual recovery tag',
+    options: {},
+    tag: 'v9.9.9',
+    error: /does not exist/,
+  },
+  {
+    name: 'tag/package version mismatch',
+    options: { packageVersion: '1.2.4' },
+    error: /does not match package version/,
+  },
+  {
+    name: 'lightweight tag',
+    options: { annotated: false },
+    error: /must be annotated/,
+  },
+  {
+    name: 'tag outside canonical main ancestry',
+    options: { onMain: false },
+    error: /not an ancestor of origin\/main/,
+  },
+  {
+    name: 'stale canonical main commit with the same package version',
+    options: { mainAhead: true },
+    error: /does not identify the current origin\/main commit/,
+  },
+]) {
+  test(`the pre-publish validator rejects a ${scenario.name}`, async () => {
+    const fixture = await releaseIntentFixture(scenario.options);
+    try {
+      const result = await validateReleaseIntent(fixture, scenario.tag);
+      assert.ok(result.error, 'validation unexpectedly succeeded');
+      assert.match(`${result.stderr}\n${result.stdout}`, scenario.error);
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+}
 
 test('the install manifest ships both release primitives named by the skill', async () => {
   const manifest = JSON.parse(await readFile(join(REPO, 'agent-workflow-kit.package.json')));
@@ -20,11 +178,31 @@ test('the install manifest ships both release primitives named by the skill', as
 test('both release skill surfaces name only the owned scoped npm package', async () => {
   const claude = await readFile(join(REPO, '.claude/skills/kit-release/SKILL.md'), 'utf8');
   const codex = await readFile(join(REPO, '.agents/skills/kit-release/SKILL.md'), 'utf8');
+  assert.equal(codex, claude);
   for (const body of [claude, codex]) {
     assert.match(body, /`@ikon85\/agent-workflow-kit`/);
   }
 });
 
+test('maintainer docs and the accepted ADR agree that merge integrates and an annotated tag publishes', async () => {
+  const paths = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    'README.md',
+    '.claude/skills/kit-release/SKILL.md',
+    '.agents/skills/kit-release/SKILL.md',
+    'docs/adr/0004-release-intent-is-a-version-tag.md',
+  ];
+  const bodies = await Promise.all(
+    paths.map((path) => readFile(join(REPO, path), 'utf8')),
+  );
+  for (const [index, body] of bodies.entries()) {
+    assert.match(body, /annotated\s+[`*]?v<version>[`*]?\s+tag/i, paths[index]);
+    assert.match(body, /integrat/i, paths[index]);
+  }
+  assert.match(bodies.at(-1), /Status: accepted \(2026-07-22, issue #204\)/);
+});
+
 test('patch, minor, and major confirmations select exactly one target version', () => {
   assert.equal(nextVersion('1.2.3', 'patch'), '1.2.4');
   assert.equal(nextVersion('1.2.3', 'minor'), '1.3.0');