okstra 0.63.0 → 0.64.0

package/runtime/templates/reports/final-report.template.md

@@ -151,7 +151,7 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {%- endif %}
 
 {% if header.taskType == 'implementation-planning' %}
-## 5.5 Implementation Plan Deliverables
+## 5.4 Implementation Plan Deliverables
 
 ### Option Candidates{% if t("sectionAside.optionCandidates") != "Option Candidates" %} ({{ t("sectionAside.optionCandidates") }}){% endif %}
 

package/runtime/validators/validate-run.py

@@ -748,6 +748,20 @@ def _parse_diff_summary_files(content: str) -> list[str]:
     return _DIFF_ROW_PATH_RE.findall(section.group(0))
 
 
+def _task_root_from_run_dir(run_dir: Path) -> Path:
+    """run_dir 에서 `runs` 디렉터리를 앵커로 task_root 를 복원한다.
+
+    일반 task-type: run_dir = task_root/runs/<task-type> → task_root.
+    implementation(stage 격리): run_dir = task_root/runs/implementation/stage-<N>
+    → 같은 task_root. `runs` 를 위로 탐색하므로 stage-<N> 레벨이 추가돼도
+    안전하다. `runs` 가 조상에 없으면 기존 동작(두 단계 위)로 폴백한다.
+    """
+    for parent in run_dir.parents:
+        if parent.name == "runs":
+            return parent.parent
+    return run_dir.parent.parent
+
+
 def _validate_conformance(report_path: Path, failures: list[str],
                           surface_patterns: object = None) -> None:
     """Tier 3 conformance 게이트(implementation / final-verification).
@@ -759,10 +773,13 @@ def _validate_conformance(report_path: Path, failures: list[str],
     """
     # conformance 산출물은 task-level(<task_root>/qa)에 있어 planning/
     # implementation/final-verification 가 공유한다. report_path 는
-    # task_root/runs/<task-type>/reports/final-report.md 이므로 task_root 는
-    # run_dir(=report_path.parent.parent)에서 두 단계 위.
+    # task_root/runs/<task-type>/reports/final-report.md (implementation 은
+    # stage 격리로 runs/implementation/stage-<N>/reports/...) 이므로 고정 parent
+    # 카운트 대신 `runs` 디렉터리를 앵커로 task_root 를 찾는다 — stage-<N> 레벨이
+    # 있어도 task_root/qa 로 정확히 떨어진다.
     run_dir = report_path.parent.parent
-    qa_dir = run_dir.parent.parent / "qa"
+    task_root = _task_root_from_run_dir(run_dir)
+    qa_dir = task_root / "qa"
     manifest_path = qa_dir / "conformance-manifest.json"
     if not manifest_path.is_file():
         return

package/src/install.mjs

@@ -44,6 +44,7 @@ Usage:
 
 Effect (copy mode):
   ${"$HOME"}/.okstra/lib/python   <- runtime/python
+  ${"$HOME"}/.okstra/lib/validators <- runtime/validators  (stage/report structure validators)
   ${"$HOME"}/.okstra/bin           <- runtime/bin
   ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
