okstra 0.38.1 → 0.40.0

package/runtime/validators/validate_fanout.py

@@ -0,0 +1,99 @@
+"""Validator for requirements-discovery fan-out packets + index.
+
+Called by validators/validate-run.py when task_type == "requirements-discovery"
+and a `fan-out/` directory exists under the run dir.
+"""
+from __future__ import annotations
+
+import re
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_SCRIPTS_DIR = Path(__file__).resolve().parent.parent / "scripts"
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+from okstra_ctl.work_categories import WORK_CATEGORIES  # noqa: E402
+from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402
+
+_NEXT_PHASES = ("error-analysis", "implementation-planning")
+_UNIT_RE = re.compile(r"unit-\d{3}")
+# index.md 번호목록 항목에서만 unit-NNN 을 추출 — 내러티브 문장 중복 방지
+_INDEX_ENTRY_RE = re.compile(r"^\s*\d+\.\s+(unit-\d{3})\b", re.MULTILINE)
+
+
+@dataclass
+class ValidationResult:
+    ok: bool
+    errors: list[str] = field(default_factory=list)
+
+
+def _frontmatter(text: str) -> dict[str, str]:
+    if not text.startswith("---"):
+        return {}
+    end = text.find("\n---", 3)
+    if end == -1:
+        return {}
+    fm: dict[str, str] = {}
+    last_key: str | None = None
+    for line in text[3:end].splitlines():
+        if ":" in line and not line.startswith((" ", "\t")):
+            k, _, v = line.partition(":")
+            fm[k.strip()] = v.strip()
+            last_key = k.strip()
+        elif last_key and line.strip().startswith("- "):
+            # YAML 블록리스트 항목 — 해당 키 값에 공백으로 이어 붙임
+            token = line.strip()[2:].strip()
+            fm[last_key] = (fm.get(last_key, "") + " " + token).strip()
+    return fm
+
+
+def _parse_deps(raw: str) -> list[str]:
+    return _UNIT_RE.findall(raw or "")
+
+
+def validate_fanout(run_dir: Path) -> ValidationResult:
+    run_dir = Path(run_dir)
+    fo = run_dir / "fan-out"
+    if not fo.is_dir():
+        return ValidationResult(ok=True)
+
+    errors: list[str] = []
+    units: dict[str, list[str]] = {}
+    for pkt in sorted(fo.glob("unit-*.md")):
+        fm = _frontmatter(pkt.read_text(encoding="utf-8"))
+        uid = fm.get("unit-id", "")
+        if uid != pkt.stem:
+            errors.append(f"{pkt.name}: unit-id {uid!r} != filename stem {pkt.stem!r}")
+        if fm.get("domain") not in WORK_CATEGORIES:
+            errors.append(f"{pkt.name}: domain {fm.get('domain')!r} not in {WORK_CATEGORIES}")
+        if fm.get("recommended-next-phase") not in _NEXT_PHASES:
+            errors.append(f"{pkt.name}: recommended-next-phase not in {_NEXT_PHASES}")
+        units[pkt.stem] = _parse_deps(fm.get("depends-on", ""))
+
+    if not units:
+        errors.append("fan-out/: directory exists but no unit-*.md packets found")
+        return ValidationResult(ok=False, errors=errors)
+
+    order: list[str] = []
+    try:
+        order = topological_order(units)
+    except CycleError as exc:
+        errors.append(f"depends-on cycle: {exc}")
+    except ValueError as exc:
+        errors.append(f"depends-on unresolved: {exc}")
+
+    index = fo / "index.md"
+    if not index.is_file():
+        errors.append("fan-out/index.md missing")
+    else:
+        listed = _INDEX_ENTRY_RE.findall(index.read_text(encoding="utf-8"))
+        if set(listed) != set(units):
+            errors.append(
+                f"index.md units {sorted(set(listed))} != packets {sorted(units)}"
+            )
+        elif order and listed != order:
+            errors.append(f"index.md order {listed} is not the topological order {order}")
+
+    return ValidationResult(ok=not errors, errors=errors)

