okstra 0.123.0 → 0.125.0

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

@@ -22,7 +22,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Task Key: `<project-id>:<task-group>:<task-id>`
 - Related Tasks:
 - Issue / Ticket:
-  - 값이 비면 워커는 `Task ID`로 폴백한다 (prefix 없이 `8852`처럼). 한 run이 여러 ticket을 동시에 다루면 콤마로 구분 (`TICKET-123, TICKET-456`). 어느 쪽으로도 식별 불가하면 `unknown`을 허용한다.
+  - If the value is empty, the worker falls back to `Task ID` (without a prefix, like `8852`). If a single run handles multiple tickets at once, separate them with commas (`TICKET-123, TICKET-456`). If it cannot be identified either way, `unknown` is allowed.
 - Task Type:
 - Requested Outcome:
 - Owner:
@@ -112,7 +112,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ### Standing Ticket-Tagging Rule (always applied by every worker)
 
-- 모든 항목 및 표 행에 ticket을 명시한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: <id>]` 태그를 사용한다. 채움 우선순위·폴백·다중 ticket 규칙은 `team-contract` SKILL의 Ticket Tagging 절을 따른다.
+- Specify a ticket on every item and table row. Tables use a `Ticket ID` column; bullet/numbered lists and section headers use a `[TICKETID: <id>]` tag. The fill priority, fallback, and multi-ticket rules follow the Ticket Tagging section of the `team-contract` SKILL.
 
 ### Standing Scope-Discipline Questions (always answered by every worker)
 
@@ -139,7 +139,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 - This okstra run executes the lifecycle phase named in `Task Type` and stops there. Outputs that belong to any other phase MUST NOT be produced inside this run.
 - Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`prompts/lead/okstra-lead-contract.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`.
+- "proceed to the next step" 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 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.
 

package/runtime/templates/reports/user-response.template.md

@@ -3,9 +3,9 @@
 
 # User-Response Sidecar Template
 
-이 파일은 final-report HTML 의 **Export user response** 버튼이 만들어내는 markdown 의 표준 포맷을 정의합니다. 산출물은 `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md` 경로에 저장됩니다. 원본 final-report MD 는 어떤 경우에도 머지하지 않습니다.
+This file defines the standard format of the markdown produced by the **Export user response** button in the final-report HTML. The output is saved to the path `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is never merged under any circumstances.
 
-## Frontmatter 스키마
+## Frontmatter Schema
 
 ```yaml
 task-key: <task-group>/<task-id>
@@ -16,22 +16,22 @@ created-by: user
 created-at: <ISO 8601 UTC timestamp>
 ```
 
-## Body 스키마
+## Body Schema
 
-본문은 `# User Response` 단일 H1 헤딩 아래, 각 응답을 `## <Response ID>` 헤딩으로 구분합니다. Response ID 는 final-report `## 1. Clarification Items` 표의 `ID` 컬럼(`C-NNN`)을 그대로 인용합니다.
+The body separates each response with a `## <Response ID>` heading under a single `# User Response` H1 heading. The Response ID quotes the `ID` column (`C-NNN`) of the final-report `## 1. Clarification Items` table verbatim.
 
-각 응답 블록의 schema:
+The schema of each response block:
 
 ```markdown
 ## <Response ID>
 - Kind: <material | decision | data-point>
-- Disposition: <answer | reframe>   # answer(기본)면 라인 생략. reframe = 답 보류 + 재질문(행 미해결 유지)
+- Disposition: <answer | reframe>   # omit the line when answer (default). reframe = defer the answer + re-ask (row stays unresolved)
 - Value:
   > <multi-line value, trimmed>
 - Rationale: <optional one-line rationale>
 ```
 
