@dtlabs/ai-toolkit 0.12.0 → 0.14.0

package/docs/task-executor-bootstrap.md

@@ -0,0 +1,195 @@
+# Task Executor Bootstrap
+
+> Companion to [`docs/task-executor-cli.md`](task-executor-cli.md), which documents the CLI
+> contract (commands, flags, exit codes, JSON schema) in detail and is not repeated here. This
+> document covers the **operational** side: how a real operator/coordinator starts a run after
+> Gates 1/2, the Windows-only qualification that gates whether `start` will run at all, and the
+> persistence caveats an operator must know about before trusting a run's state — all pulled
+> from FTR-018's own approved artifacts and test findings, not restated from memory.
+
+---
+
+## 1. The supervised delivery procedure after Gates 1/2
+
+Once a feature's Requirements, Tech-Spec and Work Breakdown are approved (Gate 1 and Gate 2 both
+recorded in `{PREFIX}-Approvals.md`), the `implement-feature` skill's **Step 6 — Launch the task
+executor (Implementation Phase)** (`src/claude/skills/implement-feature/SKILL.md`) takes over.
+
+The key behavioral change from the retired `pm-phase3` model, as stated in Step 6 itself:
+
+- Implementation is **no longer dispatched as a subagent**. There is no `pm-phase3` workflow, no
+  Tier-1 dispatch guard, and no `pm-phase3:dispatch` ledger entry for this step.
+- Once Gate 2 is approved, the skill's job is limited to **presenting or launching one explicit
+  `task-executor` start command** — the executor process itself then owns the repo, plans,
+  executes, checkpoints and resumes tasks deterministically, independent of the chat.
+- **No subagent orchestrates the run, and no assistant or agent involvement is required for each
+  task transition once the run has started.** A single durable command launch is enough, and the
+  run may keep going, checkpointing and resuming, even after the launching conversation ends.
+
+Concretely (Step 6a), the skill builds:
+
+```bash
+ai-toolkit executor start \
+  --project . \
+  --feature <path-to-feature.md> \
+  --max-concurrency 1 \
+  --claude-path <resolved-claude-cli-path> \
+  --task-timeout-ms <task-timeout-ms, e.g. 900000> \
+  --agent-budget-usd <per-agent budget in USD, e.g. 5.00>
+```
+
+If the host's ordinary terminal capability can launch a durable external command, the skill
+launches it directly so the process persists independently of the chat. If not, it shows the
+exact command for the user to run themselves in a terminal — it does **not** fake a durable
+launch by running it as a blocking in-chat command.
+
+In both cases, the `run-id` printed by `start` must be captured — it is required for every
+subsequent `status`, `diagnose`, `stop`, `reconcile`, `resume`, and `replan` call; there is no
+implicit last-run selection.
+
+**The run may outlive the launching conversation.** The skill explicitly does not block on the
+run reaching a terminal state; it proceeds to its own Step 7 with whatever the latest status
+reports at that point. To check on a run later — from the same conversation, a new one, or no
+conversation at all — the operator uses the read-only `status` subcommand documented in
+`docs/task-executor-cli.md`:
+
+```bash
+ai-toolkit executor status --project <path> --run-id <uuid>
+```
+
+Note, per the CLI reference, that `status` (like `diagnose`) is currently a stub that always
+throws `NOT_IMPLEMENTED` (exit 1) — the command surface and its intended read-only summary shape
+(task status counts, run status, total cost from the ledger) are defined, but the real body has
+not been built yet (attributed there to `US-06-TASK-BE-01`). Until it lands, checking on a
+running or finished executor run means reading the ledger and per-run state directly, or using
+`reconcile`/`resume`, both of which are fully implemented and report each task's classification.
+
+For the full flag reference, exit-code table, and JSON result schemas of every subcommand
+(`start`, `status`, `diagnose`, `stop`, `reconcile`, `resume`, `replan`), see
+`docs/task-executor-cli.md` — this document intentionally does not restate that contract.
+
+---
+
+## 2. Windows-only E-02 qualification
+
+The executor's process-supervision guarantees — tree-kill of in-flight attempts, tag-based
+worker-liveness scanning, and immediate-stop confirmation — are proven for **Windows only**. This
+is FTR-018's Gate-1 binding constraint #3 (`FTR-018-Approvals.md`):
+
+> **E-02 is Windows-only qualified.** Other platforms require dedicated proofs before their
+> execution is enabled; no implicit cross-platform guarantee.
+
+This is not a paper constraint: `execute()` in `lib/task-executor/index.js` checks
+`process.platform !== 'win32'` as its **very first validation step** — before any other argument
+validation, before deriving the execution root, before touching the plan snapshot, and before
+acquiring the ownership lease — and throws `PLATFORM_NOT_QUALIFIED` (CLI exit code 7) on any
+non-Windows platform (US-08-TASK-BE-05, behaviorally tested by US-08-TASK-TEST-02's
+`platform-guard.test.js`, which asserts no agent dispatch and no worktree creation occur on a
+simulated non-win32 platform).
+
+In other words: there is **no implicit cross-platform guarantee, and no partial or best-effort
+execution on other platforms**. On any platform other than Windows, `start` refuses to run at
+all rather than degrading silently.
+
+---
+
+## 3. Persistence caveats
+
+These are the real, already-confirmed caveats and limitations discovered during this feature's
+own delivery. Each one is cited to its source rather than paraphrased from memory.
+
+### a. E-01 residual: worktree persistence not re-reproduced in the isolated proof run
+
+Per `FTR-018-Approvals.md`, Gate 1 section (OQ-01a / E-01 sub-point), the 2026-09-28 binding
+closure of the agent-provenance proof carries an explicit residual:
+
+> **Residual:** persistence not re-reproduced in this run (Write permission-denied); proven
+> separately by the original Test B.
+
+That is: the isolated 2026-09-28 proof run that closed the *definition-binding* question (verified
+agent-hash → loaded definition) did **not** itself re-demonstrate worktree persistence, because
+the Write tool was permission-denied in that isolated cwd. Persistence is proven by a separate,
+earlier proof (the original Test B referenced in the same evidence record), not by this run. An
+operator relying only on the E-01 dossier for "the whole chain is proven end-to-end in one run"
+should know that persistence and definition-binding were proven in two separate runs, not one.
+
+### b. Windows filesystem-race flake on atomic write (operational, not a code defect)
+
+`store.js`'s state persistence uses a temp-write-then-rename atomic-write protocol
+(`_atomicWriteFileSync` in `lib/task-executor/store.js`: open a same-directory exclusive temp
+file, write, `fsyncSync`, close, then `fs.renameSync(tmpPath, filePath)`). This is the same
+atomic-write discipline the executor's own production state persistence (`writeState`) relies on.
+
+**Operational note:** under heavy concurrent I/O load on Windows (e.g. many parallel Jest workers
+writing state files simultaneously), this rename step can occasionally hit a transient
+filesystem error (EPERM / rename race) that is environment-load-dependent rather than
+deterministic — it has not reproduced when run in isolation, and is not a defect in the
+atomic-write logic itself. Anyone operating or testing the executor under high Windows I/O
+contention should expect this as a known environmental characteristic, not treat an occasional
+transient failure of this shape as evidence of a code bug.
+
+### c. `resume()`/`reconcile()` only inspect and report — no automatic continuation
+
+Confirmed by US-07-TASK-TEST-01 (`tests/task-executor/sequential.test.js`, commit `25b2663`):
+
+> Finding, confirmed and NOT worked around: resume()/reconcile() only inspect and report - there
+> is currently no way to actually continue/finish an interrupted run (execute() always mints a
+> fresh runId and resets all tasks to pending). This is a known, explicit architecture gap, not a
+> bug - documented in the test file for any future work that wants to add real continuation.
+
+**Operator implication:** "resuming" a run today means safely inspecting what has already been
+durably completed and getting an evidence-based classification per task — it does **not** mean
+the interrupted run will automatically finish its remaining tasks. `execute()` always starts a
+brand-new run (a fresh `runId`, all tasks reset to pending); there is no run loop wired into
+`resume()`.
+
+### d. Dormant concurrency gap in `dispatchTaskAttempt` (must be resolved before N>1 wiring)
+
+Confirmed by US-08-TASK-TEST-01 (`tests/task-executor/parallel.test.js`, commit `2f06883`),
+Finding B:
+
+> a real, currently-dormant concurrency gap: two concurrent dispatchTaskAttempt calls requesting
+> the IDENTICAL, not-yet-existing attemptNumber for the same task both dispatch real subprocesses
+> - neither is rejected, only one attempt record persists, and its processIdentity is
+> byte-identical for both calls (derived only from runId/taskId/attemptNumber), so persisted state
+> cannot even reveal two real processes ran. Currently unreachable via any real production entry
+> point (execute()'s only caller dispatches one attempt at a time sequentially, and no N>1
+> orchestrator exists), but flagged prominently for whoever eventually wires real N>1 dispatch.
+
+**Operator implication:** this race cannot fire today because `execute()` is strictly
+sequential (`maxConcurrency=1` only; see docs/task-executor-cli.md — any other value is
+rejected as `UNSUPPORTED_CONCURRENCY`, never silently downgraded) and no orchestrator calls
+`dispatchTaskAttempt` concurrently. It is a **constraint that must be resolved before any future
+N>1 wiring work** lands, not something safe to rely on or ignore once that work begins.
+
+### e. Verification receipts already on disk are not consulted on resume (efficiency gap)
+
+Confirmed by US-09-TASK-TEST-01 (`tests/task-executor/fault-injection.test.js`, commit `e601e3d`),
+Finding 1:
+
+> there is no distinct durable state for "verification passed, review not yet dispatched" - a
+> crash in that exact window leaves reconcile() unable to tell it apart from "verification never
+> ran", so a resume may safely but redundantly re-run verification commands whose receipts are
+> already sitting on disk. Not an AC-10 violation (nothing is ever wrongly marked complete) - a
+> design/efficiency observation for a future decision, not fixed here.
+
+**Operator implication:** a resume after a crash in that narrow window is always *safe* (nothing
+is ever falsely marked complete), but may be redundant — it can re-run verification commands,
+including potentially expensive ones, that already passed and whose receipts already exist on
+disk.
+
+### f. N>1 parallel-execution primitives exist and are tested, but are not wired into `execute()`
+
+`createTaskWorktree`, `createSlotPool` (US-08-TASK-BE-01/02), `integrateAttempt`
+(`lib/task-executor/git.js`, US-08-TASK-BE-03) and `registerIntegratedSHA`
+(`lib/task-executor/store.js`, US-08-TASK-BE-04) are all real, already-implemented functions, and
+US-08-TASK-TEST-01's `parallel.test.js` exercises them together end-to-end for N=2/3 scenarios.
+But as that same commit's message states plainly:
+
+> there is no real "execute() with maxConcurrency=N" path yet (execute() still rejects anything
+> but N=1), so this proves the standalone primitives compose correctly rather than exercising a
+> not-yet-existing orchestrator.
+
+**Operator implication:** these primitives are proven to compose correctly in isolation, but
+`execute()` remains N=1 / sequential only. Do not expect `--max-concurrency` values other than
+`1` to do anything but fail fast with `UNSUPPORTED_CONCURRENCY` today.

