okstra 0.202.0 → 0.205.0

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

@@ -0,0 +1,36 @@
+# Translator Prompt Preamble (canonical)
+
+This file is the audience-specific contract for `translator`. Read it and the shared Worker Error Contract end-to-end. The task instructions in this prompt own this run's commands, paths, and target language; this file owns how you translate and what you may write.
+
+## Output ownership
+
+Write only the translations file at `**Result Path:**`, the completion pointer at `**Worker Result Path:**`, and the reading audit at `**Audit sidecar path:**`. The publish command named in the task instructions owns the sidecar the renderer overlays; do not write that file yourself.
+
+Never edit the report record, the narrative Markdown, the rendered HTML, or any project source file.
+
+Never add, remove, or re-order the `T-NNN` items relative to the work list you were given. Never translate a value the work list did not offer you: its absence is deliberate, because the renderer reads those values as machinery and a translated copy breaks the page silently.
+
+Never return the translated text inline. The file on disk is the artifact; your return message names the paths and the verification result.
+
+## Required reading
+
+Read the complete work list before translating any item, continuing in chunks when it is long. A partial read produces a partial sidecar, and the items you never saw render in the source language with no error raised.
+
+## How to translate
+
+Judge every term on whether the translation or the original carries the meaning faster to a working developer in the target language, and pick that one. The goal is a reader who understands the report sooner, not a document with no English left in it.
+
+- **Never touch**: code identifiers, file paths, CLI commands and flags, model names, commit SHAs, URLs, and anything already inside backticks. Reproduce them character for character.
+- **Keep the English word** when that is what developers in the target language actually say. Forcing a native coinage onto `commit`, `worktree`, `merge`, `lint`, `diff`, `stage`, `rollback` or `PR` makes the sentence *slower* to read, not more local.
+- **Translate the explanation.** Connective prose — why something matters, what a reader should do, what a finding means — is where the translation earns its place. Carry the meaning, not the word order.
+- **Do not translate literally.** A word-for-word rendering that is technically correct and unreadable has failed. Say what the sentence means the way a developer would say it.
+- **Gloss on first use, once.** When a technical term does need translating, write it as `<translation>(<English>)` the first time it appears in the document, then use the translation alone. Never gloss the same term twice.
+- **One claim per sentence.** Where the English stacks four clauses behind em-dashes, split it. The reader gains nothing from the original's punctuation.
+- **Match the register.** A verdict line is terse; a rationale paragraph is explanatory. Do not inflate a three-word cell into a sentence, or compress a paragraph into a fragment.
+- **Leave it out when you cannot do it justice.** An omitted item renders in the source language, which is a correct fallback. A confident mistranslation is not.
+
+## Failure handling
+
+A failing verification check means a pointer resolves nowhere — you altered or invented one. Fix the translation and run the check again; do not return while it fails.
+
+Record your own tool failures through the file named by `**Worker Error Contract Path:**`.

package/runtime/validators/checks/validate-assets-01.py

@@ -22,15 +22,14 @@ def check(source_path: Path, target_path: Path) -> None:
         errors.append(f"build-output asset does not match source: {target_path}")
 
 
-# 1. Worker agent files: agents/workers/*-worker.md -> runtime/agents/workers/*-worker.md
-#
-workers_source = agents_source_root / "workers"
-workers_target = runtime_root / "agents" / "workers"
-if not workers_source.is_dir():
-    errors.append(f"missing agents/workers source directory: {workers_source}")
+# 1. Agent contracts: agents/common.json + agents/roles/* + agents/operations/*
+#    -> runtime/agents/*. 호스트 전역 에이전트 정의는 더 이상 없다(ADR-0017).
+if not agents_source_root.is_dir():
+    errors.append(f"missing agents source directory: {agents_source_root}")
 else:
