claude-dev-env 1.95.0 → 2.0.1

package/skills/grokify/evals/run-capability-evals.mjs

@@ -0,0 +1,545 @@
+#!/usr/bin/env node
+/**
+ * Opt-in live Grok capability evals (E1–E5).
+ *
+ * Never wired into package.json `test`. Requires GROK_CAPABILITY_EVALS=1 or --run.
+ */
+import { spawnSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const OPT_IN_ENV = 'GROK_CAPABILITY_EVALS';
+const OPT_IN_VALUE = '1';
+const RUN_FLAG = '--run';
+const GROK_BINARY = process.env.GROK_BIN || 'grok';
+const DEFAULT_MAX_TURNS = 12;
+const SPAWN_MAX_TURNS = 20;
+const SKILL_MAX_TURNS = 16;
+const WRITE_MAX_TURNS = 12;
+const WORKFLOW_MAX_TURNS = 8;
+const PROBE_FILE_NAME = 'capability-probe-write.txt';
+const PROBE_FILE_CONTENTS = 'capability-probe-ok';
+const HOOKS_LOG_NAME = 'hooks.log';
+const HOOKS_LOG_GLOBAL_SETTINGS_MARKER = 'global/settings';
+const HOOKS_LOG_PRE_TOOL_USE_MARKER = 'pre_tool_use';
+const SPAWN_MARKER = 'SPAWN_OK';
+const SPAWN_SUBAGENT_TOOL = 'spawn_subagent';
+const GROK_SPAWN_TIMEOUT_MS = 600000;
+const SPAWN_MAX_BUFFER_BYTES = 20 * 1024 * 1024;
+const WORKFLOW_RESULT_NO_TOOL = 'no_tool';
+const SPAWN_TIMEOUT_ERROR_CODE = 'ETIMEDOUT';
+const ENVELOPE_TEXT_FIELDS_BY_PRIORITY = ['result', 'text', 'message'];
+const STREAM_EVENT_TEXT_FIELDS_BY_PRIORITY = ['result', 'text', 'content'];
+
+const E1_PROMPT = `You are running a capability inventory. Do not edit files.
+
+1. Inspect your available tools.
+2. Check whether agents and skills directories exist under the user's Claude config (typical locations: ~/.claude/agents, ~/.claude/skills).
+
+Reply with ONLY one JSON object and nothing else:
+{
+  "can_spawn_subagent_tool": <true if a spawn_subagent tool is available>,
+  "tool_names": [<string tool names>],
+  "agents_dir_exists": <bool>,
+  "skills_dir_exists": <bool>
+}`;
+
+const E2_PROMPT = `You are measuring spawn_subagent.
+
+1. Use spawn_subagent (or the equivalent agent-spawn tool) once.
+2. Instruct the child to print exactly ${SPAWN_MARKER} on its first line, then list basenames from the agents directory under the user's Claude config (for example ~/.claude/agents).
+3. Wait for the child to finish.
+
+Reply with ONLY one JSON object and nothing else:
+{
+  "spawn_succeeded": <true if the child ran and returned ${SPAWN_MARKER}>,
+  "child_excerpt": "<excerpt of child output that includes its first line>"
+}`;
+
+const E3_PROMPT = `You are measuring skill readability under an agent definition.
+
+1. Read any one skill entrypoint under the user's Claude skills path (for example ~/.claude/skills/*/SKILL.md). Prefer a short file if several exist.
+2. Confirm you loaded an agent definition for this run (this process was started with --agent).
+
+Reply with ONLY one JSON object and nothing else:
+{
+  "skill_read_ok": <true if you read a skill file's contents>,
+  "skill_path": "<path you read or empty string>",
+  "agent_definition_loaded": <true if an agent definition is active>
+}`;
+
+const E4_PROMPT = `You are measuring write capability in the current working directory.
+
+1. Write a file named ${PROBE_FILE_NAME} in the current working directory with exact contents: ${PROBE_FILE_CONTENTS}
+2. Do not write anything else.
+
+Reply with ONLY one JSON object and nothing else:
+{
+  "write_succeeded": <true if the write completed>,
+  "written_path": "<absolute or relative path written>"
+}`;
+
+const E5_PROMPT = `You are measuring whether a Claude/GSD Workflow tool is available.
+
+Inspect your tool list. Do not invent a Workflow tool.
+
+Reply with ONLY one JSON object and nothing else:
+{
+  "has_workflow_tool": <true only if a Workflow tool is present>,
+  "result": <"has_tool" or "no_tool">
+}`;
+
+function isOptedIn(allArguments) {
+  if (allArguments.includes(RUN_FLAG)) {
+    return true;
+  }
+  return process.env[OPT_IN_ENV] === OPT_IN_VALUE;
+}
+
+function printOptInHelp() {
+  console.log(
+    [
+      'Grok capability evals are opt-in only (not part of npm test / CI).',
+      '',
+      'Run with either:',
+      `  ${OPT_IN_ENV}=${OPT_IN_VALUE} node skills/grokify/evals/run-capability-evals.mjs`,
+      '  node skills/grokify/evals/run-capability-evals.mjs --run',
+      '',
+      'See skills/grokify/evals/README.md.',
+    ].join('\n'),
+  );
+}
+
+function mintLeaderSocketPath(runDirectory, evalName) {
+  return join(runDirectory, `leader-${evalName}.sock`);
+}
+
+function writePromptFile(runDirectory, evalName, promptText) {
+  const promptPath = join(runDirectory, `${evalName}-prompt.md`);
+  writeFileSync(promptPath, promptText, 'utf8');
+  return promptPath;
+}
+
+function buildGrokArguments({
+  promptPath,
+  workingDirectory,
+  leaderSocketPath,
+  maxTurns,
+  agentName,
+}) {
+  const allArguments = [
+    '--prompt-file',
+    promptPath,
+    '--cwd',
+    workingDirectory,
+    '--output-format',
+    'json',
+    '--always-approve',
+    '--max-turns',
+    String(maxTurns),
+    '--permission-mode',
+    'bypassPermissions',
+    '--leader-socket',
+    leaderSocketPath,
+  ];
+  if (agentName) {
+    allArguments.push('--agent', agentName);
+  }
+  return allArguments;
+}
+
+function runGrok({
+  promptPath,
+  workingDirectory,
+  leaderSocketPath,
+  maxTurns,
+  agentName,
+}) {
+  const allArguments = buildGrokArguments({
+    promptPath,
+    workingDirectory,
+    leaderSocketPath,
+    maxTurns,
+    agentName,
+  });
+  const processResult = spawnSync(GROK_BINARY, allArguments, {
+    encoding: 'utf8',
+    cwd: workingDirectory,
+    maxBuffer: SPAWN_MAX_BUFFER_BYTES,
+    timeout: GROK_SPAWN_TIMEOUT_MS,
+    windowsHide: true,
+  });
+  return {
+    exitCode: processResult.status,
+    stdout: processResult.stdout || '',
+    stderr: processResult.stderr || '',
+    error: processResult.error || null,
+  };
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function extractLastBalancedObject(text) {
+  const doubleQuote = '"';
+  const escapeCharacter = '\\';
+  let isInsideString = false;
+  let isNextCharacterEscaped = false;
+  let openBraceDepth = 0;
+  let objectStartIndex = -1;
+  let lastParsedObject = null;
+  for (let index = 0; index < text.length; index += 1) {
+    const character = text[index];
+    if (isInsideString) {
+      if (isNextCharacterEscaped) {
+        isNextCharacterEscaped = false;
+      } else if (character === escapeCharacter) {
+        isNextCharacterEscaped = true;
+      } else if (character === doubleQuote) {
+        isInsideString = false;
+      }
+      continue;
+    }
+    if (character === doubleQuote) {
+      isInsideString = true;
+    } else if (character === '{') {
+      if (openBraceDepth === 0) {
+        objectStartIndex = index;
+      }
+      openBraceDepth += 1;
+    } else if (character === '}' && openBraceDepth > 0) {
+      openBraceDepth -= 1;
+      if (openBraceDepth === 0) {
+        try {
+          const parsed = JSON.parse(text.slice(objectStartIndex, index + 1));
+          if (isPlainObject(parsed)) {
+            lastParsedObject = parsed;
+          }
+        } catch {
+          // not a JSON object; keep scanning for a later balanced candidate
+        }
+      }
+    }
+  }
+  return lastParsedObject;
+}
+
+export function tryParseJsonObject(text) {
+  const trimmed = text.trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (isPlainObject(parsed)) {
+      return parsed;
+    }
+  } catch {
+    // fall through to balanced-object extraction
+  }
+  return extractLastBalancedObject(trimmed);
+}
+
+function extractStringField(parsedEnvelope, fieldName) {
+  if (!parsedEnvelope || typeof parsedEnvelope !== 'object') {
+    return null;
+  }
+  const fieldValue = parsedEnvelope[fieldName];
+  if (typeof fieldValue === 'string') {
+    return fieldValue;
+  }
+  return null;
+}
+
+function pickStringFieldByPriority(candidate, fieldNames) {
+  for (const fieldName of fieldNames) {
+    const fieldValue = extractStringField(candidate, fieldName);
+    if (fieldValue !== null) {
+      return fieldValue;
+    }
+  }
+  return null;
+}
+
+export function extractResultText(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) {
+    return '';
+  }
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (Array.isArray(parsed)) {
+      const resultEvent = parsed.findLast(
+        (eachEvent) =>
+          eachEvent &&
+          typeof eachEvent === 'object' &&
+          eachEvent.type === 'result' &&
+          typeof eachEvent.result === 'string',
+      );
+      if (resultEvent) {
+        return resultEvent.result;
+      }
+      const textChunks = [];
+      for (const eachEvent of parsed) {
+        if (!eachEvent || typeof eachEvent !== 'object') {
+          continue;
+        }
+        const eventText = pickStringFieldByPriority(
+          eachEvent,
+          STREAM_EVENT_TEXT_FIELDS_BY_PRIORITY,
+        );
+        if (eventText !== null) {
+          textChunks.push(eventText);
+        }
+      }
+      if (textChunks.length > 0) {
+        return textChunks.join('\n');
+      }
+    }
+    if (parsed && typeof parsed === 'object') {
+      const envelopeText = pickStringFieldByPriority(
+        parsed,
+        ENVELOPE_TEXT_FIELDS_BY_PRIORITY,
+      );
+      if (envelopeText !== null) {
+        return envelopeText;
+      }
+    }
+  } catch {
+    // stdout is plain text
+  }
+  return trimmed;
+}
+
+export function parsePayload(stdout) {
+  const resultText = extractResultText(stdout);
+  return tryParseJsonObject(resultText) || tryParseJsonObject(stdout);
+}
+
+function assertCondition(condition, message) {
+  if (!condition) {
+    throw new Error(message);
+  }
+}
+
+function resolveDefaultAgentName() {
+  return process.env.GROK_CAPABILITY_EVAL_AGENT || 'Explore';
+}
+
+function describeLaunchFailure(label, processResult) {
+  const launchError = processResult.error;
+  if (
+    launchError &&
+    typeof launchError === 'object' &&
+    launchError.code === SPAWN_TIMEOUT_ERROR_CODE
+  ) {
+    return `${label}: grok timed out after ${GROK_SPAWN_TIMEOUT_MS}ms`;
+  }
+  if (launchError !== null) {
+    return `${label}: failed to launch grok: ${launchError}`;
+  }
+  return `${label}: grok exit ${processResult.exitCode}\n${processResult.stderr}\n${processResult.stdout}`;
+}
+
+function launchEval(runDirectory, { evalName, promptText, maxTurns, agentName }) {
+  const label = evalName.toUpperCase();
+  const promptPath = writePromptFile(runDirectory, evalName, promptText);
+  const processResult = runGrok({
+    promptPath,
+    workingDirectory: runDirectory,
+    leaderSocketPath: mintLeaderSocketPath(runDirectory, evalName),
+    maxTurns,
+    agentName,
+  });
+  if (processResult.error !== null || processResult.exitCode !== 0) {
+    throw new Error(describeLaunchFailure(label, processResult));
+  }
+  const payload = parsePayload(processResult.stdout);
+  assertCondition(
+    payload !== null,
+    `${label}: could not parse JSON payload from grok output`,
+  );
+  return payload;
+}
+
+function runEvalOne(runDirectory) {
+  const payload = launchEval(runDirectory, {
+    evalName: 'e1',
+    promptText: E1_PROMPT,
+    maxTurns: DEFAULT_MAX_TURNS,
+  });
+  assertCondition(
+    payload.can_spawn_subagent_tool === true,
+    `E1: expected can_spawn_subagent_tool === true, got ${JSON.stringify(payload.can_spawn_subagent_tool)}`,
+  );
+  const allToolNames = Array.isArray(payload.tool_names)
+    ? payload.tool_names.map(String)
+    : [];
+  assertCondition(
+    allToolNames.includes(SPAWN_SUBAGENT_TOOL),
+    `E1: expected tool_names to include ${SPAWN_SUBAGENT_TOOL}, got ${JSON.stringify(allToolNames)}`,
+  );
+  return payload;
+}
+
+function runEvalTwo(runDirectory) {
+  const payload = launchEval(runDirectory, {
+    evalName: 'e2',
+    promptText: E2_PROMPT,
+    maxTurns: SPAWN_MAX_TURNS,
+  });
+  assertCondition(
+    payload.spawn_succeeded === true,
+    `E2: expected spawn_succeeded === true, got ${JSON.stringify(payload.spawn_succeeded)}`,
+  );
+  const childExcerpt =
+    typeof payload.child_excerpt === 'string' ? payload.child_excerpt : '';
+  assertCondition(
+    childExcerpt.includes(SPAWN_MARKER),
+    `E2: expected child_excerpt to include ${SPAWN_MARKER}, got ${JSON.stringify(payload.child_excerpt)}`,
+  );
+  return payload;
+}
+
+function runEvalThree(runDirectory) {
+  const payload = launchEval(runDirectory, {
+    evalName: 'e3',
+    promptText: E3_PROMPT,
+    maxTurns: SKILL_MAX_TURNS,
+    agentName: resolveDefaultAgentName(),
+  });
+  assertCondition(
+    payload.skill_read_ok === true,
+    `E3: expected skill_read_ok === true, got ${JSON.stringify(payload.skill_read_ok)}`,
+  );
+  assertCondition(
+    payload.agent_definition_loaded === true,
+    `E3: expected agent_definition_loaded === true, got ${JSON.stringify(payload.agent_definition_loaded)}`,
+  );
+  return payload;
+}
+
+function runEvalFour(runDirectory) {
+  const payload = launchEval(runDirectory, {
+    evalName: 'e4',
+    promptText: E4_PROMPT,
+    maxTurns: WRITE_MAX_TURNS,
+  });
+  const probePath = join(runDirectory, PROBE_FILE_NAME);
+  assertCondition(
+    existsSync(probePath),
+    `E4: probe file missing under the eval cwd (write_succeeded claim: ${JSON.stringify(payload.write_succeeded)})`,
+  );
+  const probeContents = readFileSync(probePath, 'utf8');
+  assertCondition(
+    probeContents.includes(PROBE_FILE_CONTENTS),
+    `E4: probe file contents mismatch: ${JSON.stringify(probeContents)}`,
+  );
+  const hooksLogPath = join(runDirectory, HOOKS_LOG_NAME);
+  let hooksNote = 'hooks.log not present (soft check skipped)';
+  if (existsSync(hooksLogPath)) {
+    const hooksLogText = readFileSync(hooksLogPath, 'utf8').toLowerCase();
+    const hasGlobalSettings = hooksLogText.includes(
+      HOOKS_LOG_GLOBAL_SETTINGS_MARKER,
+    );
+    const hasPreToolUse = hooksLogText.includes(HOOKS_LOG_PRE_TOOL_USE_MARKER);
+    hooksNote =
+      hasGlobalSettings && hasPreToolUse
+        ? 'hooks.log contains global/settings and pre_tool_use'
+        : 'hooks.log present but missing expected markers (soft)';
+  }
+  return { payload, hooksNote };
+}
+
+export function isWorkflowToolAbsent(payload) {
+  if (!payload || typeof payload !== 'object') {
+    return false;
+  }
+  return (
+    payload.has_workflow_tool === false &&
+    payload.result === WORKFLOW_RESULT_NO_TOOL
+  );
+}
+
+function runEvalFive(runDirectory) {
+  const payload = launchEval(runDirectory, {
+    evalName: 'e5',
+    promptText: E5_PROMPT,
+    maxTurns: WORKFLOW_MAX_TURNS,
+  });
+  assertCondition(
+    isWorkflowToolAbsent(payload),
+    `E5: expected has_workflow_tool === false and result === "no_tool", got ${JSON.stringify(payload)}`,
+  );
+  return payload;
+}
+
+function main() {
+  if (!isOptedIn(process.argv.slice(2))) {
+    printOptInHelp();
+    process.exit(0);
+  }
+
+  const runDirectory = mkdtempSync(join(tmpdir(), 'grok-capability-evals-'));
+  console.log(`run directory: ${runDirectory}`);
+
+  try {
+    console.log('E1 tool inventory...');
+    const e1Payload = runEvalOne(runDirectory);
+    console.log('E1 ok', JSON.stringify(e1Payload));
+
+    console.log('E2 spawn_subagent...');
+    const e2Payload = runEvalTwo(runDirectory);
+    console.log('E2 ok', JSON.stringify(e2Payload));
+
+    console.log('E3 --agent + skill read...');
+    const e3Payload = runEvalThree(runDirectory);
+    console.log('E3 ok', JSON.stringify(e3Payload));
+
+    console.log('E4 probe write...');
+    const e4Outcome = runEvalFour(runDirectory);
+    console.log(
+      'E4 ok',
+      JSON.stringify({
+        payload: e4Outcome.payload,
+        hooksNote: e4Outcome.hooksNote,
+      }),
+    );
+
+    console.log('E5 workflow tool absence...');
+    const e5Payload = runEvalFive(runDirectory);
+    console.log('E5 ok', JSON.stringify(e5Payload));
+
+    console.log('ALL CAPABILITY EVALS PASSED');
+  } catch (failure) {
+    console.error(String(failure && failure.stack ? failure.stack : failure));
+    process.exitCode = 1;
+  } finally {
+    try {
+      rmSync(runDirectory, { recursive: true, force: true });
+    } catch {
+      // best-effort cleanup
+    }
+  }
+}
+
+function isDirectExecution() {
+  const entryArgument = process.argv[1];
+  if (!entryArgument) {
+    return false;
+  }
+  return resolve(fileURLToPath(import.meta.url)) === resolve(entryArgument);
+}
+
+if (isDirectExecution()) {
+  main();
+}

