okstra 0.34.1 → 0.36.1

package/src/install.mjs

@@ -15,6 +15,10 @@ const SETTINGS_TEMPLATE_SRC_REL = ["templates", "reports", "settings.template.js
 // Destination under ~/.okstra/. Project-local .claude/settings.local.json symlinks here.
 const SETTINGS_TEMPLATE_DST_REL = ["templates", "settings.local.json"];
 
+// okstra-managed CLAUDE.md template. Per-project <PROJECT>/.project-docs/okstra/CLAUDE.md
+// symlinks here; <PROJECT>/CLAUDE.md gets an `@.project-docs/okstra/CLAUDE.md` import line.
+const CLAUDE_MD_TEMPLATE_REL = ["templates", "okstra.CLAUDE.md"];
+
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "okstra_vendor", "lib"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
@@ -42,7 +46,7 @@ Usage:
 Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/bin           <- runtime/bin
-  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
+  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md / okstra.CLAUDE.md)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
   ${"$HOME"}/.claude/agents/<worker>.md <- runtime/agents/workers/<worker>.md
@@ -54,6 +58,7 @@ Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
   ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
+  ${"$HOME"}/.okstra/templates/okstra.CLAUDE.md     -> <repo>/templates/okstra.CLAUDE.md
   ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name>   (symlink dir)
   ${"$HOME"}/.claude/agents/<worker>.md -> <repo>/agents/workers/<worker>.md
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
@@ -64,6 +69,11 @@ project-local <project>/.claude/settings.local.json that okstra-setup
 provisions, granting per-project Claude Code permissions for okstra
 worker wrapper scripts without modifying the user's global settings.
 
+The okstra.CLAUDE.md file is the symlink target referenced by every
+project-local <project>/.project-docs/okstra/CLAUDE.md that okstra-setup provisions;
+<project>/CLAUDE.md gets an "@.project-docs/okstra/CLAUDE.md" import block so Claude
+Code automatically picks up the okstra runtime guidance.
+
 Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ so
 that Claude Code's subagent discovery picks them up; they cannot live
 inside the package alone because the harness only scans ~/.claude/agents/