-    for source_path in sorted(workers_source.glob("*.md")):
-        check(source_path, workers_target / source_path.name)
+    for source_path in sorted(agents_source_root.rglob("*.json")):
+        relative = source_path.relative_to(agents_source_root)
+        check(source_path, runtime_root / "agents" / relative)
 
 # 2. Lead contract + internal lead resources: prompts/lead/* + prompts/coding-preflight/*
 #    -> runtime/prompts/*. These ship as runtime resources (okstra install copies

package/runtime/validators/validate-brief.py

@@ -47,6 +47,10 @@ Checks performed per brief file:
     it is checked by `okstra_ctl.group_context.validate_group_context` (four
     required sections, no template placeholder left, directory slug matches
     the frontmatter `task-group`). Any other `type` is a failure.
+16. No required section except `## Source Material` still carries the
+    template's `<...>` scaffolding — a paragraph wrapped in angle brackets,
+    a `- <...>` bullet, or a `> augmented: <label>` line. Source Material is
+    exempt because it holds the reporter's words verbatim.
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -656,6 +660,71 @@ def check_variant_required_sections(
             )
 
 
+# 템플릿의 `<...>` 문구는 작성자가 바꿔 쓸 자리다. 그대로 남으면 다음 phase 가
+# 그 문구를 제보 내용으로 읽는다. 문구는 여러 줄에 걸친 한 문단이라 줄 단위
+# `is_template_example` 만으로는 잡히지 않는다 — 문단을 합쳐서 본다.
+_AUGMENTED_LABEL_SCAFFOLD_RE = re.compile(r"^>\s*augmented:\s*<label>")
+
+
+def _paragraphs_outside_fences(body: str) -> Iterable[list[str]]:
+    paragraph: list[str] = []
+    in_fence = False
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+        if in_fence or stripped.startswith("```") or not stripped:
+            if paragraph:
+                yield paragraph
+                paragraph = []
+            continue
+        paragraph.append(stripped)
+    if paragraph:
+        yield paragraph
+
+
+def template_scaffold(body: str) -> list[str]:
+    """Template scaffolding left in a section body, one entry per leftover."""
+    found: list[str] = []
+    for paragraph in _paragraphs_outside_fences(body):
+        joined = " ".join(paragraph)
+        if joined.startswith("<") and joined.endswith(">"):
+            found.append(joined)
+            continue
+        found.extend(
+            line
+            for line in paragraph
+            if is_template_example(line) or _AUGMENTED_LABEL_SCAFFOLD_RE.match(line)
+        )
+    return found
+
+
+def check_template_scaffold(text: str, scope: str, errors: list[str]) -> None:
+    """Required sections must not keep the template's `<...>` scaffolding.
+
+    `## Source Material` is exempt: it holds the reporter's words verbatim,
+    and those can legitimately contain angle-bracketed text.
+    """
+    headings = [
+        REQUIREMENT_SECTION,
+        *ALWAYS_REQUIRED_SECTIONS,
+        _GATE_SECTION,
+        *(heading for heading, _prefix in _END_STATE_SECTIONS),
+    ]
+    if scope == "codebase":
+        headings += ["Scan Scope", "Priority Lenses"]
+    else:
+        headings.append("Problem / Symptom")
+    for heading in headings:
+        leftover = template_scaffold(section_body(text, heading))
+        if leftover:
+            errors.append(
+                f"'## {heading}' still carries template text {leftover[0][:60]!r} — "
+                "replace it with the brief's content, or _(none)_ when the section "
+                "is deliberately empty. Downstream phases read this section as written"
+            )
+
+
 def check_reporter_confirmations(
     rc_status: str | None, reporter_rows: list[str], errors: list[str]
 ) -> None:
@@ -724,6 +793,7 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     check_requirement_section(text, errors)
     check_end_state_sections(text, scope, errors)
     check_variant_required_sections(text, scope, errors)
+    check_template_scaffold(text, scope, errors)
 
     # 2. brief-id matches filename stem
     stem = path.stem

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

