okstra 0.62.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 %}
 
@@ -235,18 +235,15 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {% for stage in implementationPlanning.stages %}
 ## 5.5.{{ stage.stage }} Stage {{ stage.stage }}: {{ stage.title }}
 
-Slice value: {{ stage.sliceValue }}
-
-Acceptance: {{ stage.acceptance }}
-
+- **Slice value:** {{ stage.sliceValue }}
+- **Acceptance:** {{ stage.acceptance }}
 {% if stage.conformanceTests %}
-Conformance tests: stage-{{ stage.stage }} — {{ stage.conformanceTests }}
+- **Conformance tests:** stage-{{ stage.stage }} — {{ stage.conformanceTests }}
 {% else %}
-Conformance exemption: {{ stage.conformanceExemption }}
+- **Conformance exemption:** {{ stage.conformanceExemption }}
 {% endif %}
 {% if stage.tddExemption %}
-
-TDD exemption: {{ stage.tddExemption }}
+- **TDD exemption:** {{ stage.tddExemption }}
 {% endif %}
 
 ### Carry-In

package/runtime/templates/reports/i18n/en.json

@@ -68,7 +68,7 @@
     "columnRelatedIds": "Related item IDs"
   },
   "finalVerdict": {
-    "intro": "Final conclusion and recommended direction. `Direction` values: `continue-investigation / begin-implementation / approve / reject / hold`. When `task-type` is `final-verification`, `Verdict Token` is one of `accepted / conditional-accept / blocked` and serves as the `release-handoff` entry gate. For all other task-types: `not-applicable`."
+    "intro": "This run's final conclusion and next action. **`Direction`** is the recommended next action — one of `continue-investigation`, `begin-implementation`, `approve`, `reject`, or `hold` — and is present for every task-type. **`Verdict Token`** is meaningful only for the `final-verification` task-type, where it is one of `accepted`, `conditional-accept`, or `blocked` and serves as the `release-handoff` entry gate. For every other task-type, `Verdict Token` is always `not-applicable`."
   },
   "evidence": {
     "sourceItemsColumnNote": "The `Source items` column is described in §6.1."

package/runtime/templates/reports/i18n/ko.json

@@ -68,7 +68,7 @@
     "columnRelatedIds": "관련 항목 IDs"
   },
   "finalVerdict": {
-    "intro": "최종 결론과 권장 방향입니다. `Direction` 값: `continue-investigation / begin-implementation / approve / reject / hold`. `task-type` 이 `final-verification` 일 때 `Verdict Token` 은 `accepted / conditional-accept / blocked` 중 하나이며 `release-handoff` 진입 게이트로 쓰입니다. 그 외 task-type 에서는 `not-applicable`."
+    "intro": "이 run 의 최종 결론과 다음 행동입니다. **`Direction`** 은 권장 다음 행동으로 `continue-investigation`(조사 계속) · `begin-implementation`(구현 시작) · `approve`(승인) · `reject`(반려) · `hold`(보류) 중 하나이며, 모든 task-type 에 존재합니다. **`Verdict Token`** 은 `final-verification` task-type 에서만 의미를 가집니다 — `accepted` · `conditional-accept` · `blocked` 중 하나로 `release-handoff` 진입 게이트로 쓰입니다. 그 외 task-type 에서 `Verdict Token` 은 항상 `not-applicable`(해당 없음) 입니다."
   },
   "evidence": {
     "sourceItemsColumnNote": "`Source items` 열 설명은 §6.1 과 동일합니다."

package/runtime/templates/worker-prompt-preamble.md

@@ -114,6 +114,16 @@ For task types `requirements-discovery`, `error-analysis`, `implementation-plann
 
 See `skills/okstra-team-contract/SKILL.md` "Worker Output Contract" for the full frontmatter schema and section ordering rules. This preamble is consistent with that contract; the team-contract document is authoritative if the two ever diverge.
 
+## Return message to the lead (all workers)
+
+The short message you return inline to the lead — the text shown to the user as your agent box — MUST begin with one line identifying the model you ran under, copied verbatim from the `**Model:** <Role>, <modelExecutionValue>` line in your dispatch prompt:
+
+```
+**Model:** <Role>, <modelExecutionValue>
+```
+
+Emit that line first, then your normal status / summary text on the following lines. This keeps the acting model visible in every worker box — across every provider (Claude / Codex / Gemini / report-writer) and every dispatch type (initial analysis, convergence reverify, report authoring). Copy the value exactly; never guess, abbreviate, or substitute a provider default. If your prompt carries no `**Model:**` line, say so in the return message rather than inventing one. Each worker spec applies this rule at its own concrete return point — see `agents/workers/claude-worker.md` "Stop Condition", `agents/workers/_cli-wrapper-template.md` step 8d, and `agents/workers/report-writer-worker.md` "Authoring Contract".
+
 ## Writing style (all prose output — analysis workers + report-writer)
 
 When you write in Korean (`Report Language: ko` / `meta.reportLanguage = "ko"`), write so a Korean developer understands it on first read. Translate the **meaning**, never the dictionary word.

package/runtime/validators/validate-implementation-plan-stages.py

@@ -162,11 +162,16 @@ def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[Valida
     return errs
 
 
-SLICE_VALUE = re.compile(r"^\s*Slice value\s*:\s*(.+?)\s*$", re.M)
-ACCEPTANCE = re.compile(r"^\s*Acceptance\s*:\s*(.+?)\s*$", re.M)
-TDD_EXEMPTION = re.compile(r"^\s*TDD exemption\s*:\s*\S", re.M)
-CONFORMANCE_TESTS = re.compile(r"^\s*Conformance tests\s*:\s*\S", re.M)
-CONFORMANCE_EXEMPTION = re.compile(r"^\s*Conformance exemption\s*:\s*\S", re.M)
+# Each label line may be plain (`Slice value: …`) or rendered as a bold-label
+# bullet (`- **Slice value:** …`). The optional `(?:[-*]\s+)?` bullet marker and
+# the two optional `\*\*` groups accept both forms; the bold wraps the colon, so
+# the closing `**` sits AFTER the colon.
+_LABEL_PREFIX = r"^\s*(?:[-*]\s+)?(?:\*\*)?"
+SLICE_VALUE = re.compile(_LABEL_PREFIX + r"Slice value\s*:\s*(?:\*\*)?\s*(.+?)\s*$", re.M)
+ACCEPTANCE = re.compile(_LABEL_PREFIX + r"Acceptance\s*:\s*(?:\*\*)?\s*(.+?)\s*$", re.M)
+TDD_EXEMPTION = re.compile(_LABEL_PREFIX + r"TDD exemption\s*:\s*(?:\*\*)?\s*\S", re.M)
+CONFORMANCE_TESTS = re.compile(_LABEL_PREFIX + r"Conformance tests\s*:\s*(?:\*\*)?\s*\S", re.M)
+CONFORMANCE_EXEMPTION = re.compile(_LABEL_PREFIX + r"Conformance exemption\s*:\s*(?:\*\*)?\s*\S", re.M)
 
 
 def _check_slice_tdd(text: str, stages: List[StageMeta]) -> List[ValidationError]:

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);