okstra 0.34.1 → 0.36.1

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

@@ -0,0 +1,135 @@
+{
+  "_meta": {
+    "lang": "ko",
+    "note": "okstra final-report 고정 문자열 (한국어). 키는 en.json 과 정확히 일치해야 한다. 키를 추가하면 en.json 도 같은 커밋에서 추가한다."
+  },
+  "emptyState": {
+    "consensusItems": "- 합의 항목 없음.",
+    "differences": "- 유의미한 차이 없음. 1.1 Consensus 가 그대로 유효합니다.",
+    "primaryEvidence": "- 주 증거 없음.",
+    "secondaryEvidence": "- 보조 증거 또는 대안 해석 없음.",
+    "risks": "- 누락된 정보·위험 없음.",
+    "dependencyRisk": "- 의존성·마이그레이션 위험 없음.",
+    "dissent": "- 반대 의견 없음.",
+    "outOfPlanEdits": "- 계획 외 편집 없음.",
+    "declinedFixRecommendations": "- 없음.",
+    "discrepancy": "- 없음.",
+    "lingeringRisks": "- 추적 대상 잔존 위험 없음.",
+    "noClarification": "- 추가 정보 요청 없음. Section 2 의 최종 판단이 그대로 유효합니다.",
+    "noFollowUp": "- 후속 작업 없음. 본 run 의 다음 phase 는 §6 (Recommended Next Steps) 참고."
+  },
+  "columns": {
+    "summary": "한 줄 요약",
+    "source": "출처 (brief/source/worker)",
+    "rawTokens": "처리 토큰",
+    "billableTokens": "환산 토큰",
+    "billableTokensInputEquiv": "환산 토큰 (input 기준)",
+    "cost": "비용 (USD)",
+    "checkMethod": "확인 방법"
+  },
+  "sectionAside": {
+    "dependencyRisk": "의존성·마이그레이션 위험",
+    "validationChecklist": "검증 체크리스트",
+    "rollbackStrategy": "롤백 전략",
+    "planBodyVerification": "계획 본문 검증",
+    "recommendedOption": "권장 옵션",
+    "optionCandidates": "옵션 후보",
+    "tradeOffMatrix": "트레이드오프 매트릭스",
+    "stepwiseExecutionOrder": "단계별 실행 순서"
+  },
+  "sectionIntro": {
+    "verdictCard": "한눈에 보는 결과 카드. 본 표의 모든 값은 `## 2. Final Verdict` 및 `## 6. Recommended Next Steps` 의 권위 있는 값과 정확히 일치해야 합니다.",
+    "clarificationCarryIn": "이전 보고서의 `## 5. Clarification Items` 표 매 행(`C-001`, `C-002`, …) 을 새 증거에 비추어 검토하고, 각 행의 `Status` 를 `resolved` 또는 `obsolete` 로 갱신한 뒤 본 run 의 `## 5.` 표에 carry-in 합니다. 해소 근거(파일:라인 / 로그 / 워커 결과) 를 함께 인용합니다.",
+    "ticketCoverage": "3~5 개 row 로 핵심 문제·요구사항·검증 대상을 표로 정리합니다. brief, 소스 자료, worker 결과를 근거로 작성합니다.",
+    "executionStatus": "각 worker 의 status, 배정 모델, key finding 을 한 표에 모읍니다. worker 산출물을 근거 없는 주장으로 대체하지 않습니다.",
+    "sourceItemsRule": "`Source items` 규칙: 본 합의 row 가 어느 워커의 어느 항목들에서 합성됐는지를 `<worker>:<item-id>` 페어 콤마-리스트로 적습니다. 자세한 정책은 `prompts/profiles/_common-contract.md` \"Cross-worker traceability\" SSOT.",
+    "stepRule": "규칙: 한 step 은 약 2~5 분. 모든 step 은 정확한 파일 경로와 명령어 포함.",
+    "planBodyVerification": "Phase 6 에서 report-writer 가 합성한 4.5 본문을 lead 가 plan-item 단위로 워커들에게 다시 던지고 평결을 수집한 결과.",
+    "clarificationItems": "다음 run 으로 넘어가기 전에 사용자가 답하거나 자료를 첨부해야 하는 항목을 **한 표 안에서** 추적합니다."
+  },
+  "tokenSummary": {
+    "heading": "토큰 사용량 요약",
+    "tableHeaderItem": "항목",
+    "rowLead": "Lead",
+    "rowWorkerTotal": "Worker 합계",
+    "rowGrandTotal": "**전체 합계**",
+    "rowCliExtra": "Codex/Gemini CLI 추가 비용"
+  },
+  "verdictCard": {
+    "tableHeaderLabel": "항목",
+    "tableHeaderValue": "값",
+    "approvalRequiredSuffix": "frontmatter `approved` 가 `true` 여야 `implementation` 진입 가능",
+    "rationaleLabel": "근거 요약",
+    "nextStepLabel": "다음 단계"
+  },
+  "ticketCoverage": {
+    "intro": "본 run 이 다룬 ticket 의 역방향 인덱스. 본문 항목들은 모두 `Ticket ID` 컬럼 또는 `[TICKETID: <id>]` 태그로 ticket 과 묶여 있습니다.",
+    "columnSections": "등장 섹션",
+    "columnRelatedIds": "관련 항목 IDs",
+    "ruleNote": "규칙: `Ticket ID` 는 본문에서 등장한 ticket 키와 정확히 동일 문자열. `Issue / Ticket` 이 비어 폴백된 경우 `Task ID` 값을 prefix 없이 그대로 (예: `8852`). 식별 불가는 `unknown`."
+  },
+  "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`."
+  },
+  "evidence": {
+    "sourceItemsColumnNote": "`Source items` 컬럼 규칙은 §1.1 과 동일."
+  },
+  "roundHistory": {
+    "round2SkippedReasonNote": "값은 `queue-empty | max-rounds-1 | all-reverify-non-result | not-skipped | convergence-disabled | single-analyser-only` 중 하나."
+  },
+  "implementationPlanning": {
+    "optionInterfacesLabel": "영향 인터페이스 / 공개 계약 / 다운스트림 소비자",
+    "optionBlastRadiusLabel": "폭발 반경 추정",
+    "recommendedTableHeaderLabel": "항목",
+    "recommendedTableHeaderValue": "값",
+    "coreReasonLabel": "핵심 이유",
+    "rationaleLabel": "근거 (Trade-off 행 / 원칙)",
+    "rejectedSummaryLabel": "채택되지 않은 옵션 요약",
+    "columnImpact": "영향",
+    "columnMitigation": "완화 / 선행 작업"
+  },
+  "releaseHandoff": {
+    "auditNote": "git/gh mutating 명령이 실행된 phase 의 감사 기록.",
+    "branchStateAside": "run 시작 시점",
+    "gitStatusShortLabel": "`git status --short` 출력",
+    "existingPrLabel": "기존 PR 존재 여부",
+    "userSelectionsAside": "메뉴 응답 기록",
+    "questionsTableHeader": {
+      "questionId": "질문 ID",
+      "questionBody": "질문 본문",
+      "userResponse": "사용자 응답 (원문)",
+      "allowedOptions": "응답이 가능한 보기"
+    },
+    "h1Body": "어떤 작업을 실행할까요?",
+    "h2Body": "PR base 브랜치 (H1=`push + PR` 인 경우)",
+    "h3Body": "PR title/body 초안 처리",
+    "h2DefaultLabel": "(n/a)",
+    "h2OptionsLabel": "staging / preprod / prod / main / dev / 사용자 입력",
+    "noMutationNote": "(mutating 명령 미실행 — H1=`skip` 또는 H3=`cancel`)",
+    "commandsTableHeader": {
+      "outputSummary": "stdout/stderr 요약"
+    }
+  },
+  "executionMeta": {
+    "runExecutorWorktreePath": "본 run 의 `EXECUTOR_WORKTREE_PATH`",
+    "runBaseRef": "본 run 의 base ref"
+  },
+  "evidenceMeta": {
+    "commitListSummary": "인용된 commit list / diff summary 요약",
+    "targetWorktreePath": "검증 대상 worktree path",
+    "capturedHeadBaseSha": "run 시작 시 capture 한 head/base SHA",
+    "gitStatusAtRunStart": "`git status --short` (run 시작 시점)"
+  },
+  "clarification": {
+    "fillAndRerun": "답을 채우신 뒤 같은 phase 를 다시 실행:",
+    "separateTerminalLabel": "별도 터미널",
+    "columnGuide": "컬럼 가이드 (전체 정의는 `prompts/profiles/_common-contract.md §Clarification request policy` SSOT 참조):"
+  },
+  "followUpTasks": {
+    "headingAside": "후속 작업"
+  },
+  "finalVerification": {
+    "validationEvidenceAside": "요구사항 커버리지",
+    "columnRequirement": "Requirement (plan/brief 인용)"
+  }
+}