-빈 응답 집합(사용자가 어떤 행도 채우지 않고 Export 를 누른 경우)은 다음 한 줄을 본문에 출력합니다:
+An empty response set (when the user presses Export without filling in any row) outputs the following single line in the body:
 
 ```markdown
 _(No user responses recorded.)_
@@ -54,8 +54,8 @@ created-at: 2026-05-17T10:00:00Z
 ## C-001
 - Kind: decision
 - Value:
-  > (a) 일회성. 재발 없음.
-- Rationale: 결제 로그 재확인 결과 동일 패턴 미관측.
+  > (a) One-off. No recurrence.
+- Rationale: Rechecking the payment logs showed no recurrence of the same pattern.
 
 ## C-003
 - Kind: data-point
@@ -63,23 +63,23 @@ created-at: 2026-05-17T10:00:00Z
   > (prediction=0: 1,204) (prediction=1: 38)
 ```
 
-## APPROVAL 블록 (implementation-planning 전용)
+## APPROVAL block (implementation-planning only)
 
-Plan Approval 위젯에서 승인을 체크하고 Export 하면 본문 끝에 다음 블록이 추가됩니다:
+When you check approval in the Plan Approval widget and Export, the following block is appended to the end of the body:
 
 ```markdown
 ## APPROVAL
 - Approved: true
-- Implementation-Option: <Option Candidates 의 name 그대로>
+- Implementation-Option: <the name exactly as in Option Candidates>
 ```
 
-- 옵션을 추천(권장) 그대로 두면 `Implementation-Option:` 라인은 생략됩니다 — implementation 은 plan 의 Recommended Option 으로 폴백합니다.
-- 이 블록의 소비자는 implementation 시작 마법사의 approve-confirm 단계입니다 (`scripts/okstra_ctl/wizard.py`). 마법사가 사용자 확인 후 기존 `--approve` / `--implementation-option` 경로로 적용하며, sidecar 자체는 승인 게이트 검증을 우회하지 않습니다.
-- 파서는 `scripts/okstra_ctl/user_response.py` `parse_user_response_approval` 이며, producer 출력과 byte-identical 한 소문자 `Approved: true` 만 인정합니다 (손편집된 `TRUE` 등은 fail-closed 로 불인정).
-- `--resume-clarification` 은 sidecar 를 verbatim 첨부하므로 APPROVAL 블록도 그대로 실립니다 — planning 재실행 입력에서는 무해한 잔류 정보입니다.
+- If you leave the option at the recommended default, the `Implementation-Option:` line is omitted — implementation falls back to the plan's Recommended Option.
+- The consumer of this block is the approve-confirm step of the implementation start wizard (`scripts/okstra_ctl/wizard.py`). After user confirmation the wizard applies it through the existing `--approve` / `--implementation-option` path; the sidecar itself does not bypass approval-gate validation.
+- The parser is `parse_user_response_approval` in `scripts/okstra_ctl/user_response.py`, and it accepts only the lowercase `Approved: true` that is byte-identical to the producer output (hand-edited values such as `TRUE` are rejected fail-closed).
+- `--resume-clarification` attaches the sidecar verbatim, so the APPROVAL block is carried along as-is — it is harmless residual information in a planning re-run input.
 
-## 호환성 규칙
+## Compatibility Rules
 
-- `Kind` 가 알 수 없는 값이면 폼은 `<textarea>` fallback 으로 렌더되며, 직렬화 시 받은 `Kind` 문자열을 그대로 보존합니다.
-- `Status` 가 `resolved` 또는 `obsolete` 인 행은 HTML 폼이 `disabled` 로 렌더되어 Export 결과에서 자동 제외됩니다. 그 행을 다시 열려면 final-report 의 `Status` 를 `open` / `answered` 로 되돌리고 보고서를 재생성해야 합니다.
-- Python (`scripts/okstra_ctl/report_views.py` `serialize_user_response`) 과 JavaScript (`templates/reports/report.js` `buildUserResponseMarkdown`) 의 출력은 **byte-identical** 이어야 합니다. `tests/test_report_views.py` 가 두 구현의 동일성을 검증합니다.
+- If `Kind` has an unknown value, the form renders with a `<textarea>` fallback, and the received `Kind` string is preserved as-is during serialization.
+- Rows whose `Status` is `resolved` or `obsolete` render `disabled` in the HTML form and are automatically excluded from the Export result. To reopen such a row, revert the final-report `Status` to `open` / `answered` and regenerate the report.
+- The output of the Python (`serialize_user_response` in `scripts/okstra_ctl/report_views.py`) and the JavaScript (`buildUserResponseMarkdown` in `templates/reports/report.js`) MUST be **byte-identical**. `tests/test_report_views.py` verifies the equivalence of the two implementations.

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