@@ -34,6 +34,7 @@ from okstra_ctl.stage_map import (  # noqa: E402
     parse_stage_dependencies,
     parse_stage_map_text,
     schema_v2_report,
+    stage_number_gap_message,
 )
 
 HARD_STEP_CAP = 8
@@ -86,7 +87,7 @@ def _stage_numbers_monotonic(
 ) -> List[ValidationError]:
     return [
         ValidationError("S2", r.stage_number,
-            f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}")
+            stage_number_gap_message(r.stage_number, i))
         for i, r in enumerate(stages, start=1)
         if r.stage_number != i
     ]

package/runtime/validators/validate-run.py

@@ -43,6 +43,7 @@ from okstra_project.resolver import resolve_architecture  # noqa: E402
 from okstra_ctl.conformance import (  # noqa: E402
     conformance_result_file,
     detect_surfaces,
+    declared_stage_surface_gaps,
     exempt_stage_surface_conflicts,
     evaluate_conformance,
     manifest_required_surfaces,
@@ -2120,7 +2121,13 @@ def _declared_conformance_errors(
             and all(isinstance(value, str) for value in actual_requires)
             else None
         )
-        if actual_capabilities != frozenset(declaration.get("requires") or []):
+        # 넓히는 것만 허용한다 — 선언보다 많은 capability 는 더 엄격한 검증이다.
+        # 승인된 계획이 `requires` 를 좁게 적고 그 stage 의 diff 가 다른 표면을
+        # 건드리면, diff-surface 대조는 넓힐 것을 요구하는데 정확 일치는 그것을
+        # 거절해 같은 계획으로는 통과할 입력이 없었다(2026-09-22 dev-10860
+        # Stage 1). 좁히는 것은 선언한 검증을 빼는 것이므로 여전히 불일치다.
+        declared_capabilities = frozenset(declaration.get("requires") or [])
+        if actual_capabilities is None or not actual_capabilities >= declared_capabilities:
             errors.append(f"stage {stage_number} requires mismatch")
     # 계획이 면제한 stage 에 구현이 실제 Tier 3 항목을 붙이는 것은 허용한다 —
     # 면제 stage 의 diff 가 db/io/http/external 표면을 건드려 diff-surface 대조에
@@ -2183,6 +2190,24 @@ def _project_surface_patterns(project_root: Path) -> object:
         return None
 
 
+def _implemented_stages(data_path: Path) -> frozenset[int]:
+    """이 태스크에서 구현이 끝난 stage. 원장을 못 읽으면 빈 집합이다."""
+    from okstra_ctl.consumers import read_stage_consumer_state
+
+    try:
+        state = read_stage_consumer_state(data_path.parent.parent)
+    except (OSError, UnicodeError, ValueError):
+        return frozenset()
+    return frozenset(state.done_stages)
+
+
+def _is_implemented_stage(stage: object, implemented: frozenset[int]) -> bool:
+    number = stage.get("stage") if isinstance(stage, dict) else None
+    return isinstance(number, int) and not isinstance(number, bool) and (
+        number in implemented
+    )
+
+
 def _validate_planning_conformance_declared(
     report_path: Path,
     failures: list[str],
@@ -2209,7 +2234,17 @@ def _validate_planning_conformance_declared(
     ip = data.get("implementationPlanning")
     if not isinstance(ip, dict):
         return
-    _planning_conformance_declarations(ip.get("stages"), failures)
+    # 구현이 끝난 stage 는 이 게이트의 대상이 아니다. 그 본문은 다음 계획 run 에
+    # 그대로 이월되고(ADR-0015), 이월된 본문은 고칠 수 없다 — 규칙이 그 사이에
+    # 넓어졌다면 통과 가능한 값이 없는 요구가 된다(2026-09-24, dev-10860: 이월된
+    # stage 2·3·5 가 오늘의 표면 패턴으로 `requires` 누락 판정).
+    implemented = _implemented_stages(data_path)
+    stages = [
+        stage
+        for stage in ip.get("stages") or ()
+        if not _is_implemented_stage(stage, implemented)
+    ]
+    _planning_conformance_declarations(stages, failures)
     if ip.get("planningContract") != "selected-direction":
         from okstra_ctl.implementation_direction import (
             stage_validation_executability_errors,
@@ -2217,6 +2252,8 @@ def _validate_planning_conformance_declared(
 
         failures.extend(stage_validation_executability_errors(ip))
     for conflict in exempt_stage_surface_conflicts(data, surface_patterns):
+        if conflict["stage"] in implemented:
+            continue
         failures.append(
             "conformance gate BLOCKING: stage "
             f"{conflict['stage']} declares `Conformance exemption:` but its "
@@ -2229,6 +2266,19 @@ def _validate_planning_conformance_declared(
             "blocks the same stage after the work is done, where the approved "
             "plan can no longer be corrected."
         )
+    for gap in declared_stage_surface_gaps(data, surface_patterns):
+        if gap["stage"] in implemented:
+            continue
+        failures.append(
+            "conformance gate BLOCKING: stage "
+            f"{gap['stage']} declares `Conformance tests:` with "
+            f"requires={gap['requires']} but its planned paths touch surface(s) "
+            f"{gap['surfaces']}: {', '.join(gap['paths'])} — add "
+            f"{gap['surfaces']} to that stage's `requires`, or move those paths "
+            "out of it. The implementation run's diff-surface check demands "
+            "the wider set after the work is done, where the approved plan can "
+            "no longer be corrected."
+        )
 
 
 def _validate_conformance_surfaces(
@@ -5728,7 +5778,7 @@ def _validate_verified_row_recorded(
     report_path: Path,
     failures: list[str],
 ) -> None:
-    """A release-ready single-stage verification must leave its `verified` row.
+    """A release-ready verification must leave a `verified` row per cleared stage.
 
     `okstra handoff record-verified` validates its own inputs, but nothing
     checked that it ever ran. Skipping it leaves the report saying `accepted`
@@ -5737,7 +5787,8 @@ def _validate_verified_row_recorded(
     the only recoveries are re-running an expensive phase or hand-editing the
     registry.
     """
-    if str(data.get("verificationScope") or "") != "single-stage":
+    scope = str(data.get("verificationScope") or "")
+    if scope not in ("single-stage", "whole-task"):
         return
     if not release_handoff_allowed(data):
         return
@@ -5752,11 +5803,17 @@ def _validate_verified_row_recorded(
     if rows is None:
         return
     head = ((data.get("finalVerification") or {}).get("sourceImplementationReport") or {}).get("capturedHeadSha")
+    # 전체 task 행의 `head_commit` 은 그 stage 자신의 완료 커밋이다. 검증된 head
+    # 는 `verified_head_commit` 에 있으므로, 그 행을 stage 커밋으로 찾으면 모든
+    # stage 가 누락으로 읽힌다.
+    head_field = (
+        "verified_head_commit" if scope == "whole-task" else "head_commit"
+    )
     verified = {
         row.get("stage")
         for row in rows
         if isinstance(row, dict) and row.get("status") == "verified"
-        and head and row.get("head_commit") == head
+        and head and row.get(head_field) == head
         and row.get("final_verdict") == data.get("finalVerdict")
         and _data_path_for(Path(str(row.get("report_path") or ""))).resolve() == _data_path_for(report_path).resolve()
     }
@@ -5766,9 +5823,9 @@ def _validate_verified_row_recorded(
             f"final-verification cleared stage(s) {missing} for release but "
             "`runs/implementation-planning/consumers.jsonl` carries no "
             "`verified` row matching this report and captured commit. Run `okstra handoff record-verified` "
-            "before finishing — without that row the report says accepted "
-            "while the registry says unverified, and the stage is never "
-            "offered for a stage-group PR "
+            "before finishing — once per cleared stage — without that row the "
+            "report says accepted while the registry says unverified, and the "
+            "stage is never offered for a pull request "
             '(final-verification.md §"Verified-row recording").'
         )
 
@@ -8065,19 +8122,19 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "`blocksReleaseHandoff: false`."
         )
 
+    if routing_token == "final-verification" and token == "accepted":
+        failures.append(
+            "final-verification: routingRecommendation cites `final-verification` "
+            "but the verdict is `accepted` — an accepted verdict carries no blocker "
+            "to re-verify. Route to release-handoff or done."
+        )
+
     scope = data.get("verificationScope", "whole-task")
     if scope not in ("whole-task", "single-stage"):
         failures.append(
             f"final-verification: verificationScope must be `whole-task` or "
             f"`single-stage`, got {scope!r}."
         )
-    if scope == "single-stage" and routing_token == "release-handoff":
-        failures.append(
-            "final-verification: verificationScope `single-stage` cannot recommend "
-            "plain release-handoff routing — a single-stage accepted verdict may "
-            "only route to `release-handoff(stage-group)` (partial-PR mode); "
-            "whole-task release-handoff requires whole-task verification."
-        )
 
 
 def validate_report_views(report_path: Path, failures: list[str]) -> None:

package/runtime/validators/validate-schedule.py

@@ -441,6 +441,15 @@ def _validate_format(path: Path) -> list[str]:
                     f"{why}; a stage block is Steps plus Exit criteria"
                 )
 
+    # 9b. The At a Glance work column is titled in the schedule's language.
+    glance_header = (
+        f"| # | {labels['glance_work_column']} | Category | Priority | Effort | Days | Risk |"
+    )
+    if "## At a Glance" in section_positions and glance_header not in text:
+        violations.append(
+            f"`## At a Glance` requires the header literal {glance_header!r}"
+        )
+
     # 10. Days total format inside At a Glance: `**N tasks total / estimated effort: X.X ~ Y.Y days (Effort sum)**`
     if "## At a Glance" in section_positions:
         start = section_positions["## At a Glance"]

package/docs/for-ai/README.md

@@ -1,68 +0,0 @@
-# Okstra Skills AI Manuals
-
-This directory is a compressed manual for an AI to quickly select and precisely run okstra public skills. The authoritative contract is `skills/*/SKILL.md`; this document is the operational guide for the AI. When the source skills, templates, validators, or CLI registry conflict, prefer the source skills and the actual validator/CLI implementation.
-
-## Verified Sources
-
-- Public skill list: [`src/lib/skill-catalog.mjs`](../../src/lib/skill-catalog.mjs)
-- Skill sources: [`skills/`](../../skills/)
-- CLI command surface: [`src/cli-registry.mjs`](../../src/cli-registry.mjs)
-- brief template: [`templates/reports/brief.template.md`](../../templates/reports/brief.template.md)
-- schedule template: [`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md)
-- brief validator: [`validators/validate-brief.py`](../../validators/validate-brief.py)
-- schedule validator: [`validators/validate-schedule.py`](../../validators/validate-schedule.py)
-
-## Skill Routing
-
-| User intent | Skill to use | Manual |
-|---|---|---|
-| Install/initialize okstra on a new project or a new machine | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
-| Turn requirements, tickets, links, a codebase scan, or an error-zip into an okstra input brief | `okstra-brief-gen` | [`skills/okstra-brief-gen.md`](skills/okstra-brief-gen.md) |
-| Start an okstra run or execute the next phase in the current Claude Code session | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
-| Manage okstra tasks across multiple projects — bundling, assignment, sync snapshots, child launch packets | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
-| Check status, history, report, time, logs, cost, errors, error-zip, run-audit, recap | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
-| Collect and aggregate the results of multiple task runs across a task-group (or the whole project) into a synthesized summary | `okstra-rollup` | [`skills/okstra-rollup.md`](skills/okstra-rollup.md) |
-| Project-wide recent run coverage, tokens, known cost, CPU, and wall-clock usage by task type | `okstra-usage` | [`skills/okstra-usage.md`](skills/okstra-usage.md) |
-| Generate a client-facing work schedule for a whole task-group | `okstra-schedule-gen` | [`skills/okstra-schedule-gen.md`](skills/okstra-schedule-gen.md) |
-| Store or search conversations/decisions/preferences/requirements in the global Memory Book | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
-| Create or join a global room and send or read addressed messages across host sessions | `okstra-chat` | [`skills/okstra-chat.md`](skills/okstra-chat.md) |
-| Manage the implementation-task worktree-based docker compose user-test environment | `okstra-container-build` | [`skills/okstra-container-build.md`](skills/okstra-container-build.md) |
-| Answer the unresolved clarification questions an okstra run left behind in-session and record the approval gate | `okstra-user-response` | [`skills/okstra-user-response.md`](skills/okstra-user-response.md) |
-| Register a PR body template or generate a PR description from a branch diff (global, git repository) | `okstra-pr-gen` | [`skills/okstra-pr-gen.md`](skills/okstra-pr-gen.md) |
-| Review the changed code of one okstra `implementation` stage or of any branch against the coding-preflight rules, and write the result to a file | `okstra-code-review` | [`skills/okstra-code-review.md`](skills/okstra-code-review.md) |
-
-## Shared Execution Rules
-
-1. Run commands as separate Bash calls whenever the source skill requires it. In particular, do not wrap `okstra preflight --runtime claude-code`, `okstra wizard ...`, or `okstra container ...` calls in `&&`, `||`, `$(...)`, a leading variable assignment, `eval`, or `export`.
-2. An `okstra <subcmd>` call bootstraps its own Python path. Unless a skill states otherwise, do not build `okstra paths --shell` or `export PYTHONPATH=...`.
-3. Most skills except `okstra-setup` do not use an `npx` fallback. If the runtime is missing, tell the user to run `/okstra-setup` and stop. But if it fails with `unknown command: <cmd>`, the `okstra` binary on PATH is older than the skill — point the user to `npm i -g okstra@latest` rather than `/okstra-setup`, and stop.
-4. Project artifacts go under `<PROJECT_ROOT>/.okstra/` by default. The exceptions are `okstra-memory` (`~/.okstra/memory-book/`) and `okstra-chat` (`~/.okstra/chat/`).
-5. `runtime/` is build output. When fixing a source skill or template, edit the source under `skills/`, `templates/`, `validators/`, `scripts/`, `src/` and apply it via a build.
-6. Do not guess the contents of a tracker, URL, file, report, log, zip, template, or validator. Use only what you have confirmed by reading or running with a tool.
-7. Read-side skills also produce some artifacts. `okstra-inspect errors` produces an error report Markdown and `okstra-inspect error-zip` produces an anonymized zip. Even in these cases, keep the purpose-specific fixed CLI fields as the source of truth.
-
-## The Order the AI Reads In
-
-1. Pick a skill in this file.
-2. Read only the matching `docs/for-ai/skills/<skill>.md`.
-3. If the skill requires actual execution, confirm the relevant step in the source [`skills/<skill>/SKILL.md`](../../skills/).
-4. When writing a brief or schedule, also confirm the template and the validator.
-
-## Public Skill List
-
-The public skills listed in this AI manual are the following 14:
-
-- `okstra-setup`
-- `okstra-brief-gen`
-- `okstra-run`
-- `okstra-manager`
-- `okstra-memory`
-- `okstra-chat`
-- `okstra-inspect`
-- `okstra-rollup`
-- `okstra-usage`
-- `okstra-schedule-gen`
-- `okstra-container-build`
-- `okstra-user-response`
-- `okstra-pr-gen`
-- `okstra-code-review`