package/runtime/templates/reports/implementation-planning-input.template.md

@@ -105,3 +105,21 @@ The final report of an `implementation-planning` run MUST contain every section
 
 - This input can be used as a planning draft before creating `okstra-task-brief.md`.
 - Reuse the same `Task Group` and `Task ID` if this plan belongs to the same long-lived task.
+
+## Stage Output Shape (reference)
+
+This run's final report MUST emit `## 4.5 Stage Map` and `## 4.5.<i> Stage <i>` sections per the implementation-planning profile §"Required deliverable shape". Two illustrative shapes:
+
+### Shape A — single stage (small work)
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|-------|-------|-------|
+| 1 | tiny rename | (none) | 2 | src/foo.ts:renamedFoo |
+
+### Shape B — three stages, two parallel
+| stage | title | depends-on | step-count | exit-contract-summary |
+|-------|-------|-------|-------|-------|
+| 1 | foo API skeleton | (none) | 4 | src/foo/api.ts:exportedFoo |
+| 2 | baz settings split | (none) | 2 | src/baz/settings.ts, env BAZ_MODE |
+| 3 | bar integration | 1, 2 | 3 | src/bar/use-foo.ts, GET /bar |
+
+Stages 1 and 2 in Shape B are `depends-on (none)` → can be run by two parallel `implementation` runs.

