@dtlabs/ai-toolkit 0.13.0 → 0.14.1

package/CHANGELOG.md

@@ -1,4 +1,56 @@
 ## 0.1.4 (2026-07-21)
+## [0.14.1](https://github.com/dtlab-tech/ai-toolkit/compare/v0.14.0...v0.14.1) (2026-09-30)
+
+
+### Bug Fixes
+
+* **workflows:** make gaia-validate-feature-docs a single-pass, host-owned validator ([2721088](https://github.com/dtlab-tech/ai-toolkit/commit/27210884375c7302cfcf84433d3da3412c857cc1))
+* **workflows:** single-pass, host-owned document validator ([2b606fb](https://github.com/dtlab-tech/ai-toolkit/commit/2b606fb2d0df54e244abe473ea81b613eda30537))
+
+## [0.14.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.13.0...v0.14.0) (2026-09-30)
+
+
+### Features
+
+* **FTR-018:** add agent provenance verification via agents resolve ([27fce79](https://github.com/dtlab-tech/ai-toolkit/commit/27fce7943bda58c546528e839fd83c7c7b2ee1ce))
+* **FTR-018:** add checkpoint intent persistence ([27332e3](https://github.com/dtlab-tech/ai-toolkit/commit/27332e3a38ece600af2f3c3964637dc5f09a5607))
+* **FTR-018:** add Claude subprocess adapter with result validation ([ddcfcd0](https://github.com/dtlab-tech/ai-toolkit/commit/ddcfcd07de8253465a4faf98805956491457706c))
+* **FTR-018:** add commit creation with task trailers ([b11c5af](https://github.com/dtlab-tech/ai-toolkit/commit/b11c5afd995b30c3c8ff136e1449d9c94397e1e7))
+* **FTR-018:** add controlled staging with path enumeration ([81cdc26](https://github.com/dtlab-tech/ai-toolkit/commit/81cdc26904191f189eb9aefc5f86941857368db7))
+* **FTR-018:** add cooperative and immediate stop modes ([2a410ba](https://github.com/dtlab-tech/ai-toolkit/commit/2a410ba0b28d6fdfa9369b439a10e098a250bdf0))
+* **FTR-018:** add DAG validation and cycle detection ([ae08348](https://github.com/dtlab-tech/ai-toolkit/commit/ae0834872f41e339d68a43088c229d6185528d2b))
+* **FTR-018:** add evidence evaluation per edge-cases table ([767a9e0](https://github.com/dtlab-tech/ai-toolkit/commit/767a9e040c6600ae6e7ce81816454bde9923c7ea))
+* **FTR-018:** add exclusive lease protocol ([68f42d1](https://github.com/dtlab-tech/ai-toolkit/commit/68f42d14b87ac6c2672415307248e5a47fada574))
+* **FTR-018:** add executor CLI commands to bin/cli.js ([6b59e65](https://github.com/dtlab-tech/ai-toolkit/commit/6b59e650aebe73b47593c7ee24ed2b803468e53c))
+* **FTR-018:** add executor state protocol (store.js) with versioned schema and atomic writes ([f6d989b](https://github.com/dtlab-tech/ai-toolkit/commit/f6d989b42796d8e37099770e2ebc7fa4f282cab3))
+* **FTR-018:** add ledger finalizeActivity for executor task completion ([be6187a](https://github.com/dtlab-tech/ai-toolkit/commit/be6187aead37c0ab7caf956be867df45c5db8fae))
+* **FTR-018:** add N-limit concurrency control and slot reservation ([6f6cfae](https://github.com/dtlab-tech/ai-toolkit/commit/6f6cfae15d47b6f7f371168bc1ef91db12091236))
+* **FTR-018:** add ownership guard for atomic lease transitions ([a2da308](https://github.com/dtlab-tech/ai-toolkit/commit/a2da3080c5bed54e375a5ce1467a2cc01b0482b7))
+* **FTR-018:** add plan snapshot with content digest ([512bfbf](https://github.com/dtlab-tech/ai-toolkit/commit/512bfbfa6d097d52f7e913f1be16031dd2f214fa))
+* **FTR-018:** add platform qualification guard (Windows-only) ([96c09a0](https://github.com/dtlab-tech/ai-toolkit/commit/96c09a0d00280f8a5893cdaa7bc2a1a190247f9c))
+* **FTR-018:** add replan command with approval validation ([094ef1a](https://github.com/dtlab-tech/ai-toolkit/commit/094ef1a683f91f33350feb314d02adcc932a7e66))
+* **FTR-018:** add resume and reconcile command logic ([be3d9a0](https://github.com/dtlab-tech/ai-toolkit/commit/be3d9a078b00666db8e9521e7e9c714c58f97554))
+* **FTR-018:** add review agent dispatch ([0a463e6](https://github.com/dtlab-tech/ai-toolkit/commit/0a463e6346af977f4bee66bd8b9c443df40112c5))
+* **FTR-018:** add sequential executor main loop (execute()) ([32895ad](https://github.com/dtlab-tech/ai-toolkit/commit/32895ad387d509620d143ca03e63d692aa47f102))
+* **FTR-018:** add serial integration with dispatch-order sequencing ([9681bb7](https://github.com/dtlab-tech/ai-toolkit/commit/9681bb7c853c4c42644a05e6a37fd424ec5e4c0b))
+* **FTR-018:** add stable topological scheduler for task ordering ([63ba632](https://github.com/dtlab-tech/ai-toolkit/commit/63ba632bcccb2ba9996836cf9280e5facec819c6))
+* **FTR-018:** add stale lock detection with process liveness ([391295c](https://github.com/dtlab-tech/ai-toolkit/commit/391295c862ac76e4def7ad6d74fcaac6f2cceb69))
+* **FTR-018:** add task dispatch orchestration ([429c892](https://github.com/dtlab-tech/ai-toolkit/commit/429c892d9f6d2b1b9c53bb2987a8104775e873f3))
+* **FTR-018:** add task-executor module skeleton (index.js) ([339fd57](https://github.com/dtlab-tech/ai-toolkit/commit/339fd5708aa02e55cddc8759be13de05b34aa367))
+* **FTR-018:** add verification command executor ([f03a342](https://github.com/dtlab-tech/ai-toolkit/commit/f03a3425144c3d807e30884874f55e5c76ad6e4b))
+* **FTR-018:** add Work Breakdown CSV parser and phase mapping ([84830ac](https://github.com/dtlab-tech/ai-toolkit/commit/84830ac35ca02615c628d6bd1a96c7cbc2dcc6ff))
+* **FTR-018:** add Work Breakdown Markdown parser (plan.js) ([b26ef0e](https://github.com/dtlab-tech/ai-toolkit/commit/b26ef0e2d949ab4d11278266e67ae8c57565de0c))
+* **FTR-018:** document executor CLI contract; fix unreachable exit code 8 ([3e7a02b](https://github.com/dtlab-tech/ai-toolkit/commit/3e7a02bb341dc8e98f964299b54427eedd06a1f2))
+* **FTR-018:** integrate executor into implement-feature skill ([24eb4cd](https://github.com/dtlab-tech/ai-toolkit/commit/24eb4cdacb477aeed2008199dbe44b56f29d16ce))
+* **runtime:** add deterministic workflow host and owned ledger lifecycle ([aa3c350](https://github.com/dtlab-tech/ai-toolkit/commit/aa3c3503a676c77ff3c76019464a738f8bbc060e))
+
+
+### Bug Fixes
+
+* **FTR-018:** fix CI failures on Linux (ubuntu-latest / GitHub Actions) ([7054af9](https://github.com/dtlab-tech/ai-toolkit/commit/7054af9eb4f9109063c0254fe29df75fcabe5a4e))
+* **workflows:** deterministic workflow control plane and owned ledger lifecycle ([aec810f](https://github.com/dtlab-tech/ai-toolkit/commit/aec810f2b93b2ccbb38034e66c0d25897f621298))
+* **workflows:** replace LLM control-plane wrappers with deterministic operations ([603ec2f](https://github.com/dtlab-tech/ai-toolkit/commit/603ec2fd197e3e381362ef2fc974977b45b56798))
+
 ## [0.13.0](https://github.com/dtlab-tech/ai-toolkit/compare/v0.12.0...v0.13.0) (2026-09-09)
 
 

package/bin/cli.js

@@ -1876,7 +1876,9 @@ async function main() {
     return;
   }
 
-  if (argv[0] === '--local') {
+  if (argv[0] === 'workflow') {
+    await require('../lib/workflow-runner').main(argv.slice(1));
+  } else if (argv[0] === '--local') {
     await installLocal(argv[1] || '.', force, dryRun);
   } else if (argv[0] === '--global') {
     const homeIdx = argv.indexOf('--home');
@@ -2021,7 +2023,7 @@ async function main() {
         process.stderr.write(`Error spawning script: ${result.error.message}\n`);
         process.exit(1);
       }
-      process.exit(result.status || 0);
+      process.exit(Number.isInteger(result.status) ? result.status : 1);
     } catch (err) {
       process.stderr.write(err.message + '\n');
       process.exit(1);
@@ -2111,6 +2113,8 @@ async function main() {
     await handleAgentsCommand(argv.slice(1));
   } else if (argv[0] === 'ledger') {
     handleLedgerCommand(argv.slice(1));
+  } else if (argv[0] === 'executor') {
+    await handleExecutorCommand(argv.slice(1));
   } else if (fs.existsSync(argv[0]) && fs.statSync(argv[0]).isDirectory()) {
     await installLocal(argv[0], force, dryRun);
   } else {
@@ -2554,6 +2558,365 @@ async function handleAgentsCommand(argv) {
   }
 }
 
+// ── executor CLI git-context helpers ─────────────────────────────────────────
+// US-09-TASK-INFRA-01 (FTR-018): lib/task-executor/index.js's execute()/stop()
+// take only `project` and derive commonDir/executionRoot themselves via their
+// own internal _resolveCommonGitDir/_currentBranchRef helpers — but
+// reconcile()/resume()/replan() take `executionRoot`/`projectDir`/`taskRef` as
+// SEPARATE, already-derived arguments instead. Neither internal helper is
+// exported from that module (module.exports there is deliberately narrow —
+// see its own export list), and this task's brief is explicit: do not modify
+// lib/task-executor/index.js. These two helpers duplicate that exact same
+// git-command technique (same argv, same error codes: GIT_SPAWN_FAILED,
+// GIT_REF_RESOLUTION_FAILED, EXECUTE_VALIDATION_ERROR for a detached HEAD) so
+// the CLI can compute the values reconcile/resume/replan need from the single
+// --project flag the Tech-Spec's CLI contract actually exposes for them.
+function _executorResolveCommonGitDir(projectDir) {
+  const { spawnSync } = require('child_process');
+  const res = spawnSync('git', ['rev-parse', '--git-common-dir'], {
+    cwd: projectDir, shell: false, encoding: 'utf8', windowsHide: true,
+  });
+  if (res.error || res.status !== 0) {
+    const err = new Error(
+      'executor: failed to resolve the common Git directory for "' + projectDir + '": ' +
+        (res.error ? res.error.message : (res.stderr || '').trim())
+    );
+    err.code = 'GIT_SPAWN_FAILED';
+    throw err;
+  }
+  return path.resolve(projectDir, res.stdout.trim());
+}
+
+function _executorExecutionRoot(projectDir) {
+  return path.join(_executorResolveCommonGitDir(projectDir), 'ai-toolkit', 'execution');
+}
+
+function _executorCurrentBranchRef(projectDir) {
+  const { spawnSync } = require('child_process');
+  const res = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+    cwd: projectDir, shell: false, encoding: 'utf8', windowsHide: true,
+  });
+  if (res.error || res.status !== 0) {
+    const err = new Error(
+      'executor: failed to resolve the current branch for "' + projectDir + '": ' +
+        (res.error ? res.error.message : (res.stderr || '').trim())
+    );
+    err.code = 'GIT_REF_RESOLUTION_FAILED';
+    throw err;
+  }
+  const name = res.stdout.trim();
+  if (name === 'HEAD') {
+    const err = new Error(
+      'executor: "' + projectDir + '" has a detached HEAD — a task ref cannot be derived automatically'
+    );
+    err.code = 'EXECUTE_VALIDATION_ERROR';
+    throw err;
+  }
+  return name;
+}
+
+// ── executor exit-code mapping ───────────────────────────────────────────────
+// FTR-018-Tech-Spec.md section 10 defines a FIXED 9-value exit-code enum for
+// the executor CLI (0 success; 1 unexpected I/O; 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) — but the lib/task-executor/*.js
+// + lib/execution-ledger.js + lib/agent-registry.js modules underneath it
+// collectively throw several dozen distinct `err.code` values. This table is
+// the single explicit, documented judgment call synthesizing all of them into
+// the fixed enum; it does not re-derive or duplicate the underlying modules'
+// own validation, it only classifies their already-thrown codes for exit
+// status purposes. Grouping rules, in the order applied:
+//
+//   3 (ownership/live worker conflict) — every lease/ownership-lock code, and
+//     every code meaning "a competing coordinator or live worker exists":
+//     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 (evidence/plan/approval mismatch) — everything meaning "the plan,
+//     approval, or recorded evidence does not match what was expected",
+//     including "expected evidence/record could not be found" (same bucket as
+//     PLAN_NOT_FOUND, per this task's own brief) and immutable-record replay
+//     conflicts (a conflicting second decision is itself an evidence
+//     mismatch, not an I/O failure): SUCCESSOR_NOT_APPROVED,
+//     SUCCESSOR_PLAN_NOT_FOUND, PLAN_NOT_FOUND, PLAN_PARSE_ERROR,
+//     REPLAN_UNKNOWN_TASK_MAPPING, ATTEMPT_NUMBER_MISMATCH,
+//     STATE_READBACK_MISMATCH, STATE_NOT_FOUND, STATE_TASK_NOT_FOUND,
+//     STATE_ATTEMPT_NOT_FOUND, STATE_TASK_EXISTS, TREE_MISMATCH,
+//     PARENT_MISMATCH, COMMIT_REINSPECTION_MISMATCH,
+//     INTEGRATION_PARENT_MISMATCH, INTEGRATION_REINSPECTION_MISMATCH,
+//     INTEGRATION_WORKTREE_STATE_MISMATCH, INTEGRATION_WORKTREE_NOT_CLEAN,
+//     INTEGRATION_SOURCE_NOT_FOUND, INTEGRATION_SOURCE_NOT_ON_BRANCH,
+//     UNEXPECTED_INDEX_CHANGE, STAGING_MISMATCH, DEFINITION_HASH_MISMATCH,
+//     SHA_REGISTRATION_CONFLICT, SHA_REGISTRATION_STAGE_ERROR,
+//     INTEGRATION_SHA_CONFLICT, INTEGRATION_SHA_STAGE_ERROR,
+//     CHECKPOINT_INTENT_STAGE_ERROR, RECEIPT_CONFLICT, RECEIPT_NOT_FOUND,
+//     INTENT_CONFLICT, INTENT_NOT_FOUND, METADATA_CONFLICT,
+//     ACTIVITY_NOT_FOUND, TERMINAL_CONFLICT.
+//
+//   5 (worker/verification/review failure) — the dispatched agent/worker
+//     process itself failed, could not be verified, or could not be spawned:
+//     CLAUDE_SPAWN_FAILED, AGENT_NOT_VERIFIED, RESOLUTION_FAILED.
+//
+//   6 (integration conflict) — INTEGRATION_CONFLICT.
+//
+//   7 (runtime not qualified) — PLATFORM_NOT_QUALIFIED.
+//
+//   2 (invalid config/input) — every *_VALIDATION_ERROR code (there are many;
+//     matched by suffix in mapExecutorErrorToExitCode below rather than
+//     enumerated one-by-one), plus UNSUPPORTED_CONCURRENCY (Tech-Spec:
+//     "reject, never downgrade"), CLAUDE_EXECUTABLE_NOT_FOUND ("unsupported
+//     executable ... fail before mutation"), UNKNOWN_AGENT_TYPE,
+//     METADATA_RESERVED_FIELD, METADATA_UNKNOWN_KEY, INVALID_STATUS.
+//
+//   1 (unexpected I/O) — the DEFAULT for everything else, including every
+//     *_CORRUPTED/CORRUPT_* code, every GIT_*_FAILED/*_FAILED git-command-
+//     spawn code, STATE_UNRECOVERABLE, and — explicitly, per this task's own
+//     brief — NOT_IMPLEMENTED. `status`/`diagnose` are still NOT_IMPLEMENTED
+//     stubs in lib/task-executor/index.js (attributed to US-06-TASK-BE-01/02,
+//     neither of which has actually built their real body yet); this CLI
+//     wires them through exactly like the other five commands and lets that
+//     error surface through this same mapping table honestly — it is not
+//     hidden or special-cased, it simply falls into the default bucket.
+//
+// 8 (paused awaiting human decision) has no throw site and is deliberately
+// absent from this table: execute()'s/resume()'s 'paused' run status is a
+// SUCCESS-path result field (returned, not thrown), so no error code maps to
+// exit 8 here. It is instead selected on the success path, in
+// handleExecutorCommand's own emitSuccess helper below, by inspecting
+// result.runStatus.
+const EXECUTOR_EXIT_CODE_BY_ERROR_CODE = {
+  // 3 — ownership / live worker conflict
+  LEASE_HELD: 3, LEASE_NOT_OWNER: 3, LEASE_STILL_LIVE: 3, LEASE_LIVENESS_UNKNOWN: 3,
+  LEASE_NOT_FOUND: 3, GUARD_HELD: 3, NO_LOCK_HELD: 3, COMPETING_COORDINATOR_LIVE: 3,
+  COMPETING_COORDINATOR_LIVENESS_UNKNOWN: 3, LIVE_WORKER_BLOCKS_REPLAN: 3,
+
+  // 4 — evidence / plan / approval mismatch
+  SUCCESSOR_NOT_APPROVED: 4, SUCCESSOR_PLAN_NOT_FOUND: 4, PLAN_NOT_FOUND: 4,
+  PLAN_PARSE_ERROR: 4, REPLAN_UNKNOWN_TASK_MAPPING: 4, ATTEMPT_NUMBER_MISMATCH: 4,
+  STATE_READBACK_MISMATCH: 4, STATE_NOT_FOUND: 4, STATE_TASK_NOT_FOUND: 4,
+  STATE_ATTEMPT_NOT_FOUND: 4, STATE_TASK_EXISTS: 4, TREE_MISMATCH: 4,
+  PARENT_MISMATCH: 4, COMMIT_REINSPECTION_MISMATCH: 4, INTEGRATION_PARENT_MISMATCH: 4,
+  INTEGRATION_REINSPECTION_MISMATCH: 4, INTEGRATION_WORKTREE_STATE_MISMATCH: 4,
+  INTEGRATION_WORKTREE_NOT_CLEAN: 4, INTEGRATION_SOURCE_NOT_FOUND: 4,
+  INTEGRATION_SOURCE_NOT_ON_BRANCH: 4, UNEXPECTED_INDEX_CHANGE: 4, STAGING_MISMATCH: 4,
+  DEFINITION_HASH_MISMATCH: 4, SHA_REGISTRATION_CONFLICT: 4, SHA_REGISTRATION_STAGE_ERROR: 4,
+  INTEGRATION_SHA_CONFLICT: 4, INTEGRATION_SHA_STAGE_ERROR: 4, CHECKPOINT_INTENT_STAGE_ERROR: 4,
+  RECEIPT_CONFLICT: 4, RECEIPT_NOT_FOUND: 4, INTENT_CONFLICT: 4, INTENT_NOT_FOUND: 4,
+  METADATA_CONFLICT: 4, ACTIVITY_NOT_FOUND: 4, TERMINAL_CONFLICT: 4,
+
+  // 5 — worker / verification / review failure
+  CLAUDE_SPAWN_FAILED: 5, AGENT_NOT_VERIFIED: 5, RESOLUTION_FAILED: 5,
+
+  // 6 — integration conflict
+  INTEGRATION_CONFLICT: 6,
+
+  // 7 — runtime not qualified
+  PLATFORM_NOT_QUALIFIED: 7,
+
+  // 2 — invalid config/input (non-*_VALIDATION_ERROR entries; every
+  // *_VALIDATION_ERROR code is matched by suffix in mapExecutorErrorToExitCode
+  // below rather than listed here)
+  UNSUPPORTED_CONCURRENCY: 2, CLAUDE_EXECUTABLE_NOT_FOUND: 2, UNKNOWN_AGENT_TYPE: 2,
+  METADATA_RESERVED_FIELD: 2, METADATA_UNKNOWN_KEY: 2, INVALID_STATUS: 2,
+
+  // 1 — unexpected I/O (explicit entries kept for documentation clarity even
+  // though 1 is also the default fallback below)
+  STATE_CORRUPTED: 1, RECEIPT_CORRUPTED: 1, INTENT_CORRUPTED: 1, LEASE_CORRUPTED: 1,
+  CORRUPT_LEDGER: 1, STATE_UNRECOVERABLE: 1, NOT_IMPLEMENTED: 1,
+  GIT_SPAWN_FAILED: 1, GIT_STATUS_FAILED: 1, GIT_ADD_FAILED: 1, GIT_WRITE_TREE_FAILED: 1,
+  GIT_DIFF_FAILED: 1, GIT_COMMIT_TREE_FAILED: 1, REF_UPDATE_FAILED: 1, GIT_CAT_FILE_FAILED: 1,
+  GIT_MERGE_BASE_FAILED: 1, GIT_REV_PARSE_FAILED: 1, GIT_CHERRY_PICK_FAILED: 1,
+  GIT_REF_RESOLUTION_FAILED: 1, INTEGRATION_CLEANUP_FAILED: 1,
+};
+
+function mapExecutorErrorToExitCode(code) {
+  if (typeof code === 'string' && Object.prototype.hasOwnProperty.call(EXECUTOR_EXIT_CODE_BY_ERROR_CODE, code)) {
+    return EXECUTOR_EXIT_CODE_BY_ERROR_CODE[code];
+  }
+  // Suffix-based catch-all for the many *_VALIDATION_ERROR codes
+  // (DISPATCH_VALIDATION_ERROR, LEASE_VALIDATION_ERROR,
+  // CLAUDE_PROCESS_VALIDATION_ERROR, STATE_VALIDATION_ERROR,
+  // STAGING_VALIDATION_ERROR, DETECT_CHANGED_PATHS_VALIDATION_ERROR,
+  // COMMIT_VALIDATION_ERROR, INTEGRATION_VALIDATION_ERROR,
+  // WORKTREE_VALIDATION_ERROR, SLOT_POOL_VALIDATION_ERROR,
+  // SHA_REGISTRATION_VALIDATION_ERROR, INTEGRATION_SHA_VALIDATION_ERROR,
+  // CHECKPOINT_INTENT_VALIDATION_ERROR, EXECUTE_VALIDATION_ERROR,
+  // STOP_VALIDATION_ERROR, and any future addition following the same naming
+  // convention) — every one of them means "malformed caller input", i.e.
+  // exit 2, without needing its own table row.
+  if (typeof code === 'string' && code.endsWith('_VALIDATION_ERROR')) {
+    return 2;
+  }
+  // Unknown/unmapped code, including a missing .code entirely: safe default.
+  return 1;
+}
+
+// ── executor dispatcher ───────────────────────────────────────────────────────
+// US-09-TASK-INFRA-01 (FTR-018): Routes `ai-toolkit executor <subcommand>
+// [flags]` to lib/task-executor/index.js's execute/status/diagnose/stop/
+// reconcile/resume/replan (the seven commands of the CLI contract in
+// FTR-018-Tech-Spec.md section 10). All executor domain logic lives in
+// lib/task-executor/*.js; this function only parses CLI flags, derives the
+// couple of git-context values reconcile()/resume()/replan() require but do
+// not derive themselves (see _executorExecutionRoot/_executorCurrentBranchRef
+// above), and maps thrown error codes to the Tech-Spec's fixed exit-code enum
+// (see mapExecutorErrorToExitCode above) — it is NOT a second copy of any
+// executor logic.
+//
+// Flag-rejection mechanism for "no --force*, lock/state path overrides,
+// implicit --abandon or runtime concurrency adjustment" (Tech-Spec section
+// 10): this parser simply never recognizes such flags for any subcommand
+// below. An unrecognized flag is silently ignored rather than explicitly
+// rejected — there is nothing to reject because nothing here ever reads an
+// arbitrary flag by name and forwards it to a filesystem path or lock
+// primitive; only the whitelisted flags per subcommand are ever read via
+// getFlag()/hasFlag().
+async function handleExecutorCommand(argv) {
+  const subcommand = argv[0];
+  const remaining = argv.slice(1);
+
+  function getFlag(name) {
+    const idx = remaining.indexOf(name);
+    return idx !== -1 && remaining[idx + 1] !== undefined ? remaining[idx + 1] : undefined;
+  }
+
+  function emitSuccess(result) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    // Tech-Spec section 10 exit code 8 ("paused awaiting human decision") is a
+    // SUCCESS-path outcome, not an error — only execute()'s and resume()'s
+    // result objects can legitimately carry `runStatus: 'paused'` (see the
+    // exit-code mapping comment above EXECUTOR_EXIT_CODE_BY_ERROR_CODE for why
+    // no *_ERROR code maps to 8). reconcile/stop/replan results never carry a
+    // `runStatus` field at all, and status/diagnose never reach this success
+    // path (still NOT_IMPLEMENTED) — so this check is a no-op for every other
+    // subcommand's result shape and never needs to be scoped by subcommand.
+    process.exitCode = result && result.runStatus === 'paused' ? 8 : 0;
+  }
+
+  function emitError(err) {
+    const code = err && err.code ? err.code : undefined;
+    const exitCode = mapExecutorErrorToExitCode(code);
+    process.stderr.write(JSON.stringify({
+      status: 'error',
+      code: code || 'UNKNOWN',
+      message: err && err.message ? err.message : String(err),
+    }, null, 2) + '\n');
+    process.exitCode = exitCode;
+  }
+
+  function usageError(message) {
+    process.stderr.write('Error: ' + message + '\n');
+    process.exitCode = 2;
+  }
+
+  const projectDir = path.resolve(getFlag('--project') || process.cwd());
+
+  try {
+    const taskExecutor = require('../lib/task-executor');
+
+    if (subcommand === 'start') {
+      const feature = getFlag('--feature');
+      if (!feature) { usageError('executor start requires --feature'); return; }
+      const maxConcurrencyRaw = getFlag('--max-concurrency');
+      const taskTimeoutMsRaw  = getFlag('--task-timeout-ms');
+      const agentBudgetUsdRaw = getFlag('--agent-budget-usd');
+      const result = await taskExecutor.execute({
+        project: projectDir,
+        feature: feature,
+        maxConcurrency: maxConcurrencyRaw === undefined ? undefined : Number(maxConcurrencyRaw),
+        claudePath: getFlag('--claude-path'),
+        taskTimeoutMs: taskTimeoutMsRaw === undefined ? undefined : Number(taskTimeoutMsRaw),
+        agentBudgetUsd: agentBudgetUsdRaw === undefined ? undefined : Number(agentBudgetUsdRaw),
+      });
+      emitSuccess(result);
+
+    } else if (subcommand === 'status') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor status requires --run-id'); return; }
+      const result = await taskExecutor.status({ project: projectDir, runId: runId });
+      emitSuccess(result);
+
+    } else if (subcommand === 'diagnose') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor diagnose requires --run-id'); return; }
+      const result = await taskExecutor.diagnose({ project: projectDir, runId: runId });
+      emitSuccess(result);
+
+    } else if (subcommand === 'stop') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor stop requires --run-id'); return; }
+      const result = await taskExecutor.stop({
+        project: projectDir,
+        runId: runId,
+        mode: getFlag('--mode') || 'graceful',
+      });
+      emitSuccess(result);
+
+    } else if (subcommand === 'reconcile' || subcommand === 'resume') {
+      const runId = getFlag('--run-id');
+      if (!runId) { usageError('executor ' + subcommand + ' requires --run-id'); return; }
+      const executionRoot = _executorExecutionRoot(projectDir);
+      const taskRef        = _executorCurrentBranchRef(projectDir);
+      const fn = subcommand === 'reconcile' ? taskExecutor.reconcile : taskExecutor.resume;
+      const result = await fn({
+        executionRoot: executionRoot,
+        runId: runId,
+        projectDir: projectDir,
+        taskRef: taskRef,
+      });
+      emitSuccess(result);
+
+    } else if (subcommand === 'replan') {
+      const runId    = getFlag('--run-id');
+      const feature  = getFlag('--feature');
+      if (!runId)   { usageError('executor replan requires --run-id'); return; }
+      if (!feature) { usageError('executor replan requires --feature (the approved successor plan)'); return; }
+
+      // --task-mapping-json is NOT one of the Tech-Spec table's listed
+      // arguments for replan (only --run-id/--feature are) — but
+      // lib/task-executor/index.js's replan() requires args.taskMapping to be
+      // an array (DISPATCH_VALIDATION_ERROR otherwise) and never invents one
+      // itself (see its own doc comment: "taskMapping is an explicit,
+      // caller-supplied old->new task ID mapping"). Following this session's
+      // established pattern of flagging gaps rather than papering over them:
+      // this flag is documented here as a necessary CLI-layer extension
+      // beyond the literal table, using the same `--*-json` structured-input
+      // convention the ledger subcommand already established
+      // (--metadata-json). Omitting it defaults to an empty mapping (a valid
+      // array — "no task carries forward" — never rejected by replan()).
+      let taskMapping = [];
+      const taskMappingJson = getFlag('--task-mapping-json');
+      if (taskMappingJson !== undefined) {
+        try {
+          taskMapping = JSON.parse(taskMappingJson);
+        } catch (parseErr) {
+          usageError('--task-mapping-json is not valid JSON: ' + parseErr.message);
+          return;
+        }
+      }
+
+      const executionRoot = _executorExecutionRoot(projectDir);
+      const taskRef        = _executorCurrentBranchRef(projectDir);
+      const result = await taskExecutor.replan({
+        executionRoot: executionRoot,
+        runId: runId,
+        projectDir: projectDir,
+        taskRef: taskRef,
+        feature: feature,
+        taskMapping: taskMapping,
+      });
+      emitSuccess(result);
+
+    } else {
+      usageError('unknown executor subcommand: ' + (subcommand || '(none)'));
+    }
+  } catch (err) {
+    emitError(err);
+  }
+}
+
 // ── entry point guard ─────────────────────────────────────────────────────────
 // Run the CLI only when invoked directly (node bin/cli.js).
 // When required as a module (e.g., by Jest), skip main() and export pure
@@ -2600,5 +2963,11 @@ if (require.main === module) {
     resolveFeaturesRoot,
     computeFileSha256,
     handleAgentsCommand,
+    handleExecutorCommand,
+    mapExecutorErrorToExitCode,
+    EXECUTOR_EXIT_CODE_BY_ERROR_CODE,
+    _executorResolveCommonGitDir,
+    _executorExecutionRoot,
+    _executorCurrentBranchRef,
   };
 }

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.