package/skills/orchestrator/SKILL.md

@@ -21,16 +21,12 @@ delegating to Sonnet-5 workers came out cheaper and faster
 than a solo frontier agent held to the same verification rigor, with
 84-98% of the team's input tokens billed at the worker rate.
 
-Claude Code has no `multiagent` coordinator field or Managed-Agents-style
-`create_agent`/`send_to_agent` primitives; this skill reaches the same
-shape with the tools Claude Code already has. Under this skill the session
-is the orchestrator. In Claude Code the user always talks to the session and never to a
-subagent, so the session is the user's sole interface: all user-facing
-communication flows through it. It spawns and resumes executor subagents
+Under this skill the session
+is the orchestrator. It spawns and resumes executor subagents
 — `clean-coder` and the like — and those executors do every bit of the
 execution: the code edits, the build runs, the test runs. The orchestrating
 session drives the plan and routes hard decisions to the shared advisor
-(Claude: warm `session-advisor`; Grok: Claude CLI advisor via the chain runner).
+(Claude: warm `session-advisor`; a third-party host: Claude CLI advisor via the chain runner).
 
 ## Gotchas
 
@@ -43,7 +39,7 @@ session drives the plan and routes hard decisions to the shared advisor
   wasted. Hand every code edit and every build or test run to an executor; keep
   the orchestrating session's own tool use to orchestration and light
   verification reads. Hard decisions go to the shared advisor (Claude:
-  `session-advisor` via SendMessage; Grok: Claude CLI advisor via the chain).
+  `session-advisor` via SendMessage; a third-party host: Claude CLI advisor via the chain).
 - **Flat ad hoc spawns bypass routing.** Every execution task goes through a
   workflow-backed spawn or workflow resume so the required agent type, model,
   prompt packet, and sidecar metadata stay attached to the work.
