okstra 0.225.0 → 0.226.0

package/runtime/prompts/lead/phase-routing.md

@@ -15,7 +15,7 @@ Allowed targets:
 - `implementation`
 - `done`
 
-`finalVerification.routingRecommendation` is an **object** with exactly two fields — `target`, one value from the Allowed targets list, and `rationale`, the sentence tying that choice to the verdict and the blocker list. Free routing prose is not the field; a target named only in the prose does not route the task, because Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone. `final-verification` re-runs this phase on the same head and is for exactly one situation: every remaining blocker is an environment or configuration fault whose cause this report already names — a `qaCommands` entry pointing at a path that no longer exists, a missing credential, a stale fixture — so nothing in the code, the plan, or the selected direction is being re-decided. Name the repair in the `rationale`. When any blocker needs a code, plan, or direction change, route to the phase that owns that change instead; routing a defect you have not diagnosed back into this phase re-runs the verification that already failed. Both `release-handoff` forms are allowed ONLY when the verdict is release-ready — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false`. Either verification scope may route there: release-handoff opens one PR per stage, so a release-ready `single-stage` run is the evidence for that stage's PR, and `release-handoff(stage-group)` is only a scope qualifier that projects onto the same phase. `done` ends the lifecycle here. Enforcement: `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object; `validators/validate-run.py` rejects a missing `target` and a verdict that is not release-ready routed to either `release-handoff` form (naming the condition ids that block it).
+`finalVerification.routingRecommendation` is an **object** with exactly two fields — `target`, one value from the Allowed targets list, and `rationale`, the sentence tying that choice to the verdict and the blocker list. Free routing prose is not the field; a target named only in the prose does not route the task, because Phase 7 projects `workflow.nextRecommendedPhase` from `target` alone. `final-verification` re-runs this phase on the same head and is for exactly one situation: every remaining blocker is an environment or configuration fault whose cause this report already names — a `qaCommands` entry pointing at a path that no longer exists, a missing credential, a stale fixture — so nothing in the code, the plan, or the selected direction is being re-decided. Name the repair in the `rationale`. When any blocker needs a code, plan, or direction change, route to the phase that owns that change instead; routing a defect you have not diagnosed back into this phase re-runs the verification that already failed. Both `release-handoff` forms are allowed ONLY when the verdict is release-ready — `accepted`, or `conditional-accept` with every condition declaring `blocksReleaseHandoff: false`. Either verification scope may route there: release-handoff opens one PR per stage, so a release-ready `single-stage` run is the evidence for that stage's PR, and `release-handoff(stage-group)` is only a scope qualifier that projects onto the same phase. `done` ends the lifecycle here. A report carrying a blocker whose `defectClass.recurrence` is `recurring` — an earlier final-verification run of the same target already blocked on that mechanism — routes to `error-analysis`, `implementation-option-selection`, or `implementation-planning` so the whole class is re-planned; `implementation` and `final-verification` are refused there. Enforcement: `schemas/final-report-v2.0.schema.json` rejects a `target` outside the enum, a missing `rationale`, and a string in place of the object; `validators/validate-run.py` rejects a missing `target` and a verdict that is not release-ready routed to either `release-handoff` form (naming the condition ids that block it); `phases/final_verification/validation.py` `_validate_recurring_class_routing` rejects the recurring-class case.
 
 ## release-handoff
 
@@ -35,11 +35,15 @@ Enforcement: `technicalVerification.routing.nextTaskType` and phase-continuation
 
 ## implementation-option-selection
 
-When no candidate is valid and explicit eligible technical facts remain, route to `technical-verification` to collect experimental evidence. Keep `rankedOptions` empty and `recommendedOptionId` null. `validate_blocked_answer_channel` rejects this route while user decisions remain unresolved or no safe, explicitly classified technical fact is available. Historical blocked reports can be supplied explicitly without rewriting their verdict.
+When no candidate is valid and explicit eligible technical facts remain, route to `technical-verification` to collect experimental evidence. A fact that only a deployed environment or another later gate can close is `deferred-gate`, not `technical-verification`: technical-verification may not deploy, so routing such a fact there returns the same fact. A `deferred-gate` fact that names its `gate` does not make the candidate invalid. Keep `rankedOptions` empty and `recommendedOptionId` null. `validate_blocked_answer_channel` rejects this route while user decisions remain unresolved or no safe, explicitly classified technical fact is available. Historical blocked reports can be supplied explicitly without rewriting their verdict.
 
 With valid options set routing to `pending-direction-selection`; without a valid option use `blocked`.
 