package/docs/task-executor-cli.md

@@ -0,0 +1,319 @@
+# Task Executor CLI
+
+> Documents the **real, currently-implemented** behavior of `ai-toolkit executor <subcommand>`
+> (`bin/cli.js`'s `handleExecutorCommand`, wired to `lib/task-executor/index.js`), part of
+> FTR-018 (deterministic task execution, checkpoints and resume).
+>
+> This file describes what the code actually does today, not the aspirational CLI contract in
+> `FTR-018-Tech-Spec.md` section 10. Every discrepancy between the two is called out explicitly
+> below rather than silently reconciled.
+
+---
+
+## Invocation
+
+```bash
+ai-toolkit executor <subcommand> [flags]
+# or, inside this repo:
+node bin/cli.js executor <subcommand> [flags]
+```
+
+`--project <path>` is accepted by every subcommand and defaults to `process.cwd()` when omitted.
+All other flags are per-subcommand (see below). Any flag not explicitly recognized for a
+subcommand is silently ignored — there is no generic flag-forwarding path, so nothing reaches a
+filesystem path or lock primitive except the whitelisted flags read via `getFlag()`/`hasFlag()`.
+
+**Discrepancy vs. Tech-Spec:** section 10 documents `--format json or text (default)` as a
+common flag. The real CLI has no `--format` flag at all — `handleExecutorCommand` always emits
+JSON (`JSON.stringify(result, null, 2)`) on success and always emits JSON on error. There is no
+text-mode output in the current implementation.
+
+---
+
+## Commands
+
+### `start`
+
+```bash
+ai-toolkit executor start --project <path> --feature <path> [--max-concurrency N] [--claude-path <path>] [--task-timeout-ms <ms>] [--agent-budget-usd <amount>]
+```
+
+| Flag | Required | Default | Notes |
+|---|---|---|---|
+| `--project` | no | `process.cwd()` | Repo root; also resolves the common Git directory |
+| `--feature` | **yes** | — | Path to the feature's `feature.md`; the CLI usage-errors (exit 2, no JSON) if omitted |
+| `--max-concurrency` | no | `1` | Forwarded to `execute()` as a Number; only `1` is currently supported (see below) |
+| `--claude-path` | no | — | Absolute path to the qualified Claude CLI executable |
+| `--task-timeout-ms` | no | — | Forwarded as a Number |
+| `--agent-budget-usd` | no | — | Forwarded as a Number; persisted into run config, not itself enforced |
+
+Backs `lib/task-executor/index.js`'s `execute()`. Validates gates/config, acquires the
+repo-wide execution lease for a brand-new run, builds an immutable plan snapshot from the
+feature's own `{PREFIX}-Work-Breakdown.md/.csv`, and drives a sequential (slot count 1)
+dispatch → verify → review → checkpoint loop to completion or block.
+
+Only `maxConcurrency=1` is implemented — any other requested value is **rejected**
+(`UNSUPPORTED_CONCURRENCY`), never silently downgraded. `execute()` also refuses to run at all
+on any platform other than `win32` (see "Platform qualification" below), before touching any
+other validation.
+
+### `status`
+
+```bash
+ai-toolkit executor status --project <path> --run-id <uuid>
+```
+
+`--run-id` is required (usage error, exit 2, if omitted). Read-only summary of a run: task
+status counts, current run status, and total cost from the ledger.
+
+**Not implemented.** `status()` in `lib/task-executor/index.js` is currently a stub that always
+throws `NOT_IMPLEMENTED` (attributed to US-06-TASK-BE-01, which has not built its real body
+yet). Calling `ai-toolkit executor status` today always fails with exit code 1 and an error
+JSON body — it does not return the summary shape documented in its own JSDoc until that task is
+implemented.
+
+### `diagnose`
+
+```bash
+ai-toolkit executor diagnose --project <path> --run-id <uuid>
+```
+
+`--run-id` is required. Intended as a read-only detailed evidence dump (per-task/attempt
+evidence, ownership/lease state, repair suggestions).
+
+**Not implemented.** Same situation as `status`: `diagnose()` is a stub that always throws
+`NOT_IMPLEMENTED` (attributed to US-06-TASK-BE-02). Calling it today always exits 1 with an
+error JSON body.
+
+### `stop`
+
+```bash
+ai-toolkit executor stop --project <path> --run-id <uuid> [--mode graceful|immediate]
+```
+
+| Flag | Required | Default | Notes |
+|---|---|---|---|
+| `--run-id` | **yes** | — | |
+| `--mode` | no | `'graceful'` | Only `'graceful'` or `'immediate'` are accepted; anything else throws `STOP_VALIDATION_ERROR` |
+
+Persists a stop request and acknowledges receipt only — it never itself claims the run has
+stopped.
+
+- `graceful` (default): persists the request; the already-running `execute()` loop is the only
+  thing that actually enforces the block, at its next natural iteration boundary.
+- `immediate`: additionally attempts real termination of every in-flight attempt (stage
+  `dispatching`/`running` with a recorded process tag), via the same Windows-only tagged-process
+  tree-kill technique used elsewhere in this module, then polls for confirmed termination.
+
+Idempotent: if the run's current status is already `stopping` or settled
+(`completed`/`blocked`/`superseded`/`paused`), this call is a pure no-op and reports the
+originally-recorded mode.
+
+### `reconcile`
+
+```bash
+ai-toolkit executor reconcile --run-id <uuid> [--project <path>]
+```
+
+`--run-id` is required. `--project` resolves the execution root and the current-branch task ref
+automatically (via `git rev-parse --abbrev-ref HEAD` in the given `--project`, or its default,
+the current directory) — there is no separate flag for these; the CLI derives them itself.
+
+Reconciles persisted state and evidence for a run and classifies every task's current attempt.
+**Only repairs proven gaps — it never dispatches new work and never creates new integrations.**
+The only two repairs it can apply are: registering a commit SHA when a checkpoint-prepared
+attempt's tip exactly matches its own persisted checkpoint intent, and finalizing a task
+checkpoint when a committed attempt's registered SHA is confirmed reachable but the task's
+status was not yet advanced. Refuses to proceed (`COMPETING_COORDINATOR_LIVE` /
+`COMPETING_COORDINATOR_LIVENESS_UNKNOWN`) if a different, live-or-unknown-liveness coordinator
+holds the repo-wide execution lease.
+
+### `resume`
+
+```bash
+ai-toolkit executor resume --run-id <uuid> [--project <path>]
+```
+
+Same flags/derivation as `reconcile` (in fact the CLI dispatches both `reconcile` and `resume`
+through the identical flag-parsing branch, selecting the target function by subcommand name).
+Enforces the same "no live competing coordinator" precondition, then calls `reconcile()` to
+apply its repairs, then reports each task's current status plus the next-safe-action
+classification `reconcile()` already computed. Does **not** dispatch new work itself — there is
+no run loop wired into `resume()` yet (the real dispatch loop lives in `execute()`); its scope
+ends at "reconcile, then report what is safe to continue."
+
+### `replan`
+
+```bash
+ai-toolkit executor replan --run-id <uuid> --feature <path> [--project <path>] [--task-mapping-json '<json>']
+```
+
+| Flag | Required | Default | Notes |
+|---|---|---|---|
+| `--run-id` | **yes** | — | The original run being replanned |
+| `--feature` | **yes** | — | Path to the **successor** feature's `feature.md` (the approved successor plan) |
+| `--project` | no | `process.cwd()` | Resolves execution root + current-branch task ref, same as `reconcile`/`resume` |
+| `--task-mapping-json` | no | `'[]'` (empty array) | JSON array of `{oldTaskId, newTaskId}` objects |
+
+**Discrepancy vs. Tech-Spec:** the table in section 10 lists only `--run-id`/`--feature` for
+`replan`. The real `replan()` in `lib/task-executor/index.js` requires `args.taskMapping` to be
+an array (throwing `DISPATCH_VALIDATION_ERROR` otherwise) and never invents one itself. The CLI
+therefore added `--task-mapping-json` as a necessary extension beyond the literal table, using
+the same `--*-json` structured-input convention the `ledger` subcommand already established
+(`--metadata-json`). This is documented here as an intentional, flagged gap — not silently
+papered over — per the implementing agent's own note at the flag's parse site in `bin/cli.js`.
+Omitting the flag defaults to an empty mapping (a valid "no task carries forward" array), never
+a rejection.
+
+Grants **no approval itself** — the successor's Gate 2 approval must already exist on disk
+(`## Gate 2` heading in its `Approvals.md`, produced entirely outside the executor by the normal
+`implement-feature` gate protocol). Does not dispatch, start, or touch the successor run in any
+way. Validates the caller-supplied old→new task mapping against both the original run's recorded
+tasks and the successor's plan snapshot, computes carry-completion eligibility per pair
+(read-only), refuses if any original-run attempt's worker liveness is not confirmed dead
+(`LIVE_WORKER_BLOCKS_REPLAN`), then records the mapping as a durable intent and marks the
+original run `superseded`. Never deletes or rewrites any task/attempt evidence.
+
+---
+
+## Exit codes
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Successful operation/request |
+| 1 | Unexpected I/O (also the default for any unmapped/unknown error code) |
+| 2 | Invalid config/input |
+| 3 | Ownership/live worker conflict |
+| 4 | Evidence/plan/approval mismatch |
+| 5 | Worker/verification/review failure |
+| 6 | Integration conflict |
+| 7 | Runtime not qualified |
+| 8 | Paused awaiting human decision |
+
+This table matches `bin/cli.js`'s `EXECUTOR_EXIT_CODE_BY_ERROR_CODE` mapping (plus a
+suffix-based catch-all: any error code ending in `_VALIDATION_ERROR` maps to exit 2). A few
+notable groupings from that mapping:
+
+- **3** — every lease/ownership code: `LEASE_HELD`, `LEASE_NOT_OWNER`, `LEASE_STILL_LIVE`,
+  `LEASE_LIVENESS_UNKNOWN`, `LEASE_NOT_FOUND`, `GUARD_HELD`, `NO_LOCK_HELD`,
+  `COMPETING_COORDINATOR_LIVE`, `COMPETING_COORDINATOR_LIVENESS_UNKNOWN`,
+  `LIVE_WORKER_BLOCKS_REPLAN`.
+- **4** — every "plan/evidence/approval doesn't match" code, including
+  `SUCCESSOR_NOT_APPROVED`, `PLAN_NOT_FOUND`, `PLAN_PARSE_ERROR`, `REPLAN_UNKNOWN_TASK_MAPPING`,
+  `STATE_NOT_FOUND`/`STATE_TASK_NOT_FOUND`/`STATE_ATTEMPT_NOT_FOUND`, `TREE_MISMATCH`,
+  `RECEIPT_CONFLICT`, `INTENT_CONFLICT`, and many more (see the source comment for the full
+  list).
+- **5** — `CLAUDE_SPAWN_FAILED`, `AGENT_NOT_VERIFIED`, `RESOLUTION_FAILED`.
+- **6** — `INTEGRATION_CONFLICT`.
+- **7** — `PLATFORM_NOT_QUALIFIED` (see "Platform qualification" below).
+- **1 (default)** — includes `NOT_IMPLEMENTED` explicitly, so `status`/`diagnose` calls exit 1
+  today, not some special code.
+
+**Exit code 8 is a success-path outcome, never a thrown error** — unlike every other code
+above, which is assigned only on the error path via `mapExecutorErrorToExitCode`. Per the
+Tech-Spec, 8 means "paused awaiting human decision": `execute()`'s and `resume()`'s result
+objects can both legitimately carry `runStatus: 'paused'` (set when a `stop()` request — either
+mode — was observed at a loop boundary; `resume()` simply passes through whatever `runStatus`
+was last persisted, including `'paused'`). `handleExecutorCommand`'s shared `emitSuccess()`
+inspects `result.runStatus` and sets exit code **8** when it is `'paused'`, else **0** — this is
+a no-op check for `reconcile`/`stop`/`replan` (their result shapes never carry a `runStatus`
+field at all) and never applies to `status`/`diagnose` (still `NOT_IMPLEMENTED`, so they never
+reach the success path).
+
+---
+
+## JSON result schema
+
+### Success (stdout, exit matches the table above)
+
+Every command that has a real implementation returns a **versioned result object** —
+`{ protocolVersion, ... }` — written to stdout as pretty-printed JSON. Per
+`lib/task-executor/index.js`'s own JSDoc/return statements:
+
+**`start` (`execute()`) and `resume`:**
+```json
+{
+  "protocolVersion": 1,
+  "runId": "<uuid>",
+  "runStatus": "completed | blocked | paused",
+  "tasks": [ { "taskId": "US-01-T01", "status": "checkpointed" } ]
+}
+```
+`resume`'s object additionally carries `tasks[].nextAction` (the next-safe-action classification
+from `reconcile()`) and a top-level `repairsApplied` array — both additive beyond the minimum
+shape above.
+
+**`stop`:**
+```json
+{
+  "protocolVersion": 1,
+  "runId": "<uuid>",
+  "requestAccepted": true,
+  "mode": "graceful | immediate",
+  "idempotent": true,
+  "terminationConfirmed": true,
+  "killAttempts": [
+    { "taskId": "US-01-T01", "attemptNumber": 1, "processIdentity": "ai-toolkit-task:...", "confirmed": true }
+  ]
+}
+```
+`idempotent` is present only on an idempotent replay. `terminationConfirmed`/`killAttempts` are
+present only for a newly-accepted `immediate` request — never for `graceful`, never for an
+idempotent replay.
+
+**`reconcile`:**
+```json
+{
+  "protocolVersion": 1,
+  "runId": "<uuid>",
+  "repairsApplied": [ { "taskId": "US-01-T01", "action": "registerCommitSHA" } ],
+  "classifications": [ { "taskId": "US-01-T01", "classification": "...", "action": "..." } ]
+}
+```
+
+**`replan`:**
+```json
+{
+  "protocolVersion": 1,
+  "originalRunId": "<uuid>",
+  "successorPlanDigest": "<digest>",
+  "taskMapping": [
+    { "oldTaskId": "US-01-T01", "newTaskId": "US-01-T01", "carriesCompletion": true }
+  ]
+}
+```
+
+**`status`/`diagnose`:** no success shape exists yet — both are `NOT_IMPLEMENTED` stubs (see
+above); every call surfaces the error shape below with `code: "NOT_IMPLEMENTED"`.
+
+### Error (stderr, exit per the table above)
+
+```json
+{
+  "status": "error",
+  "code": "NO_LOCK_HELD",
+  "message": "dispatchTaskAttempt: no repo-wide execution lease held by runId \"...\" at ..."
+}
+```
+
+This is `bin/cli.js`'s real `emitError()` shape: `code` falls back to `'UNKNOWN'` if the thrown
+error carries no `.code`; `message` falls back to `String(err)` if the error carries no
+`.message`.
+
+A malformed CLI invocation (e.g. missing a required flag) is a **usage error**, not one of the
+JSON error shapes above: it writes a plain `Error: <message>` line to stderr and sets exit code 2
+directly, without going through `mapExecutorErrorToExitCode`.
+
+---
+
+## Platform qualification
+
+`execute()` checks `process.platform !== 'win32'` as its very first validation step — before any
+other argument validation, before deriving the execution root, before touching the plan
+snapshot, and before acquiring the ownership lease — and throws `PLATFORM_NOT_QUALIFIED` (exit
+7) on any non-Windows platform. This reflects FTR-018's Gate-1 binding constraint: the E-02
+process-supervision evidence (tree-kill via `taskkill`, tag-based liveness scanning via
+`Win32_Process` CIM queries) that the executor's crash-recovery/stop/worker-liveness machinery
+depends on is qualified for Windows only (US-08-TASK-BE-05). There is no implicit
+cross-platform guarantee — other platforms require their own dedicated qualification proof
+before `start` will run on them at all.