@@ -245,7 +255,8 @@ async function installLinkMode(repoPath, paths, opts) {
   const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
 
-  await installSettingsTemplate(repoAbs, paths, { mode: "link", dryRun, quiet });
+  await installNamedTemplate(repoAbs, paths, { mode: "link", dryRun, quiet }, SETTINGS_TEMPLATE_DESCRIPTOR);
+  await installNamedTemplate(repoAbs, paths, { mode: "link", dryRun, quiet }, CLAUDE_MD_TEMPLATE_DESCRIPTOR);
 
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
@@ -395,13 +406,14 @@ async function installAgentsLink(repoAbs, opts) {
   return { installed: names };
 }
 
-async function installSettingsTemplate(srcRoot, paths, opts) {
+async function installNamedTemplate(srcRoot, paths, opts, descriptor) {
   const { mode, refresh = false, dryRun = false, quiet = false } = opts;
-  const src = join(srcRoot, ...SETTINGS_TEMPLATE_SRC_REL);
-  const dst = join(paths.home, ...SETTINGS_TEMPLATE_DST_REL);
+  const { srcRel, dstRel, label } = descriptor;
+  const src = join(srcRoot, ...srcRel);
+  const dst = join(paths.home, ...dstRel);
 
   if (!(await fileExists(src))) {
-    if (!quiet) process.stdout.write(`  settings template: source missing — skipped (${src})\n`);
+    if (!quiet) process.stdout.write(`  ${label}: source missing — skipped (${src})\n`);
     return { installed: false };
   }
 
@@ -409,7 +421,7 @@ async function installSettingsTemplate(srcRoot, paths, opts) {
 
   if (mode === "link") {
     const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  settings template: ${action} (${dst} -> ${src})\n`);
+    if (!quiet) process.stdout.write(`  ${label}: ${action} (${dst} -> ${src})\n`);
     return { installed: action !== "skipped" };
   }
 
@@ -426,7 +438,7 @@ async function installSettingsTemplate(srcRoot, paths, opts) {
   }
 
   if (!needsCopy) {
-    if (!quiet) process.stdout.write(`  settings template: skipped (hash match)\n`);
+    if (!quiet) process.stdout.write(`  ${label}: skipped (hash match)\n`);
     return { installed: false };
   }
 
@@ -436,10 +448,22 @@ async function installSettingsTemplate(srcRoot, paths, opts) {
     const buf = await fs.readFile(src);
     await writeFileAtomic(dst, buf, 0o644);
   }
-  if (!quiet) process.stdout.write(`  settings template: copied -> ${dst}\n`);
+  if (!quiet) process.stdout.write(`  ${label}: copied -> ${dst}\n`);
   return { installed: true };
 }
 
+const SETTINGS_TEMPLATE_DESCRIPTOR = {
+  srcRel: SETTINGS_TEMPLATE_SRC_REL,
+  dstRel: SETTINGS_TEMPLATE_DST_REL,
+  label: "settings template",
+};
+
+const CLAUDE_MD_TEMPLATE_DESCRIPTOR = {
+  srcRel: CLAUDE_MD_TEMPLATE_REL,
+  dstRel: CLAUDE_MD_TEMPLATE_REL,
+  label: "claude.md template",
+};
+
 async function installSkillsCopy(runtimeRoot, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
@@ -553,10 +577,11 @@ export async function runInstall(args) {
     paths.bin,
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
-  // templates/ tree — report.css / report.js / *.template.md are consumed at
-  // runtime by okstra-render-report-views.py and final-report assembly. They
-  // are NOT covered by installSettingsTemplate (which only handles the
-  // editable settings.local.json sidecar), so without this step copy-mode
+  // templates/ tree — report.css / report.js / *.template.md / okstra.CLAUDE.md
+  // are consumed at runtime by okstra-render-report-views.py, final-report
+  // assembly, and the per-project .project-docs/okstra/CLAUDE.md symlink provisioned by
+  // setup. They are NOT covered by installNamedTemplate (which only handles
+  // the renamed settings.local.json sidecar), so without this step copy-mode
   // installs miss every asset other than that single file. See
   // okstra-render-report-views.py _TEMPLATES_DIRS for the lookup path.
   const templatesResult = await copyTreeIfChanged(
@@ -588,7 +613,9 @@ export async function runInstall(args) {
   const agentResult = await installAgentsCopy(runtimeRoot, opts);
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
 
-  await installSettingsTemplate(runtimeRoot, paths, { mode: "copy", ...opts });
+  await installNamedTemplate(runtimeRoot, paths, { mode: "copy", ...opts }, SETTINGS_TEMPLATE_DESCRIPTOR);
+  // okstra.CLAUDE.md is already covered by the runtime/templates tree copy
+  // above (same src/dst path, no rename). No second call needed in copy mode.
 
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);

package/src/setup.mjs

@@ -293,9 +293,37 @@ export async function run(args) {
     );
   }
 
+  let claudeMd = { symlink: null, importInjected: false };
+  try {
+    claudeMd = await ensureProjectClaudeMd(projectRoot);
+  } catch (err) {
+    process.stderr.write(
+      `warning: failed to wire <PROJECT>/CLAUDE.md @ .project-docs/okstra/CLAUDE.md import — ` +
+        `Claude Code sessions in this project will not auto-load okstra guidance. (${err.message})\n`,
+    );
+  }
+
+  let agentsMdSymlink = null;
+  try {
+    agentsMdSymlink = await ensureProjectAgentsMd(projectRoot);
+  } catch (err) {
+    process.stderr.write(
+      `warning: failed to provision <PROJECT>/AGENTS.md symlink — ` +
+        `codex / aider sessions in this project will not auto-load okstra guidance. (${err.message})\n`,
+    );
+  }
+
   process.stdout.write(
     JSON.stringify(
-      { ok: true, ...result, projectJsonPath, settingsLocalJson: settingsSymlink },
+      {
+        ok: true,
+        ...result,
+        projectJsonPath,
+        settingsLocalJson: settingsSymlink,
+        claudeMdSymlink: claudeMd.symlink,
+        claudeMdImportInjected: claudeMd.importInjected,
+        agentsMdSymlink,
+      },
       null,
       2,
     ) + "\n",
@@ -348,3 +376,107 @@ async function backupAndReplace(target, template) {
   await fs.rename(target, backup);
   await fs.symlink(template, target);
 }
+
+const CLAUDE_MD_TEMPLATE_PATH = join(homedir(), ".okstra", "templates", "okstra.CLAUDE.md");
+const CLAUDE_MD_SYMLINK_REL = join(".project-docs", "okstra", "CLAUDE.md");
+const CLAUDE_MD_IMPORT_LINE = "@.project-docs/okstra/CLAUDE.md";
+const CLAUDE_MD_MARKER_BEGIN = "<!-- okstra:claude-md:begin (managed by okstra setup — do not edit) -->";
+const CLAUDE_MD_MARKER_END = "<!-- okstra:claude-md:end -->";
+
+async function ensureProjectClaudeMd(projectRoot) {
+  try {
+    await fs.access(CLAUDE_MD_TEMPLATE_PATH);
+  } catch {
+    return { symlink: null, importInjected: false };
+  }
+
+  const symlink = await ensureClaudeMdSymlink(projectRoot);
+  const importInjected = await ensureClaudeMdImport(projectRoot);
+  return { symlink, importInjected };
+}
+
+async function ensureClaudeMdSymlink(projectRoot) {
+  const target = join(projectRoot, CLAUDE_MD_SYMLINK_REL);
+  await fs.mkdir(join(target, ".."), { recursive: true });
+
+  let existingStat;
+  try {
+    existingStat = await fs.lstat(target);
+  } catch {
+    existingStat = null;
+  }
+
+  if (existingStat?.isSymbolicLink()) {
+    const current = await fs.readlink(target);
+    const resolved = current.startsWith("/") ? current : join(target, "..", current);
+    if (resolved === CLAUDE_MD_TEMPLATE_PATH) return target;
+    await backupAndReplace(target, CLAUDE_MD_TEMPLATE_PATH);
+    return target;
+  }
+  if (existingStat) {
+    await backupAndReplace(target, CLAUDE_MD_TEMPLATE_PATH);
+    return target;
+  }
+
+  await fs.symlink(CLAUDE_MD_TEMPLATE_PATH, target);
+  return target;
+}
+
+async function ensureClaudeMdImport(projectRoot) {
+  const claudeMdPath = join(projectRoot, "CLAUDE.md");
+  const block = `${CLAUDE_MD_MARKER_BEGIN}\n${CLAUDE_MD_IMPORT_LINE}\n${CLAUDE_MD_MARKER_END}\n`;
+
+  let existing;
+  try {
+    existing = await fs.readFile(claudeMdPath, "utf8");
+  } catch (err) {
+    if (err.code !== "ENOENT") throw err;
+    await fs.writeFile(claudeMdPath, block, { mode: 0o644 });
+    return true;
+  }
+
+  if (existing.includes(CLAUDE_MD_MARKER_BEGIN) && existing.includes(CLAUDE_MD_MARKER_END)) {
+    return false;
+  }
+
+  const separator = blockSeparatorFor(existing);
+  await fs.writeFile(claudeMdPath, existing + separator + block, { mode: 0o644 });
+  return true;
+}
+
+function blockSeparatorFor(existing) {
+  if (existing.length === 0) return "";
+  if (existing.endsWith("\n\n")) return "";
+  if (existing.endsWith("\n")) return "\n";
+  return "\n\n";
+}
+
+async function ensureProjectAgentsMd(projectRoot) {
+  try {
+    await fs.access(CLAUDE_MD_TEMPLATE_PATH);
+  } catch {
+    return null;
+  }
+
+  const target = join(projectRoot, "AGENTS.md");
+
+  let existingStat;
+  try {
+    existingStat = await fs.lstat(target);
+  } catch {
+    existingStat = null;
+  }
+
+  if (existingStat?.isSymbolicLink()) {
+    const current = await fs.readlink(target);
+    const resolved = current.startsWith("/") ? current : join(target, "..", current);
+    if (resolved === CLAUDE_MD_TEMPLATE_PATH) return target;
+    return null;
+  }
+  if (existingStat) {
+    return null;
+  }
+
+  await fs.symlink(CLAUDE_MD_TEMPLATE_PATH, target);
+  return target;
+}

package/src/uninstall.mjs

@@ -11,18 +11,27 @@ const BIN_ENTRYPOINTS = [
   "okstra-central.sh",
   "okstra-token-usage.py",
   "okstra-error-log.py",
+  "okstra-render-report-views.py",
+  "okstra-render-final-report.py",
+  "okstra-wrapper-status.py",
 ];
 
 const FALLBACK_SKILL_NAMES = [
   "okstra-setup",
+  "okstra-brief",
   "okstra-run",
-  "okstra-status",
-  "okstra-history",
+  "okstra-inspect",
   "okstra-schedule",
   "okstra-context-loader",
   "okstra-team-contract",
   "okstra-convergence",
   "okstra-report-writer",
+  // Pre-merge names — kept so uninstall on an upgraded machine still cleans
+  // them out of ~/.claude/skills/ once the user runs `okstra uninstall`.
+  // Safe to drop after a few releases when nobody has them installed.
+  "okstra-status",
+  "okstra-history",
+  "okstra-logs",
   "okstra-report-finder",
   "okstra-time-summary",
 ];
@@ -44,7 +53,9 @@ const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra, ~/.
 Usage:
   okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
                                 dev-link, installed-skills.json,
-                                installed-agents.json} AND
+                                installed-agents.json,
+                                templates/settings.local.json,
+                                templates/okstra.CLAUDE.md} AND
                                 ~/.claude/skills/<name> AND
                                 ~/.claude/agents/<worker>.md for every
                                 entry in the install manifests (fallback:
@@ -52,6 +63,12 @@ Usage:
                                 Preserves user data: recent.jsonl,
                                 active.jsonl, projects/, archive/,
                                 state.json, .locks/
+                                Per-project artifacts created by 'okstra setup'
+                                (<PROJECT>/.project-docs/okstra/CLAUDE.md symlink,
+                                <PROJECT>/CLAUDE.md import block,
+                                <PROJECT>/AGENTS.md symlink,
+                                <PROJECT>/.claude/settings.local.json symlink)
+                                are NOT touched — remove them manually if needed.
   okstra uninstall --purge      Remove the entire ~/.okstra directory AND
                                 ~/.claude/skills/<okstra-*> AND
                                 ~/.claude/agents/<*-worker.md> (DESTRUCTIVE).
@@ -182,6 +199,13 @@ export async function runUninstall(args) {
   await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
 
   await removePath(join(paths.home, "templates", "settings.local.json"), opts);
+  await removePath(join(paths.home, "templates", "okstra.CLAUDE.md"), opts);
+  // Per-project artifacts (<PROJECT>/.project-docs/okstra/CLAUDE.md symlink,
+  // <PROJECT>/AGENTS.md symlink, and the @.project-docs/okstra/CLAUDE.md import
+  // block inside <PROJECT>/CLAUDE.md) are NOT removed here — uninstall is
+  // machine-level and does not know which projects opted in. Symlinks will
+  // dangle until the user removes them manually or re-runs okstra install +
+  // okstra setup.
   // Remove templates/ if now empty.
   const templatesDir = join(paths.home, "templates");
   if (await pathExists(templatesDir)) {

package/runtime/skills/okstra-history/SKILL.md

@@ -1,165 +0,0 @@
----
-name: okstra-history
-description: Use when the user asks to list past okstra runs, check execution history, review previous cross-verification results, or wants to re-run a past okstra task. Trigger words include "okstra history", "past runs", "run history", "re-run", "list tasks".
----
-
-# OKSTRA History
-
-## When to Use
-
-- List past okstra task executions (one row per task, with latest-run summary).
-- Drill into the per-run history of a specific task.
-- Build a new run from an old run's parameters (re-run), or continue an in-flight one (resume).
-
-This skill is for **listing / re-dispatching**. For reading a single final report by task-key, use `okstra-report-finder` instead.
-
-## Re-run vs Resume — decide upfront
-
-Before invoking Step 3 or Step 4, classify the user's intent. The two paths are NOT interchangeable.
-
-| Intent | Trigger phrases | Use |
-|---|---|---|
-| **Re-run** — start a fresh run (new run-seq, new manifest, new report) reusing an old run's parameters | "re-run", "다시 실행", "another pass", "rerun with same brief" | Step 3 |
-| **Resume** — continue an interrupted Claude session for an existing run, no new run-seq | "resume", "continue", "이어서", "session ended" | Step 4 |
-
-If the user is ambiguous, ask. Defaulting to the wrong one either wastes a fresh run-seq or silently abandons a recoverable session.
-
-## Step 0: Verify okstra runtime + project setup
-
-Run each of the following commands as a **separate Bash tool call**. Each command starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call. The LLM (you) inspects each command's output and decides what to do next in natural language — never in shell.
-
-1. `okstra ensure-installed`
-   If this exits non-zero, tell the user: "okstra not installed — run `npx okstra@latest install` once, then retry this skill." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
-
-2. `okstra check-project --json`
-   Reads the project from the current working directory. Parse the JSON from stdout. The shape is `{ok, projectRoot, projectJsonPath, projectId}`.
-
-   - `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
-   - `ok: true` → carry `projectRoot` as a literal string and use it to locate `.project-docs/okstra/discovery/task-catalog.json`.
-
-Subsequent `okstra <subcmd>` calls self-bootstrap their Python path, so this skill never needs `okstra paths --shell` / `export PYTHONPATH=...`.
-
-## Step 1: Read the Task Catalog
-
-1. Read `.project-docs/okstra/discovery/task-catalog.json`.
-2. Apply filters from user input (all optional, AND-combined):
-   - `--task-type <type>` → keep entries whose `taskType` matches.
-   - `--latest-run-status <status>` → keep entries whose `latestRunStatus` matches (e.g. `completed`, `contract-violated`, `error`).
-   - `--task-group <group>` → keep entries whose `taskGroup` matches.
-3. Sort the surviving `tasks` array by `updatedAt` descending.
-4. Page: default `--limit 20`. After printing the table, if rows were truncated, add `... <N> more (pass --limit <N> to see all)`.
-5. Extract the following fields from each task:
-
-| Field | Description |
-|------|------|
-| `taskKey` | Task identifier — always 3 colon-separated segments: `<project-id>:<task-group>:<task-id>` (see `parse_task_key` in `okstra_project/state.py`). |
-| `taskType` | `requirements-discovery` / `error-analysis` / `implementation-planning` / `implementation` / `final-verification` / `release-handoff` |
-| `currentStatus` | Task lifecycle status written by the contract validator. Values: `todo` (seeded by spawn-followups), `completed`, `contract-violated`. Empty string = validator has not yet run. NOT the same as the user-managed `workStatus` (managed by `okstra-status`). |
-| `latestRunStatus` | Status of the most recent run (`completed`, `contract-violated`, `error`, ...) |
-| `latestRunManifestPath` | Run-manifest path of the most recent run — feed this into Step 3 to re-run from the latest parameters |
-| `updatedAt` | Last update time (ISO 8601) |
-| `latestReportPath` | Latest report path |
-| `latestResumeCommandPath` | Resume command path (Step 4) |
-| `historyTimelinePath` | `<task-root>/history/timeline.json` (Step 2 reads from here) |
-
-6. Output format:
-
-```markdown
-## okstra Task History — <project-id>
-
-| # | Task Key | Type | currentStatus | latestRunStatus | Last Run | Report |
-|---|----------|------|---------------|------------------|----------|--------|
-| 1 | proj:group:id | error-analysis | completed | completed | 2026-04-05 22:59 | .project-docs/.../final-report-*.md |
-| 2 | proj:group:id2 | final-verification | todo | error | 2026-04-04 15:30 | -- |
-```
-
-### Catalog absent — fallback
-
-If `.project-docs/okstra/discovery/task-catalog.json` does not exist, do NOT bail out. The catalog is a derived index — manifests on disk are the source of truth.
-
-1. Glob `<projectRoot>/.project-docs/okstra/tasks/*/*/task-manifest.json`.
-2. For each manifest, read `taskKey`, `taskGroup`, `taskType`, `currentStatus`, `latestRunStatus`, `updatedAt`, `latestReportPath`, `latestResumeCommandPath`, `latestRunManifestPath`, `historyTimelinePath`.
-3. Apply the same filters/sort/limit and print the same table, prefixed with: `note: task-catalog.json missing; reconstructed from task manifests on disk.`
-4. Only if the glob yields zero manifests: respond `There is no okstra execution history yet.`
-
-## Step 2: Run History by Task
-
-When a user selects a specific task or requests detailed history:
-
-1. Retrieve the `historyTimelinePath` path for the task from the task catalog.
-2. Read the `runs` array from `timeline.json`.
-3. Fields to extract from each run:
-
-| Field | Description |
-|------|------|
-| `runTimestamp` | Execution time (ISO 8601) |
-| `runDateTimeSegment` | YYYY-MM-DD_HH-MM-SS |
-| `taskType` | `--task-type` argument value |
-| `status` | Run status |
-| `runManifestPath` | This run's `run-manifest-*.json` — feed into Step 3 to re-run from this specific run's parameters |
-| `reportPath` | Final report path |
-| `resumeCommandPath` | Resume Claude session for this run (Step 4) |
-| `relatedTasks` | List of related task-keys |
-
-4. Output format:
-
-```markdown
-## Runs for <task-key>
-
-| # | Timestamp | Type | Status | Report |
-|---|-----------|------|--------|--------|
-| 1 | 2026-04-05 22:59 | error-analysis | completed | .../final-report-*.md |
-| 2 | 2026-04-04 15:30 | error-analysis | error | -- |
-```
-
-## Step 3: Re-run (build a NEW run from an old run's parameters)
-
-This builds a **fresh run** — new run-seq, new manifest, new report — using the parameters captured in a previous `run-manifest-*.json`. It does NOT touch the old run's artifacts; use Step 4 if the user wants to continue an interrupted session instead.
-
-1. Pick the source run-manifest: the `runManifestPath` from a Step 2 timeline entry, or the task's `latestRunManifestPath` from Step 1.
-2. Read the run-manifest JSON and extract required arguments:
-   - `projectId` → `--project-id`
-   - `taskGroup` → `--task-group`
-   - `taskId` → `--task-id`
-   - `taskType` → `--task-type`
-   - `taskBriefPath` → `--task-brief`
-3. Extract optional arguments (include only when present in the source manifest):
-   - `recommendedWorkers` → `--workers` (comma-separated)
-   - `relatedTasks` → `--related-tasks`
-   - model overrides → `--claude-model`, `--codex-model`, `--gemini-model` (when different from default)
-   - for `taskType: implementation`: `teamContract.executor.provider` → `--executor <claude|codex|gemini>` (when different from `claude`)
-4. **`taskType: implementation` only — resolve `--base-ref`:** the base ref is NOT stored in the run-manifest; it lives in the worktree registry at `~/.okstra/worktrees/registry.json` against the registered branch. Before assembling the command:
-   - If a worktree for this task-key is already registered, the existing branch & base are reused — omit `--base-ref` unless the user explicitly wants a different starting point.
-   - If no worktree is registered (e.g. it was cleaned up), `--base-ref` is mandatory. Ask the user for the ref to branch from (e.g. `main`, a commit SHA, a tag) before running.
-5. Display the assembled command:
-
-```bash
-okstra.sh \
-  --project-id <project-id> \
-  --task-group <task-group> \
-  --task-id <task-id> \
-  --task-type <task-type> \
-  --task-brief <brief-path> \
-  --workers <worker-list>
-```
-
-6. Once the user confirms, execute it using the Bash tool.
-
-## Step 4: Resume (continue an interrupted run)
-
-This continues an existing Claude session for a run that did not finish. It does NOT create a new run-seq — for a fresh dispatch, use Step 3.
-
-1. Read `latestResumeCommandPath` from the task catalog (Step 1) — or `resumeCommandPath` from a specific timeline entry (Step 2).
-2. Verify the file exists on disk.
-3. If present:
-   ```bash
-   bash <resume-command-path>
-   ```
-4. If absent, report: `No resume script available for this run. Use Step 3 to start a fresh run instead.`
-
-## Output Rules
-
-- Display concisely in a table format
-- Dates in `YYYY-MM-DD HH:MM` format
-- Display status fields as-is from disk (`completed`, `contract-violated`, `todo`, `error`, empty, ...). Do not normalize or remap.
-- Display `--` if no report is available