@@ -55,25 +51,20 @@ session drives the plan and routes hard decisions to the shared advisor
   reach that agent later. A named agent is reachable by name.
 - **Only the orchestrating session owns the shared advisor's lifecycle.** An
   executor that finds the advisor unreachable (Claude warm agent, or Claude
-  CLI bind on Grok) reports that upward; it never spawns a replacement itself.
+  CLI bind on a third-party host) reports that upward; it never spawns a replacement itself.
 
 ## Process
 
 1. **Check whether the refresh loop is already running this
    session.** If it is, do not schedule a second loop. Reuse any live
-   shared advisor bind (Claude warm `session-advisor`, or Grok Claude CLI
-   bind — run step 3 only when none exists yet), then skip straight to step 4.
-
-2. **Register the discipline reminder.** By default, schedule it with
-   `ScheduleWakeup` at `delaySeconds: 1200`, prompt `/orchestrator-refresh`,
-   where each refresh re-schedules the next one — a 1200-second wakeup costs
-   one prompt-cache miss per firing and nothing more (see Gotchas). The loop
-   mechanism (`/loop 20m /orchestrator-refresh`) is the escape hatch when
-   `ScheduleWakeup` is not available. Either way the reminder is the
-   enforcement surface: each firing re-asserts the discipline while the run is
-   in flight.
-
-3. **Bind the shared advisor before any executor.** Detect the host profile
+   shared advisor bind (Claude warm `session-advisor`, or a third-party host's
+   Claude CLI bind — run step 3 only when none exists yet), then skip straight to step 4.
+
+2. **Register the discipline reminder.** schedule it with
+   `ScheduleWakeup` at `delaySeconds: 1800`, prompt `/orchestrator-refresh`,
+   where each refresh re-schedules the next one.
+
+3. **Bind a shared advisor before any executor.** Detect the host profile
    first (see Host profiles in
    [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md)).
    On a **Claude host**, follow the Warm-up procedure in that doc (Agent spawn
@@ -85,18 +76,18 @@ session drives the plan and routes hard decisions to the shared advisor
    [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md);
    it is not a "spawn only at the floor" rule. Paste the **Claude host**
    Advisor block from that doc, with the resolved agent name filled in, into
-   every executor's spawn prompt. On a **Grok host**, skip the Agent spawn —
+   every executor's spawn prompt. On a **third-party host**, skip the Agent spawn —
    bind a max-tier Claude advisor through the protocol's CLI Claude-chain path
    (Fable high, then Opus max; `claude_chain_runner.py` for account usage
-   failover). Paste the **Grok host** Advisor block from that doc into every
+   failover). Paste the **Third-party host** Advisor block from that doc into every
    executor's spawn prompt — never the Claude SendMessage block. Every row in
    the routing table is a consumer of the shared advisor, not just this
    session. The orchestrating session owns the shared advisor's lifecycle end
    to end (Agent spawn or CLI bind, drift handling per the shared doc,
    shutdown at task end); executors only ever SendMessage the warm agent
    (Claude) or report to this session so it can consult the CLI advisor
