okstra 0.38.1 → 0.40.0

package/src/setup.mjs

@@ -1,13 +1,9 @@
 import { promises as fs } from "node:fs";
-import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { homedir } from "node:os";
 import { join, resolve as resolvePath } from "node:path";
 import { resolvePaths } from "./paths.mjs";
-import {
-  CLAUDE_MD_IMPORT_LINE as DIRS_CLAUDE_MD_IMPORT_LINE,
-  claudeMdSymlinkRelative,
-} from "./okstra-dirs.mjs";
+import { fileExists, runProcess } from "./_proc.mjs";
 
 const USAGE = `okstra setup — register the current project with okstra
 
@@ -38,21 +34,6 @@ Exit codes:
   2   PROJECT_ROOT could not be resolved
 `;
 
-function runProcess(cmd, args, env) {
-  return new Promise((resolve) => {
-    const child = spawn(cmd, args, {
-      stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, ...env },
-    });
-    let stdout = "";
-    let stderr = "";
-    child.stdout.on("data", (b) => (stdout += b.toString()));
-    child.stderr.on("data", (b) => (stderr += b.toString()));
-    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
-    child.on("close", (code) => resolve({ code, stdout, stderr }));
-  });
-}
-
 function parseArgs(args) {
   const opts = {
     projectId: null,
@@ -79,14 +60,6 @@ function parseArgs(args) {
   return opts;
 }
 
-async function fileExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
 
 function prompt(question) {
   return new Promise((resolve) => {
@@ -297,26 +270,6 @@ 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 @ .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(
       {
@@ -324,9 +277,6 @@ export async function run(args) {
         ...result,
         projectJsonPath,
         settingsLocalJson: settingsSymlink,
-        claudeMdSymlink: claudeMd.symlink,
-        claudeMdImportInjected: claudeMd.importInjected,
-        agentsMdSymlink,
       },
       null,
       2,
@@ -381,106 +331,3 @@ async function backupAndReplace(target, template) {
   await fs.symlink(template, target);
 }
 
-const CLAUDE_MD_TEMPLATE_PATH = join(homedir(), ".okstra", "templates", "okstra.CLAUDE.md");
-const CLAUDE_MD_SYMLINK_REL = claudeMdSymlinkRelative();
-const CLAUDE_MD_IMPORT_LINE = DIRS_CLAUDE_MD_IMPORT_LINE;
-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

@@ -54,8 +54,7 @@ Usage:
   okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
                                 dev-link, installed-skills.json,
                                 installed-agents.json,
-                                templates/settings.local.json,
-                                templates/okstra.CLAUDE.md} AND
+                                templates/settings.local.json} AND
                                 ~/.claude/skills/<name> AND
                                 ~/.claude/agents/<worker>.md for every
                                 entry in the install manifests (fallback:
@@ -64,10 +63,7 @@ Usage:
                                 active.jsonl, projects/, archive/,
                                 state.json, .locks/
                                 Per-project artifacts created by 'okstra setup'
-                                (<PROJECT>/.okstra/CLAUDE.md symlink,
-                                <PROJECT>/CLAUDE.md import block,
-                                <PROJECT>/AGENTS.md symlink,
-                                <PROJECT>/.claude/settings.local.json 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
@@ -199,13 +195,10 @@ 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>/.okstra/CLAUDE.md symlink,
-  // <PROJECT>/AGENTS.md symlink, and the @.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.
+  // Per-project <PROJECT>/.claude/settings.local.json symlinks are NOT removed
+  // here — uninstall is machine-level and does not know which projects opted
+  // in. They 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/templates/okstra.CLAUDE.md

@@ -1,104 +0,0 @@
-# okstra — agent guidance (managed)
-
-This file is shipped by `okstra install` and surfaced into the active project
-through two channels by `okstra setup`:
-
-- **Claude Code**: `<PROJECT>/CLAUDE.md` gets an `@.okstra/CLAUDE.md`
-  import block (per-project symlink to this template). Existing user content
-  in `CLAUDE.md` is preserved — the block lives between
-  `<!-- okstra:claude-md:begin ... -->` markers.
-- **Codex / Aider / other AGENTS.md-aware agents**: `<PROJECT>/AGENTS.md` is
-  created as a direct symlink to this template — but **only if AGENTS.md does
-  not already exist**. okstra never overwrites a hand-written AGENTS.md.
-
-It is **owned by the okstra package**: every `okstra install` overwrites
-`~/.okstra/templates/okstra.CLAUDE.md` from the version currently on disk in
-the npm package. Edits made directly to this file (or to the per-project
-`<PROJECT>/.okstra/CLAUDE.md` / `<PROJECT>/AGENTS.md` symlinks)
-will be lost on the next install. Put project-specific overrides outside the
-managed block in `<PROJECT>/CLAUDE.md` instead (or replace `AGENTS.md` with
-your own file — okstra will respect it).
-
-## What okstra is
-
-okstra is a multi-agent cross-verification orchestrator. A Claude lead drives
-the run; codex / gemini / claude workers produce independent analyses; a
-report writer worker synthesises the final report. Day-to-day usage happens
-through slash commands inside a Claude Code session.
-
-## Slash commands
-
-| Command | When to use |
-| --- | --- |
-| `/okstra-setup` | First-time bootstrap in a new project — writes `.okstra/project.json`, provisions `.claude/settings.local.json` and `.okstra/CLAUDE.md`. |
-| `/okstra-brief` | Turn a requirements doc / ticket / link / conversation into the markdown task brief consumed by `okstra-run`. |
-| `/okstra-run` | Start a cross-verification task in the current session. Drives the interactive wizard. |
-| `/okstra-status` | Inspect overall okstra task status, current phase, blockers, next recommended phase. Also flips a task's workStatus (todo / in-progress / blocked / done). |
-| `/okstra-history` | List past runs, review previous results, queue a re-run. |
-| `/okstra-schedule` | Generate a consolidated work plan across multiple tasks in a task-group. |
-| `/okstra-convergence` | Iterative cross-verification between workers in Phase 5.5; classify findings by consensus level. |
-| `/okstra-report-finder` | Locate the final-report path for a given task key, or read a past report to continue work. |
-| `/okstra-report-writer` | Author / persist the final synthesis report (Phase 6–7). |
-| `/okstra-time-summary` | Per-task / per-worker elapsed time breakdown for a task-id. |
-| `/okstra-logs` | List, size, and clean up `*.log` sidecars from past worker dispatches. |
-
-Type the slash command — do not paraphrase the trigger words into prose.
-
-## Workflow boundaries
-
-- The Claude lead **does not** produce independent worker findings. It
-  dispatches workers, monitors them, and drives convergence. Analysis is the
-  workers' job.
-- Worker wrappers (`okstra-codex-exec.sh`, `okstra-gemini-exec.sh`) run from
-  `~/.okstra/bin/` and are pre-authorised via `<PROJECT>/.claude/settings.local.json`
-  (a symlink to `~/.okstra/templates/settings.local.json`). Do **not**
-  duplicate those permissions in the user's global `~/.claude/settings.json`.
-- Each okstra run provisions a task-scoped git worktree under
-  `~/.okstra/worktrees/`. Files synced from the main checkout are governed by
-  `worktreeSyncDirs` in `.okstra/project.json` (default:
-  `.project-docs`, `.scratch`, `graphify-out`, `.claude`).
-- QA gating is configured via `qaCommands` in the same `project.json`.
-  Verifiers reject mutation-style commands (`--fix`, `--write`, `cargo update`,
-  `npm install`, etc.); declare check-only variants only.
-
-## Coding Principles (BLOCKING — agent self-checks before declaring work complete)
-
-These apply to every worker writing or editing project code (executor and verifiers alike). Enforcement is self-check: the agent runs each rule's check immediately before reporting "done"; skipping a check is itself a contract violation.
-
-1. **DRY — single reference point** — One implementation per capability. A second caller signals "extract shared logic", not "duplicate path".
-2. **KISS — simplest sufficient design** — Add abstraction layers (helper modules, strategy/factory, configuration flags, indirection) only when an existing concrete call site requires them. *Self-check: name the second caller now; if you cannot, inline.* *Example violation: extracting `formatUserName()` helper used by exactly one call site, "in case we need it elsewhere".*
-3. **YAGNI — build only for current requirements** — No speculative parameters, optional configs, "future-proof" hooks, or pre-1.0 backwards-compat shims. *Self-check: every newly introduced identifier has ≥1 current internal caller, or was explicitly user-requested.* *Example violation: adding `options?: { retries?, timeout? }` parameter when the current call passes nothing.*
-4. **Clean Code — names carry WHAT, comments explain WHY** — Identifiers must make intent obvious; if a comment would describe WHAT the code does, rename instead. Reserve comments for non-obvious WHY (hidden constraint, workaround, surprising invariant). Delete dead/commented-out code immediately — git history is the archive. *Example — WHAT (rename instead): `// increment counter` above `i++`. WHY (keep): `// retry up to 3x: upstream returns 502 during deploys`.*
-5. **Function length cap — 50 lines** — A single function/method body must stay within 50 lines, counting only effective code (exclude blank lines, comments, and pure data declarations such as large enums, lookup tables, or constant maps). Crossing the cap is an extraction signal, not a style nit. *Self-check: for any function newly added or substantially edited, count effective body lines; if over 50, split before declaring complete, or surface the violation and confirm with the user.*
-
-## Phase model (high level)
-
-```
-Phase 1  context-loader          → load brief + project context
-Phase 2  team-contract           → confirm lead + worker roster
-Phase 3  worker dispatch         → workers run independently in parallel
-Phase 4  result collection       → gather worker outputs
-Phase 5  cross-review            → workers critique each other's findings
-Phase 5.5 convergence            → classify findings, iterate until stable
-Phase 6  report-writer dispatch  → synthesise final report
-Phase 7  artifact persistence    → manifests, central index update
-```
-
-The lead skill (`okstra-run`) advances phases automatically. Use
-`/okstra-status` to inspect the current phase and `next-recommended-phase`
-hint when resuming.
-
-## Troubleshooting hints
-
-- "okstra runtime missing" / `InstallationError` — run
-  `npx okstra@latest install` (or `okstra ensure-installed`).
-- Worker dispatch refused by Claude Code permissions — verify
-  `<PROJECT>/.claude/settings.local.json` is a symlink to
-  `~/.okstra/templates/settings.local.json`; re-run `/okstra-setup` to
-  re-provision.
-- `qa-command not configured: <category>` warnings — add the missing
-  `lint` / `format` / `typecheck` / `test` entries to `qaCommands` in
-  `project.json`.
-
-For deeper documentation see the package README and `docs/` in the okstra
-source tree.