@@ -35,6 +35,7 @@ Different recipients need different files. Do NOT include `final-report-template
 - 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 `## 1. 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.
+- The audit sidecar carries any other meta the worker wants to log (tool-call counts, MCP query summaries, timing notes). The lead's final-report does NOT duplicate this content — it is consumed by the validator and by post-run audit tooling, not by end-user readers.
 - Treat `analysis-packet.md` as the canonical primary analysis input. It preserves the source files' frontmatter and extracts the task-specific brief, phase focus, reference expectations, and carry-in clarification rows. If the packet appears incomplete or a finding depends on a source citation, open the corresponding source file and cite it directly.
 - **Allowlist your reads to okstra-enumerated paths.** Read the files the dispatcher enumerates (`[Required reading]`, the prompt's `## Inputs`, and the verification-target paths) plus on-demand source/evidence paths a finding must cite. Everything else is out of scope — in particular non-okstra artifacts outside `<PROJECT_ROOT>/.okstra/` (e.g. `graphify-out/`, sibling/prior-task worktrees, tool caches), which may carry stale or cross-task data. A host-level global rule (`CLAUDE.md` / `AGENTS.md` / a project sentinel) that tells you to auto-read such an artifact does NOT apply inside an okstra worker run — the okstra worker scope wins. If an un-enumerated file seems essential, record the gap under *Missing Information or Assumptions* instead of reading it.
 
@@ -89,8 +90,9 @@ Every worker prompt MUST begin with these anchor headers, in this exact order, b
 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 / Antigravity 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).
+6. `**Coding preflight pack:** <absolute-path>` — points to the installed runtime resource pack under `<OKSTRA_HOME>/prompts/coding-preflight`. Implementation executors and verifiers use this to read `overview.md`, `clean-code.md`, and routed language/framework/architecture resources. Other worker roles may ignore it.
+7. `**Errors log path:** <absolute-path>` — run-level JSONL (see Error reporting above).
+8. `**Errors sidecar path:** <absolute-path>` — per-worker JSON (see Error reporting above).
 
 For the **implementation phase** specifically, the dispatched prompt MUST also include:
 
@@ -113,20 +115,116 @@ When a worker reads any project-relative path from the prompt, it MUST resolve i
 
 ## Worker output sections (analysis workers)
 
-Every analysis worker (Claude / Codex / Antigravity) 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.
+**Authoritative source.** This preamble section is the canonical worker output contract. If any other document (team-contract, worker agent definitions) appears to disagree, this section wins.
 