-   (Grok). When the CLI chain cannot bind, fail closed and report to the user
-   — do not answer the four signals as this Grok session.
+   (a third-party host). When the CLI chain cannot bind, fail closed and report
+   to the user — do not answer the four signals as this third-party session.
 
 4. **Orchestrate the task.** Hold the plan and the user conversation. Execute
    workflow-backed spawns or resumes using the routing table below, and keep
@@ -114,7 +105,7 @@ session drives the plan and routes hard decisions to the shared advisor
    - The chosen approach is being reconsidered.
 
    **Claude host:** consult the shared `session-advisor` via `SendMessage`.
-   **Grok host:** executors report to this orchestrating session; this session
+   **Third-party host:** executors report to this orchestrating session; this session
    consults the bound Claude CLI advisor (`claude_chain_runner.py` +
    `--resume`) and relays the four-signal reply (no Agent-tool
    `session-advisor`, no SendMessage to one). Every consult gets back one of
@@ -153,10 +144,14 @@ Routing rules:
   it.
 - Exploration workflows return file paths, line numbers, and direct evidence;
   they do not write code or mutate repo state.
+- Fan-out worker fleets use the **grok-spawn** skill when that skill is
+  installed and grok is usable (`grok_worker_preflight.py` soft gate). The
+  Claude Code Agent tool remains the Claude-host alternative for in-process
+  workers.
 
 ## Agent reuse (non-negotiable)
 
