--- name: kaola-workflow-adapt description: Use when authoring an adaptive workflow-plan.md — freely compose a task-shaped DAG of role nodes, then the validator proves it in-grammar and freezes it. Mirror of commands/kaola-workflow-adapt.md for Codex runtime. --- ## Codex Profile Freshness Gate On every entry or resume into this skill, before any role probe, retry, re-plan, or real dispatch, run the normal preflight gate, not `--doctor`. Resolve exactly one enabled installed Kaola edition from `codex plugin list --json`, then execute the bundled `kaola-workflow-codex-preflight.js` from that edition's exact marketplace/name/version cache tuple. Never search `$PWD/plugins` or select the lexically first cache entry: ```bash if ! KAOLA_CODEX_PLUGIN_LIST_OUT="$(codex plugin list --json 2>&1)"; then printf 'profile_preflight_refused: plugin metadata unavailable: %s\n' "$KAOLA_CODEX_PLUGIN_LIST_OUT" >&2 exit 1 fi if ! KAOLA_CODEX_PLUGIN_META="$(node -e ' const value=JSON.parse(process.argv[1]); const allowed=new Set(["kaola-workflow","kaola-workflow-gitlab","kaola-workflow-gitea"]); const rows=(Array.isArray(value.installed)?value.installed:[]).filter(row => row && row.installed === true && row.enabled === true && allowed.has(row.name)); if(rows.length!==1)throw new Error(`expected exactly one enabled installed Kaola edition; got ${rows.length}`); const row=rows[0]; for(const [label,item] of [["marketplace",row.marketplaceName],["name",row.name],["version",row.version]])if(typeof item!=="string"||item==="."||item===".."||!/^[A-Za-z0-9._-]+$/.test(item))throw new Error(`unsafe ${label}`); if(row.pluginId!==`${row.name}@${row.marketplaceName}`)throw new Error("plugin identity mismatch"); process.stdout.write([row.marketplaceName,row.name,row.version].join("\t")); ' "$KAOLA_CODEX_PLUGIN_LIST_OUT" 2>&1)"; then printf 'profile_preflight_refused: invalid plugin metadata: %s\n' "$KAOLA_CODEX_PLUGIN_META" >&2 exit 1 fi IFS=$'\t' read -r KAOLA_CODEX_MARKETPLACE KAOLA_CODEX_PLUGIN_NAME KAOLA_CODEX_PLUGIN_VERSION <<< "$KAOLA_CODEX_PLUGIN_META" KAOLA_CODEX_CACHE_ROOT="$HOME/.codex/plugins/cache" if ! KAOLA_CODEX_PREFLIGHT="$(node -e ' const fs=require("fs"),path=require("path"); const [home,base,marketplace,name,version]=process.argv.slice(1); const resolvedHome=path.resolve(home),resolvedBase=path.resolve(base); if(resolvedBase!==path.join(resolvedHome,".codex","plugins","cache"))throw new Error("plugin cache root escapes HOME"); let cursor=resolvedHome; const homeStat=fs.lstatSync(cursor); if(homeStat.isSymbolicLink()||!homeStat.isDirectory())throw new Error("HOME is unsafe"); const parts=[".codex","plugins","cache",marketplace,name,version,"scripts","kaola-workflow-codex-preflight.js"]; for(let index=0;index&1)"; then printf 'profile_preflight_refused: exact active preflight unavailable: %s\n' "$KAOLA_CODEX_PREFLIGHT" >&2 exit 1 fi KAOLA_CODEX_PREFLIGHT_ARGS=(--project-root "$PWD" --no-autofix --json) if [ -n "${KAOLA_CODEX_PREFLIGHT_PLAN:-}" ]; then KAOLA_CODEX_PREFLIGHT_ARGS+=(--plan "$KAOLA_CODEX_PREFLIGHT_PLAN") fi if ! KAOLA_CODEX_PREFLIGHT_OUT="$(node "$KAOLA_CODEX_PREFLIGHT" "${KAOLA_CODEX_PREFLIGHT_ARGS[@]}" 2>&1)"; then printf 'profile_preflight_refused: %s\n' "$KAOLA_CODEX_PREFLIGHT_OUT" >&2 exit 1 fi if ! KAOLA_CODEX_PREFLIGHT_STATUS="$(node -e 'const v=JSON.parse(process.argv[1]);if(typeof v.status!=="string")throw new Error("missing status");process.stdout.write(v.status)' "$KAOLA_CODEX_PREFLIGHT_OUT" 2>&1)"; then printf 'profile_preflight_refused: malformed preflight result: %s\n' "$KAOLA_CODEX_PREFLIGHT_STATUS" >&2 exit 1 fi if [ "$KAOLA_CODEX_PREFLIGHT_STATUS" != ok ]; then printf 'profile_preflight_refused: %s\n' "$KAOLA_CODEX_PREFLIGHT_OUT" >&2 exit 1 fi ``` The exact active cache root is `$HOME/.codex/plugins/cache/$KAOLA_CODEX_MARKETPLACE/$KAOLA_CODEX_PLUGIN_NAME/$KAOLA_CODEX_PLUGIN_VERSION`. The base invocation is `--project-root "$PWD" --no-autofix --json`; the gate merges persisted config from HOME through the repository root to `"$PWD"`. When this skill owns a frozen adaptive plan, set `KAOLA_CODEX_PREFLIGHT_PLAN` to that exact plan before running the block so `--plan` is also enforced. Continue only after exit 0 and parsed `status: "ok"`. Exact-byte drift such as `profile_bytes_mismatch` is `profile_preflight_refused`: STOP before any `agents.spawn_agent` call, never record `subagent-invoked`, and do not relabel profile/config drift as tool unavailability or local fallback. Re-run the gate if the installed profile set changes. # Skill: kaola-workflow-adapt ## In-progress re-plan control plane This fence outranks normal adaptive startup and authoring. Before any claim, handoff, or planner startup action, read the project state and transaction status. When either reports `replan_in_progress`, keep the frozen parent `workflow-plan.md` authoritative. Read-only orientation reports the exact `replan_phase`, `transaction_id`, `parent_plan_hash`, `child_plan_hash` (or `none`), and `last_cas_result`; never reconstruct them from memory. The single legal mutation while the fence is active is: ```bash REPLAN_SCRIPT="plugins/kaola-workflow/scripts/kaola-workflow-replan.js" if [ ! -f "$REPLAN_SCRIPT" ]; then REPLAN_SCRIPT="$(find "$HOME/.codex/plugins/cache" -path '*/kaola-workflow/*/scripts/kaola-workflow-replan.js' -print -quit 2>/dev/null)" fi [ -n "$REPLAN_SCRIPT" ] && [ -f "$REPLAN_SCRIPT" ] || { echo "BLOCKED: kaola-workflow-replan.js unavailable" >&2; exit 1; } node "$REPLAN_SCRIPT" resume --project {project} --json ``` Do not run normal startup, ordinary adaptive handoff, scheduler, task-mirror refresh, archive, or finalize during an intermediate phase. `decision:ask` remains advisory and adds no gate. If resume returns `replan_planner_dispatch_required`, dispatch the genuine `workflow-planner` profile in its Re-plan dispatch mode with only the repository root, project, `transaction_id`, `dispatch_nonce`, profile identity, the exact `.cache/replan-planner-packet.json` path, and its reason/source evidence. No role sequence, node ids, dependencies, write sets, cardinality, shape, model, or exact DAG fragment may come from the orchestrator; that is `planner_control_boundary_violation`. The planner alone writes the seeded `workflow-plan.next.md` plus `.cache/replan-planner-attestation.json`, and main then invokes the same resume command. Missing or mismatched proof is `replan_planner_attestation_invalid`. An invalid child uses the bounded unfrozen child-repair loop with the same planner and verbatim validator errors; the main session never repairs the child DAG. At the bound, stop with typed evidence—never start another claim or path. A verified legacy-v1 parent enters its schema-2 child through this transaction; normal startup and other legacy behavior remain unchanged. Phase-0 of the adaptive path: the agent **freely authors** a task-shaped DAG for *this* issue — which roles, how many, in what shape — into a `workflow-plan.md`. There is no template library and no knob-binding ceremony. Mirror of `commands/kaola-workflow-adapt.md` for the Codex runtime. Reads and updates `kaola-workflow/{project}/workflow-state.md`. Adaptive is the unconditional default; `fast`/`full` are explicit path-naming escapes, never an automatic fallback (see `kaola-workflow-next` Startup Step 0a-1). ## Reviewer Contract V2 Authoring Every newly authored plan declares `plan_schema_version: 2`. Never freeze a new draft with a missing version or `plan_schema_version: 1`. A verified already-frozen plan whose hash-covered Meta predates the version field is the only legacy case: route it byte-preserving as `contract_version: 1`, and never rewrite its plan, evidence vocabulary, or journal. If execution later emits `replan_required`, return that typed packet to the owning orchestrator; this authoring surface never thaws the frozen DAG or activates a replacement plan. Schema-2 `## Meta` records the complete validation policy: the exact `validation_command`, normalized `validation_cwd`, `validation_repetitions` from 1 through 5, `validation_pass_rule: all`, `validation_timeout_minutes` from 1 through 120, and a canonical sorted `validation_env_allowlist`. A code-producing plan requires both the command and timeout. Also record `code_certifier`, `security_certifier`, `inherited_frontier_digest`, and `inherited_frontier_classes`. Use `none` only when that class is absent; when authoritative handoff state supplies an inherited digest/classes pair, copy it exactly and never synthesize, drop, or change it. Use this schema-2 node header exactly: `| id | role | depends_on | declared_write_set | cardinality | shape | selector_source | model | wait_budget_minutes | observes | gate_claim | gate_surface | gate_aggregation | certifies |` Every review gate has a nonempty single-line `gate_claim` and `gate_surface`. `gate_aggregation` is `sequence` for a singleton, `replicated_majority` for replicas sharing one surface, or `partitioned_all` for members with distinct surfaces. The graph-derived mode is authoritative: a change-gate `adversarial-verifier` carries a canonical sorted `certifies` producer list, an investigation verifier carries an empty one, and code/security certifier producer sets remain validator-derived. Non-gate rows leave all four gate columns empty. Design a real common certifier wall for every required code/security frontier; branch-local reviewers do not satisfy the planner-designated certifier metadata. Compact-plan and exact-file write-set rules remain binding. ## The grammar (the closed envelope) Each node is one row of the `## Nodes` table: `| id | role | depends_on | declared_write_set | cardinality | shape | model |`. - **role** must be in the installed library (the nine canonical roles + any maintainer-installed role such as `adversarial-verifier`). The validator hard-rejects an unknown role. - **model** (optional) — declarative reasoning/wait-budget metadata from `{reasoning|standard}`. Every named Codex role profile omits model and effort so the child inherits the current parent session; this cell never selects child strength and never conflicts with a role's historical/default metadata class. The legacy `opus`/`sonnet` aliases remain accepted as `reasoning`/`standard`; new plans author neutral tokens. An out-of-vocab cell is a freeze refusal (`model_invalid`); a `main-session-gate` must not carry a model; absent/`—` resolves through the same role-static tier, and an unresolved card refuses as `codex_tier_unresolved`. - **shape** is exactly one of three productions: `sequence`, `fanout()` (N instances of one role over pairwise-disjoint declared write sets — author N as wide as the subtasks are genuinely independent; `FANOUT_CAP` caps only *runtime concurrency*, not authored width), or `loop()` (one role re-invoked up to a static cap; loops do not fan out). - **cardinality** is a **reserved / advisory** column: parsed but not validated or used (fan-out width is the row count in a `fanout()`); its text still feeds `plan_hash` as part of `## Nodes`, so keep the column present and stable. - A single unique `finalize` sink is mandatory — it makes the gate checks decidable. - A gate is a wall the validator finds in the graph: `code-reviewer` must **post-dominate** every implement node; `security-reviewer` must post-dominate every sensitive node. Not a flag the author can set. Capture the **frozen issue labels** into a `## Meta` `labels:` line (a non-author field) so the validator can derive sensitivity. ## Caps and the sink (fixed by the harness) `FANOUT_CAP` (default **4**) is a **runtime concurrency limit**, NOT a width bound on the authored plan: it is the maximum number of `fanout()` siblings the executor dispatches at once — the executor opens up to `FANOUT_CAP` legs and drains the rest via rolling top-up (queue the overflow, top up as a slot frees). Author a fan-out as wide as the work is genuinely independent over disjoint write sets; the validator validates dependency shape / disjointness / gates / write-set safety, never width. `LOOP_CAP` (**5**; a loop must run at least once — `loop(0)` is a typed refusal). **There is no per-node file-count ceiling** — keep a cohesive write set in ONE node even when large (root-level + dot-leading paths count as real writes). **Write sets are EXACT file paths, never directories:** a directory / trailing-slash entry (`src/`) or a `..`-bearing token is **refused at freeze** (it is dead at the exact-match barrier); semantically-coupled cross-edition mirrors and generated-aggregator siblings stay in ONE node (they move atomically), and a fan-out splits only genuinely-independent disjoint work — never a directory grant. > **The one shape the freeze wall cannot catch:** a **bare token naming a path that does NOT > exist at freeze but becomes a DIRECTORY by write-time** — the classic staged *scaffold→extend* plan > (the very shape the adaptive path is designed to author). The freeze-time bare-directory check > `statSync`s the token and skips a not-yet-created path as a legitimate new file, so a > `mymod` token that an earlier node turns into the directory `mymod/` slips through. It then dies at > the exact-path barrier as `write_set_granularity`, escalating a purely-mechanical artifact to a > consent halt (`revalidateForResume` carries **no** shape checks — no `statSync`/`isDirectory`/ > `directory_shaped` — so resume can never re-catch it either). **Always declare the EXACT files a > staged node will create (`mymod/a.js`, `mymod/b.js`), never a bare dir-to-be.** The unique **`finalize`** sink may only write docs/state (e.g. `CHANGELOG.md`); a non-docs write on the sink trips `code-reviewer`. ## A complete example (`workflow-plan.md`) Minimal in-grammar plan to copy and adapt — explore, a `planner` node that shapes and dominates the implements, two parallel `tdd-guide` implements over **disjoint top-level directories**, a `code-reviewer` that post-dominates both, a `doc-updater` for the changed docs, and the unique `finalize` sink. Being a write-role fan-out it routes to **ask**. ```markdown # Workflow Plan — issue # ## Meta labels: enhancement ## Nodes | id | role | depends_on | declared_write_set | cardinality | shape | |-----------|---------------|---------------------|--------------------|-------------|--------------| | explore | code-explorer | — | — | 1 | sequence | | plan | planner | explore | — | 1 | sequence | | impl-csv | tdd-guide | plan | exporter/csv.js | 1 | fanout(impl) | | impl-html | tdd-guide | plan | renderer/html.js | 1 | fanout(impl) | | review | code-reviewer | impl-csv, impl-html | — | 1 | sequence | | docs | doc-updater | review | docs/api.md | 1 | sequence | | finalize | finalize | review, docs | CHANGELOG.md | 1 | sequence | ``` Disjointness is checked at **top-level-directory** granularity, so fan-out siblings must live under different top-level directories. ## Shaping guidance (recommendations, not gates) The validator enforces only the **walls** — the unique `finalize` sink, G1 (`code-reviewer` post-dominates code-producing nodes), G2 (`security-reviewer` post-dominates sensitive nodes). Everything below is author judgment the grammar will **not** refuse; the example above models both. - **Plan before you build.** For a non-trivial implement, consider a `planner` (or `code-architect`) **node** that precedes — and so dominates — the implement nodes (the forward-reasoning roles). One `planner` above a fan-out's shared parent covers every leg (not one per leg). Trivial or mechanical work can skip it, or use the fast path. - **Update the docs you changed.** When the change touches README / API docs / architecture / a public interface, consider a `doc-updater` node before `finalize` — the sink only does CHANGELOG / state bookkeeping. - **Choose the right implement role.** Default to `tdd-guide`; pick `implementer` ONLY for an enumerated non-test-first category — behavior-preserving refactor; scaffolding / boilerplate / wiring; config / IaC / scripts; UI / markup; migrations / fixtures; integration glue — and RECORD which one (`non_tdd_reason`). Asymmetric tie-breaker: if a meaningful failing unit test CAN be written for the work, use `tdd-guide`; when in doubt, use `tdd-guide`. "Hard to test" is NOT a valid `non_tdd_reason`; bug fixes are ALWAYS `tdd-guide`. A mixed node (some sub-tasks test-first, some not) should be split into separate nodes by lane, or routed to the stricter role (`tdd-guide`). Both `tdd-guide` and `implementer` require `code-reviewer` post-dominance (G1); `implementer` is equal-burden, different-shape — it swaps RED→GREEN for change-type-appropriate verification (regression-green / build-green / executable smoke-integration), NOT a lighter path. - Author a `knowledge-lookup` node when the task depends on external library or API behavior, framework conventions, or open-web/expertise knowledge that cannot be confirmed from the local codebase alone. This mirrors the Phase 1 `knowledge-lookup` trigger. - **Provision gate instrumentation upstream, never in the gate.** When a `main-session-gate` needs instrumentation to execute (a probe scene/test/fixture, INCLUDING build wiring), author an upstream writer node (`tdd-guide`/`implementer`) to produce it inside ITS OWN declared write set; the gate never authors or deletes files, it only RUNS what was provisioned. State the durability decision in the plan: durable (committed, env-gated — preferred; the probe becomes a regression asset) or ephemeral (the deletion is likewise owned by a downstream writer/finalize node, with the path in THAT node's declared write set). Out-of-repo scratch stays legal for a gate whose harness can probe from an external path. ### Question-shaped & bug-shaped issues When the issue is a **question without a settled answer** ("which approach?", "is X viable?", "why does Y happen?"), the `workflow-planner` authors an **investigation**, not a build DAG around an unvalidated premise (which would launder the guess past the artifact-vs-plan verdict). The arc maps onto existing roles with **zero new grammar**: **probe → assume → adversarially critique → converge** — read-only `code-explorer`/`knowledge-lookup` probes (authored as a read-only fan-out, dispatched concurrently) → `planner` proposes 2–3 candidate answers, each with an explicit falsification test → `adversarial-verifier` (a separate subagent; read-only but has Bash, so for a bug it **runs the existing reproduction**) tries to refute the leading answer → `planner`/`synthesizer` converges. **Freeze-once split:** Case A (shape knowable, answer not) authors the whole DAG up front (or `select()` for the enumerable version); Case B (shape depends on findings — e.g. a flaky-bug diagnosis) runs a short read-only shaping epoch, then continues through the claim-preserving re-plan control plane into one immutable child epoch (new `plan_hash`, parent remains frozen). For a **bug**, the falsification criterion IS the reproduction ("root cause or symptom mask?"); cannot-reproduce-after-a-bounded-probe → the `consent`-halt valve (`write-halt --reason consent`), never a guess-fix. Escalate values, not facts; `decision:ask` stays advisory (no new gate). Full pattern: the `workflow-planner` profile. ## Front end: claim + author (the `workflow-planner` agent role) The adaptive path opens by delegating to ONE subagent. **You MUST delegate the starting contract and the DAG authoring to the `workflow-planner` agent role** — do NOT run the claim or author the `## Nodes` table inline in this session. The Codex Profile Freshness Gate above is authoritative: missing, stale, malformed, or shadowed project/global profiles are `profile_preflight_refused` and STOP before delegation. Only after that gate succeeds, if the runtime agent tool itself is genuinely unavailable or model-refuses the spawn, may this session run the claim + author inline; record that runtime evidence as `local-fallback-tool-unavailable` in the compliance ledger. The planner never freezes, judges risk, asks the user, or dispatches further — it returns control here. The persisted detection paths are `.codex/agents/kaola-workflow/` for a trusted project override and `~/.codex/agents/kaola-workflow/` for the global default; the preflight alone resolves precedence. The router enters with the agent-selected target issue for fresh adaptive work; the planner RETURNS the `{project}` used after. **Re-entry (unfrozen plan):** an *authored-but-NOT-frozen* plan (a prior governance refusal / declined ask / abort — no `plan_hash`) routes back here; SKIP the freshness gate + planner delegation and re-run the planner+handoff on the existing plan (the planner MAY overwrite an unfrozen plan; never a frozen one); the handoff freezes mechanically. A pre-freeze exit leaves a **resumable** project; `kaola-workflow-claim.js discard --project {project}` abandons it. **Entry guard (this session, before the delegation).** Run the **authoring guard**. It needs no project. Adaptive authoring is always allowed, so this returns `authoring_allowed: true`; the call preserves the mechanical gate shape and the planner's `startup` still routes the claim via `claimProject`: ```bash kaola_script(){ _n="$1"; _self=""; [ -f "./package.json" ] && _self="$(node -e "try{process.stdout.write(require(process.cwd()+'/package.json').name||'')}catch(e){}" 2>/dev/null)"; if [ "$_self" = "kaola-workflow" ]; then for _p in "./scripts/$_n" "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/scripts/$_n}" "$HOME/.claude/kaola-workflow/scripts/$_n"; do [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; done; else for _p in "${CLAUDE_PLUGIN_ROOT:+$CLAUDE_PLUGIN_ROOT/scripts/$_n}" "$HOME/.claude/kaola-workflow/scripts/$_n" "./scripts/$_n"; do [ -f "$_p" ] && { printf '%s\n' "$_p"; return; }; done; fi; return 1; } node "$(kaola_script kaola-workflow-claim.js)" authoring-allowed ``` If the JSON `status` is `authoring_refused`, surface the typed refusal and STOP. **Git freshness (BEFORE the claim).** If `authoring_allowed`, gate on a clean main *before* delegating: nothing is claimed yet — run the Startup git-freshness checks against the MAIN repo (`git pull --ff-only` if behind). If it cannot resolve cleanly (dirty, or a merge / rebase / stash / reset is needed), STOP and ask — do NOT delegate, so **no folder / `workflow:in-progress` label is created until git is clean** (the front end claims here at repo-root — the adaptive claim provisions a repo-local hidden worktree at `/.kw/worktrees//`, the same as full/fast paths; the planner authors + freezes at repo-root and does NOT itself cd into the worktree — so the router's post-claim freshness-block release no longer guards this path). **Co-tenant clean-check.** That dirty check disregards `kaola-workflow/*` and `.kw/*` scratch of OTHER active lanes (so a co-tenant session is not falsely refused) but still fails on any uncommitted code change; this session's own in-progress state stays enforced. Once main is clean, **delegate to the `workflow-planner`**: it runs `kaola-workflow-claim.js startup --runtime --workflow-path adaptive --target-issue --attest-planner-spawn` (`--workflow-path adaptive` is REQUIRED — a subagent shell does not inherit KAOLA_PATH; `--attest-planner-spawn` is REQUIRED on every planner-run startup — it back-fills the planner's own dispatch marker into .cache/dispatch-log.jsonl for closure attestation; only the dispatched workflow-planner passes it; add `--sink pr` only for a requested PR sink; on Codex, first run the same preflight doctor detection as `kaola-workflow-next`'s Codex Dispatch Mode Detection step and append `--codex-dispatch-mode ` when a mode was found — absent detection leaves the claim on its fail-closed `v1-thread-id` default), authors the `## Meta` + `## Nodes` DAG + empty `## Node Ledger` into the project's `workflow-plan.md` via Write, runs the validator `--json` as a self-check (NOT `--freeze`, NOT `authoring-allowed`), then RUNS `kaola-workflow-adaptive-handoff.js --project {project} --json` (freezes, resume-checks, stages roadmap, writes Planning Evidence; does NOT open node1 or record the node1 baseline — `kaola-workflow-plan-run` owns the full node lifecycle including the first node; decision:ask is recorded metadata, not a gate), and RETURNS the handoff packet. It never JUDGES risk or asks the user (decision:ask is recorded metadata); it RUNS the handoff, which freezes mechanically, and returns the packet; it never dispatches. If the project already has a `workflow-plan.md` it refuses-and-returns (never overwrite a frozen plan). On a claim refusal — any `claim_verdict` that is NOT `acquired`/`owned` — no `workflow-state.md` is written. Surface `claim_reasoning` and classify by `result`: - `result: refuse` (e.g. `workflow_path_refused`, `target_occupied`, `user_target_blocked`, `user_target_red`, `user_target_closed`, `target_unavailable`, `target_unverified`, or `claim: none`): **HARD STOP** (**fail closed** — do not retry a different issue, do not blind-read a missing state file). The determinate RED is final. - `result: escalate` (`target_indeterminate` / `target_set_indeterminate`): the classifier subprocess faulted and bounded retry is exhausted. **PAUSE and ASK THE USER** — offer to retry, pick a different target, go offline, or abort. This is NOT an `adaptive-node write-halt`; no plan/ledger exists yet at claim time. **Planner-first control boundary.** The main session performs ONLY the allowed non-design preflight above (read repo/session rules, confirm target issue, authoring-allowed check, git freshness, non-design target availability), then dispatches `workflow-planner` immediately as the first issue-specific action. The main session MUST NOT pre-author the `## Nodes` DAG, choose role sequence/deps/shapes/write-sets, or pass a mandatory full DAG / `AUTHOR EXACTLY` / `do not redesign` prompt to the planner — the adaptive front-end design is the planner's to own, not the main session's. Doing so earns a typed refusal: `planner_control_boundary_violation`. The ONLY exception is in the bounded unfrozen-plan validator-repair loop (after `handoff_status: plan_invalid` on an UNFROZEN plan): the orchestrator MAY re-dispatch the planner with the verbatim validator errors + the prior plan as repair context, because the planner already owns that unfrozen draft. Use direct v2 control-plane dispatch: ```yaml agents.spawn_agent: task_name: "workflow_planner_" agent_type: "workflow-planner" fork_turns: "none" message: "Repository root: . Selected issue/set/project: . Apply the kaola-workflow-adapt skill and workflow-planner profile contract. Return only the bounded durable handoff packet." ``` Sanitize the stable task suffix to lowercase letters, digits, and underscores. This is an isolated, self-contained control-plane brief; omit transient `model` and `reasoning_effort`, and never use `fork_turns: "all"`. Codex v1 keeps `fork_turns: "none"` and the established identity/header convention. The observed full-history rejection is an **argument-shape refusal**: correct the shape and retry the same workflow-planner role, task identity, isolated brief, and bounded durable return exactly once. Never author inline; reserve `local-fallback-tool-unavailable` for genuinely unavailable agent tooling. **Read the durable state, not the planner's prose.** On success take `{project}` from the return, re-read `kaola-workflow/{project}/workflow-state.md` (the `## Sink` block, `workflow_path: adaptive`) and `kaola-workflow/{project}/workflow-plan.md` (internalize the `## Nodes` DAG you govern, dispatch, and freeze). The claim (at repo-root — the adaptive claim provisions a worktree at `/.kw/worktrees//`; the planner authors + freezes at repo-root) was cut from a now-clean main (git-freshness ran before the claim, above). **Read the handoff packet.** The planner RAN `kaola-workflow-adaptive-handoff.js` and returned a checklist-backed packet (plan already frozen, Planning Evidence written; the handoff does NOT open node1 or record the node1 baseline — `kaola-workflow-plan-run` owns the full node lifecycle including the first node). The handoff is mechanical; `decision:ask` is audit metadata only — it freezes-and-proceeds, NEVER pauses for approval. - **`handoff_status: ready_to_run`** (all checklist true) → hand off DIRECTLY to `kaola-workflow-plan-run {project}` (even when `decision:ask`, no approval gate). `kaola-workflow-plan-run` owns the complete node lifecycle — it opens and dispatches every node including the first, via `kaola-workflow-adaptive-node.js`. - **`handoff_status: plan_invalid`** (validator refused; plan never froze, NOTHING written) → bounded **repair loop**: re-dispatch the `workflow-planner` with the verbatim `errors`/`validator_verdict` so it overwrites the UNFROZEN plan with a corrected DAG and re-runs the handoff. Retry ~2x (counter in the orchestrator, never in the script). After repeated failure (~2x) → real decision: **discard+restart a fresh adaptive run** (`kaola-workflow-claim.js discard --project {project}` then a fresh adaptive start) / **STOP + surface a concrete blocker** with validator evidence. This fallback applies only to normal startup while the draft is unfrozen; it is forbidden under `replan_in_progress`. NEVER downgrade to fast/full — there is no automatic fallback between paths; the only fallbacks are inside adaptive (bounded repair, in-place posture). Never silently loop. After `handoff_status: ready_to_run` (and ONLY then), re-read `kaola-workflow/{project}/workflow-plan.md` to internalize the frozen `## Nodes` table, then create the orchestrator's task list. **The task list MUST NOT be created before `handoff_status: ready_to_run` is confirmed and the frozen plan has been read** — the planner owns the design; the task list is a mechanical reflection of the frozen result, not a pre-planned outline. **Establish the task list = the workflow nodes** (use the runtime task surface) — one task per row of the frozen `## Nodes` table, labeled `id · role`, in `depends_on` order; a live mirror of the `## Node Ledger` (the durable source of truth) that the executor flips `in_progress` when it dispatches that node's role (after `open-next`) and `completed` after the commit step closes it (`n/a` nodes → skipped). Then hand off to `kaola-workflow-plan-run {project}`. ## Bundle Lane — Multi-Issue Adaptive Claim When the router delivers a same-scope bundle (explicit-bundle or auto-bundle mode — see `kaola-workflow-next` Bundle Lane section), the `workflow-planner` runs the bundle claim instead of the single-issue claim. The issue set was already selected and stated by the main orchestrator; the planner validates and claims it. ### Bundle startup call The planner passes `--target-issues A,B,C` (sorted ascending, comma-separated) instead of `--target-issue N`. On Codex, detect `KAOLA_CODEX_DISPATCH_MODE` first (the same preflight doctor detection as the single-issue claim above), then pass it through: ```bash KAOLA_DISPATCH_MODE_FLAG="" [ -n "${KAOLA_CODEX_DISPATCH_MODE:-}" ] && KAOLA_DISPATCH_MODE_FLAG="--codex-dispatch-mode $KAOLA_CODEX_DISPATCH_MODE" node "$claim_script" startup \ --runtime codex \ --workflow-path adaptive \ --target-issues 42,47,53 \ --attest-planner-spawn \ $KAOLA_DISPATCH_MODE_FLAG ``` Compatibility rule: `--target-issue` / `KAOLA_TARGET_ISSUE` keep current one-issue behavior unchanged. `--target-issues` / `KAOLA_TARGET_ISSUES` are the ONLY multi-issue startup path. If both are set, the script refuses with `target_ambiguity`; never pass both. ### Bundle project and branch shape - Active folder (project name): `bundle-42-47-53` (sorted ascending, deduplicated). - Branch: `workflow/bundle-42-47-53`. - `workflow-state.md` records the primary issue as `issue_number: 42` plus three additive bundle fields: `issue_numbers: 42,47,53`, `bundle_id: bundle-42-47-53`, `closure_policy: all_or_nothing`. ### Bundle is adaptive-only The bundle lane requires `workflow_path: adaptive`. The startup script refuses with `bundle_requires_adaptive` when the path is `fast` or `full`. ### Bundle authoring The planner receives the full issue set and authors ONE implementation-lane DAG in `workflow-plan.md` — not a mechanical one-node-per-issue plan. The `## Meta` block carries a conservative union of labels across all bundle issues so sensitivity and security gates are derived correctly. ### Bundle finalization (one closure for all) A bundle run ends at ONE finalization. The finalization step: - closes every issue in `issue_numbers` (all-or-nothing); - removes every corresponding `.roadmap/issue-N.md` source; - regenerates `kaola-workflow/ROADMAP.md` once; - archives one bundle folder; - produces one closure receipt recording `primary_issue`, `issue_numbers`, `closed_issues`, `failed_issue_closures`, and removed roadmap sources. ### Claim refusals (bundle-specific) | code | trigger | |------|---------| | `target_ambiguity` | both `--target-issue` and `--target-issues` set | | `target_set_empty` | issue list empty or missing | | `target_set_too_large` | list exceeds `KAOLA_BUNDLE_MAX_ISSUES` (default 4) | | `bundle_requires_adaptive` | `workflow_path` is not `adaptive` | | `target_set_conflicts_active_work` | any member is already claimed | | `target_set_has_closed_issue` | any member is already closed | | `target_set_red` | classifier returns `red` for any member | | `target_set_unavailable` | member state probe failed (online) | | `target_set_unverified` | member unverifiable (offline, no local evidence) | | `target_set_label_rollback_failed` | partial claim could not be fully rolled back | | `target_set_mismatch` | persisted `issue_numbers` in `workflow-state.md` does not match the claimed `--target-issues` set — startup validated the claim but the persisted state is inconsistent | On any bundle claim refusal, treat it the same as a single-issue claim refusal: surface the typed code and STOP; do not retry with a different issue set.