package/docs/workflow-control-plane.md

@@ -0,0 +1,95 @@
+# Deterministic workflow control plane
+
+The toolkit owns workflow execution in Node. An LLM is used only for document
+generation, review, and assessment. A workflow script is not a registered worker
+agent: never pass `pm-phase1`, `pm-phase2`, `pm-phase3`, `am-phase1`, or `am-phase2`
+to `agentType`, `subagent_type`, or Claude's `--agent`.
+
+## Invocation
+
+Reinstall the toolkit runtime assets after upgrading the package. The host rejects
+older installed workflows without `controlPlaneVersion: 1`, even if their old
+manifest hashes match. Use one installation scope (local or global); ambiguous or
+unverified agent installations fail closed.
+
+```text
+ai-toolkit workflow run pm-phase1 --project . --claude-path "C:\path\claude.exe" -- "internal_docs/features/FTR-123-example/feature.md"
+ai-toolkit workflow run pm-phase2 --project . --claude-path "C:\path\claude.exe" -- "internal_docs/features/FTR-123-example/feature.md"
+ai-toolkit workflow run am-phase1 --project . --claude-path "C:\path\claude.exe" -- . --scope=security,devops --prefix ASSESS-123
+ai-toolkit workflow run am-phase2 --project . -- --prefix ASSESS-123 --flagged INT-001 --ack "Reviewed by the user"
+```
+
+Resolve the actual Claude executable as described in `task-executor-bootstrap.md`.
+`--home DIR` is available for explicit installation-scope resolution. Paths are
+individual argv elements, never interpolated shell commands. Raw string arguments
+in the JavaScript API support quoted paths and preserve Windows backslashes.
+
+Exit 0 returns a JSON payload on stdout. A nonzero exit stops the pipeline; do not
+present the next approval gate. Gate 1/Gate 2 and Findings Gate decisions remain in
+the main loop. `am-phase2` requires explicit acknowledgement and a validated
+intervention selection; it does not invent approval.
+
+`pm-phase3` is a retired compatibility entry point and refuses execution. Since
+FTR-018, implementation belongs to `ai-toolkit tasks start/run`, with its task
+ownership, checkpoints, verification, review and resume protocol. The old workflow
+must not provide a fallback execution path. No JobScheduler feature is involved
+in this migration.
+
+## Audit and replacements
+
+| Original location | Deterministic operation formerly delegated to `agent()` | Replacement |
+|---|---|---|
+| pm-phase1 | agent resolution; self/worker ledger open/close | Verified host dispatch and owned activity lifecycle |
+| pm-phase1 | feature discovery, prefix, existence/mtime checks, ledger creation | Direct filesystem operations; freshness includes upstream documents; corrupt ledgers are preserved and rejected |
+| pm-phase1 | validation report existence/fabrication, process log writes | Require a nonempty fresh report from the validator; append log directly; structured validation verdict |
+| pm-phase2 | resolution and ledger operations | Same host lifecycle; unsuccessful results cannot close the owner as done |
+| pm-phase2 | validator/renderer execution, exit/output parsing and file checks | Toolkit CLI subprocess, `shell: false`, argv arrays, actual exit status, JSON parsing and disk reads |
+| pm-phase2 | raw pricing read, WB metrics, Token/Effort estimates, process log | Direct JSON reads and deterministic templates; unavailable usage/cost stays unavailable |
+| pm-phase3 | resolution, all ledger mutations, raw CSV/ledger/pricing reads, issue counts, test/git/PR commands, actuals writes | Legacy execution removed; implementation and CSV parsing already belong to the FTR-018 executor |
+| am-phase1 | discovery CLI, catalog/file reads, scope filtering, estimates/index counts | Canonical assessor map, verified resolution, strict scope filtering and deterministic Markdown parsing/templates |
+| am-phase2 | approval file, intervention selection, registry read/write/counts | Deterministic recorder with explicit input and readback |
+| FTR-018 process helper | worker identity cache and dispatch identity | Reject orchestrators; require requested canonical ID/native name agreement; cache by project + home + ID |
+
+Architecture, concurrency and quality have dedicated assessors. Security, DevOps,
+domain-model and dependencies use the generic assessor with explicit scope
+instructions. Multiple generic scopes are combined into one dispatch to avoid
+parallel writers overwriting the same report. Remediation agents are recommendations
+in intervention documents only; they are never used as assessors.
+
+## Identity, state and ownership
+
+Worker resolution checks the canonical catalog ID, verified status, exact native
+name, current definition hash, agent frontmatter name/model, and worker kind.
+Workflow resolution is separate and can never authorize worker dispatch.
+
+Every invocation has a unique owner and activity IDs. A per-prefix lock prevents
+two workflow runs from writing the same feature/assessment concurrently. The owner
+opens before work, drains parallel workers, validates outputs and serializes the
+result before its terminal transition. Worker usage and provenance are persisted.
+Legacy `open/close/fail/skip/finalizeActivity` calls cannot mutate owned entries;
+owned finalization requires the matching owner and a running entry. No name-only
+fallback is used for owned transitions. Later invocations cannot reopen an old run.
+
+The ownership token prevents accidental cross-finalization, not hostile filesystem
+access: workers and the host still run under the user's OS account. This is not a
+security sandbox.
+
+A caught failure produces `failed`. A hard OS/process kill can leave `running`,
+never a speculative `done`; workflow automatic resume/reconciliation is not added
+by this change. Retrying uses a new owner and preserves the interrupted record.
+If persistence itself fails, the error propagates rather than reporting success.
+
+## Verification and limits
+
+Regression tests execute the installed workflow source through the real host,
+resolver, filesystem and ledger. Integration tests invoke the actual structural
+validator/renderer and workflow CLI; LLM workers are deterministic test doubles.
+Coverage includes worker failure, missing outputs, corrupt ledger, late terminal
+calls, parallel rejection/drain, identity mismatch, cross-project cache leakage,
+negative semantic verdict, unknown scopes, paths with spaces and explicit approval.
+
+The live paid Claude model/permission flow has not been exercised by these tests.
+The subprocess adapter reuses FTR-018's existing qualification; no new cross-platform
+process-supervision guarantee is claimed. On Windows, the full executor test suite
+requires Git Bash ahead of the WSL launcher in PATH. User-level installations are
+not modified by running the isolated test fixtures.