@@ -577,12 +578,27 @@ export async function runInstall(args) {
     join(paths.home, "schemas"),
     { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
   );
+  // validators/ tree — validate-implementation-plan-stages.py (+ lib/) is
+  // resolved at runtime by run.py / validate-run.py via the installed package's
+  // `parents[2]/validators`, i.e. ~/.okstra/lib/validators. Without this step a
+  // copy-mode UPGRADE bumps the version stamp but never refreshes the
+  // validators, so a stale validator (e.g. a pre-renumber section schema)
+  // survives and render-bundle's stage-structure check diverges from the
+  // current template (observed: render-bundle demanding `## 4.5 Stage Map`
+  // while the report + wizard validator use `## 5.5`). Mode 0o755 preserves the
+  // executable .sh helpers in the tree.
+  const validatorsResult = await copyTreeIfChanged(
+    join(runtimeRoot, "validators"),
+    join(paths.home, "lib", "validators"),
+    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
+  );
 
   if (!opts.quiet) {
     summarise("python", pythonResult, paths.pythonpath);
     summarise("bin", binResult, paths.bin);
     summarise("templates", templatesResult, join(paths.home, "templates"));
     summarise("schemas", schemasResult, join(paths.home, "schemas"));
+    summarise("validators", validatorsResult, join(paths.home, "lib", "validators"));
   }
 
   if (pythonResult.missingSource && binResult.missingSource) {
@@ -600,6 +616,11 @@ export async function runInstall(args) {
       "warning: runtime/schemas is empty. final-report schema validation + excerpt generation will be unavailable — re-run the build step.\n",
     );
   }
+  if (validatorsResult.missingSource) {
+    process.stderr.write(
+      "warning: runtime/validators is empty. stage-structure / report validation will use stale or missing validators — re-run the build step.\n",
+    );
+  }
 
   const skillResult = await installSkillsCopy(runtimeRoot, opts);
   await writeSkillsManifest(paths.home, skillResult.installed, { dryRun: opts.dryRun });

package/src/uninstall.mjs

@@ -53,10 +53,10 @@ const AGENTS_MANIFEST_REL = "installed-agents.json";
 const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra, ~/.claude/skills, ~/.claude/agents
 
 Usage:
-  okstra uninstall              Remove ~/.okstra/{lib, bin/<known>, version,
+  okstra uninstall              Remove ~/.okstra/{lib (python + validators),
+                                bin/<known>, schemas, templates, version,
                                 dev-link, installed-skills.json,
-                                installed-agents.json,
-                                templates/settings.local.json} AND
+                                installed-agents.json} AND
                                 ~/.claude/skills/<name> AND
                                 ~/.claude/agents/<worker>.md for every
                                 entry in the install manifests (fallback:
@@ -156,6 +156,12 @@ export async function runUninstall(args) {
     process.stdout.write(`  home: ${paths.home}\n`);
   }
   await removePath(paths.pythonpath, opts);
+  // lib/validators — installed wholesale by copy mode (runtime/validators).
+  // Without removing it, `lib` stays non-empty so the rmdir below is skipped and
+  // a stale validator survives uninstall → reinstall, diverging from the current
+  // template's section schema (observed: a pre-renumber `## 4.5 Stage Map`
+  // validator outliving every later install).
+  await removePath(join(paths.home, "lib", "validators"), opts);
   for (const name of BIN_ENTRYPOINTS) {
     await removePath(join(paths.bin, name), opts);
   }
@@ -174,6 +180,10 @@ export async function runUninstall(args) {
     }
   }
 
+  // schemas/ tree — installed by copy mode (runtime/schemas). Older uninstall
+  // never removed it, leaving a stale final-report schema behind.
+  await removePath(join(paths.home, "schemas"), opts);
+
   // Remove the skills we own. Manifest is authoritative; fall back to the
   // hard-coded okstra-* names if it is missing (e.g. an install from an old
   // version that did not write the manifest).
@@ -196,24 +206,14 @@ export async function runUninstall(args) {
   }
   await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
 
-  await removePath(join(paths.home, "templates", "settings.local.json"), opts);
+  // templates/ tree — installed wholesale by copy mode (runtime/templates),
+  // including the seeded settings.local.json sidecar. Remove the whole tree so
+  // an upgrade/reinstall never serves a stale report.css / *.template.md.
+  await removePath(join(paths.home, "templates"), opts);
   // 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)) {
-    try {
-      const entries = await fs.readdir(templatesDir);
-      if (entries.length === 0) {
-        if (!opts.dryRun) await fs.rmdir(templatesDir);
-        if (!opts.quiet) process.stdout.write(`  removed empty: ${templatesDir}\n`);
-      }
-    } catch {
-      /* ignore */
-    }
-  }
 
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);