-In `candidate-comparison`, keep `preselectedDirection` null and do not route directly to `implementation-planning`. In `preselected-validation`, emit exactly one validated option, an empty `candidateAudit`, a cited `preselectedDirection`, and routing `implementation-planning`.
+A candidate that fails only on a split vote (at least one `feasible`, no safety blocker) does not route back to `technical-verification` or to another option-selection run on that ground: the same analysers return the same split. Open the approval decision the profile describes; the user's `accept-risk` answer, cited in the candidate's `splitAcceptance`, makes it valid and the run routes as a valid run.
+
+The run's mode is the one prepare recorded in the analysis packet's `## Direction Selection Mode` section (`--preselected-direction`); report that mode.
+
+In `candidate-comparison`, keep `preselectedDirection` null and do not route directly to `implementation-planning`. In `preselected-validation`, keep a cited `preselectedDirection` whose `optionId` names the one direction. When it validates, emit it as the only ranked option with an empty `candidateAudit` and routing `implementation-planning`. When it does not validate, leave `rankedOptions` empty, record it as the only `candidateAudit` row with its rejection reason, keep `recommendedOptionId` null, and route `technical-verification` or `blocked` by the rules above. Do not rewrite the record into `candidate-comparison`.
 
 ## requirements-discovery
 

package/runtime/prompts/lead/team-contract.md