package/src/_proc.mjs

@@ -0,0 +1,31 @@
+// Shared filesystem / subprocess helpers used by the Node command modules.
+// Extracted to one place so a fix lands once instead of in each command file.
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+
+export async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Run `cmd args`, capturing stdout/stderr. `env` holds *additional* vars that
+// are merged over the inherited process.env. Never rejects — failures resolve
+// with { code: -1, stderr: <message> }.
+export 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 }));
+  });
+}

package/src/check-project.mjs

@@ -1,7 +1,7 @@
 import { promises as fs } from "node:fs";
-import { spawn } from "node:child_process";
 import { join } from "node:path";
 import { buildPythonpath, resolvePaths } from "./paths.mjs";
+import { fileExists, runProcess } from "./_proc.mjs";
 
 const USAGE = `okstra check-project — verify that the current project has okstra setup
 
@@ -27,30 +27,6 @@ to proceed if the exit code is non-zero, directing the user to
 '/okstra-setup' first.
 `;
 
-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 }));
-  });
-}
-
-async function fileExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 function parseArgs(args) {
   const opts = { cwd: process.cwd(), quiet: false, json: true };
   for (let i = 0; i < args.length; i++) {

package/src/config.mjs

@@ -1,9 +1,9 @@
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve, isAbsolute } from "node:path";
-import { spawn } from "node:child_process";
 import { buildPythonpath, resolvePaths } from "./paths.mjs";
 import { OKSTRA_DIR, projectJsonPath } from "./okstra-dirs.mjs";
+import { fileExists, runProcess } from "./_proc.mjs";
 
 const USAGE = `okstra config — read / write okstra settings (project + global scopes)
 
@@ -136,15 +136,6 @@ function projectConfigPath(projectRoot) {
   return projectJsonPath(projectRoot);
 }
 
-async function fileExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function readJson(p) {
   if (!(await fileExists(p))) return null;
   const text = await fs.readFile(p, "utf8");
@@ -163,24 +154,9 @@ async function writeJsonAtomic(p, data) {
   await fs.rename(tmp, p);
 }
 
-function spawnCapture(cmd, args, env) {
-  return new Promise((resolveProc) => {
-    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) => resolveProc({ code: -1, stdout, stderr: err.message }));
-    child.on("close", (code) => resolveProc({ code, stdout, stderr }));
-  });
-}
-
 async function resolveProjectRoot(cwd) {
   const paths = await resolvePaths();
-  const result = await spawnCapture(
+  const result = await runProcess(
     "python3",
     [
       "-c",
@@ -214,7 +190,7 @@ async function effectivePrTemplatePath(projectRoot) {
   // case where we just want to surface the chain in 'config get --scope all'.
   // Python remains the source of truth at run time; this is informational.
   const paths = await resolvePaths();
-  const result = await spawnCapture(
+  const result = await runProcess(
     "python3",
     [
       "-c",
@@ -306,11 +282,11 @@ async function opSet(opts) {
   const err = spec.validate(opts.value, ctx);
   if (err) throw new Error(err);
 
-  const targetPath =
-    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
   if (scope === "project" && !projectRoot) {
     throw new Error("cwd not inside an okstra project — cannot write project scope");
   }
+  const targetPath =
+    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
   const existing = (await readJson(targetPath)) ?? {};
   existing[spec.jsonField] = opts.value;
   await writeJsonAtomic(targetPath, existing);
@@ -326,11 +302,11 @@ async function opUnset(opts) {
     scope = projectRoot ? "project" : null;
     if (!scope) throw new Error("--scope is required (project|global)");
   }
-  const targetPath =
-    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
   if (scope === "project" && !projectRoot) {
     throw new Error("cwd not inside an okstra project — cannot unset project scope");
   }
+  const targetPath =
+    scope === "project" ? projectConfigPath(projectRoot) : globalConfigPath();
   const existing = (await readJson(targetPath)) ?? {};
   if (!(spec.jsonField in existing)) {
     emit(opts, { ok: true, scope, path: targetPath, key: opts.key, removed: false });

package/src/doctor.mjs

@@ -1,8 +1,8 @@
 import { promises as fs } from "node:fs";
-import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
+import { fileExists, runProcess } from "./_proc.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
@@ -23,34 +23,13 @@ Checks:
   - version stamp matches package version
 `;
 
-async function pathExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function runProcess(cmd, args, opts = {}) {
-  return new Promise((resolve) => {
-    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], ...opts });
-    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 }));
-  });
-}
-
 async function checkPython3() {
   const r = await runProcess("python3", ["--version"]);
   if (r.code !== 0) return { ok: false, detail: `python3 not found: ${r.stderr.trim() || "missing binary"}` };
   const out = (r.stdout + r.stderr).trim();
   const m = out.match(/Python\s+(\d+)\.(\d+)/);
   if (!m) return { ok: false, detail: `unparsable python version: ${out}` };
-  const [_, maj, min] = m.map(Number);
+  const [, maj, min] = m.map(Number);
   if (maj < 3 || (maj === 3 && min < 10)) {
     return { ok: false, detail: `python ${maj}.${min} is too old (need 3.10+)` };
   }
@@ -58,9 +37,11 @@ async function checkPython3() {
 }
 
 async function checkPythonImport(moduleName, pythonpath) {
-  const r = await runProcess("python3", ["-c", `import ${moduleName}; print(${moduleName}.__name__)`], {
-    env: { ...process.env, PYTHONPATH: pythonpath },
-  });
+  const r = await runProcess(
+    "python3",
+    ["-c", `import ${moduleName}; print(${moduleName}.__name__)`],
+    { PYTHONPATH: pythonpath },
+  );
   if (r.code !== 0) {
     return { ok: false, detail: `import ${moduleName} failed: ${r.stderr.trim().split("\n").pop()}` };
   }
@@ -69,7 +50,7 @@ async function checkPythonImport(moduleName, pythonpath) {
 
 async function checkBashEntry(binDir, name) {
   const p = join(binDir, name);
-  if (!(await pathExists(p))) return { ok: false, detail: `missing ${p}` };
+  if (!(await fileExists(p))) return { ok: false, detail: `missing ${p}` };
   try {
     const st = await fs.stat(p);
     if (!(st.mode & 0o111)) return { ok: false, detail: `${name} not executable` };
@@ -101,7 +82,7 @@ export async function run(args) {
     await check("okstra_project import", () => checkPythonImport("okstra_project", paths.pythonpath)),
     await check("okstra_ctl import", () => checkPythonImport("okstra_ctl", paths.pythonpath)),
     await check("agents dir", async () =>
-      (await pathExists(paths.agents))
+      (await fileExists(paths.agents))
         ? { ok: true, detail: paths.agents }
         : { ok: false, detail: `not found: ${paths.agents}` },
     ),
@@ -113,7 +94,7 @@ export async function run(args) {
       REQUIRED_SKILLS.map((name) =>
         check(`skill: ${name}`, async () => {
           const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
-          return (await pathExists(p))
+          return (await fileExists(p))
             ? { ok: true, detail: p }
             : { ok: false, detail: `not found: ${p}` };
         }),

package/src/install.mjs

@@ -4,6 +4,7 @@ import { homedir } from "node:os";
 import { join, relative, resolve as resolveAbs } from "node:path";
 import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
+import { fileExists } from "./_proc.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -15,11 +16,7 @@ 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>/.okstra/CLAUDE.md
-// symlinks here; <PROJECT>/CLAUDE.md gets an `@.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 PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "okstra_vendor"];
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
   "okstra-codex-exec.sh",
@@ -46,7 +43,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 / okstra.CLAUDE.md)
+  ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.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
@@ -58,7 +55,6 @@ 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
@@ -69,11 +65,6 @@ 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>/.okstra/CLAUDE.md that okstra-setup provisions;
-<project>/CLAUDE.md gets an "@.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/
@@ -256,7 +247,6 @@ async function installLinkMode(repoPath, paths, opts) {
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
 
   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);
@@ -277,15 +267,6 @@ async function installLinkMode(repoPath, paths, opts) {
   return 0;
 }
 
-async function fileExists(p) {
-  try {
-    await fs.access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
 async function listSkillDirs(skillsRoot) {
   try {
     const entries = await fs.readdir(skillsRoot, { withFileTypes: true });
@@ -458,12 +439,6 @@ const SETTINGS_TEMPLATE_DESCRIPTOR = {
   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");
@@ -577,12 +552,11 @@ export async function runInstall(args) {
     paths.bin,
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
   );
-  // 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 .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
+  // 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 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(
     join(runtimeRoot, "templates"),
@@ -632,8 +606,6 @@ export async function runInstall(args) {
   await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
 
   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/migrate.mjs

@@ -1,6 +1,6 @@
-import { spawn } from "node:child_process";
 import { buildPythonpath, resolvePaths } from "./paths.mjs";
 import { LEGACY_OKSTRA_DIR, OKSTRA_DIR } from "./okstra-dirs.mjs";
+import { runProcess } from "./_proc.mjs";
 
 const USAGE = `okstra migrate — move project artifacts from ${LEGACY_OKSTRA_DIR}/ to ${OKSTRA_DIR}/
 
@@ -15,7 +15,6 @@ Usage:
   okstra migrate --apply        Execute the move and ancillary updates.
   okstra migrate --cwd <dir>    Search starting point (default: cwd).
   okstra migrate --quiet        Suppress stdout on success; exit code reports.
-  okstra migrate --json         Force JSON output (default for both modes).
 
 Exit codes:
   0   plan prepared (dry-run) or migration applied successfully
@@ -28,28 +27,12 @@ exits 1 with "nothing to migrate". Safe to wire into CI as a one-shot
 post-upgrade step.
 `;
 
-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 = { cwd: process.cwd(), apply: false, quiet: false };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--apply") opts.apply = true;
     else if (a === "--quiet" || a === "-q") opts.quiet = true;
-    else if (a === "--json") opts.json = true;
     else if (a === "--cwd") {
       const next = args[i + 1];
       if (!next || next.startsWith("--")) throw new Error("--cwd requires a path");

package/src/okstra-dirs.mjs

@@ -16,8 +16,6 @@ export const OKSTRA_DIR = ".okstra";
 // 코드 path 빌드에는 절대 사용 금지 — `OKSTRA_DIR` 만. 오로지 migration
 // 탐지/안내 메시지 용도.
 export const LEGACY_OKSTRA_DIR = ".project-docs/okstra";
-export const CLAUDE_MD_IMPORT_LINE = `@${OKSTRA_DIR}/CLAUDE.md`;
-export const LEGACY_CLAUDE_MD_IMPORT_LINE = `@${LEGACY_OKSTRA_DIR}/CLAUDE.md`;
 
 export function okstraRoot(projectRoot) {
   return join(projectRoot, OKSTRA_DIR);
@@ -26,12 +24,3 @@ export function okstraRoot(projectRoot) {
 export function projectJsonPath(projectRoot) {
   return join(okstraRoot(projectRoot), "project.json");
 }
-
-export function claudeMdSymlinkPath(projectRoot) {
-  return join(okstraRoot(projectRoot), "CLAUDE.md");
-}
-
-export function claudeMdSymlinkRelative() {
-  // setup.mjs 의 기존 `CLAUDE_MD_SYMLINK_REL` 와 동일한 project-relative 값.
-  return join(OKSTRA_DIR, "CLAUDE.md");
-}