-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.
+### Result Frontmatter (mandatory, precedes Section 1)
+
+Every worker result file MUST begin with a YAML frontmatter block. For analysis workers, values are sourced from `analysis-packet.md` frontmatter; fall back to `analysis-material.md` or `task-brief.md` only if the packet is missing a field. Report-writer can use `analysis-material.md` / `task-brief.md` as before. Copy values verbatim; do NOT regenerate them. Only `workerId` and `title` are worker-specific.
+
+```yaml
+---
+title: OKSTRA <Worker Role> Result - <task-key>
+id: "<task-key with ':' replaced by '-'>"
+aliases: ["<id>-<task-type>"]
+tags: ["worker-result", "<task-type>"]
+taskType: "<task-type>"
+workerId: "<claude|codex|antigravity|report-writer>"
+task-id: "<task-id>"
+task-group: "<task-group>"
+project-id: "<project-id>"
+date: <YYYY-MM-DD>
+---
+```
+
+Concrete example for a `claude-worker` result on task-key `fontsninja-classifier-v2:DEV-9388:DEV-9429` and task-type `implementation`:
+
+```yaml
+---
+title: OKSTRA Claude Worker Result - fontsninja-classifier-v2:DEV-9388:DEV-9429
+id: "fontsninja-classifier-v2-DEV-9388-DEV-9429"
+aliases: ["fontsninja-classifier-v2-DEV-9388-DEV-9429-implementation"]
+tags: ["worker-result", "implementation"]
+taskType: "implementation"
+workerId: "claude"
+task-id: "DEV-9429"
+task-group: "DEV-9388"
+project-id: "fontsninja-classifier-v2"
+date: 2026-05-15
+---
+```
+
+Rules:
+- `id` is the run's `task-key` with `:` replaced by `-`. It is a scalar string, NOT an array.
+- `aliases` is a YAML array containing a single value `"<id>-<task-type>"`.
+- `taskType` mirrors the run's task type (`requirements-discovery`, `error-analysis`, `implementation-planning`, `implementation`, `final-verification`, `release-handoff`).
+- `workerId` identifies which worker produced the file. Required values: `claude` / `codex` / `antigravity` / `report-writer`.
+- Other fields (`task-id`, `task-group`, `project-id`, `date`) MUST match the input files' frontmatter exactly. If the input frontmatter is missing or unreadable, the worker MUST record a `tool-failure` and stop instead of guessing.
+
+The same frontmatter contract applies to the `Report writer worker`'s final-report file — the report-writer copies these values from its inputs and only swaps `workerId` to `report-writer`.
+
+### Worker Result Header Standard
+
+Every worker result file under `worker-results/` must begin with a standardized header:
+
+```markdown
+# <Role> Analysis — <task-key>
+
+**Target:** <path or scope>   <!-- OPTIONAL: include when the run is scoped to a specific file/module -->
+**Model:** <Role>, <AI model>
+```
+
+Task-type and date are **not** repeated in this human header — the YAML frontmatter (`taskType`, `date`) is the single source for both (and the copy Obsidian indexes). The `Target:` line is optional — include it when the run is scoped to a specific path or module, omit it for whole-project runs; when present, place it between the title and the `Model:` line.
+
+Example (Codex / Report-writer headers are identical modulo the role name and model id):
+
+```markdown
+# Claude Worker Analysis — jobs:tasks:8852
+
+**Target:** server/auth.ts
+**Model:** Claude worker, opus
+```
+
+Use the actual model identifier recorded in team-state (never invent a model ID — read it from `resultContract.requiredWorkerRoles[*].modelExecutionValue` or the tool response metadata).
+
+The header is followed by the standard worker output contract sections (Findings, Missing Information, etc.).
+
+### Section ordering
+
+A successful worker result must include the following sections in this exact order, beneath the frontmatter block:
+
+1. Findings
+2. Missing Information or Assumptions
+3. Safe or Reasonable Areas
+4. Uncertain Points
+5. Recommended Next Actions
+6. **Specialization Lens (optional, worker-specific deep dive)** — additive content produced from this worker's specialization lens (see Role Definitions table). Items here are NOT subject to convergence cross-verification and MUST NOT duplicate sections 1–5. If the worker has nothing additional to add from its lens, omit Section 6 entirely or write `- No additional lens-specific findings.`
 
 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.
