okstra 0.54.0 → 0.56.0

package/runtime/bin/okstra-inject-report-index.py

@@ -0,0 +1,66 @@
+#!/usr/bin/env python3
+"""CLI entry for the top-of-report index / scroll-anchor injector.
+
+Usage:
+    python3 scripts/okstra-inject-report-index.py \\
+        <final-report.md> \\
+        [--report-language en|ko]
+
+Adds the top-of-report Index (section list + ID index) and `<a id="...">`
+scroll anchors to a markdown report that was authored *free-form* rather
+than rendered from a data.json. The only such task-type today is
+`improvement-discovery`: its `## 5.9 Improvement Candidates` table is
+written directly by the report-writer worker, so the data.json renderer
+(which injects the index for every other task-type) never sees it.
+
+Idempotent — re-running on an already-indexed report is a no-op.
+"""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+_HERE = Path(__file__).resolve().parent
+# Make ``okstra_ctl`` importable for in-repo invocation (the installed
+# runtime adds ``~/.okstra/lib/python`` via the wrapper scripts).
+sys.path.insert(0, str(_HERE))
+
+from okstra_ctl.i18n import SUPPORTED_LANGS  # noqa: E402
+from okstra_ctl.render_final_report import (  # noqa: E402
+    FinalReportRenderError,
+    inject_index_into_file,
+)
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(
+        description="Inject the top-of-report index + scroll anchors into a free-form markdown report.",
+    )
+    parser.add_argument(
+        "report",
+        type=Path,
+        help="Path to the final-report markdown to rewrite in place.",
+    )
+    parser.add_argument(
+        "--report-language",
+        choices=list(SUPPORTED_LANGS),
+        default="en",
+        help="Language for the index labels (Index/목차, …). Default: en.",
+    )
+    args = parser.parse_args(argv)
+
+    try:
+        bytes_written = inject_index_into_file(
+            args.report, report_language=args.report_language
+        )
+    except FinalReportRenderError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+
+    print(f"injected index + anchors -> {args.report} ({bytes_written} bytes)")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/bin/okstra.sh