package/runtime/templates/reports/improvement-discovery-input.template.md

@@ -0,0 +1,78 @@
+---
+title: OKSTRA Improvement Discovery Input - {{TASK_KEY}}
+id: {{FM_ID}}
+tags: {{FM_TAGS}}
+status: ready-for-agent
+aliases: {{FM_ALIASES}}
+date: {{TASK_DATE}}
+task-id: "{{TASK_ID}}"
+task-group: "{{TASK_GROUP}}"
+project-id: "{{PROJECT_ID}}"
+taskType: "{{FM_TASK_TYPE}}"
+---
+
+# OKSTRA Improvement Discovery Input
+
+## Identity
+
+- Project ID:
+- Task Group:
+- Task ID:
+- Related Tasks:
+- Issue / Ticket:
+  - 값이 비면 워커는 `Task ID` 로 폴백한다.
+- Task Type: `improvement-discovery`
+- Requested Outcome:
+
+## Scope (from brief frontmatter)
+
+- scan-scope:
+- out-of-scope:
+- priority-lenses:
+- candidate-cap (1..12, default 8):
+
+## Context
+
+- Why this scope is being scanned now:
+- Recent change context (last N commits to scan-scope):
+- Stakeholders or owners of the scope:
+
+## Desired Outcome
+
+- What kinds of improvements do you want surfaced?
+- Anti-goals (improvements you do NOT want this run to propose):
+
+## Constraints
+
+- Untouchable areas:
+- Compatibility / deadline constraints:
+- Performance / regression budget (if applicable):
+
+## Phase 1.5 — Lead Reflect-Back Grilling
+
+This section is filled in by the lead during Phase 1.5 before worker dispatch.
+Workers MUST read the resolved values from `runs/improvement-discovery/<seq>/state/phase-1.5-grilling.md`
+rather than the unresolved brief.
+
+- Reflect-back summary:
+- Open questions (Q1..QN):
+- Resolved scope:
+- Resolved lenses:
+
+## Improvement Candidates (workers populate this)
+
+| Cand ID | Lens | Title | Scope | Severity | Effort | Consensus | Source workers | Recommended next-phase | Evidence |
+|---------|------|-------|-------|----------|--------|-----------|----------------|------------------------|----------|
+
+## Questions for Analysers
+
+1. Within the resolved scope and priority lenses, what are the highest-impact improvement candidates?
+2. Which candidates have full cross-worker consensus, and which are worker-unique?
+3. For each candidate, what is the safest next phase (requirements-discovery / implementation-planning / error-analysis)?
+4. Which candidates would you intentionally exclude despite being technically valid, and why?
+5. Are there any signals that the scope itself is mis-defined (and should be re-narrowed before discovery proceeds)?
+
+## Conversion Note
+
+- Each candidate the user picks becomes a new okstra task. Suggested task-key: `<task-group>/imp-<Cand-ID>`.
+- The candidate row's Recommended next-phase determines which `--task-type` to launch with.