-- **Resume before you spawn, always.** A warm agent carries its context and
+- **Resume before you spawn, always.** A warm agent (active within the past 59 minutes)  carries its context and
   cached tokens; a fresh spawn starts cold and pays to rebuild both.
   Resume the existing workflow agent by name or `agentId` when it holds
   relevant context. Prefer that path every time an existing workflow agent
@@ -166,6 +161,24 @@ Routing rules:
 - **Name the agent to resume.** When a PLAN from the shared advisor fits a warm
   agent, name which agent to resume and where.
 
+## Task ledger discipline
+
+The task list is the run's ledger, and it must be reconcilable against the live
+agents at any moment. Four invariants hold at all times:
+
+1. **No untracked work.** Every unit of delegated work has a task BEFORE its
+   executor spawns — TaskCreate first, then Agent.
+2. **Ownership is live.** At spawn, set the task `in_progress` with `owner` =
+   the executor's agent name. One task, one owner.
+3. **Completion follows evidence.** A task turns `completed` only when the
+   executor's result is back AND merged into run state — never on dispatch,
+   never on a self-report alone (see `workers-done-before-complete`).
+4. **Dependencies mirror the plan.** Phase order is encoded as `blockedBy`
+   links, updated the moment the plan changes.
+
+Reconcile on every state change (spawn, completion notification, plan change)
+and on every `/orchestrator-refresh` firing.
+
 ## Constraints
 
 - One `/orchestrator` per session; the invocation guard blocks a second
@@ -179,7 +192,7 @@ Routing rules:
   session (see
   [`_shared/advisor/advisor-protocol.md`](../../_shared/advisor/advisor-protocol.md))
   — on Claude, executors consult a warm `session-advisor` via SendMessage; on
-  Grok, executors report here and this session relays the Claude CLI advisor.
+  a third-party host, executors report here and this session relays the Claude CLI advisor.
   Executors never spawn or respawn the advisor.
 - Reuse a warm agent over a cold spawn whenever one holds relevant context.