@@ -176,7 +176,7 @@ After each worker attempt returns (regardless of role), Lead MUST verify the can
 - The result file exists but its audit sidecar does not, at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md`. Workers write both in the same step, so a result without a sidecar means the Reading Confirmation block — the only evidence the worker read its inputs — was never produced. `validate-run.py` fails the run on this at Phase 7 either way (`validate_worker_results_audit`); checking it here spends the existing one-retry budget while the role can still be re-dispatched, instead of surfacing hours later when the worker session is gone.
 - `okstra worker-audit-check --run-dir <runDirectoryPath from the active run context> --task-type <t> --seq <n> --worker <id>` exits 2 on a backticked `path:line` citation in the worker's result that has no matching Evidence read row in its audit sidecar. Run it the moment you collect each result. Phase 7 enforces the same rules from the same implementation (`okstra_ctl.worker_audit_ledger`), but by then the worker session is gone and the only remaining moves are editing the result yourself — which destroys the audit chain the ledger exists to provide — or ending the run `contract-violated`. While the session is alive, `SendMessage` to the worker so it corrects its own citation; that costs about a minute against a re-dispatch or a failed run.
 
-The same audit check parses command evidence from canonical rows such as `- Evidence command: {"command":"npm run check","cwd":"<project-root>","exitCode":0,"outputSummary":"all checks passed"}`. Workers record only commands that produced or verified a conclusion, not exploratory `rg`, `ls`, or file-opening commands. A malformed row is a contract failure returned by `okstra_ctl.worker_audit_ledger`; send the failure to the worker while its session is still available. Nothing scans these rows for secrets, so a row is never refused for how a setting is named — `AUTH_MODE=off` and `TOKEN_TTL=60` record verbatim. Do not tell a worker to drop or paraphrase a row on those grounds: a worker that cannot record the command it ran has no way to satisfy the evidence ledger that demands it.
+The same audit check parses command evidence from canonical rows such as `- Evidence command: {"command":"npm run check","cwd":"<directory the command ran in>","exitCode":0,"outputSummary":"all checks passed"}`. Workers record only commands that produced or verified a conclusion, not exploratory `rg`, `ls`, or file-opening commands. A malformed row is a contract failure returned by `okstra_ctl.worker_audit_ledger`; send the failure to the worker while its session is still available. Nothing scans these rows for secrets, so a row is never refused for how a setting is named — `AUTH_MODE=off` and `TOKEN_TTL=60` record verbatim. Do not tell a worker to drop or paraphrase a row on those grounds: a worker that cannot record the command it ran has no way to satisfy the evidence ledger that demands it.
 
 **One-retry policy:**
 

package/runtime/prompts/wizard/prompts.ko.json

@@ -526,6 +526,21 @@
       "label": "지난 run 의 확인 질문에 답한 파일 경로 (이어서 도는 run 에서만, 없으면 빈 줄)",
       "echo_template": "clarification: {value}"
     },
+    "selection_mode_pick": {
+      "label": "이번 방향 선택 run 의 모드를 고르세요. 설계 워커는 이 모드를 분석 패킷의 `## Direction Selection Mode` 절에서 읽습니다. 이미 정해진 방향 하나를 검증만 할 run 이면 preselected-validation 을 고르고 그 방향과 근거를 적으세요.",
+      "options": {
+        "candidate-comparison": "candidate-comparison — 후보를 최대 3개 제안하고 비교",
+        "preselected-validation": "preselected-validation — 정해진 방향 하나만 검증 (방향과 근거 직접 입력)"
+      },
+      "labels": {
+        "upstream": " 이어받는 리포트의 다음 단계 지시: {steps}"
+      },
+      "echo_template": "selection-mode: {value}"
+    },
+    "preselected_direction": {
+      "label": "검증할 방향과 그 방향을 정한 근거(명세 리비전, 브리프 절, 이전 리포트 등)를 한 문단으로 적으세요",
+      "echo_template": "preselected-direction: {value}"
+    },
     "pr_template": {
       "label": "PR 본문 템플릿 경로 1회성 override (빈 줄이면 project.json → ~/.okstra/config.json → 스킬 디폴트 순으로 자동 해석)",
       "echo_template": "pr-template: {value}"

package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py

@@ -113,6 +113,11 @@ class CodexExecution:
         elif spec is not None:
             argv += spec.cli_args
         argv += ["--sandbox", "danger-full-access"]
+        # The available-skills catalog advertises host skills (coding-preflight,
+        # graphify) that a worker's Read scope forbids, and codex workers read
+        # them as host instructions. `$CODEX_HOME/AGENTS.md` cannot be turned off
+        # per invocation, so the Read scope line still has to cover it.
+        argv += ["-c", "skills.include_instructions=false"]
         if request.policy.auto_approve:
             argv += ["-c", "approval_policy=never"]
         argv.append("-")

package/runtime/python/okstra_ctl/analysis_packet.py

@@ -1,6 +1,7 @@
 """Build the compact analysis-worker input packet for a task run."""
 from __future__ import annotations
 
+import hashlib
 import re
 from pathlib import Path
 
@@ -94,6 +95,10 @@ CLARIFICATION_SECTIONS = (
     "Clarification Response Carried In From Previous Run",
 )
 _FRONTMATTER_RE = re.compile(r"\A---\n(?P<body>.*?)\n---\n", re.DOTALL)
+BY_REFERENCE_FORMAT = "by-reference"
+MAX_CITED_DOCUMENT_BYTES = 200_000
+_FILE_SOURCE_RE = re.compile(r"\A### Source \d+\s+—\s+file\s*\Z")
+_SOURCE_FIELD_RE = re.compile(r"\A- (ref|format):\s*(.*?)\s*\Z")
 
 
 def build_analysis_packet(
@@ -118,6 +123,9 @@ def build_analysis_packet(
     mcp_servers_text: str = "",
     technical_evidence_text: str = "",
     verification_target_path: str = "",
+    selection_mode_text: str = "",
+    cited_documents_text: str = "",
+    prior_verification_text: str = "",
 ) -> str:
     """Return the primary compact input for Claude/Codex/Antigravity analysers.
 
@@ -141,8 +149,17 @@ def build_analysis_packet(
     `technical_evidence_text` 는 carry-in 이 technical-verification 결과일 때
     `technical_evidence_packet_block` 이 렌더한 증거 위치 절이다.
 
+    `selection_mode_text` 는 implementation-option-selection 의
+    `selection_mode_packet_block` 이 렌더한 선택 모드 절이다.
+
+    `cited_documents_text` 는 `cited_documents_block` 이 렌더한 인용 로컬 문서
+    절이다. 빈 문자열이면 브리프가 참조로 인용한 파일이 없다.
+
     `verification_target_path` 는 final-verification prepare 가 run 별로 기록한
     검증 대상 스냅샷 경로(매니페스트 `verificationTargetPath` 와 같은 값)다.
+
+    `prior_verification_text` 는 같은 검증 대상의 이전 final-verification run 이
+    남긴 차단 사유를 `prior_blockers_packet_block` 이 렌더한 절이다.
     """
     brief_text = task_brief_path.read_text(encoding="utf-8")
     group_context_text = _read_optional(group_context_path) if group_context_path else ""
@@ -163,9 +180,15 @@ def build_analysis_packet(
             has_selected_direction,
         )
     )
+    # The directive overrides the brief and the plan text below it, so it comes
+    # before them. As the last section of a 4,865-line packet (dev-11562), an
+    # executor stopped on a plan/brief conflict the directive had resolved.
+    parts.extend(_directive_block(directive))
     # 짧은 포인터 절이라 46KB 에서 잘리는 읽기에서도 도착하도록 브리프보다 앞에 둔다.
     if technical_evidence_text:
         parts.extend(["", technical_evidence_text])
+    if selection_mode_text:
+        parts.extend(["", selection_mode_text])
     # 그룹 문서는 사람 절과 okstra 메모리 영역으로 갈라 싣는다. 사람 절("왜")은
     # 브리프 발췌보다 앞 — 짧고, 46KB 에서 잘리는 읽기(agy view_file)에서도
     # 도착해야 한다. 형제 task 의 결론은 브리프 뒤 — 브리프를 밀어내면 안 된다.
@@ -174,6 +197,8 @@ def build_analysis_packet(
     )
     parts.extend(_group_context_block(group_human))
     parts.extend(_brief_block(brief_text))
+    if cited_documents_text:
+        parts.extend(["", cited_documents_text])
     if mcp_servers_text:
         parts.extend(["", "## Available MCP Servers", "", mcp_servers_text])
     if direct_work_text:
@@ -193,8 +218,9 @@ def build_analysis_packet(
     parts.extend(_stage_ledger_block(stage_ledger_json))
     parts.extend(_stage_ledger_unavailable_block(stage_ledger_notice))
     parts.extend(_prior_planning_block(prior_planning_summary))
+    if prior_verification_text:
+        parts.extend(["", prior_verification_text, ""])
     parts.extend(_clarification_block(clarification_text))
-    parts.extend(_directive_block(directive))
     body = "\n".join(part.rstrip() for part in parts).rstrip() + "\n"
     return _with_section_index(body)
 
@@ -290,7 +316,8 @@ def _with_section_index(body: str) -> str:
         f"This packet is {total} lines. Read a section by line range with"
         " `sed -n '<start>,<end>p'` rather than opening the whole file: a"
         " whole-file read is truncated by some worker CLIs without reporting"
-        " it, and the sections that describe current state are last.",
+        " it, and the sections that describe current state are last. Page a"
+        " range longer than 200 lines in 200-line reads.",
         "",
         *rows,
     ]
@@ -489,6 +516,85 @@ def _group_memory_block(
     return lines
 
 
+
+def cited_documents_block(brief_text: str, project_root: Path) -> str:
+    """브리프 Source Material 이 참조로 인용한 로컬 파일을 패킷 절로 싣는다.
+
+    `- format: by-reference` 인 `### Source N — file` 항목은 본문 대신 파일을
+    가리킨다. task worktree 는 체크아웃이라 프로젝트 루트의 untracked 파일
+    (`.project-docs/` 스펙)이 없고, 설계자들은 그 스펙이 이미 정한 점에
+    `uncertain` 을 던졌다(fontradar dev-11562). prepare 는 Source Material 이
+    인용한 경로만 프로젝트 루트에서 읽기 전용으로 읽고, 루트 밖 경로는 읽지
+    않는다(artifact-home 규칙).
+    """
+    root = project_root.resolve()
+    entries: list[str] = []
+    for ref in _by_reference_file_refs(_section_map(brief_text).get("Source Material", "")):
+        candidate = Path(ref).expanduser()
+        path = (candidate if candidate.is_absolute() else root / candidate).resolve()
+        try:
+            relative = path.relative_to(root).as_posix()
+        except ValueError:
+            entries.append(f"### `{ref}`\n\n- not read: outside the project root")
+            continue
+        if not path.is_file():
+            entries.append(f"### `{relative}`\n\n- not read: no such file under the project root")
+            continue
+        content = path.read_bytes()
+        if len(content) > MAX_CITED_DOCUMENT_BYTES:
+            entries.append(
+                f"### `{relative}`\n\n- not read: {len(content)} bytes exceeds "
+                f"{MAX_CITED_DOCUMENT_BYTES}; paste the cited part into Source Material"
+            )
+            continue
+        text = content.decode("utf-8", errors="replace").rstrip("\n")
+        longest = max((len(run) for run in re.findall(r"`+", text)), default=0)
+        fence = "`" * max(3, longest + 1)
+        entries.append(
+            f"### `{relative}`\n\n"
+            f"- sha256: {hashlib.sha256(content).hexdigest()}\n\n"
+            f"{fence}\n{text}\n{fence}"
+        )
+    if not entries:
+        return ""
+    return "\n\n".join([
+        "## Cited Local Documents",
+        "Read-only copies of the files the brief's Source Material cites by "
+        "reference, read from the project root when this run was prepared. The "
+        "task worktree may not contain them. Treat each as Source Material and "
+        "cite it as `<path>:<line>`, with the line numbers of the copy below.",
+        *entries,
+    ])
+
+
+def _by_reference_file_refs(source_material: str) -> list[str]:
+    refs = [ref for ref, fmt in file_source_entries(source_material) if fmt == BY_REFERENCE_FORMAT]
+    return list(dict.fromkeys(refs))
+
+
+def file_source_entries(source_material: str) -> list[tuple[str, str]]:
+    """Source Material 의 `### Source N — file` 항목마다 (ref, format) 을 돌려준다."""
+    entries: list[tuple[str, str]] = []
+    lines = source_material.splitlines()
+    blocks: list[list[str]] = []
+    for line, fenced in zip(lines, _fence_mask(lines)):
+        if fenced:
+            continue
+        if line.startswith("### "):
+            blocks.append([line])
+        elif blocks:
+            blocks[-1].append(line)
+    for block in blocks:
+        if not _FILE_SOURCE_RE.match(block[0]):
+            continue
+        fields = dict(
+            match.groups() for line in block[1:]
+            if (match := _SOURCE_FIELD_RE.match(line))
+        )
+        if fields.get("ref", "").strip():
+            entries.append((fields["ref"].strip(), fields.get("format", "").strip()))
+    return entries
+
 def _brief_block(brief_text: str) -> list[str]:
     return [
         "",

package/runtime/python/okstra_ctl/approved_plan_stage_extract.py

@@ -0,0 +1,206 @@
+"""Project an approved implementation-planning report onto one stage.
+
+An implementation executor owns exactly one stage, but its prompt pointed it at
+the whole plan record. Measured 2026-10-30 (fontradar-v2-api dev-11562 stage 1):
+that record was 7,465 lines / 385 KB, 94 KB of it the planning phase's own
+verification ledger, and a codex executor reported `contract-violated` because
+its reads overran the CLI's tool-output limit before it made an edit.
+
+The extract keeps everything the stage can act on and drops only what is named
+in `OMITTED`, each with the reason, so a reader can tell an omission from a gap.
+Rows of a row family keep the stage's rows plus every row that names no stage
+(`plan_items._stage_scope` reads that as "applies to every stage"), and every
+row carries the `P-*` id the plan-body verification and lead directives cite it
+by. The full record stays the source of record behind `sourcePlanPath`.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any, Mapping
+
+from .json_boundary import load_owned_object, write_owned_object_atomic
+from .plan_items import PLAN_ITEM_SOURCES
+
+EXTRACT_KIND = "approved-plan-stage-extract"
+EXTRACT_SCHEMA_VERSION = 1
+
+# implementationPlanning row families filtered to the stage. Every other
+# implementationPlanning key is carried whole unless OMITTED names it.
+_STAGE_ROW_FAMILIES = (
+    "requirementCoverage",
+    "validationChecklist",
+    "rollbackStrategy",
+    "dependencyMigrationRisk",
+    "crossProjectDependencies",
+)
+# plan_items numbers a row family by position (`P-Val-4` is the fourth
+# validation row); a filtered list loses the position, so the id travels on the row.
+_PLAN_ITEM_PREFIX = {
+    family: prefix for family, prefix, _ in PLAN_ITEM_SOURCES
+    if family in _STAGE_ROW_FAMILIES
+}
+# Top-level report keys an executor acts on. Everything else at the top level is
+# report presentation, audit, or accounting and is listed in OMITTED.
+_CARRIED_REPORT_KEYS = (
+    "clarificationItems",
+    "clarificationCarryIn",
+    "endStateCoverage",
+    "missingInformation",
+    "followUpTasks",
+)
+OMITTED = {
+    "implementationPlanning.planBodyVerification": (
+        "the planning phase's verification ledger (verdicts and dissent per plan "
+        "item); the plan body above is its settled result"
+    ),
+    "implementationPlanning.designPreparation": (
+        "the stage-scoped effective decision is inlined in the executor prompt "
+        "under Effective design preparation"
+    ),
+    "implementationPlanning.userNarrative": "plain-language explanation for the human reader",
+    "implementationPlanning.stages[other]": "stages this run does not own; their Stage Map rows stay",
+    "implementationPlanning.directionRealization.fileStructure[other]": (
+        "file rows whose path this stage's entry never names"
+    ),
+    "<rows of another stage>": (
+        "requirementCoverage / validationChecklist / rollbackStrategy / "
+        "dependencyMigrationRisk / crossProjectDependencies rows whose stageRefs "
+        "exclude this stage and whose id this stage's entry never cites"
+    ),
+    "humanSummary, verdictCard, rationale, summary, finalVerdict, recommendedNextSteps": (
+        "report presentation for the approver"
+    ),
+    "crossVerification, agentActivity, evidence, executionStatus, executionRoles, tokenUsage": (
+        "planning-run audit and accounting"
+    ),
+    "meta, frontmatter, header": "report identity",
+}
+
+
+class StageExtractError(ValueError):
+    """The approved plan cannot be projected onto the requested stage."""
+
+
+def stage_extract_payload(
+    report: Mapping[str, Any],
+    stage_number: int,
+    source_plan_path: str,
+) -> dict[str, Any]:
+    planning = report.get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        raise StageExtractError("approved plan has no implementationPlanning object")
+    stage_entry = _stage_entry(planning, stage_number)
+    cited_text = json.dumps(stage_entry, ensure_ascii=False)
+    carried_planning: dict[str, Any] = {}
+    for key, value in planning.items():
+        if f"implementationPlanning.{key}" in OMITTED:
+            continue
+        if key == "stages":
+            carried_planning[key] = [stage_entry]
+        elif key in _STAGE_ROW_FAMILIES:
+            carried_planning[key] = _stage_rows(value, key, stage_number, cited_text)
+        elif key == "directionRealization" and isinstance(value, Mapping):
+            carried_planning[key] = _direction_realization(value, cited_text)
+        else:
+            carried_planning[key] = value
+    payload: dict[str, Any] = {
+        "kind": EXTRACT_KIND,
+        "schemaVersion": EXTRACT_SCHEMA_VERSION,
+        "sourcePlanPath": source_plan_path,
+        "stage": stage_number,
+        "planItemIds": (
+            "Rows carry their plan item id as `planItemId`. `P-Step-<stage>.<step>` "
+            "names step <step> of that stage's `stepwiseExecution`."
+        ),
+        "omitted": dict(OMITTED),
+        "implementationPlanning": carried_planning,
+    }
+    for key in _CARRIED_REPORT_KEYS:
+        if key in report:
+            payload[key] = report[key]
+    return payload
+
+
+def materialize_stage_extract(
+    plan_path: Path,
+    stage_number: int,
+    output_path: Path,
+) -> bool:
+    """Write the extract for a `.data.json` plan; False when the plan is not one.
+
+    A Markdown plan predates the report record and has no structure to project,
+    and a missing file is reported by the prompt's own plan anchor, so neither
+    is an error here — the executor reads the plan as it did before.
+    """
+    if not plan_path.name.endswith(".data.json") or not plan_path.is_file():
+        return False
+    report = load_owned_object(plan_path, artifact="approved implementation plan")
+    payload = stage_extract_payload(report, stage_number, str(plan_path))
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    write_owned_object_atomic(output_path, payload, artifact="approved plan stage extract")
+    return True
+
+
+def _stage_entry(planning: Mapping[str, Any], stage_number: int) -> Mapping[str, Any]:
+    stages = planning.get("stages")
+    if not isinstance(stages, list):
+        raise StageExtractError("approved plan has no stages array")
+    for entry in stages:
+        if isinstance(entry, Mapping) and entry.get("stage") == stage_number:
+            return entry
+    raise StageExtractError(f"approved plan has no stage {stage_number}")
+
+
+def _stage_rows(
+    rows: Any,
+    family: str,
+    stage_number: int,
+    cited_text: str,
+) -> list[Any]:
+    if not isinstance(rows, list):
+        return rows
+    kept = []
+    for position, row in enumerate(rows, start=1):
+        if not isinstance(row, Mapping):
+            kept.append(row)
+            continue
+        if not _row_applies(row, stage_number, cited_text):
+            continue
+        prefix = _PLAN_ITEM_PREFIX.get(family)
+        kept.append(
+            {"planItemId": f"{prefix}-{position}", **row} if prefix else dict(row)
+        )
+    return kept
+
+
+def _row_applies(row: Mapping[str, Any], stage_number: int, cited_text: str) -> bool:
+    refs = row.get("stageRefs")
+    stages = (
+        [value for value in refs if isinstance(value, int) and not isinstance(value, bool)]
+        if isinstance(refs, list) else []
+    )
+    if not stages or stage_number in stages:
+        return True
+    row_id = row.get("id")
+    return isinstance(row_id, str) and bool(row_id) and _cites(cited_text, row_id)
+
+
+def _direction_realization(
+    realization: Mapping[str, Any], cited_text: str
+) -> dict[str, Any]:
+    carried = dict(realization)
+    rows = realization.get("fileStructure")
+    if isinstance(rows, list):
+        carried["fileStructure"] = [
+            row for row in rows
+            if not isinstance(row, Mapping)
+            or not isinstance(row.get("path"), str)
+            or row["path"] in cited_text
+        ]
+    return carried
+
+
+def _cites(text: str, identifier: str) -> bool:
+    return re.search(rf"(?<![\w-]){re.escape(identifier)}(?![\w-])", text) is not None

package/runtime/python/okstra_ctl/brief_sources.py

@@ -0,0 +1,200 @@
+"""브리프 본문이 인용한 로컬 문서와 Source Material 항목을 맞춘다.
+
+task worktree 는 체크아웃이라 프로젝트 루트의 git 미추적 파일(`.project-docs/` 스펙)이
+없다. prepare 는 Source Material 의 `### Source N — file` 항목만 읽어 패킷에 싣으므로
+(`analysis_packet.cited_documents_block`), 본문에만 이름이 나온 미추적 문서는 워커에게
+닿지 않는다(fontradar dev-11562). `uncited_local_documents` 는 그런 경로를 찾고,
+`validators/validate-brief.py` 가 이를 거절한다. `attach_missing_sources` 는 기존
+브리프에 빠진 항목을 `format: by-reference` 로 덧붙인다. 다른 줄은 바꾸지 않는다.
+"""
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+from .analysis_packet import BY_REFERENCE_FORMAT, _fence_mask, _section_map, file_source_entries
+
+SOURCE_MATERIAL = "Source Material"
+ATTACH_FETCHED_VIA = "okstra brief-sources attach"
+_HTML_COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+_FRONTMATTER_RE = re.compile(r"\A---\n.*?\n---\n", re.DOTALL)
+_TOKEN_RE = re.compile(r"[^\s`'\"()\[\]<>{},;|*]+")
+_LINE_SUFFIX_RE = re.compile(r"(?::\d+(?:-\d+)?|#L\d+(?:-L?\d+)?)\Z")
+_SOURCE_NUMBER_RE = re.compile(r"\A### Source (\d+)\b")
+# okstra 자신의 산출물(브리프, 그룹 맥락, 보고서)은 okstra 가 직접 운반한다.
+_OKSTRA_HOME = ".okstra"
+# 문서만 본다. 미추적 코드 경로(`node_modules/` 타입 선언 등)는 설치로 다시 생기는 근거라
+# 브리프의 출처 문서가 아니다.
+DOCUMENT_SUFFIXES = frozenset({".md", ".markdown", ".txt", ".rst", ".adoc"})
+
+
+def _body_lines(text: str) -> list[str]:
+    return _FRONTMATTER_RE.sub("", _HTML_COMMENT_RE.sub("", text), count=1).splitlines()
+
+
+def _project_file(token: str, root: Path) -> str | None:
+    """토큰이 프로젝트 루트 아래 파일을 가리키면 루트 기준 posix 경로를 돌려준다."""
+    if "/" not in token or "://" in token:
+        return None
+    token = _LINE_SUFFIX_RE.sub("", token.rstrip(".:"))
+    candidate = Path(token).expanduser()
+    path = (candidate if candidate.is_absolute() else root / candidate).resolve()
+    try:
+        relative = path.relative_to(root)
+    except ValueError:
+        return None
+    if (not relative.parts or relative.parts[0] == _OKSTRA_HOME
+            or path.suffix.lower() not in DOCUMENT_SUFFIXES or not path.is_file()):
+        return None
+    return relative.as_posix()
+
+
+def _cited_in_body(text: str, root: Path) -> list[str]:
+    paths: dict[str, None] = {}
+    lines = _body_lines(text)
+    section = ""
+    for line, fenced in zip(lines, _fence_mask(lines)):
+        if fenced:
+            continue
+        if line.startswith("## "):
+            section = line[3:].strip()
+            continue
+        if section == SOURCE_MATERIAL:
+            continue
+        for token in _TOKEN_RE.findall(line):
+            if (relative := _project_file(token, root)) is not None:
+                paths.setdefault(relative)
+    return list(paths)
+
+
+def _sourced(text: str, root: Path) -> set[str]:
+    source_material = _section_map(_HTML_COMMENT_RE.sub("", text)).get(SOURCE_MATERIAL, "")
+    return {
+        relative
+        for ref, _ in file_source_entries(source_material)
+        for token in _TOKEN_RE.findall(ref)
+        if (relative := _project_file(token, root)) is not None
+    }
+
+
+def _git_tracked(root: Path, paths: list[str]) -> set[str] | None:
+    """`paths` 중 git 이 추적하는 것. git 저장소가 아니면 None — worktree 가 없으니 검사할 것도 없다."""
+    proc = subprocess.run(
+        ["git", "-C", str(root), "ls-files", "-z", "--", *paths],
+        capture_output=True,
+        text=True,
+        check=False,
+    )
+    if proc.returncode != 0:
+        return None
+    return {name for name in proc.stdout.split("\0") if name}
+
+
+def uncited_local_documents(text: str, project_root: Path) -> list[str]:
+    """본문이 이름을 댄 git 미추적 프로젝트 파일 중 Source Material 의 file 항목이 없는 것."""
+    root = project_root.resolve()
+    cited = [path for path in _cited_in_body(text, root) if path not in _sourced(text, root)]
+    if not cited:
+        return []
+    tracked = _git_tracked(root, cited)
+    if tracked is None:
+        return []
+    return [path for path in cited if path not in tracked]
+
+
+def _source_entry(index: int, ref: str, fetched_at: str) -> list[str]:
+    return [
+        f"### Source {index} — file",
+        "",
+        f"- ref: {ref}",
+        f"- fetched-via: {ATTACH_FETCHED_VIA}",
+        f"- fetched-at: {fetched_at}",
+        f"- format: {BY_REFERENCE_FORMAT}",
+        "",
+        "```",
+        "```",
+        "",
+    ]
+
+
+def attach_missing_sources(brief_path: Path, project_root: Path, *, now: dt.datetime) -> list[str]:
+    """빠진 file 항목을 Source Material 끝에 덧붙이고 덧붙인 경로를 돌려준다."""
+    text = brief_path.read_text(encoding="utf-8")
+    missing = uncited_local_documents(text, project_root)
+    if not missing:
+        return []
+    lines = text.split("\n")
+    mask = _fence_mask(lines)
+    start = next(
+        (i for i, (line, fenced) in enumerate(zip(lines, mask))
+         if not fenced and line.strip() == f"## {SOURCE_MATERIAL}"),
+        None,
+    )
+    if start is None:
+        raise ValueError(f"{brief_path}: no `## {SOURCE_MATERIAL}` section to attach to")
+    end = next(
+        (i for i in range(start + 1, len(lines)) if not mask[i] and lines[i].startswith("## ")),
+        len(lines),
+    )
+    numbers = [int(m.group(1)) for i in range(start + 1, end) if not mask[i]
+               if (m := _SOURCE_NUMBER_RE.match(lines[i]))]
+    while end > start + 1 and not lines[end - 1].strip():
+        end -= 1
+    stamp = now.strftime("%Y-%m-%d %H:%M")
+    entries: list[str] = [""]
+    for offset, ref in enumerate(missing, max(numbers, default=0) + 1):
+        entries.extend(_source_entry(offset, ref, stamp))
+    tail = lines[end:]
+    while tail and not tail[0].strip():
+        tail.pop(0)
+    brief_path.write_text("\n".join([*lines[:end], *entries, *tail]), encoding="utf-8")
+    return missing
+
+
+def _attach_command(args: argparse.Namespace) -> int:
+    brief = Path(args.brief).resolve()
+    try:
+        added = attach_missing_sources(brief, Path(args.project_root), now=dt.datetime.now())
+    except ValueError as exc:
+        print(f"brief-sources: {exc}", file=sys.stderr)
+        return 2
+    if not added:
+        print(f"brief-sources: nothing to attach in {brief}")
+        return 0
+    print(f"brief-sources: attached {len(added)} Source Material entr{'y' if len(added) == 1 else 'ies'} to {brief}")
+    for path in added:
+        print(f"  - {path} (format: {BY_REFERENCE_FORMAT})")
+    print("Every later prepare copies these files read-only into the analysis packet's `## Cited Local Documents`.")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="okstra brief-sources",
+        description=(
+            "Give every untracked project file a brief's body cites its own "
+            "Source Material entry, so runs copy it into the analysis packet."
+        ),
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+    attach = sub.add_parser(
+        "attach",
+        help="append a by-reference `### Source N — file` entry for each cited untracked file; edits nothing else",
+    )
+    attach.add_argument("--project-root", required=True, help="project root that holds `.okstra/`")
+    attach.add_argument("--brief", required=True, help="brief markdown file to upgrade in place")
+    attach.set_defaults(func=_attach_command)
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())