package/runtime/templates/reports/schedule.template.md

@@ -55,14 +55,23 @@ taskType: "{{FM_TASK_TYPE}}"
 ## Task Dependency Graph
 
 <!-- Use ONE of:
-     (A) literal `_의존 정보 없음_` when no edges exist;
-     (B) plain ``` fenced adjacency-list block — see SKILL §"Section: Task Dependency Graph".
+     (A) literal `_의존 정보 없음_` when no edges exist (single-task scope or no extracted edges).
+     (B) plain ``` fenced adjacency-list block. Each non-empty line is one of:
+         - adjacency: `<TASK-ID> -> <TASK-ID>[, <TASK-ID>]*`
+         - comment: `# <free prose>` (max one per group)
+         - blank: group separator
      Example (B):
      ```
      DEV-1 -> DEV-2, DEV-3
      DEV-2 -> DEV-4
+     # Phase 3 fan-out
+     DEV-5 -> DEV-6
      ```
-     Mermaid / PlantUML / Graphviz / Unicode '→' are all forbidden. -->
+     Rules:
+     - ASCII arrow `->` only; Unicode `→` is rejected so downstream tooling does not handle both.
+     - Both endpoints MUST be `TASK-ID` literals (same identifiers as the At a Glance table). Free text is forbidden.
+     - Fence MUST be plain ``` with NO language tag. ```mermaid / ```plantuml / ```graphviz / ```dot are all rejected.
+     - If only one task is in scope (no dependencies), use Shape A — do NOT emit an empty fence. -->
 _의존 정보 없음_
 
 ---

package/runtime/templates/reports/task-brief.template.md

@@ -65,7 +65,7 @@ taskType: "{{FM_TASK_TYPE}}"
   - What trade-offs, dependencies, or migrations matter?
   - What validation and rollback approach is expected?
 - If `Task Type` is `implementation`:
-  - Which approved `implementation-planning` final report authorises this run, and where is the explicit user-approval marker quoted?
+  - Which approved `implementation-planning` final report authorises this run, and is its frontmatter `approved: true` cited verbatim?
   - What is the authoritative file list and step order copied from that plan?
   - Which validation, TDD, and rollback commands must be executed and recorded with actual output?
 - If `Task Type` is `final-verification`:
@@ -141,7 +141,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`agents/SKILL.md`). The lead and every worker stay inside that boundary.
 - "다음 단계 진행해" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
 - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
-- For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or has no explicit user-approval marker. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.
+- For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.
 
 ## Available MCP Servers
 

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

@@ -0,0 +1,108 @@
+# Worker Prompt Preamble (canonical)
+
+This file is the single source of truth for the boilerplate that every okstra analysis worker, verifier, and report-writer worker must honour. The lead injects ONE anchor line into each dispatched worker prompt — `**Worker Preamble Path:** <abs-path>` — pointing here. Workers Read this file end-to-end before producing any output.
+
+It replaces the previous practice of inlining ~80 lines of identical boilerplate into every worker prompt body.
+
+---
+
+## Required reading (analysis workers + report-writer worker)
+
+You are required to read every input file enumerated by the dispatcher (the lead's prompt lists them under `[Required reading]`) from the very first character to the very last character before you produce any analysis output. Skimming, partial reads, jumping to a single section, or relying on prior knowledge of a similar file's structure is not acceptable. Each file may contain decisive context that is not surfaced in its summary or first page.
+
+### Audience-scoped enumeration (BLOCKING — performance optimization)
+
+Different recipients need different files. Do NOT include `final-report-template.md` in analysis worker prompts: analysis workers produce findings (not the final report), and forcing them to read the template inflates token usage without changing finding quality.
+
+| Recipient | Files included in `[Required reading]` |
+|---|---|
+| Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
+| Report writer worker (Phase 6) | all of the above **plus** `final-report-template.md` |
+| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [okstra-convergence](../skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
+
+### Reading rules
+
+- Use a single `Read` tool call per file with no `offset` and no `limit`. If a file is genuinely too large for one read, page through with explicit `offset` / `limit` covering the entire file, and state the page boundaries in your Findings.
+- For the carry-in clarification response, walk every row of `## 5. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface. The structural similarity between the prior final report and the upcoming output is NOT a license to skim.
+- Write the Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). One short line per input file confirming end-to-end reading. Do NOT include a `## 0. Reading Confirmation` heading in the main worker-results file — the validator fails worker-results that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
+- Do not collapse multiple input files into a single mental summary before reading them all individually. Each file has its own canonical role: brief = the user's request, profile = the lead's rules for this phase, reference-expectations = ground-truth config/deployment values, clarification-response = prior run's open questions and the user's answers, final-report-template = the structure your eventual writeup must conform to. Conflating them loses signal.
+
+---
+
+## Error reporting (all workers)
+
+If any tool call you make (Bash, Read, Edit, MCP, etc.) returns a non-zero exit code, raises an exception, or otherwise fails its intended effect, append a single entry to your worker errors sidecar at the absolute path the lead provided as `**Errors sidecar path:** <abs-path>`.
+
+If the sidecar file does not exist, create it with `{"schemaVersion": 1, "errors": []}` then append.
+
+### Entry schema
+
+```json
+{
+  "ts": "<ISO 8601 UTC>",
+  "phase": "<current okstra phase>",
+  "errorType": "tool-failure",
+  "command": "<failed command/tool signature>",
+  "commandKind": "bash | tool:Read | tool:Edit | mcp | ...",
+  "exitCode": <int or null>,
+  "durationMs": <int or null>,
+  "message": "<one-line human summary>",
+  "stderrExcerpt": "<first ~2KB of stderr, or null>",
+  "context": { ... or null }
+}
+```
+
+### Rules
+
+- Do NOT include `source` / `recordedAt` / `agent` / `agentRole` / `model` / `taskKey` — the lead fills those in when dumping the sidecar to the run-level errors log via `okstra-error-log.py append-from-worker`.
+- Do NOT use `errorType` values other than `"tool-failure"` in the sidecar. `cli-failure` events are recorded by CLI wrapper agents (codex / gemini) directly to the run-level errors log, not via the sidecar. `contract-violation` events are recorded by the lead after inspecting worker outputs.
+- Continue your task after recording; do not abort unless the failure makes the task impossible.
+
+### Path extraction (BLOCKING)
+
+Before recording anything, extract the absolute paths verbatim from the lead's dispatch prompt body:
+
+- `**Errors log path:** <abs-path>` — the run-level errors JSONL. Used by CLI wrapper agents via `okstra-error-log.py append-observed` for `cli-failure` events.
+- `**Errors sidecar path:** <abs-path>` — this worker's per-run sidecar JSON. Used by all workers for `tool-failure` events.
+
+If a required header line is absent from the dispatch prompt, return `<SENTINEL_PREFIX>_ERRORS_PATH_MISSING: lead prompt did not include **Errors log path:** / **Errors sidecar path:** headers` (substitute the worker's sentinel prefix — `CLAUDE_WORKER`, `CODEX`, `GEMINI`, or `REPORT_WRITER`) without proceeding. Do NOT synthesize the path from `<runDir>/logs/...` — that template syntax is documentation only; historical failure mode produced silently empty run-level error logs.
+
+---
+
+## Anchor headers (lead-injected, BLOCKING)
+
+Every worker prompt MUST begin with these anchor headers, in this exact order, before any other content. Workers extract them verbatim.
+
+1. `**Project Root:** <absolute-path>` — required so the worker can self-anchor without relying on inherited cwd.
+2. `**Prompt History Path:** <project-relative-path>`
+3. `**Result Path:** <project-relative-path>` — canonical destination for the worker's result file.
+4. `Assigned worker prompt history path: <absolute-path>` — same as the prompt-history path but resolved against `Project Root`. Codex / Gemini wrapper subagents extract this exact line.
+5. `**Worker Preamble Path:** <absolute-path>` — points to THIS file. Workers Read it end-to-end before doing anything else.
+6. `**Errors log path:** <absolute-path>` — run-level JSONL (see Error reporting above).
+7. `**Errors sidecar path:** <absolute-path>` — per-worker JSON (see Error reporting above).
+
+For the **implementation phase** specifically, the dispatched prompt MUST also include:
+
+- `**Worktree:** <absolute-path>` — the task worktree path.
+- `cwd for every mutating command: <absolute-path>` — same as Worktree path; used by codex / gemini wrappers as `--add-dir` / `--include-directories`.
+
+When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.
+
+---
+
+## Worker output sections (analysis workers)
+
+Every analysis worker (Claude / Codex / Gemini) produces sections 1–5 with the same dimensions. The lead does NOT bias worker prompts with per-worker emphasis — sections 1–5 are the common core, and specialization lives only in optional Section 6.
+
+1. **Findings** — what you identified
+2. **Missing Information or Assumptions** — gaps in the analysis
+3. **Safe or Reasonable Areas** — parts that look correct
+4. **Uncertain Points** — areas needing further review
+5. **Recommended Next Actions** — suggested follow-ups
+6. **Specialization Lens (optional)** — additive content from your specialization lens. Items here are NOT subject to convergence cross-verification.
+
+Every item in sections 1–5 (and any section 6) MUST carry a worker-internal item ID unique within the file. Lead synthesis preserves these as `<worker>:<item-id>` in `Source items (worker:item)` columns.
+
+For task types `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items.
+
+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.

package/runtime/validators/lib/fixtures.sh

@@ -374,6 +374,36 @@ report_path.write_text("\n".join(report_lines) + "\n")
 import os
 WORKSPACE_ROOT = os.environ.get("OKSTRA_WORKSPACE_ROOT_FOR_FIXTURE", "")
 if WORKSPACE_ROOT:
+    # Write final-report .data.json SSOT next to the markdown. The validator's
+    # validate_final_report_data() reads this via _data_path_for(report_path)
+    # and the renderer treats it as the canonical source — the markdown alone
+    # is no longer a valid run artifact (dual-format final-report rollout).
+    # Sample bundled in tests/fixtures is patched with this run's task identity.
+    task_type = str(task_manifest.get("taskType", ""))
+    sample_path = (
+        Path(WORKSPACE_ROOT)
+        / "tests" / "fixtures" / "final-report-data"
+        / f"{task_type}-001.data.json"
+    )
+    if sample_path.is_file():
+        sample = json.loads(sample_path.read_text(encoding="utf-8"))
+        sample["frontmatter"]["taskGroup"] = str(task_manifest.get("taskGroup", ""))
+        sample["frontmatter"]["taskId"] = str(task_manifest.get("taskId", ""))
+        sample["frontmatter"]["taskType"] = task_type
+        sample["frontmatter"]["projectId"] = str(task_manifest.get("projectId", ""))
+        sample["header"]["taskKey"] = str(task_manifest.get("taskKey", ""))
+        sample["header"]["taskType"] = task_type
+        name = report_path.name
+        data_path = (
+            report_path.with_name(name[:-3] + ".data.json")
+            if name.endswith(".md")
+            else report_path.with_suffix(".data.json")
+        )
+        data_path.write_text(
+            json.dumps(sample, indent=2, ensure_ascii=False) + "\n",
+            encoding="utf-8",
+        )
+
     import sys as _sys
     _sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
     try:

package/runtime/validators/lib/runners.sh

@@ -41,7 +41,7 @@ run_validator_expectation() {
 
   expected_task_manifest_relative_path="$(task_manifest_relative_path "$task_group" "$task_id")"
 
-  python3 - "$PROJECT_ROOT" "$expected_task_manifest_relative_path" "$RUN_VALIDATOR_SCRIPT" "$expected_status" "$expected_failure_substring" <<'PY'
+  python3 - "$PROJECT_ROOT" "$expected_task_manifest_relative_path" "$RUN_VALIDATOR_PATH" "$expected_status" "$expected_failure_substring" <<'PY'
 from pathlib import Path
 import json
 import subprocess

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

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""S1–S8 checks for the Stage Map structure of an approved
+implementation-planning final-report.md. Run from prepare_task_bundle
+of `implementation` task or standalone."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Tuple
+
+STAGE_MAP_HEADING = re.compile(r"^##\s+4\.5\s+Stage\s+Map\b", re.M)
+STAGE_SECTION = re.compile(
+    r"^##\s+4\.5\.(\d+)\s+Stage\s+\1\s*:\s*(.+)$", re.M
+)
+REQUIRED_SUBSECTIONS = (
+    "Carry-In",
+    "Stepwise Execution Order",
+    "Stage Exit Contract",
+    "Stage Validation",
+)
+
+
+@dataclass
+class StageMeta:
+    stage_number: int
+    title: str
+    depends_on: List[int]
+    step_count: int
+    exit_contract_summary: str
+
+
+@dataclass
+class ValidationError:
+    code: str   # S1..S8
+    stage: int  # 0 = global
+    message: str
+
+
+def _check_stage_map_present(text: str) -> List[ValidationError]:
+    if not STAGE_MAP_HEADING.search(text):
+        return [ValidationError("S1", 0,
+            "section '## 4.5 Stage Map' is missing")]
+    return []
+
+
+def _parse_stage_map(text: str) -> Tuple[List[StageMeta], List[ValidationError]]:
+    m = STAGE_MAP_HEADING.search(text)
+    if not m:
+        return [], []   # S1 already reported
+    body = text[m.end():]
+    rows = []
+    for line in body.splitlines():
+        if line.startswith("##"):
+            break
+        if not line.strip().startswith("|"):
+            continue
+        cells = [c.strip() for c in line.strip().strip("|").split("|")]
+        if len(cells) != 5:
+            continue
+        # skip header and separator rows (all-dash of any length is covered by set check)
+        if cells[0] == "stage" or set(cells[0]) <= set("-"):
+            continue
+        try:
+            n = int(cells[0])
+        except ValueError:
+            continue
+        depends_raw = cells[2].strip()
+        depends = [] if depends_raw in ("(none)", "") else [
+            int(x.strip()) for x in depends_raw.split(",") if x.strip()
+        ]
+        try:
+            step_count = int(cells[3])
+        except ValueError:
+            step_count = -1
+        rows.append(StageMeta(n, cells[1], depends, step_count, cells[4]))
+    errors: List[ValidationError] = []
+    for i, r in enumerate(rows, start=1):
+        if r.stage_number != i:
+            errors.append(ValidationError("S2", r.stage_number,
+                f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}"))
+    return rows, errors
+
+
+def _count_effective_steps(section: str) -> int:
+    m = re.search(r"^###\s+Stepwise Execution Order\b", section, re.M)
+    if not m:
+        return 0
+    body = section[m.end():]
+    nxt = re.search(r"^###\s+\w", body, re.M)
+    if nxt:
+        body = body[: nxt.start()]
+    count = 0
+    for line in body.splitlines():
+        s = line.strip()
+        if not s or s.startswith("<!--"):
+            continue
+        if not s.startswith("|"):
+            continue
+        # Reuse the same header/divider detection as _parse_stage_map:
+        # split on `|`, inspect first non-empty cell.
+        first_cell = s.strip("|").split("|")[0].strip()
+        if first_cell.lower() == "step":
+            continue
+        if set(first_cell) <= set("-: "):
+            continue
+        count += 1
+    return count
+
+
+def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+    errs: List[ValidationError] = []
+    for s in stages:
+        pattern = rf"^##\s+4\.5\.{s.stage_number}\s+Stage\s+{s.stage_number}\s*:"
+        start_m = re.search(pattern, text, re.M)
+        if not start_m:
+            errs.append(ValidationError("S3", s.stage_number,
+                f"stage section '## 4.5.{s.stage_number} Stage {s.stage_number}:' missing"))
+            continue
+        # Slice the stage's section body
+        start = start_m.end()
+        nxt = re.search(
+            rf"^##\s+4\.5\.{s.stage_number + 1}\s+Stage\s+",
+            text[start:], re.M,
+        )
+        section = text[start: start + nxt.start()] if nxt else text[start:]
+
+        for sub in REQUIRED_SUBSECTIONS:
+            if not re.search(rf"^###\s+{re.escape(sub)}\b", section, re.M):
+                errs.append(ValidationError("S4", s.stage_number,
+                    f"required subsection '### {sub}' missing"))
+
+        # S5: effective step count
+        steps = _count_effective_steps(section)
+        if steps > 6:
+            errs.append(ValidationError("S5", s.stage_number,
+                f"effective step count {steps} exceeds 6"))
+
+        # S7: step-count cell vs. real count
+        if s.step_count >= 0 and s.step_count != steps:
+            errs.append(ValidationError("S7", s.stage_number,
+                f"Stage Map step-count={s.step_count} but real count={steps}"))
+    return errs
+
+
+def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
+    errs: List[ValidationError] = []
+    valid = {s.stage_number for s in stages}
+    for s in stages:
+        for d in s.depends_on:
+            if d == s.stage_number:
+                errs.append(ValidationError("S8", s.stage_number, "self depends-on"))
+            elif d not in valid:
+                errs.append(ValidationError("S6", s.stage_number,
+                    f"depends-on {d} does not exist"))
+
+    # DAG cycle detection via Kahn's algorithm
+    # Build a graph only from valid edges (S6 errors already reported above)
+    indeg = {s.stage_number: 0 for s in stages}
+    graph: dict[int, list[int]] = {s.stage_number: [] for s in stages}
+    for s in stages:
+        for d in s.depends_on:
+            if d in graph and d != s.stage_number:
+                graph[d].append(s.stage_number)
+                indeg[s.stage_number] += 1
+
+    queue = [n for n, k in indeg.items() if k == 0]
+    visited = 0
+    while queue:
+        n = queue.pop()
+        visited += 1
+        for m in graph[n]:
+            indeg[m] -= 1
+            if indeg[m] == 0:
+                queue.append(m)
+    if visited != len(stages):
+        errs.append(ValidationError("S8", 0, "depends-on graph has a cycle"))
+    return errs
+
+
+def main(argv: List[str]) -> int:
+    p = argparse.ArgumentParser()
+    p.add_argument("--plan", required=True)
+    args = p.parse_args(argv)
+    text = Path(args.plan).read_text(encoding="utf-8")
+
+    errors: List[ValidationError] = []
+    errors.extend(_check_stage_map_present(text))
+    if errors:
+        for e in errors:
+            print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)
+        return 1
+
+    stages, s2_errs = _parse_stage_map(text)
+    errors.extend(s2_errs)
+    if stages:
+        errors.extend(_check_each_stage_section(text, stages))
+        errors.extend(_check_depends_on(stages))
+
+    if errors:
+        for e in errors:
+            print(f"{e.code} stage={e.stage}: {e.message}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))