okstra 0.7.0 → 0.9.0

package/runtime/validators/validate-run.py

@@ -36,11 +36,35 @@ def default_next_phase(task_type: str) -> str:
         "requirements-discovery": "pending-routing-decision",
         "error-analysis": "implementation-planning",
         "implementation-planning": "implementation",
-        "final-verification": "done-or-follow-up",
+        "implementation": "final-verification",
+        # final-verification 의 다음 phase 는 verdict 에 따라 갈리므로
+        # 정적 매핑은 `pending-release-handoff` 로 두고, 실제 진입은
+        # release-handoff profile 의 entry gate (`accepted` 확인) 에서 강제한다.
+        "final-verification": "pending-release-handoff",
+        "release-handoff": "done-or-follow-up",
     }
     return mapping.get(task_type, "unknown")
 
 
+def advance_next_phase(
+    current_phase: str,
+    phase_sequence: list,
+) -> str:
+    """Compute the next recommended phase after `current_phase` completes.
+
+    Walk `phase_sequence` and return the entry following `current_phase`.
+    Falls back to the static `default_next_phase` mapping when the current
+    phase is the terminal entry or is absent from the sequence (e.g. custom
+    task types that aren't part of the standard 5-phase lifecycle).
+    """
+    if isinstance(phase_sequence, list) and current_phase in phase_sequence:
+        idx = phase_sequence.index(current_phase)
+        if idx + 1 < len(phase_sequence):
+            return phase_sequence[idx + 1]
+        return "done-or-follow-up"
+    return default_next_phase(current_phase)
+
+
 def update_workflow_metadata(
     run_manifest: dict,
     task_manifest: dict,
@@ -64,6 +88,7 @@ def update_workflow_metadata(
             "implementation-planning",
             "implementation",
             "final-verification",
+            "release-handoff",
         ]
 
     phase_states = workflow.get("phaseStates", {})
@@ -77,9 +102,10 @@ def update_workflow_metadata(
         if current_phase:
             phase_states[current_phase] = current_phase_state
         last_completed_phase = current_phase or workflow.get("lastCompletedPhase", "")
-        next_recommended_phase = (
-            workflow.get("nextRecommendedPhase") or default_next_phase(current_phase)
-        )
+        # Validation just passed → actively advance to the next phase in
+        # the sequence rather than preserving a stale value that may equal
+        # current_phase (which would cause the lifecycle pointer to stall).
+        next_recommended_phase = advance_next_phase(current_phase, phase_sequence)
     else:
         current_phase_state = "blocked"
         if current_phase:
@@ -98,6 +124,12 @@ def update_workflow_metadata(
     awaiting_approval = workflow.get("awaitingApproval")
     if not isinstance(awaiting_approval, bool):
         awaiting_approval = False
+    # 승인 게이트(`User Approval Request`)는 implementation 진입 직전에 한 번만 의미를 가진다.
+    # implementation run 이 검증을 통과했다는 것은 `_validate_approved_plan` 이 이미 사용자
+    # 마커를 소비했다는 뜻이므로, 이 시점에 awaitingApproval 플래그를 명시적으로 내려
+    # 다음 phase 의 status 뷰에서 stale 상태로 남지 않게 한다.
+    if validation_status == "passed" and current_phase == "implementation":
+        awaiting_approval = False
 
     last_safe_checkpoint = workflow.get("lastSafeCheckpoint", {})
     if not isinstance(last_safe_checkpoint, dict):
@@ -440,6 +472,28 @@ def validate_team_state_usage(team_state: dict, failures: list[str]) -> None:
             "Run `python3 scripts/okstra-token-usage.py <team-state> --write --summary "
             "--substitute-final-report <final-report>`."
         )
+        return
+    # Reject zero-valued usage when the collector flagged any source as
+    # `unavailable`. This catches the silent-failure mode where the
+    # collector ran but couldn't locate session jsonls (e.g. empty
+    # claudeSession.sessionId, missing subagent jsonl).
+    grand_total = summary.get("grandTotalTokens", 0)
+    if isinstance(grand_total, (int, float)) and grand_total == 0:
+        lead = team_state.get("leadUsage") or {}
+        if lead.get("source") == "unavailable":
+            failures.append(
+                "team-state.usageSummary.grandTotalTokens is 0 and leadUsage.source is "
+                f"`unavailable` — {lead.get('note', 'reason unknown')}. Re-collect once "
+                "the lead session jsonl is locatable."
+            )
+        for worker in team_state.get("workers") or []:
+            role = (worker or {}).get("role") or (worker or {}).get("workerId") or "<worker>"
+            usage = (worker or {}).get("usage") or {}
+            if usage.get("source") == "unavailable":
+                failures.append(
+                    f"team-state.workers[{role}].usage.source is `unavailable` while "
+                    f"grandTotalTokens is 0 — {usage.get('note', 'reason unknown')}."
+                )
 
 
 PLANNING_REQUIRED_SECTIONS = (
@@ -479,6 +533,56 @@ def validate_phase_boundary(
             )
 
 
+def _refresh_task_catalog(project_root: Path, task_manifest: dict) -> tuple[bool, str]:
+    """Regenerate `discovery/task-catalog.json` so it stops trailing the
+    authoritative `task-manifest.json` after validation.
+
+    Resolves the catalog output path from the manifest, scans every
+    `task-manifest.json` under the tasks root, and rewrites the catalog
+    via `render_task_catalog_discovery`. Returns (ok, message); failure
+    is non-fatal — the validator logs a warning instead of breaking the
+    overall validation result.
+    """
+    catalog_relative = (task_manifest.get("taskCatalogPath") or "").strip()
+    if not catalog_relative:
+        return False, "taskCatalogPath missing from task-manifest — skip catalog refresh"
+
+    here = Path(__file__).resolve().parent
+    candidates = [
+        here.parent / "scripts",
+        here.parent / "python",
+    ]
+    env_pp = os.environ.get("OKSTRA_PYTHONPATH", "").strip()
+    if env_pp:
+        candidates.append(Path(env_pp))
+    for candidate in candidates:
+        if candidate.is_dir() and (candidate / "okstra_ctl").is_dir():
+            if str(candidate) not in sys.path:
+                sys.path.insert(0, str(candidate))
+            break
+
+    try:
+        from okstra_ctl.render import render_task_catalog_discovery  # noqa: E402
+    except Exception as exc:  # noqa: BLE001
+        return False, f"okstra_ctl import failed: {exc}"
+
+    tasks_root = (project_root / ".project-docs" / "okstra" / "tasks").resolve()
+    catalog_path = (project_root / catalog_relative).resolve()
+    ctx = {
+        "PROJECT_ROOT": str(project_root),
+        "OKSTRA_TASKS_ROOT": str(tasks_root),
+        "PROJECT_ID": task_manifest.get("projectId", ""),
+        "RUN_TIMESTAMP_ISO": utc_now(),
+        "TASK_KEY": task_manifest.get("taskKey", ""),
+        "OKSTRA_LATEST_TASK_RELATIVE_PATH": "",
+    }
+    try:
+        render_task_catalog_discovery(str(catalog_path), ctx)
+    except Exception as exc:  # noqa: BLE001
+        return False, f"render_task_catalog_discovery raised: {exc}"
+    return True, f"task-catalog refreshed at {catalog_relative}"
+
+
 def _import_token_usage():
     """Resolve and import the okstra_token_usage package across layouts.
 
@@ -512,6 +616,22 @@ def _needs_token_autofix(team_state: dict, report_path: Path) -> bool:
         content = report_path.read_text()
         if any(p in content for p in TOKEN_PLACEHOLDERS):
             return True
+    # Even if the collector already ran (collectedAt is set), trigger when
+    # every recorded usage is zero AND at least one source is "unavailable".
+    # That combination means the previous collection silently failed to
+    # locate session jsonls — we must surface accuracy failures rather than
+    # let zeroed data ship as the final answer.
+    grand_total = summary.get("grandTotalTokens", 0)
+    if isinstance(grand_total, (int, float)) and grand_total == 0:
+        lead_unavailable = (
+            (team_state.get("leadUsage") or {}).get("source") == "unavailable"
+        )
+        workers_unavailable = any(
+            (w or {}).get("usage", {}).get("source") == "unavailable"
+            for w in (team_state.get("workers") or [])
+        )
+        if lead_unavailable or workers_unavailable:
+            return True
     return False
 
 
@@ -690,6 +810,18 @@ def main() -> int:
     write_json(run_manifest_path, run_manifest)
     write_json(task_manifest_path, task_manifest)
 
+    # Best-effort: regenerate discovery/task-catalog.json so downstream
+    # tools (okstra-schedule, FleetView listings, etc.) don't read a stale
+    # snapshot frozen at instruction-set generation time.
+    catalog_ok, catalog_msg = _refresh_task_catalog(project_root, task_manifest)
+    if catalog_ok:
+        print(f"validate-run: {catalog_msg}", file=sys.stderr)
+    else:
+        print(
+            f"validate-run: task-catalog refresh skipped — {catalog_msg}",
+            file=sys.stderr,
+        )
+
     if args.final_status:
         final_status_path = resolve_input(args.final_status)
         final_status_path.parent.mkdir(parents=True, exist_ok=True)

package/src/install.mjs

@@ -6,7 +6,9 @@ import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
+const AGENTS_MANIFEST_REL = "installed-agents.json";
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+const CLAUDE_AGENTS_DIR = join(homedir(), ".claude", "agents");
 
 const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
 const BIN_ENTRYPOINTS = [
@@ -32,18 +34,23 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
   ${"$HOME"}/.okstra/bin           <- runtime/bin
   ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
+  ${"$HOME"}/.claude/agents/<worker>.md <- runtime/agents/workers/<worker>.md
   ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
+  ${"$HOME"}/.okstra/installed-agents.json   <- manifest of installed workers
   ${"$HOME"}/.okstra/version       <- installed package version stamp
 
 Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
   ${"$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
   ${"$HOME"}/.okstra/version          <- installed package version stamp
 
-agents/ is NOT copied — it stays inside the package (copy mode) or is
-resolved to <repo>/agents (link mode) via 'okstra paths --field agents'.
+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/
+and <project>/.claude/agents/.
 `;
 
 const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
@@ -218,6 +225,9 @@ async function installLinkMode(repoPath, paths, opts) {
   const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun });
 
+  const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
+  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
+
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -274,6 +284,98 @@ async function writeSkillsManifest(home, names, opts) {
   );
 }
 
+async function writeAgentsManifest(home, names, opts) {
+  const { dryRun = false } = opts ?? {};
+  const data = {
+    version: 1,
+    installedAt: new Date().toISOString(),
+    agents: Array.from(new Set(names)).sort(),
+  };
+  if (dryRun) {
+    process.stdout.write(`[dry-run] write agents manifest: ${data.agents.length} entries\n`);
+    return;
+  }
+  await writeFileAtomic(
+    join(home, AGENTS_MANIFEST_REL),
+    JSON.stringify(data, null, 2) + "\n",
+    0o644,
+  );
+}
+
+async function listWorkerFiles(workersRoot) {
+  try {
+    const entries = await fs.readdir(workersRoot, { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".md"))
+      .map((e) => e.name);
+  } catch (err) {
+    if (err.code === "ENOENT") return [];
+    throw err;
+  }
+}
+
+async function installAgentsCopy(runtimeRoot, opts) {
+  const { refresh, dryRun, quiet } = opts;
+  const srcRoot = join(runtimeRoot, "agents", "workers");
+  const names = await listWorkerFiles(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  agents: runtime/agents/workers empty — skipped\n");
+    return { installed: [] };
+  }
+  if (!dryRun) await fs.mkdir(CLAUDE_AGENTS_DIR, { recursive: true });
+  let copied = 0;
+  let skipped = 0;
+  for (const name of names) {
+    const src = join(srcRoot, name);
+    const dst = join(CLAUDE_AGENTS_DIR, name);
+    let needsCopy = refresh;
+    if (!needsCopy) {
+      try {
+        await fs.access(dst);
+        const [a, b] = await Promise.all([hashFile(src), hashFile(dst)]);
+        needsCopy = a !== b;
+      } catch {
+        needsCopy = true;
+      }
+    }
+    if (!needsCopy) {
+      skipped++;
+      continue;
+    }
+    if (dryRun) {
+      process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
+    } else {
+      const buf = await fs.readFile(src);
+      await writeFileAtomic(dst, buf, 0o644);
+    }
+    copied++;
+  }
+  if (!quiet) {
+    process.stdout.write(
+      `  agents: copied=${copied} skipped=${skipped} -> ${CLAUDE_AGENTS_DIR}/ (${names.length} workers)\n`,
+    );
+  }
+  return { installed: names };
+}
+
+async function installAgentsLink(repoAbs, opts) {
+  const { dryRun, quiet } = opts;
+  const srcRoot = join(repoAbs, "agents", "workers");
+  const names = await listWorkerFiles(srcRoot);
+  if (names.length === 0) {
+    if (!quiet) process.stdout.write("  agents: <repo>/agents/workers missing — skipped\n");
+    return { installed: [] };
+  }
+  if (!dryRun) await fs.mkdir(CLAUDE_AGENTS_DIR, { recursive: true });
+  for (const name of names) {
+    const src = join(srcRoot, name);
+    const dst = join(CLAUDE_AGENTS_DIR, name);
+    const action = await ensureSymlink(src, dst, { dryRun });
+    if (!quiet) process.stdout.write(`  agents/${name}: ${action}\n`);
+  }
+  return { installed: names };
+}
+
 async function installSkillsCopy(runtimeRoot, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
@@ -402,6 +504,9 @@ export async function runInstall(args) {
   const skillResult = await installSkillsCopy(runtimeRoot, opts);
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });
 
+  const agentResult = await installAgentsCopy(runtimeRoot, opts);
+  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
+
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
   }
@@ -419,6 +524,29 @@ export async function runInstall(args) {
   return 0;
 }
 
+async function agentDriftReasons(paths) {
+  const reasons = [];
+  const workersDir = join(paths.agents, "workers");
+  const expected = await listWorkerFiles(workersDir);
+  if (expected.length === 0) return reasons;
+  for (const name of expected) {
+    const target = join(CLAUDE_AGENTS_DIR, name);
+    try {
+      const lst = await fs.lstat(target);
+      if (lst.isSymbolicLink()) {
+        try {
+          await fs.stat(target);
+        } catch {
+          reasons.push(`dangling symlink ${target}`);
+        }
+      }
+    } catch {
+      reasons.push(`missing agent ${target}`);
+    }
+  }
+  return reasons;
+}
+
 function summarise(label, result, target) {
   if (result.missingSource) {
     process.stdout.write(`  ${label}: source directory missing — skipped\n`);
@@ -447,6 +575,9 @@ export async function runEnsureInstalled(args) {
   if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
     reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
   }
+  for (const reason of await agentDriftReasons(paths)) {
+    reasons.push(reason);
+  }
 
   if (reasons.length === 0) {
     if (!quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);

package/src/uninstall.mjs

@@ -26,21 +26,34 @@ const FALLBACK_SKILL_NAMES = [
   "okstra-time-summary",
 ];
 
+const FALLBACK_AGENT_NAMES = [
+  "claude-worker.md",
+  "codex-worker.md",
+  "gemini-worker.md",
+  "report-writer-worker.md",
+];
+
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
+const CLAUDE_AGENTS_DIR = join(homedir(), ".claude", "agents");
 const SKILLS_MANIFEST_REL = "installed-skills.json";
+const AGENTS_MANIFEST_REL = "installed-agents.json";
 
-const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra and ~/.claude/skills
+const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra, ~/.claude/skills, ~/.claude/agents
 
 Usage:
   okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
-                                dev-link, installed-skills.json} AND
-                                ~/.claude/skills/<name> for every entry in
-                                the install manifest (fallback: hard-coded
-                                okstra-* names). Preserves user data:
-                                recent.jsonl, active.jsonl, projects/,
-                                archive/, state.json, .locks/
+                                dev-link, installed-skills.json,
+                                installed-agents.json} AND
+                                ~/.claude/skills/<name> AND
+                                ~/.claude/agents/<worker>.md for every
+                                entry in the install manifests (fallback:
+                                hard-coded okstra-* / *-worker.md names).
+                                Preserves user data: recent.jsonl,
+                                active.jsonl, projects/, archive/,
+                                state.json, .locks/
   okstra uninstall --purge      Remove the entire ~/.okstra directory AND
-                                ~/.claude/skills/<okstra-*> (DESTRUCTIVE).
+                                ~/.claude/skills/<okstra-*> AND
+                                ~/.claude/agents/<*-worker.md> (DESTRUCTIVE).
                                 Requires -y or an interactive confirmation
   okstra uninstall --dry-run    Print the plan without touching disk
   okstra uninstall -y           Skip confirmation prompt for --purge
@@ -112,10 +125,13 @@ export async function runUninstall(args) {
     }
     if (!opts.quiet) process.stdout.write(`purging ${paths.home}\n`);
     await removePath(paths.home, opts);
-    // Skills live outside ~/.okstra — purge those too with the fallback list.
+    // Skills and worker agents live outside ~/.okstra — purge those too.
     for (const name of FALLBACK_SKILL_NAMES) {
       await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
     }
+    for (const name of FALLBACK_AGENT_NAMES) {
+      await removePath(join(CLAUDE_AGENTS_DIR, name), opts);
+    }
     return 0;
   }
 
@@ -154,6 +170,16 @@ export async function runUninstall(args) {
   }
   await removePath(join(paths.home, SKILLS_MANIFEST_REL), opts);
 
+  // Remove worker agents we own. Same authoritative-manifest pattern as skills.
+  const agentNames = await readAgentsManifest(paths.home);
+  if (!opts.quiet) {
+    process.stdout.write(`  agents: removing ${agentNames.length} entries from ${CLAUDE_AGENTS_DIR}\n`);
+  }
+  for (const name of agentNames) {
+    await removePath(join(CLAUDE_AGENTS_DIR, name), opts);
+  }
+  await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
+
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);
 
@@ -173,3 +199,14 @@ async function readSkillsManifest(home) {
   }
   return FALLBACK_SKILL_NAMES;
 }
+
+async function readAgentsManifest(home) {
+  try {
+    const raw = await fs.readFile(join(home, AGENTS_MANIFEST_REL), "utf8");
+    const data = JSON.parse(raw);
+    if (Array.isArray(data?.agents)) return data.agents;
+  } catch {
+    /* fall through */
+  }
+  return FALLBACK_AGENT_NAMES;
+}