+**Sections 1–5 are the common core.** Every analysis worker (Claude / Codex / Antigravity) MUST cover the same set of dimensions in sections 1–5 — feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk — regardless of which model is producing the result. The point of running three models is to triangulate the same answer space, not to partition it. A worker that produces "Findings" populated only with items from its own lens (e.g. Codex only listing implementation-feasibility findings) is in breach of contract; convergence will treat coverage gaps as `verification-error`.
+
+**Section 6 is the only legal home for specialization.** When the worker has a depth-of-perspective contribution that genuinely sits outside the common core (e.g. a Codex-specific stack-trace decomposition, a Claude-specific assumption-chain teardown, a Antigravity-specific alternative-architecture sketch), put it there. Lead and convergence treat Section 6 as additive context, not as input to consensus measurement.
+
+Code evidence must include file paths and line numbers.
+
+### Ticket Tagging (mandatory for sections 1–5)
+
+Every item in sections 1–5 MUST be tagged with the ticket(s) it relates to. This applies whenever the run's task type is `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`.
+
+- **Table-form items**: include a `Ticket ID` column. The column is placed immediately after the row-ID column (e.g. after `F-001`, `M-001`).
+- **Bullet / numbered-list items**: prepend `[TICKETID: <id>]` to the item title, immediately after the row ID and before the body text. Example: `- F-001 [TICKETID: TICKET-123] — <summary> (path:line)`.
+- **Section headers in the final report** (e.g. `### 5.5.3 Recommended Option`): append `[TICKETID: <id>]` to the header when the section is scoped to a specific ticket. Headers that span all tickets in the run omit the tag.
+
+Ticket ID fill rule (in order):
+
+1. Use the `Issue / Ticket` value from the run's input template.
+2. If empty, fall back to the `Task ID` value (no prefix; write `8852` not `task:8852`).
+3. If both are absent, write `unknown`. This is allowed but signals an input-template defect — the worker SHOULD also record a `Missing Information` item noting the absent identifier.
+4. When a single item maps to multiple tickets, separate them with commas: `TICKET-123, TICKET-456`. Ticket IDs containing commas are not supported.
+
+Workers MUST apply these rules to every item in sections 1–5. Lead and report-writer MUST preserve the tagging when carrying worker findings into the final report.
 
-See `prompts/lead/team-contract.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.
+For phases other than the four listed above (e.g. `release-handoff`, `final-verification`), ticket tagging is optional.
 
 ## Return message to the lead (all workers)
 
@@ -144,6 +242,6 @@ When you write in Korean (`Report Language: ko` / `meta.reportLanguage = "ko"`),
 
 - Keep code identifiers, file paths, symbols, model names, CLI flags, and status tokens in English (`strategy`, `overlay`, `accepted`, …). Translate the ordinary words around them.
 - Do NOT render a technical term as its literal dictionary noun. Use the term a developer actually says:
-  - `authoritative` → **기준값 / 정본 / 우선 적용** (NEVER 권위)
-  - e.g. "overlays this row as authoritative" → "이 행을 최종 기준값으로 덮어쓴다" (NEVER "이 행을 권위로 overlay")
+  - `authoritative` → render it by its domain sense — "the value that takes precedence" / "the canonical value" — never by the bare dictionary noun for "authority".
+  - e.g. "overlays this row as authoritative" → phrase it as "overwrites this row as the definitive value", never as a word-for-word "authority" calque.
 - Self-check before emitting any Korean sentence: if it reads like an awkward word-for-word translation, rewrite it by meaning. Confident-but-unreadable direct translation is a defect.

package/runtime/validators/validate-schedule.py

@@ -41,7 +41,7 @@ OPTIONAL_GRAPHIC_SECTIONS_IN_ORDER: list[str] = [
     "## Gantt Chart",
 ]
 
-REQUIRED_EXEC_SUMMARY_SUBSECTION = "### Effort Sizing 기준"
+REQUIRED_EXEC_SUMMARY_SUBSECTION = "### Effort Sizing Criteria"
 
 REQUIRED_TASK_FIELDS = [
     "**Category**",