@@ -123,6 +123,7 @@ PY_ARGS=(
 [[ -n "${WORK_CATEGORY-}" ]] && PY_ARGS+=(--work-category "$WORK_CATEGORY")
 [[ -n "${BASE_REF-}" ]] && PY_ARGS+=(--base-ref "$BASE_REF")
 [[ -n "${STAGE-}" ]] && PY_ARGS+=(--stage "$STAGE")
+[[ -n "${QA_WAIVER-}" ]] && PY_ARGS+=(--qa-waiver "$QA_WAIVER")
 [[ "$RENDER_ONLY" == "true" ]] && PY_ARGS+=(--render-only)
 [[ "$PLAN_VERIFICATION_ENABLED" == "false" ]] && PY_ARGS+=(--no-plan-verification)
 

package/runtime/prompts/profiles/_implementation-verifier.md

@@ -39,7 +39,28 @@ Verifier obtains the QA command set from exactly two declared sources, in order
 
 ### Execution rule
 
-Tier 1 commands run verbatim first. Then every Tier 2 entry runs once. Each command runs in the worktree cwd, and is recorded in the worker result with its exact command line, exit code, and the tail of stdout/stderr. Substituting or paraphrasing a Tier 1 command is forbidden (see Verifier-specific forbidden actions below).
+Tier 1 commands run verbatim first. Then every Tier 2 entry runs once. Then the Tier 3 stage conformance script (below) runs once. Each command runs in the worktree cwd, and is recorded in the worker result with its exact command line, exit code, and the tail of stdout/stderr. Substituting or paraphrasing a Tier 1 command is forbidden (see Verifier-specific forbidden actions below).
+
+### Tier 3 — stage conformance scripts (요구사항 부합 검증)
+
+Tiers 1·2 prove the diff *builds and passes*; Tier 3 proves the stage actually *meets the upper-level requirement* it was scoped to, by running a declared conformance script against the running state. This is a real gate — its result sidecar is the input the `validate-run.py` Tier 3 gate reads, so a missing or non-PASS result BLOCKS acceptance.
+
+- **Source.** The conformance manifest is `<task_root>/qa/conformance-manifest.json` (the directory is the `TASK_QA_PATH` token). This run's stage conformance entry is the manifest `entries[]` item whose `stageKey` equals this run's stageKey — `<task-id>-stage-<N>`, where `<N>` is the injected Stage number. Find that one entry; ignore the others (other stages are run by their own implementation runs or by final-verification).
+- **Exemption / waiver → do NOT run.** If the entry carries an `exemption` (or a user `waiver`), the verifier does NOT execute the script. It records the fact and the reason (`exemption.reason` / `waiver.reason` + `waiver.acknowledgedBy`) in the Read-only command log AND writes the result sidecar reflecting the skip. An `exemption` passes the gate outright; a `waiver` passes but is conditional (conformance left unverified by explicit user acknowledgement). No script runs in either case.
+- **Otherwise run `runCommand` in the worktree cwd.** Execute the entry's `runCommand` verbatim from the worktree cwd. Inject env from `<PROJECT_ROOT>/.okstra/project.json`'s `qaEnv` (replica DB DSN / app base URL / env file — declared in Phase 4e). This is a **replica / test environment only** path — never run it against shared / staging / prod, identical to the DB real-execution gate principle above.
+- **Interpret the standard interface.** Parse the process exit code together with stdout: the `QA-RESULT: PASS|FAIL` marker line (if several appear, the last one wins) and the per-requirement `REQ <id>: PASS|FAIL: <reason>` lines. If no `QA-RESULT` marker is emitted, the overall result is `MISSING` — which the gate treats as BLOCKING (the script broke the contract).
+- **Write the result sidecar (BLOCKING deliverable).** Write `<task_root>/qa/result-<stageKey>.json` as:
+  ```json
+  {
+    "stageKey": "<task-id>-stage-<N>",
+    "overall": "PASS",
+    "ranAt": "<UTC ISO8601>",
+    "requirements": { "<id>": { "status": "PASS", "reason": "<from REQ line>" } }
+  }
+  ```
+  `overall` is exactly one of `PASS` / `FAIL` / `MISSING`. This file is the input to the `validate-run.py` Tier 3 gate — if it is absent the gate reports the stage as "never ran" and BLOCKS, so writing it is mandatory whenever the script runs (and on the exemption/waiver skip path, recording the skip outcome).
+- **Read-only command log.** Record the `runCommand` exact line + its exit code in the Read-only command log. Unlike Tiers 1·2, a conformance script MAY mutate the **replica datastore** (exercising integrated state is its whole purpose) — but only the `qaEnv` replica target, never a shared/staging/prod store. The `runCommand` itself is still subject to the same source/lockfile mutation deny-list as Tier 2 (`--fix`, `npm install` without `ci`, etc.); a denied token aborts with `contract-violated`.
+- **No manifest / no entry for this stage.** If the manifest file is absent, or it has no entry whose `stageKey` matches this run's stageKey, the verifier records `conformance: no manifest entry for <stageKey>` and proceeds (forcing the *declaration* of conformance entries is the job of planning Step 11 + the `validate-run.py` diff-surface cross-check, not the verifier).
 
 ### Missing-tier handling
 
@@ -55,7 +76,7 @@ If the verifier's re-run result differs from what the executor reported (a passi
 
 ### Read-only command log (per verifier)
 
-The worker result MUST contain a `Read-only command log` block listing every command executed during the verifier run with its exact invocation and exit code, in execution order. No mutating command may appear in this block. This log is copied into the final report's verifier result section verbatim.
+The worker result MUST contain a `Read-only command log` block listing every command executed during the verifier run with its exact invocation and exit code, in execution order — including the Tier 3 conformance `runCommand` (or the exemption/waiver skip note when no script ran). No source-mutating command may appear in this block; the only permitted mutation is a Tier 3 conformance script writing to its `qaEnv` replica datastore, which is logged like any other command. This log is copied into the final report's verifier result section verbatim.
 
 ### Verifier evidence is independent of executor evidence
 

package/runtime/prompts/profiles/final-verification.md

@@ -36,6 +36,7 @@
   - **Validation Evidence**: for every requirement in the originating plan or task brief, cite the artifact (commit SHA, test output, log line, MCP SELECT result) that demonstrates coverage. Paraphrased "verified" claims without an artifact are rejected.
   - **Read-only command log**: any pre-existing test/validation command executed during this run MUST be listed with its exact command line and exit code. No mutating commands may appear here.
   - **Two-tier command lookup (shared with `implementation`):** when this phase performs its own independent re-validation, the command source is exactly the same two tiers `implementation` verifiers use — Tier 1 is the originating task brief / approved plan's `validation` set, Tier 2 is `<PROJECT_ROOT>/.okstra/project.json` under `qaCommands`. Auto-detecting tools from manifest files is forbidden; missing tiers are recorded as `qa-command not configured: <category>` and do NOT trigger a guess. The `cmd` deny-list (`--fix`, `--write`, ` -w`, ` -u`, `--snapshot-update`, `INSTA_UPDATE=<not-no>`, `cargo update`, `npm install` without `ci`, etc.) is enforced identically. NOTE: runtime fail-fast validation (`okstra_ctl.qa_commands.validate_qa_commands`) only fires at `--task-type implementation` run-prep, so this phase MUST self-check each `qaCommands` entry against the deny-list before executing it — if a denied token is present, skip the command and record it as a `Read-only command log` line `qa-command rejected (denied token: <token>): <label>`.
+  - **Tier 3 — stage conformance scripts (whole-task union):** because this phase verifies the **integrated, merged** state, it re-runs conformance against that state rather than per-stage. Read the task-level manifest `<task_root>/qa/conformance-manifest.json` (the directory is the `TASK_QA_PATH` token) and, in **whole-task scope**, run the `runCommand` of **every** `entries[]` item against the merged worktree, refreshing each `<task_root>/qa/result-<stageKey>.json` (`{ "stageKey", "overall": "PASS"|"FAIL"|"MISSING", "ranAt", "requirements" }`). In **single-stage scope**, run only the entry whose `stageKey` matches the verified stage. An entry carrying an `exemption` or user `waiver` is NOT executed — record the skip and reason; a `waiver` becomes a `conditional-accept` condition surfaced in the section 7 Verdict (conformance left unverified by user acknowledgement). Each `runCommand` runs in the worktree cwd with `qaEnv` env (replica DB DSN / app base URL / env file) — **replica / test environment only**, never shared / staging / prod, and the same source/lockfile mutation deny-list applies (a conformance script MAY mutate only its `qaEnv` replica datastore). Interpret each result from the exit code + stdout `QA-RESULT: PASS|FAIL` (last wins) and `REQ <id>: PASS|FAIL: <reason>` lines; no `QA-RESULT` marker → `MISSING`. Any entry whose result is not `PASS` (including `MISSING` or a never-run/missing sidecar) is an **Acceptance Blocker** (`major`+) — exactly like the DB real-execution gate above, since `accepted` requires zero blockers the verdict becomes `conditional-accept` / `blocked`. This is the same gate the `validate-run.py` Tier 3 check enforces on the result sidecars.
   - **Routing recommendation**: the next safe phase — one of `release-handoff`, `done`, `error-analysis`, `implementation-planning` — tied to the verdict and blocker list. `release-handoff` is allowed ONLY when the Verdict Token is `accepted`. `release-handoff` is additionally allowed ONLY when the verification scope (the `Verification scope:` line of the injected `VERIFICATION_TARGET` block, recorded as the report's `verificationScope` field) is `whole-task`; a `single-stage` run is partial and routes to `implementation` / `done` even on an `accepted` verdict.
 - Clarification request policy (phase-specific addendum — shared policy is in `_common-contract.md`):
   - populate `## 1. Clarification Items` only when a blocker hinges on information only the user can supply (deployment intent, intended target environment, business-rule interpretation); use `Blocks=next-phase` for items that gate continuing to release-handoff

package/runtime/prompts/profiles/implementation-planning.md

@@ -71,6 +71,10 @@
   - **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
     - `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
     - `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | expected`. **Effective row count ≤ 6** (excluding header / divider / blank). Each step is one action completable in 2–5 minutes; for code steps include actual code or diff sketch. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test that captures this stage's `Acceptance` (`expected` = FAIL); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`expected` = PASS); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section (mirrors the executor's per-step exemption in `_implementation-executor.md`). Validator S10c enforces RED-first + GREEN, or the exemption line.
+    - **Per-stage conformance declaration (mandatory one line, in the stage section — same placement freedom as `TDD exemption:`):** the stage MUST carry exactly one of:
+      - `Conformance tests: stage-<N> — <task_root>/qa/stage-<N>.<ext> (requires=[db|io|http|external,...])` — a Tier3 verification script that proves this stage's upstream requirements (brief / requirements-discovery / error-analysis / improvement-discovery → this stage's `Acceptance`) hold against **real** DB rows, real endpoints, or the real external API — NOT mocks. When you emit this line you MUST also (a) write the script to `<task_root>/qa/stage-<N>.<ext>` and (b) add a matching entry to `<task_root>/qa/conformance-manifest.json` with fields `stageKey` (= `<task-id>-stage-<N>`), `script`, `runCommand`, `requirementIds`, `requires` (subset of `{db, io, http, external}`), `passContract`, `exemption: null`, `waiver: null`. The script's standard interface: a `main` that exits `0`=PASS / non-zero=FAIL, and whose stdout ends with `QA-RESULT: PASS|FAIL` followed by one `REQ <id>: PASS|FAIL: <근거>` line per requirement.
+      - `Conformance exemption: <reason>` — only for stages that touch no db/io/http/external surface, or where unit tests fully cover the increment. (If the eventual `implementation` diff actually touches one of those surfaces, `validate-run.py`'s diff-surface cross-check is BLOCKING — an exemption cannot hide a real db/io/http/external change.)
+      The manifest lives at the **task level** (`<task_root>/qa/`, path token `TASK_QA_PATH`) and is shared across planning → implementation → final-verification. This declaration is enforced at three layers: `validators/validate-implementation-plan-stages.py` check **S11** forces every stage to carry one of the two lines; the manifest JSON structure is enforced by `validate_conformance_manifest` (run / validate-run); and the result gate (each script's `QA-RESULT`) is enforced by the verifier Tier3 + validate-run.
     - `### Stage Exit Contract` — predicted added/modified files, newly exposed identifiers/types/endpoints, downstream-usable resources.
     - `### Stage Validation` — pre / mid / post exact commands or observable outcomes for this stage only.
   - **Vertical-slice-first partition rule (1st-class):** the grouping anchor is a **thin end-to-end vertical slice** — one stage delivers a single user-observable increment, crossing whatever layers are needed (data → service → API → UI) to make that one increment work. File/module proximity is demoted to the **intra-slice grouping rule**: within a slice, keep steps touching the same file/directory/module together so the diff, PR, and rollback unit stay cohesive. **Horizontal layer-splitting is forbidden** — never carve "the DB layer" into one stage and "the service layer" into the next; that produces stages that ship no standalone user value. A stage is split ONLY when (a) a real `depends-on` data/contract dependency exists, (b) effective steps would exceed 6, or (c) it is a distinct vertical slice (a different user-value increment). Maximising the number of parallel stages is NOT a reason to split — parallelism is an emergent property of independent stages, never a partitioning goal.

package/runtime/prompts/profiles/improvement-discovery.md

@@ -32,6 +32,7 @@
   - the `## 5.9 Improvement Candidates` table populated with rows that obey the 10-column schema from `validators/validate-improvement-report.py` (Cand ID `I-NNN`, Lens from whitelist, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, gemini}, Recommended next-phase ∈ {requirements-discovery, implementation-planning, error-analysis}, Evidence as path:line list)
   - `## 7. Final Verdict` Verdict Token ∈ {`candidates-ready`, `no-candidates`, `blocked`}; Direction `routing`; Next Step "사용자에게 후보 K개 선택 의뢰 (## 5.9 표 참조)"
   - `## 3. Recommended Next Steps` first entry summarises per-candidate routing and proposes new task-key names of the form `<task-group>/imp-<Cand-ID>`
+  - this report is authored free-form (improvement-discovery is not in the data.json schema enum); after the markdown is written, the report-writer runs `scripts/okstra-inject-report-index.py <report.md> --report-language <en|ko>` to add the top-of-report Index + `I-NNN`/`C-NNN` scroll anchors. The run validator fails the report when the Index anchor is missing.
 - Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
   - if scan-scope or priority-lenses cannot be made concrete during Phase 1.5, end the run with Verdict Token `blocked`, populate `## 1. Clarification Items` with `Blocks=next-phase` rows, and do not run worker dispatch
   - every clarification row carries a recommended answer + one-line rationale inside the `Expected form` cell

package/runtime/python/okstra_ctl/clarification_items.py

@@ -46,8 +46,17 @@ class ClarificationItem:
     raw_status: str
 
 
+# The final-report renderer injects a scroll anchor into ID-defining first
+# cells — either leading (`<a id="c-001"></a>C-001`) or inside the bold marker
+# (`**<a id="e-001"></a>E-001**`). Strip every such empty anchor during cell
+# normalization so the ID parses as a bare token for clarification parsing AND
+# the HTML view's `C-\d+` form detection, and so the anchor never leaks into
+# the HTML view as html-escaped literal text.
+_CELL_ANCHOR_RE = re.compile(r'<a id="[^"]*"></a>')
+
+
 def _strip_backticks(cell: str) -> str:
-    s = cell.strip()
+    s = _CELL_ANCHOR_RE.sub("", cell.strip()).strip()
     if s.startswith("`") and s.endswith("`") and len(s) >= 2:
         s = s[1:-1].strip()
     return s

package/runtime/python/okstra_ctl/conformance.py

@@ -0,0 +1,270 @@
+"""Stage conformance(Tier 3) 매니페스트 검증 + `QA-RESULT` 파서.
+
+implementation/final-verification 의 verifier 는 stage 별 conformance 스크립트를
+실행해 상위 요구사항 부합을 검증한다. 본 모듈은 그 검증/파싱의 결정론적 코어다.
+
+1. `conformance-manifest.json` 구조 검증 (`validate_conformance_manifest`).
+2. 스크립트 stdout 의 `QA-RESULT` 마커 파싱 (`parse_qa_result`).
+
+스크립트 실행/게이트 강제는 verifier prompt 와 validators/validate-run.py 가 담당한다.
+"""
+from __future__ import annotations
+
+import fnmatch
+import re
+from dataclasses import dataclass
+
+# diff 가 건드린 표면과 대조할 capability 태그 화이트리스트.
+CAPABILITY_WHITELIST: tuple[str, ...] = ("db", "io", "http", "external")
+
+
+def _check_nonempty_str(value: object, path: str, errors: list[str]) -> bool:
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{path} must be a non-empty string")
+        return False
+    return True
+
+
+def _check_capabilities(value: object, path: str, errors: list[str]) -> None:
+    if not isinstance(value, list):
+        errors.append(f"{path} must be an array")
+        return
+    for cap in value:
+        if cap not in CAPABILITY_WHITELIST:
+            errors.append(
+                f"{path}: unknown capability {cap!r} "
+                f"(allowed: {', '.join(CAPABILITY_WHITELIST)})"
+            )
+
+
+def _check_exemption(value: object, path: str, errors: list[str]) -> None:
+    if value is None:
+        return
+    if not isinstance(value, dict):
+        errors.append(f"{path} must be an object or null")
+        return
+    _check_nonempty_str(value.get("reason"), f"{path}.reason", errors)
+    _check_nonempty_str(value.get("declaredAt"), f"{path}.declaredAt", errors)
+
+
+def _check_waiver(value: object, path: str, errors: list[str]) -> None:
+    if value is None:
+        return
+    if not isinstance(value, dict):
+        errors.append(f"{path} must be an object or null")
+        return
+    _check_nonempty_str(value.get("acknowledgedBy"), f"{path}.acknowledgedBy", errors)
+    _check_nonempty_str(value.get("reason"), f"{path}.reason", errors)
+    _check_nonempty_str(value.get("at"), f"{path}.at", errors)
+    _check_capabilities(value.get("scope", []), f"{path}.scope", errors)
+
+
+def _check_entry(entry: object, idx: int, errors: list[str]) -> None:
+    path = f"entries[{idx}]"
+    if not isinstance(entry, dict):
+        errors.append(f"{path} must be an object")
+        return
+    _check_nonempty_str(entry.get("stageKey"), f"{path}.stageKey", errors)
+    _check_nonempty_str(entry.get("script"), f"{path}.script", errors)
+    _check_nonempty_str(entry.get("runCommand"), f"{path}.runCommand", errors)
+    _check_nonempty_str(entry.get("passContract"), f"{path}.passContract", errors)
+    req_ids = entry.get("requirementIds")
+    if (
+        not isinstance(req_ids, list)
+        or not req_ids
+        or not all(isinstance(r, str) and r.strip() for r in req_ids)
+    ):
+        errors.append(f"{path}.requirementIds must be a non-empty array of strings")
+    _check_capabilities(entry.get("requires", []), f"{path}.requires", errors)
+    _check_exemption(entry.get("exemption"), f"{path}.exemption", errors)
+    _check_waiver(entry.get("waiver"), f"{path}.waiver", errors)
+
+
+def validate_conformance_manifest(manifest: object) -> list[str]:
+    """conformance-manifest 전체 검증. 위반 메시지 리스트 반환(비면 안전).
+
+    매니페스트 부재(None)는 합법 — 스크립트 없는 task 가 있을 수 있고, 게이트
+    강제(diff surface 대조)는 validators/validate-run.py 가 판정한다.
+    """
+    if manifest is None:
+        return []
+    if not isinstance(manifest, dict):
+        return [f"conformance manifest must be an object, got {type(manifest).__name__}"]
+    entries = manifest.get("entries")
+    if not isinstance(entries, list):
+        return ["conformance manifest .entries must be an array"]
+    errors: list[str] = []
+    seen: set[str] = set()
+    for idx, entry in enumerate(entries):
+        _check_entry(entry, idx, errors)
+        key = entry.get("stageKey") if isinstance(entry, dict) else None
+        if isinstance(key, str) and key:
+            if key in seen:
+                errors.append(f"entries[{idx}].stageKey duplicate: {key!r}")
+            seen.add(key)
+    return errors
+
+
+_QA_RESULT_RE = re.compile(r"^QA-RESULT:\s*(PASS|FAIL)\s*$", re.MULTILINE)
+_REQ_LINE_RE = re.compile(r"^REQ\s+(\S+):\s*(PASS|FAIL):\s*(.*)$", re.MULTILINE)
+
+
+@dataclass
+class QaResult:
+    overall: str  # "PASS" | "FAIL" | "MISSING"
+    requirements: dict[str, dict[str, str]]  # id -> {"status": "PASS"|"FAIL", "reason": str}
+
+
+def parse_qa_result(stdout: str) -> QaResult:
+    """스크립트 stdout 에서 `QA-RESULT` 마커 + `REQ` 줄 파싱.
+
+    마커가 없으면 overall='MISSING' — 스크립트가 계약을 안 지킨 것이므로 게이트는
+    FAIL 로 취급한다. 마커가 여럿이면 마지막 것을 채택한다.
+    """
+    text = stdout or ""
+    markers = _QA_RESULT_RE.findall(text)
+    overall = markers[-1] if markers else "MISSING"
+    requirements: dict = {}
+    for rid, status, reason in _REQ_LINE_RE.findall(text):
+        requirements[rid] = {"status": status, "reason": reason.strip()}
+    return QaResult(overall=overall, requirements=requirements)
+
+
+@dataclass
+class ConformanceVerdict:
+    stage_key: str
+    status: str        # "PASS" | "BLOCKING" | "WAIVED" | "EXEMPT"
+    ok: bool           # 진행 허용 여부 (PASS/WAIVED/EXEMPT 면 True)
+    conditional: bool  # WAIVED 일 때만 True — conformance 미검증(사용자 확인)
+    message: str
+
+
+def decide_conformance_gate(entry: dict, result: object) -> ConformanceVerdict:
+    """단일 stage entry + 실행 결과(`QaResult | None`)로 게이트 판정.
+
+    우선순위: exemption → waiver → 결과 평가. 미실행/MISSING/FAIL 은 BLOCKING.
+    면제·waiver 의 형태 검증은 `validate_conformance_manifest` 가 이미 보장한다.
+    """
+    key = entry.get("stageKey", "<unknown>")
+    exemption = entry.get("exemption")
+    if exemption:
+        return ConformanceVerdict(
+            key, "EXEMPT", True, False,
+            f"conformance exempted: {exemption.get('reason', '')}",
+        )
+    waiver = entry.get("waiver")
+    if waiver:
+        return ConformanceVerdict(
+            key, "WAIVED", True, True,
+            f"conformance waived by {waiver.get('acknowledgedBy', '?')}: "
+            f"{waiver.get('reason', '')}",
+        )
+    overall = getattr(result, "overall", None)  # None when result is None → "never ran"
+    if overall == "PASS":
+        return ConformanceVerdict(key, "PASS", True, False, "conformance PASS")
+    if overall is None:
+        return ConformanceVerdict(
+            key, "BLOCKING", False, False,
+            "conformance script never ran (no result recorded)",
+        )
+    if overall == "MISSING":
+        return ConformanceVerdict(
+            key, "BLOCKING", False, False,
+            "conformance script ran but emitted no QA-RESULT marker",
+        )
+    return ConformanceVerdict(key, "BLOCKING", False, False, f"conformance {overall}")
+
+
+def qa_result_from_dict(data: object) -> QaResult:
+    """결과 사이드카(JSON dict)를 `QaResult` 로 복원. Phase 3 의 verifier 가 쓴
+    `result-stage-<N>.json` 을 validate-run 이 로드할 때 쓴다. 형태가 깨졌으면
+    overall='MISSING'(=BLOCKING 취급)으로 안전하게 강등한다."""
+    if not isinstance(data, dict):
+        return QaResult(overall="MISSING", requirements={})
+    overall = data.get("overall")
+    if overall not in ("PASS", "FAIL", "MISSING"):
+        overall = "MISSING"
+    reqs = data.get("requirements")
+    return QaResult(overall=overall, requirements=reqs if isinstance(reqs, dict) else {})
+
+
+def evaluate_conformance(manifest: object, results_by_stage: object) -> list[ConformanceVerdict]:
+    """매니페스트 전 entry 에 대해 게이트 판정 목록을 반환.
+
+    `results_by_stage`: stageKey -> `QaResult`. 키가 없으면 미실행(None)으로 본다.
+    매니페스트 구조 검증은 호출 전에 `validate_conformance_manifest` 로 끝낸다는 전제.
+    """
+    entries = manifest.get("entries") if isinstance(manifest, dict) else None
+    if not isinstance(entries, list):
+        return []
+    results = results_by_stage if isinstance(results_by_stage, dict) else {}
+    verdicts: list[ConformanceVerdict] = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            continue
+        result = results.get(entry.get("stageKey"))
+        verdicts.append(decide_conformance_gate(entry, result))
+    return verdicts
+
+
+# 경로 → capability surface 기본 매핑. 프로젝트별 override 는 qaEnv.surfacePatterns
+# (Phase 4e). 'external' 은 경로로 감지하기 어려워 기본 패턴 없음 — 명시 선언 의존.
+_DEFAULT_SURFACE_PATTERNS: dict[str, tuple[str, ...]] = {
+    "db": ("*.sql", "*migration*", "*repository*", "*.entity.*", "*entities*", "*schema.prisma*"),
+    "http": ("*controller*", "*.routes.*", "*router*", "*endpoint*", "*.api.*"),
+    "io": ("*filesystem*", "*storage*", "*.fs.*"),
+}
+
+
+def detect_surfaces(file_paths: object, patterns: object = None) -> set[str]:
+    """변경된 파일 경로들에서 capability surface 집합을 감지(소문자 fnmatch).
+    `patterns` 미지정 시 기본 매핑 사용."""
+    table = patterns if isinstance(patterns, dict) else _DEFAULT_SURFACE_PATTERNS
+    found: set[str] = set()
+    for raw in file_paths or []:
+        if not isinstance(raw, str):
+            continue
+        path = raw.strip().lower()
+        for surface, globs in table.items():
+            if any(fnmatch.fnmatch(path, g) for g in globs):
+                found.add(surface)
+    return found
+
+
+def parse_qa_waiver_arg(arg: object) -> tuple[str, str] | None:
+    """`--qa-waiver` 값 `<stageKey>:<reason>` 를 (stageKey, reason) 로 분해.
+    형식이 아니거나 비면 None."""
+    if not isinstance(arg, str) or ":" not in arg:
+        return None
+    key, reason = arg.split(":", 1)
+    key, reason = key.strip(), reason.strip()
+    if not key or not reason:
+        return None
+    return key, reason
+
+
+def apply_qa_waiver(manifest: object, stage_key: str, reason: str, *, at: str,
+                    acknowledged_by: str = "user") -> bool:
+    """매니페스트에서 stage_key entry 의 `waiver` 를 채운다(in place). 찾으면 True.
+    사용자 확인형 우회(spec §7.2) — reason 은 사용자 지시 원문."""
+    entries = manifest.get("entries") if isinstance(manifest, dict) else None
+    if not isinstance(entries, list):
+        return False
+    for entry in entries:
+        if isinstance(entry, dict) and entry.get("stageKey") == stage_key:
+            entry["waiver"] = {"acknowledgedBy": acknowledged_by, "reason": reason,
+                               "scope": [], "at": at}
+            return True
+    return False
+
+
+def manifest_required_surfaces(manifest: object) -> set[str]:
+    """매니페스트 전 entry 의 `requires` 합집합 — 선언된 surface 집합."""
+    entries = manifest.get("entries") if isinstance(manifest, dict) else None
+    if not isinstance(entries, list):
+        return set()
+    out: set[str] = set()
+    for entry in entries:
+        if isinstance(entry, dict) and isinstance(entry.get("requires"), list):
+            out.update(c for c in entry["requires"] if isinstance(c, str))
+    return out

package/runtime/python/okstra_ctl/paths.py

@@ -117,6 +117,7 @@ def compute_run_paths(
     task_index = task_root / "task-index.md"
     instruction_set = task_root / "instruction-set"
     analysis_packet = instruction_set / "analysis-packet.md"
+    task_qa = task_root / "qa"
     runs_dir = task_root / "runs"
     history_dir = task_root / "history"
     timeline_file = history_dir / "timeline.json"
@@ -202,6 +203,7 @@ def compute_run_paths(
         "TASK_INDEX_PATH": str(task_index),
         "INSTRUCTION_SET_PATH": str(instruction_set),
         "ANALYSIS_PACKET_PATH": str(analysis_packet),
+        "TASK_QA_PATH": str(task_qa),
         "RUNS_DIR": str(runs_dir),
         "HISTORY_DIR": str(history_dir),
         "TIMELINE_PATH": str(timeline_file),