okstra 0.129.1 → 0.130.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.129.1",
+  "version": "0.130.1",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.129.1",
-  "builtAt": "2026-07-21T04:57:17.399Z",
+  "package": "0.130.1",
+  "builtAt": "2026-07-21T10:57:23.020Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/agents/workers/antigravity-worker.md

@@ -207,6 +207,13 @@ and the run-level error log staying empty.
      --stderr-excerpt-file "<captured-stderr-path or omit>"
    ```
 
+   Keep `--message` to the error you actually observed (`HTTP 429`,
+   `connection refused`, `1045 access denied`) — asserting that a sandbox or
+   permission boundary blocked the call requires `--context-json` carrying
+   `cause` plus both `causeEvidence` probes, and an unevidenced block claim in
+   `--message` is rejected on the spot (and again on dump if you route it to
+   the sidecar instead).
+
    The lead prompt provides `**Errors log path:**`, `<task-key>`, and
    `<phase>` alongside the prompt history path. If any of these are
    missing, fall back to logging to the worker errors sidecar instead —

package/runtime/agents/workers/codex-worker.md

@@ -207,6 +207,13 @@ and the run-level error log staying empty.
      --stderr-excerpt-file "<captured-stderr-path or omit>"
    ```
 
+   Keep `--message` to the error you actually observed (`HTTP 429`,
+   `connection refused`, `1045 access denied`) — asserting that a sandbox or
+   permission boundary blocked the call requires `--context-json` carrying
+   `cause` plus both `causeEvidence` probes, and an unevidenced block claim in
+   `--message` is rejected on the spot (and again on dump if you route it to
+   the sidecar instead).
+
    The lead prompt provides `**Errors log path:**`, `<task-key>`, and
    `<phase>` alongside the prompt history path. If any of these are
    missing, fall back to logging to the worker errors sidecar instead —

package/runtime/agents/workers/report-writer-worker.md

@@ -102,6 +102,7 @@ Rules (the schema enforces most of these — they are listed here so you know *w
 - Cite file paths and line numbers in every `evidence.primary[].source` / `consensus[].evidence` cell.
 - Preserve every analysis worker's ticket tagging — every row's `ticketId` field carries the ticket key or the task-fallback. For single-ticket runs, set `ticketCoverage` to `{"singleTicket": "<ticket>"}`. For runs that do not require ticket tagging (`release-handoff`, `final-verification`), set `ticketCoverage` to `{"omit": true}`.
 - For `implementation-planning`, populate `implementationPlanning.requirementCoverage` with one row per concrete requirement from the brief / packet, using IDs `R-001`, `R-002`, ... in source order. `coveredBy` MUST name the specific Option Candidate plus Stage/Step that satisfies the requirement. Use `status: "covered"` only when the report's plan actually covers it; otherwise use `gap` or `blocked C-NNN` and ensure the corresponding `Clarification Items` row blocks approval. Do not collapse this into `ticketCoverage`; ticket coverage is not requirement coverage.
+- For `implementation-planning`, each `requirementCoverage` row's `source` is a graded cell, not prose — free text like `"carry-in from requirements-discovery C-001"` is rejected. Write exactly one of: `brief:<heading>`, where the heading literally exists in the task brief; `derived:R-NNN — <one-line reason>`, whose chain must terminate at a `brief:` or `contract:` row of the same table without cycling; or `contract:<rule>`, for artifacts okstra's own phase contract mandates, whose allowlist is exactly the two tokens `decision-record-step` (the §5.4 Decision Drafts materialization step) and `glossary-step` (the glossary proposal step) — any other rule name is rejected, so never invent one. (Maintainer SSOT for that allowlist: `scripts/okstra_ctl/scope_provenance.py` in the okstra repo.) A requirement you cannot source this way does not belong in the table: put it in `clarificationItems[]` with `Blocks=approval`. **Enforced:** `validators/validate-run.py` `_validate_requirement_provenance`. In the same table, anchor every stage number in `coveredBy` to a `Stage` / `Stages` word (`Stage 2`, `Stages 1-3`) — `_validate_stage_has_requirement` reads that cell as prose and fails the plan when a Stage Map stage is cited by no row.
 - For `implementation-planning`, also populate `implementationPlanning.decisionDrafts` (one row per decision meeting all three decision-record criteria; `[]` otherwise) and `implementationPlanning.skippedAdrCandidates` (evaluated-but-dropped adr-candidates; `[]` otherwise). The schema excerpt enumerates the row shape; the renderer emits §5.4 `### Decision Drafts`. When `decisionDrafts` is non-empty, the plan's stages MUST carry a stepwise step that creates `.okstra/decisions/<NNNN>-<slug>.md` (validate-run gates this).
 - When the `Task Type` is `improvement-discovery`, populate `## 5.9 Improvement Candidates` with the 10-column schema enforced by `validators/validate_improvement_report.py`. Source the row IDs (`I-NNN`), lens whitelist, and Source workers patterns from `scripts/okstra_ctl/improvement_lenses.py` — do NOT introduce new lens names or worker prefixes. `improvement-discovery` is NOT in the data.json schema enum, so author its markdown directly (not via `okstra-render-final-report.py`). Immediately after writing the markdown, run (`Bash`): `okstra inject-report-index <markdown path> --report-language <en|ko>`. That adds the top-of-report Index plus `I-NNN` / `C-NNN` scroll anchors; the run validator fails the report when the Index anchor is absent.
 

package/runtime/bin/okstra-error-log.py

@@ -23,6 +23,26 @@ ALLOWED_AGENTS = {
 ALLOWED_AGENT_ROLES = {"lead", "worker", "report-writer"}
 SUPPORTED_SIDECAR_SCHEMA_VERSIONS = {1}
 
+ALLOWED_CAUSES = {
+    "sandbox-denied", "service-unavailable", "auth-failed", "unknown",
+}
+# A `sandbox-denied` claim is only admissible with both probes attached.
+CAUSE_EVIDENCE_FIELDS = ("targetProbe", "controlProbe")
+# Both probes share a record's PIPE_BUF_BYTES budget with stderrExcerpt, so
+# they cannot reuse the 2048 cap that assumes stderrExcerpt owns it alone.
+CAUSE_PROBE_MAX_BYTES = 256
+# Backstop vocabulary: scanned in `message` only — never in stderrExcerpt,
+# where a kernel's real "Operation not permitted" is legitimate content.
+# Deliberately excludes bare "blocked"/"blocks": everyday English that would
+# reject honest records like "test blocked on upstream dependency".
+_BLOCKING_CLAIM_TERMS = (
+    "sandbox", "not permitted", "permission denied", "eperm",
+)
+# The backstop targets *unclassified* blocking claims. A worker that declared
+# a specific cause has already done the honest work — `auth-failed` legitimately
+# reads "permission denied" (MySQL 1045).
+_UNCLASSIFIED_CAUSES = (None, "unknown")
+
 
 def _now_utc():
     return dt.datetime.now(dt.timezone.utc)
@@ -32,24 +52,80 @@ def _iso(t):
     return t.isoformat()
 
 
-def truncate_stderr(s):
-    """Truncate stderr text to STDERR_EXCERPT_MAX_BYTES, multibyte-safe."""
+def _truncate_utf8(s, limit):
+    """Truncate to `limit` bytes without splitting a multibyte character."""
     if s is None:
         return None
     encoded = s.encode("utf-8")
-    if len(encoded) <= STDERR_EXCERPT_MAX_BYTES:
+    if len(encoded) <= limit:
         return s
-    cut = encoded[:STDERR_EXCERPT_MAX_BYTES]
-    # 멀티바이트 경계 보호: 디코드 가능해질 때까지 끝 바이트 제거
+    cut = encoded[:limit]
     while cut:
         try:
-            decoded = cut.decode("utf-8")
-            return decoded + TRUNCATION_SUFFIX
+            return cut.decode("utf-8") + TRUNCATION_SUFFIX
         except UnicodeDecodeError:
             cut = cut[:-1]
     return TRUNCATION_SUFFIX
 
 
+def truncate_stderr(s):
+    """Truncate stderr text to STDERR_EXCERPT_MAX_BYTES, multibyte-safe."""
+    return _truncate_utf8(s, STDERR_EXCERPT_MAX_BYTES)
+
+
+def normalize_cause_context(context, *, message):
+    """Validate a record's cause claim and return the normalized context.
+
+    Raises ValueError on three conditions:
+    - `cause` is set to a value outside ALLOWED_CAUSES;
+    - `cause` is 'sandbox-denied' but the two probes are missing or blank —
+      those probes are what distinguish a real denial from an unreachable
+      or auth-gated target, the misdiagnosis this gate exists to stop;
+    - `message` asserts a block in prose while the record left its cause
+      unclassified, which would smuggle the same claim past the gate.
+    """
+    cause = context.get("cause") if isinstance(context, dict) else None
+
+    if cause is not None and cause not in ALLOWED_CAUSES:
+        raise ValueError(
+            f"invalid cause: {cause!r} (allowed: {sorted(ALLOWED_CAUSES)})"
+        )
+
+    if cause == "sandbox-denied":
+        evidence = context.get("causeEvidence")
+        if not isinstance(evidence, dict):
+            raise ValueError(
+                "cause 'sandbox-denied' requires context.causeEvidence with "
+                f"{list(CAUSE_EVIDENCE_FIELDS)}"
+            )
+        normalized_evidence = {}
+        for field in CAUSE_EVIDENCE_FIELDS:
+            value = evidence.get(field)
+            if not isinstance(value, str) or not value.strip():
+                raise ValueError(
+                    f"cause 'sandbox-denied' requires a non-empty "
+                    f"context.causeEvidence.{field}: record the command and "
+                    f"its raw output that proves the claim"
+                )
+            normalized_evidence[field] = _truncate_utf8(
+                value, CAUSE_PROBE_MAX_BYTES
+            )
+        return {**context, "causeEvidence": normalized_evidence}
+
+    if message and cause in _UNCLASSIFIED_CAUSES:
+        lowered = message.lower()
+        hit = next((t for t in _BLOCKING_CLAIM_TERMS if t in lowered), None)
+        if hit:
+            raise ValueError(
+                f"message asserts a blocking claim ({hit!r}) without "
+                "context.cause='sandbox-denied' + context.causeEvidence. "
+                "Either attach the two probes, or state the cause you "
+                "actually verified."
+            )
+
+    return context
+
+
 def append_jsonl_line(path, record):
     """Append a single JSON record as one line to ``path``.
 
@@ -119,6 +195,9 @@ def append_observed(
         raise ValueError(f"invalid agent: {agent!r}")
     if agent_role not in ALLOWED_AGENT_ROLES:
         raise ValueError(f"invalid agentRole: {agent_role!r}")
+    # Runs before append_jsonl_line so a rejected claim leaves no trace in the
+    # log: a written-then-flagged record is still a record someone can cite.
+    context = normalize_cause_context(context, message=message)
     ts = _iso(now or _now_utc())
     rec = {
         "ts": ts,
@@ -159,6 +238,7 @@ def dump_from_worker_sidecar(
       - ``agent`` or ``agent_role`` is not in the allow-lists
       - sidecar ``schemaVersion`` is not in ``SUPPORTED_SIDECAR_SCHEMA_VERSIONS``
       - any entry's ``errorType`` is not in ``ALLOWED_ERROR_TYPES``
+      - any entry asserts a blocking cause without its required evidence
 
     Returns 0 (no-op) if the sidecar file does not exist or its
     ``errors`` list is empty.
@@ -187,6 +267,9 @@ def dump_from_worker_sidecar(
         et = e.get("errorType")
         if et not in ALLOWED_ERROR_TYPES:
             raise ValueError(f"invalid errorType in sidecar: {et!r}")
+        entry_context = normalize_cause_context(
+            e.get("context"), message=e.get("message")
+        )
         rec = {
             "ts": e.get("ts"),
             "recordedAt": recorded_at,
@@ -203,7 +286,7 @@ def dump_from_worker_sidecar(
             "durationMs": e.get("durationMs"),
             "message": e.get("message"),
             "stderrExcerpt": truncate_stderr(e.get("stderrExcerpt")),
-            "context": e.get("context"),
+            "context": entry_context,
         }
         append_jsonl_line(out_path, rec)
         count += 1

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

@@ -271,6 +271,8 @@ okstra error-log append-observed \
   --stderr-excerpt "<last stderr lines, or use --stderr-excerpt-file>"
 ```
 
+Keep `--message` to the error actually observed — asserting that a sandbox or permission boundary blocked the call requires `--context-json` carrying `cause` plus both `causeEvidence` probes, and an unevidenced block claim in `--message` is rejected. If an `append-from-worker` dump is rejected for that reason, correct the offending sidecar entry and re-run the dump instead of skipping it: the dump aborts at the rejected entry, so every later entry in that sidecar never reaches the run log.
+
 The wrapper subagent records this through its selected adapter — Lead does NOT need to re-record. Token usage is not inferred from dispatch return values; call `collect_usage` at the start of Phase 7.
 
 ## Phase 5.5: Convergence loop

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

@@ -120,7 +120,15 @@
   - validation checklist (pre / mid / post) — each item is an exact command or observable outcome
   - rollback strategy — exact revert path (commits, flags, migrations) and the signal that triggers rollback
   - **Requirement admissibility (scope boundary):** a brief line becomes a Requirement Coverage row only when **a stage can satisfy it by changing files in this repository** — source, tests, config, or deployment *manifest files*. A line whose satisfaction needs a person's approval, a ticket status change, or an action against live infrastructure (applying a manifest, a cutover, creating a dashboard or alert, validating in staging/production) is NOT a requirement for this phase: it belongs to the brief's `## External Gates`, and this plan neither creates a stage for it nor cites it in coverage. Briefs generated by `okstra-brief-gen` pre-split these into `## Acceptance Criteria` (admissible) and `## External Gates` (not); when reading an older brief that carries a raw Definition-of-Done checklist, apply the same test line by line. The boundary is the *action*, not the topic — "add the flag to `values-prod.yaml`" is admissible, "apply that manifest to prod" is not. Planning an operational stage this phase cannot execute (see the run-scope rule above forbidding deployments) produces steps whose commands never resolve, which the §5.5.9 gate then correctly blocks — the plan must not create that deadlock in the first place.
-  - **Requirement Coverage (mandatory, §5.5.8):** one row per concrete requirement from the task brief / packet. Assign stable IDs `R-001`, `R-002`, ... in source order. Columns: `ID | Source | Requirement | Covered by option / stage / step | Status`. `Source` cites the brief heading or file/line where the requirement came from. `Covered by` must name the specific Option Candidate and Stage/Step that satisfies it, not just "recommended option". **Enforced:** `validators/validate-run.py` `_validate_requirement_coverage_covered_by` fails a `covered` row whose `coveredBy` is bare "recommended option", names no Option/Stage/Step anchor, or cites a Stage number absent from the Stage Map (whether the cited step *actually satisfies* the requirement remains a worker `DISAGREE(f)` judgment). `Status` is one of `covered`, `gap`, or `blocked C-NNN`. If any row is `gap` or `blocked C-NNN`, the Plan Body Verification gate MUST NOT be `passed` / `passed-with-dissent`; add a matching `Blocks=approval` row for the blocker and keep `approved: false`.
+  - **Scope provenance (BLOCKING):** every Requirement Coverage row's `Source` cell must be exactly one of three forms, and every Stage Map stage must be cited by at least one coverage row's `Covered by`. The forms:
+    - `brief:<heading>` — a heading that literally exists in the task brief. A heading the brief does not contain is a fabricated requirement.
+    - `derived:R-NNN — <one-line rationale>` — derived from another row in the same table. The chain must terminate at a `brief:` or `contract:` row and must not cycle. Use this for genuine technical consequences: a migration stage is `derived:R-003 — R-003 cannot be satisfied without a schema change`.
+    - `contract:<rule>` — an artifact okstra's own phase contract mandates, so it has no brief line to cite. The allowlist is exactly `decision-record-step` (the §5.4 Decision Drafts materialization step) and `glossary-step` (the glossary proposal step); the SSOT is `scripts/okstra_ctl/scope_provenance.py`. Never widen this form to launder work the brief did not ask for.
+    An item you can give none of these three sources to is **not a requirement and not a stage**. Its only admissible outlet is a `## 1. Clarification Items` row with `Blocks=approval`, carrying the recommendation format from `_clarification-recommendation.md`. Do not fold it into an option, a stage, or a step "while we are in here" — that is the scope expansion this rule exists to stop. This makes concrete the planning-input rule that any change beyond what `Requirement Summary` explicitly demands is out of scope by default. **Enforced:** `validators/validate-run.py` `_validate_requirement_provenance` (source resolution) and `_validate_stage_has_requirement` (no stage without a requirement).
+    - **The reach of this gate — do not over-trust it.** What is mechanically enforced is the *form* of each source, that a `brief:` heading literally exists, that a `derived:` chain terminates without cycling, and that no stage is uncited. What is **not** enforced is whether the cited source genuinely demands the requirement. Every brief carries the same generic headings (`## Acceptance Criteria`, `## Context`, …), so attaching invented work to a real heading still parses clean. The gate's value is that it forces every item to name an origin and makes fabrication explicit and auditable — judging whether that origin actually demands the item remains a reviewer / `DISAGREE(f)` responsibility, and passing this gate is never evidence that the scope is justified.
+    - **Stage citation format:** the reverse check reads each `Covered by` cell as prose, so a stage counts as cited only when its number is anchored to a `Stage` / `Stages` word on the same line. These all read: `Stage 2`; `Stage 1, Stage 2, Stage 3`; `Stages 1, 2, 3`; `Stages 1, 2, and 3`; ranges (`Stages 1-3`, `Stages 1 to 3`, `Stages 1 through 3`); and `and` / `&` conjunctions. A bare number with no `stage` word anchoring it is NOT read as a citation, so `covered by the recommended option, step 4` cites nothing. **Enforced:** `validators/validate-run.py` `_validate_stage_has_requirement` fails the plan when any Stage Map stage is cited by no coverage row.
+    - Because that reader only sees prose, it cannot tell a citation from a mention: `Stage 1 (superseded by Stage 2)` still counts Stage 1 as cited, and one row citing `Stages 1-64` rubber-stamps every stage in the map. Cite the stages a requirement is actually satisfied by — not stages merely mentioned, and never a blanket range standing in for the work of checking.
+  - **Requirement Coverage (mandatory, §5.5.8):** one row per concrete requirement from the task brief / packet. Assign stable IDs `R-001`, `R-002`, ... in source order. Columns: `ID | Source | Requirement | Covered by option / stage / step | Status`. `Source` follows the three-form grammar defined in the **Scope provenance** rule above — a free-form `file:line` is not one of the three forms and is rejected. When this run's brief is a fan-out packet, the task manifest's `taskBriefPath` points at that packet file, so `brief:` cites the packet's own headings (`## Scope`, `## Evidence`, `## Requirement Provenance`) — not the headings of the upstream user brief the packet came from. `Covered by` must name the specific Option Candidate and Stage/Step that satisfies it, not just "recommended option". **Enforced:** `validators/validate-run.py` `_validate_requirement_coverage_covered_by` fails a `covered` row whose `coveredBy` is bare "recommended option", names no Option/Stage/Step anchor, or cites a Stage number absent from the Stage Map (whether the cited step *actually satisfies* the requirement remains a worker `DISAGREE(f)` judgment). `Status` is one of `covered`, `gap`, or `blocked C-NNN`. If any row is `gap` or `blocked C-NNN`, the Plan Body Verification gate MUST NOT be `passed` / `passed-with-dissent`; add a matching `Blocks=approval` row for the blocker and keep `approved: false`.
   - **Review-rule compliance plan:** when a project-local review rule pack is found, each Option Candidate MUST include the design implication of those rules in its File Structure / interfaces / blast-radius notes. For any helper or data transform used by more than one changed service, the plan must either place it in a shared module or explicitly justify why duplication is intentional. For any test step, the plan must state the observable behavior being asserted, not the internal collaborator call being pinned. For any exported/public method added or renamed, the step must carry the intended noun/side-effect semantics so implementation names can be reviewed before code is written.
   - the YAML frontmatter MUST include the line `approved: false` (report-writer always emits the unflipped value). The user authorises the next `implementation` run by flipping it to `approved: true` (manual edit or `--approve` CLI). Do NOT recreate any `User Approval Request` body block — the validator fails reports that contain one (see `validators/validate-run.py` deprecated patterns).
   - the YAML frontmatter MUST include the line `implementation-option:` directly under `approved:` (report-writer always emits it with an **empty value**). The user selects which Option Candidate the next `implementation` run executes by filling this line with that option's name (manual edit or `--implementation-option <name>` CLI). When left empty, the `implementation` run falls back to the `Recommended Option`.
@@ -144,7 +152,7 @@
   2. **Placeholder scan** — search the report for the patterns in the No-placeholder rule above and fix inline.
   3. **Internal consistency** — option file lists, trade-off matrix, and recommended step list must agree on file paths, names, and signatures. A symbol called `clearLayers()` in the matrix and `clearFullLayers()` in the steps is a bug.
   4. **Ambiguity check** — any requirement that could be read two ways must be made explicit or moved to the `## 1. Clarification Items` table as a `Blocks=approval` row.
-  5. **Scope check** — if the recommended plan now spans multiple independent subsystems, recommend splitting into separate planning runs rather than shipping an oversized plan.
+  5. **Scope check** — if the recommended plan now spans multiple independent subsystems, recommend splitting into separate planning runs rather than shipping an oversized plan. Then walk the plan in the expansion direction: for every stage, name the Requirement Coverage row that demanded it, and for every requirement row, read its `Source` cell as a skeptic — does the cited brief heading actually exist, and does a `derived:` rationale state a real technical consequence rather than a preference? Move anything that fails to a `Blocks=approval` clarification row.
   6. **Review-rule preflight check** — if a project review rule pack exists, map each relevant rule to the recommended option. Reject the draft if it knowingly creates a violation that the later PR reviewer would flag, unless the plan records a specific rationale and follow-up. In particular, scan for repeated helper stacks across planned files, tests that assert delegation to the same calculator/helper they exercise, public names that hide side effects, domain rules placed in repositories/adapters, and APIs made dead by this change.
   7. **Plan-body verification reconciliation (BLOCKING for implementation-planning).** For every §5.5.9 `planItems[]` entry whose verdicts make it `majority-disagree`, set that item's `clarificationId` to a `C-<N>` row that MUST exist in `## 1. Clarification Items` with `Kind` chosen per the standard policy and `Blocks=approval`. **Enforced:** `validators/validate-run.py` `_validate_plan_body_clarification_matching` recomputes each item's class and fails when a majority-disagree item has no `clarificationId`, or its `clarificationId` is dangling / points at a non-`approval` row. For `partial-consensus` and `dissent-isolated` plan-items, the dissenting opinion lives in §5.5.9 `Dissent log` and is NOT promoted to §5.
   8. **Stage Map self-check** — for every stage, count the effective rows of its `Stepwise Execution Order` table by hand; reject the draft if any stage exceeds 8. Confirm each stage declares a non-empty `Slice value:` and `Acceptance:` line, the three `Test case (success|boundary|failure):` lines (or carries a `TDD exemption:` line), and that its first step `action` starts with `RED:` with a later `GREEN:` — this is what validator S10 enforces, including S10d on the test-case lines. Read each stage's three test-case lines as a reviewer: reject any that restates the happy path in all three slots, leaves `boundary` blank, or writes `N/A` where a real edge input exists. Walk the `depends-on` graph and confirm it is a DAG (no cycle, no self-reference). For each `depends-on` link, confirm it encodes a real data/contract dependency — do NOT add links to serialise unrelated work, and do NOT split a stage merely to create more parallel stages. **Parallel-safety:** for every pair of `depends-on (none)` stages, confirm their `Stage Exit Contract` predicted file sets are disjoint; if they share a file, merge them or add a `depends-on` link (validator S9 rejects overlap). **Project-boundary:** confirm no stage mixes edits from two projects (different repo/`PROJECT_ROOT` or different top-level deployable module); if any stage does, split it per project. For multi-project plans, confirm each stage's `title` carries its `[<project>]` tag and the `Cross-project parallelism:` line under the table records the parallel-vs-sequenced determination (with the forcing dependency) for every project pair; for cross-repo work, confirm it is split into separate per-repo runs (required — one run structurally cannot touch another repo) rather than crammed into one task's stages.

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

@@ -35,6 +35,7 @@
     `domain`(work-category 5-enum: bugfix / feature / refactor / ops / improvement),
     `depends-on`(an inline list of unit-ids within the same fan-out `[unit-001]`, or `[]` if none),
     `recommended-next-phase`(error-analysis | implementation-planning) are filled in.
+    Each packet MUST carry a non-empty `## Requirement Provenance` section whose every bullet is `brief:<heading>` (a heading that literally exists in the task brief) or `contract:<rule>`. `derived:` is not admissible in a packet — cross-packet derivation cannot be resolved from a single packet, so each unit anchors directly on the brief. A unit you cannot source that way is not a work item: raise it as a clarification row instead of publishing a packet for it. **Enforced:** `validators/validate_fanout.py` `_check_provenance`.
   - in `runs/requirements-discovery/fan-out/index.md`, list the packets in depends-on topological order
     as a numbered list (`1. unit-001`) (a generated view; explicitly do not hand-edit). The depends-on graph
     must be a DAG — `validate_fanout` rejects a cycle as a validation failure, so if a cycle appears,
@@ -61,7 +62,7 @@
   - if any blocking input is missing at the time of writing the final report, populate `## 1. Clarification Items` in `final-report-template.md` (a single unified table; `Blocks=next-phase` for items the next run cannot start without)
   - prefer concrete questions whose answers map directly to a routing decision (`bugfix` vs `feature`, `error-analysis` vs `implementation-planning`, etc.). State each option in plain language with one sentence describing what choosing it would mean for the next phase.
 {{INCLUDE:_clarification-recommendation.md}}
-  - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity that can be answered by `Read` / `Grep` / file inspection MUST be resolved that way and recorded with file:line evidence. Writing a clarification row for something the codebase already answers is a defect of this phase.
+  - **Codebase-first ambiguity resolution (defect rule)**: any ambiguity that can be answered by `Read` / `Grep` / file inspection MUST be resolved that way and recorded with file:line evidence. Writing a clarification row for something the codebase already answers is a defect of this phase. **Boundary — facts only, never intent:** this rule governs questions of *fact* ("what does this code do", "where is this called", "does this field exist"). It never governs questions of *intent* ("should we do this at all", "is this in scope", "which outcome does the reporter want"). Scope and intent are not the kind of question a codebase can answer, so inspecting files never discharges them — raise them as clarification rows. Resolving a scope question by inference and building on that inference is the mirror defect, and a more expensive one.
   - **Evidence note required inside `Statement`**: every clarification row includes `Evidence checked: <path:line>` or `Evidence checked: none — <human-only reason>` in the `Statement` cell. `none` is allowed ONLY when the row's nature is "only a human can answer this" (reporter intent, business priority, external authority). A row with `none` that *could* have been answered by the codebase is a defect.
 - Cross-verification mode:
   - Phase 5.5 convergence runs in **adversarial mode** for this phase (`convergence.adversarial=true`). Verifiers actively try to refute each worker's finding by directly re-inspecting the cited evidence; the burden of proof sits on the claim. See `prompts/lead/convergence.md` §"Adversarial Verification Mode". A single evidence-backed refutation prevents a finding from reaching consensus.

package/runtime/python/okstra_ctl/md_table.py

@@ -2,10 +2,12 @@
 producer/consumer of final-report (and schedule) tables.
 
 GFM treats every unescaped ``|`` inside a cell as a column boundary — even
-inside inline-code spans — and renders ``\\|`` back as a literal ``|``.
-Producers therefore escape cell text with ``escape_pipes`` (exposed as the
-``mdcell`` Jinja filter in ``render_final_report``), and consumers split rows
-with ``split_pipe_row``, which honours the same ``\\|`` convention.
+inside inline-code spans — and renders ``\\|`` back as a literal ``|``. A row
+is also line-terminated, so a newline inside a value truncates the row at that
+point and drops every column after it. Producers therefore normalise cell text
+with ``to_cell_text`` (exposed as the ``mdcell`` Jinja filter in
+``render_final_report``), and consumers split rows with ``split_pipe_row``,
+which honours the same ``\\|`` convention.
 """
 from __future__ import annotations
 
@@ -17,17 +19,24 @@ UNESCAPED_PIPE_RE = re.compile(r"(?<!\\)\|")
 
 _SEPARATOR_CELL_RE = re.compile(r"\s*:?-+:?\s*")
 
+_NEWLINE_RE = re.compile(r"\r\n|\r|\n")
 
-def escape_pipes(value: Any) -> str:
-    """Escape literal ``|`` as ``\\|`` for use inside a markdown table cell.
 
-    Idempotent: pipes that are already escaped are left alone, so re-rendering
-    (Phase 7) never stacks backslashes. ``None`` renders as the empty string —
-    the same contract as the template's ``or ''`` fallbacks.
+def to_cell_text(value: Any) -> str:
+    """Render a value as one markdown table cell: no newlines, no bare ``|``.
+
+    Newlines fold to ``<br>`` (a blank line becomes ``<br><br>``, keeping the
+    paragraph break visible) and literal ``|`` is escaped as ``\\|``.
+
+    Idempotent: pipes that are already escaped are left alone and the folded
+    ``<br>`` carries no newline, so re-rendering (Phase 7) never stacks
+    backslashes or breaks. ``None`` renders as the empty string — the same
+    contract as the template's ``or ''`` fallbacks.
     """
     if value is None:
         return ""
-    return UNESCAPED_PIPE_RE.sub(r"\\|", str(value))
+    folded = _NEWLINE_RE.sub("<br>", str(value).strip())
+    return UNESCAPED_PIPE_RE.sub(r"\\|", folded)
 
 
 def split_pipe_row(line: str) -> list[str]:

package/runtime/python/okstra_ctl/render_final_report.py

@@ -50,7 +50,7 @@ from jinja2 import ChainableUndefined, Environment, FileSystemLoader
 
 from okstra_ctl.final_report_schema import SchemaError, load_schema, validate as schema_validate
 from okstra_ctl.i18n import I18nError, SUPPORTED_LANGS, load_dictionary, make_jinja_global
-from okstra_ctl.md_table import UNESCAPED_PIPE_RE, escape_pipes
+from okstra_ctl.md_table import UNESCAPED_PIPE_RE, to_cell_text
 from okstra_ctl.models import UnknownModelError, resolve_model_metadata
 from okstra_ctl.schema_excerpt import excerpt_cut_from_version
 from okstra_ctl.seeding import installed_version
@@ -437,10 +437,12 @@ def _build_environment(template_dir: Path) -> Environment:
     env.filters["yaml_scalar"] = _yaml_scalar
     env.filters["yaml_inline_list"] = _yaml_inline_list
     env.filters["model_detail"] = _model_detail
-    # `mdcell` escapes literal `|` in worker prose so a value like "PASS|FAIL"
-    # cannot split a markdown table row. Table-cell interpolations only —
-    # never code blocks / headings / prose, where `\|` would render verbatim.
-    env.filters["mdcell"] = escape_pipes
+    # `mdcell` neutralises the two things in worker prose that can break a
+    # markdown table row: a literal `|` (splits the row) and a newline
+    # (truncates it, dropping every later column). Table-cell interpolations
+    # only — never code blocks / headings / prose, where `\|` and `<br>` would
+    # render verbatim.
+    env.filters["mdcell"] = to_cell_text
     # `mdquote` re-marks continuation lines of a blockquote nested in a list
     # item; the fenced siblings use Jinja's builtin `indent` for the same
     # reason. Both exist because only the first line of an interpolation

package/runtime/python/okstra_ctl/scope_provenance.py

@@ -0,0 +1,129 @@
+"""Single source of truth for scope-provenance grammar.
+
+Every requirement a phase emits must declare where it came from. Shared by
+validators/validate-run.py and validators/validate_fanout.py so the grammar
+cannot drift between the planning report and the fan-out packets.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+# Items okstra's own phase contracts mandate — they have no brief line to cite.
+# Keep this narrow: a wide allowlist turns into a bypass for invented scope.
+CONTRACT_RULES = frozenset(
+    {
+        "decision-record-step",  # implementation-planning.md: decisionDrafts materialization
+        "glossary-step",         # implementation-planning.md: glossary proposals
+    }
+)
+
+# Mirrors the report schema's requirement id pattern
+# (schemas/final-report-v1.0.schema.json: `^R-\d{3,}$`).
+_REQ_ID_RE = re.compile(r"^R-\d{3,}$")
+_BRIEF_RE = re.compile(r"^brief:\s*(?P<heading>.+?)\s*$")
+_DERIVED_RE = re.compile(r"^derived:\s*(?P<parent>\S+)\s*[—-]\s*(?P<reason>.+?)\s*$")
+_CONTRACT_RE = re.compile(r"^contract:\s*(?P<rule>.+?)\s*$")
+_BRIEF_HEADING_RE = re.compile(r"^(#{1,6}\s+.+?)\s*$")
+_FENCE_RE = re.compile(r"^\s*(`{3,}|~{3,})")
+
+
+def normalize_heading(text: str) -> str:
+    """Heading text stripped of its `#` markers and surrounding whitespace.
+
+    Applied to both sides of the citation comparison so `brief:Acceptance
+    Criteria` and `brief:## Acceptance Criteria` both name the same heading.
+    The comparison stays exact after this — a heading the brief lacks must
+    still fail.
+    """
+    return " ".join(text.lstrip("#").split())
+
+
+def brief_headings(brief_path: Path) -> set[str]:
+    """Markdown headings present in the brief, normalized for comparison.
+
+    An unreadable brief yields an empty set so callers degrade to skipping
+    heading verification instead of failing every brief-sourced citation.
+
+    Fenced regions are skipped: a shell comment inside a ```bash block starts
+    with `#` too, and admitting it would let a requirement cite a "heading" the
+    reporter never wrote.
+    """
+    try:
+        text = Path(brief_path).read_text(encoding="utf-8")
+    except OSError:
+        return set()
+
+    headings: set[str] = set()
+    fence: str | None = None
+    for line in text.splitlines():
+        if m := _FENCE_RE.match(line):
+            marker = m.group(1)
+            if fence is None:
+                fence = marker[0]
+            elif marker[0] == fence:
+                fence = None
+            continue
+        if fence is not None:
+            continue
+        if m := _BRIEF_HEADING_RE.match(line):
+            headings.add(normalize_heading(m.group(1)))
+    return headings
+
+
+@dataclass(frozen=True)
+class SourceRef:
+    kind: Literal["brief", "derived", "contract", "invalid"]
+    value: str = ""
+    reason: str = ""
+
+
+def parse_source(raw: str) -> SourceRef:
+    text = (raw or "").strip()
+    if m := _DERIVED_RE.match(text):
+        parent = m.group("parent")
+        if not _REQ_ID_RE.match(parent):
+            return SourceRef("invalid")
+        return SourceRef("derived", parent, m.group("reason"))
+    if m := _BRIEF_RE.match(text):
+        return SourceRef("brief", m.group("heading"))
+    if m := _CONTRACT_RE.match(text):
+        rule = m.group("rule")
+        if rule not in CONTRACT_RULES:
+            return SourceRef("invalid")
+        return SourceRef("contract", rule)
+    return SourceRef("invalid")
+
+
+def resolve_chain(rows: dict[str, SourceRef]) -> dict[str, str]:
+    """Walk each row's derivation chain to its terminator.
+
+    Returns id -> "ok" or a one-line reason the chain is not admissible.
+    """
+    result: dict[str, str] = {}
+    for rid in rows:
+        seen: list[str] = []
+        cursor = rid
+        while True:
+            if cursor in seen:
+                result[rid] = f"derivation cycle: {' -> '.join(seen + [cursor])}"
+                break
+            seen.append(cursor)
+            ref = rows.get(cursor)
+            if ref is None:
+                result[rid] = f"derives from `{cursor}` which is not a row in this table"
+                break
+            if ref.kind in ("brief", "contract"):
+                result[rid] = "ok"
+                break
+            if ref.kind == "derived":
+                cursor = ref.value
+                continue
+            result[rid] = (
+                f"unrecognized source on `{cursor}` — must be one of "
+                "`brief:<heading>`, `derived:R-NNN — <reason>`, `contract:<rule>`"
+            )
+            break
+    return result

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -6,6 +6,7 @@ from typing import Any, Mapping
 
 from .paths import okstra_home
 from .worker_prompt_policy import (
+    GRILLING_LOG_HEADER,
     PromptPlan,
     WORKER_ERROR_CONTRACT_FILENAME,
     WORKER_PREAMBLE_FILENAME_BY_AUDIENCE,
@@ -75,7 +76,7 @@ def worker_prompt_headers(
     ])
     if _string_value(manifest.get("taskType")) == "improvement-discovery":
         headers.append(
-            f"**Phase 1.5 Grilling Log:** "
+            f"{GRILLING_LOG_HEADER} "
             f"{_improvement_grilling_log_path(project_root, manifest)}"
         )
     if _string_value(manifest.get("taskType")) == "final-verification":

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -14,6 +14,9 @@ PromptAudience = Literal[
     "lead-only",
 ]
 
+# The prompt emitter, the run validator, and the worker-facing docs all bind to
+# this literal; restating it anywhere else silently forks the dispatch contract.
+GRILLING_LOG_HEADER = "**Phase 1.5 Grilling Log:**"
 FINAL_VERIFICATION_HEADERS = (
     "**Worktree:**",
     "**Verification scope:**",
@@ -98,7 +101,7 @@ def resolve_prompt_plan(
             "analysis",
             equality_group="analysis-core",
             packet_only=True,
-            required_headers=("**Phase 1.5 Grilling Log:**",),
+            required_headers=(GRILLING_LOG_HEADER,),
         )
     return _plan("analysis", equality_group="analysis-core", packet_only=True)
 

package/runtime/templates/reports/fan-out-unit.template.md

@@ -16,6 +16,17 @@ recommended-next-phase: {{NEXT_PHASE}}
 
 <!-- Self-contained description of the single work item this unit covers. Do not mix it with other units. -->
 
+## Requirement Provenance
+
+<!-- Where this unit's scope came from. One bullet per source. Every bullet must be
+     `brief:<heading>` (a heading that literally exists in the task brief) or
+     `contract:<rule>` (an okstra-mandated artifact). A unit you cannot source this
+     way is not a work item — raise it as a clarification instead of inventing it.
+     Unlike a planning report, `derived:<parent> — <reason>` is NOT accepted here: a
+     packet is validated on its own, so the parent it names cannot be resolved. -->
+
+- brief:
+
 ## Evidence
 
 <!-- path:line evidence. Locations that requirements-discovery confirmed via file inspection. -->

package/runtime/templates/worker-error-contract.md

@@ -27,14 +27,24 @@ If the sidecar does not exist when a real failure occurs, create `{"schemaVersio
   "durationMs": null,
   "message": "<one-line human summary>",
   "stderrExcerpt": null,
-  "context": null
+  "context": {
+    "cause": "sandbox-denied | service-unavailable | auth-failed | unknown",
+    "causeEvidence": {
+      "targetProbe": "<command + raw output proving the target's state>",
+      "controlProbe": "<command + raw output proving another target is reachable>"
+    }
+  }
 }
 ```
 
+`context` and both `cause` fields are optional; omit `context` entirely (`null`) when there is nothing to add.
+
 ### Rules
 
 - Do not add `source`, `recordedAt`, `agent`, `agentRole`, `model`, or `taskKey`; the lead supplies them when merging the sidecar.
 - The sidecar accepts only `errorType: "tool-failure"`. CLI wrappers write `cli-failure` directly to the run log; the lead records `contract-violation`.
+- To record a block (sandbox/permission) as the cause, submit `context.cause = "sandbox-denied"` together with both probes in `context.causeEvidence`. Without the probes, leave `cause` as `unknown` — and then keep `message` to what you observed (`connection refused`, `1045 access denied`), not what you infer. A block asserted in `message` prose is rejected exactly like one asserted in `cause`, so "sandbox blocked it" with `cause: unknown` fails the write too. Failing to reach a target and the target being down are not the same fact — never assert the former without checking. Only `sandbox-denied` requires evidence; `service-unavailable` and `auth-failed` do not. Each probe is stored truncated to 256 bytes, so lead with the decisive command and its output.
+- [Guideline] Put raw output in `stderrExcerpt` verbatim. Never merge several commands' output into one line, summarize it, or elide it with `...`. Once the host, port, and errno are gone, the cause cannot be recovered later.
 - Continue after recording unless the failure makes the task impossible.
 
 ### Path extraction (BLOCKING)

package/runtime/validators/lib/common.sh

@@ -33,12 +33,3 @@ assert_contains() {
     fail "Expected to find [$expected_text] in $target_path"
   fi
 }
-
-assert_not_contains() {
-  local target_path="$1"
-  local unexpected_text="$2"
-
-  if grep -F -- "$unexpected_text" "$target_path" >/dev/null 2>&1; then
-    fail "Did not expect to find [$unexpected_text] in $target_path"
-  fi
-}

package/runtime/validators/validate-run.py

@@ -49,6 +49,13 @@ from okstra_ctl.final_report_paths import final_report_data_path as _data_path_f
 from okstra_ctl.improvement_assignment import (  # noqa: E402
     validate_primary_lens_assignments,
 )
+from okstra_ctl.worker_prompt_policy import GRILLING_LOG_HEADER  # noqa: E402
+from okstra_ctl.scope_provenance import (  # noqa: E402
+    brief_headings,
+    normalize_heading,
+    parse_source,
+    resolve_chain,
+)
 from okstra_ctl.design_prep import (  # noqa: E402
     DesignPrepError,
     _planning_seq as _design_prep_planning_seq,
@@ -472,7 +479,7 @@ def _grilling_log_path_from_prompts(
     worker_ids: list[str],
     records: list[PromptRecord],
 ) -> tuple[Path | None, list[str]]:
-    header = "**Phase 1.5 Grilling Log:**"
+    header = GRILLING_LOG_HEADER
     values: set[str] = set()
     errors: list[str] = []
     for record in records:
@@ -2869,6 +2876,134 @@ def _validate_requirement_coverage_covered_by(data: dict, failures: list[str]) -
             )
 
 
+def _validate_requirement_provenance(
+    data: dict, brief_path: Path, failures: list[str]
+) -> None:
+    """Every requirement must declare where it came from.
+
+    The planning input template already states that any change beyond what
+    `Requirement Summary` demands is out of scope by default; without this
+    check that sentence has no enforcement point and a phase can invent
+    requirements freely.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    rows = [r for r in (ip.get("requirementCoverage") or []) if isinstance(r, dict)]
+    if not rows:
+        return
+
+    refs = {
+        str(r.get("id") or "").strip(): parse_source(str(r.get("source") or ""))
+        for r in rows
+    }
+    headings = brief_headings(brief_path)
+
+    for rid, ref in refs.items():
+        if ref.kind == "brief" and headings:
+            if normalize_heading(ref.value) not in headings:
+                failures.append(
+                    f"final-report data.json: requirementCoverage `{rid}` cites brief "
+                    f"heading `{ref.value}` which does not exist in the brief. A "
+                    "requirement must trace to a line the reporter actually wrote."
+                )
+
+    for rid, verdict in resolve_chain(refs).items():
+        if verdict != "ok":
+            failures.append(
+                f"final-report data.json: requirementCoverage `{rid}` provenance "
+                f"failed — {verdict}. An item with no admissible source is not a "
+                "requirement: raise it as a `Blocks=approval` clarification instead."
+            )
+
+
+_CITED_STAGE_RANGE = r"(?:[-–]|\bto\b|\bthrough\b)"
+_CITED_STAGE_ITEM = rf"\d+(?:\s*{_CITED_STAGE_RANGE}\s*\d+)?"
+# `, and` / `, &` is one separator, not a separator followed by a stray word:
+# `Stages 1, 2, and 3` is the idiomatic plural and must not orphan stage 3.
+_CITED_STAGE_SEP = r"(?:,\s*(?:and|&)?|and|&)"
+_CITED_STAGE_LIST_RE = re.compile(
+    rf"\bstages?[ \t]*({_CITED_STAGE_ITEM}(?:\s*{_CITED_STAGE_SEP}\s*{_CITED_STAGE_ITEM})*)",
+    re.IGNORECASE,
+)
+_CITED_STAGE_ITEM_RE = re.compile(
+    rf"(\d+)(?:\s*{_CITED_STAGE_RANGE}\s*(\d+))?", re.IGNORECASE
+)
+_CITED_STAGE_RANGE_MAX_SPAN = 64
+
+
+def _cited_stage_numbers(covered_by: str) -> set[int]:
+    """Stage numbers a `coveredBy` cell cites, in every prose form a planner writes.
+
+    Deliberately not `_COVERED_BY_STAGE_REF_RE`: the two directions disagree on
+    what "no match" means — forward treats it as nothing to verify and passes,
+    reverse treats it as nothing cited and orphans every stage — so the reverse
+    reader must cover `Stages 1, 2`, `Stages 1-3` and `Stage 1 and 2` too.
+    Numbers stay anchored to a word-initial `stage`/`stages` token on the same
+    line; harvesting bare numbers — or letting the anchor reach across a line
+    break, or match the tail of `Substage`/`Backstage` — would let any prose,
+    including a row disclaiming every stage, justify any stage.
+    """
+    cited: set[int] = set()
+    for span in _CITED_STAGE_LIST_RE.finditer(covered_by):
+        for item in _CITED_STAGE_ITEM_RE.finditer(span.group(1)):
+            start = int(item.group(1))
+            cited.add(start)
+            if item.group(2) is None:
+                continue
+            end = int(item.group(2))
+            cited.add(end)
+            # A reversed or absurdly wide range is a typo, not a citation of
+            # everything between its endpoints.
+            if 0 <= end - start <= _CITED_STAGE_RANGE_MAX_SPAN:
+                cited.update(range(start, end))
+    return cited
+
+
+# Statuses under which a row asserts the plan does work for the requirement.
+# `gap` is excluded: it states the plan does NOT cover the requirement, so it
+# can justify no stage. `blocked C-NNN` is included — the requirement is real
+# and the stage serving it is not invented scope, only pending a user answer,
+# and such a row already forces a non-passing gate and `approved: false`, so
+# orphaning its stage here would only push planners to delete legitimate work.
+_COVERAGE_CLAIMING_STATUS_RE = re.compile(r"^(covered|blocked C-\d{3,})$")
+
+
+def _validate_stage_has_requirement(data: dict, failures: list[str]) -> None:
+    """Reverse of `_validate_requirement_coverage_covered_by`.
+
+    That check proves every requirement reaches a stage; this one proves every
+    stage traces back to a requirement. Without it a plan can carry stages no
+    one asked for and still pass every gate.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    stage_numbers = {
+        s.get("stage")
+        for s in (ip.get("stages") or [])
+        if isinstance(s, dict) and isinstance(s.get("stage"), int)
+    }
+    if not stage_numbers:
+        return
+
+    cited: set[int] = set()
+    for row in (ip.get("requirementCoverage") or []):
+        if not isinstance(row, dict):
+            continue
+        if not _COVERAGE_CLAIMING_STATUS_RE.match(str(row.get("status") or "").strip()):
+            continue
+        cited |= _cited_stage_numbers(str(row.get("coveredBy") or ""))
+
+    for orphan in sorted(stage_numbers - cited):
+        failures.append(
+            f"final-report data.json: Stage {orphan} is cited by no requirementCoverage "
+            "row — it traces back to nothing the brief asked for. Either cite the "
+            "requirement it serves, or drop it and raise it as a `Blocks=approval` "
+            "clarification (profile: scope provenance)."
+        )
+
+
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;
@@ -3323,7 +3458,7 @@ def _validate_convergence_states(run_dir, failures) -> None:
         )
 
 
-def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
+def _validate_requirements_discovery_fanout(run_dir, failures, brief_path=None) -> None:
     """requirements-discovery run 에 fan-out/ 이 있으면 packet+index 를 검증해
     실패를 ``requirements-discovery: `` 접두로 folding 한다. fan-out 이 없으면 no-op.
     """
@@ -3340,7 +3475,7 @@ def _validate_requirements_discovery_fanout(run_dir, failures) -> None:
             f"requirements-discovery: validate_fanout import failed — {exc}"
         )
         return
-    result = validate_fanout(_Path(run_dir))
+    result = validate_fanout(_Path(run_dir), brief_path)
     if not result.ok:
         for err in result.errors:
             failures.append(f"requirements-discovery: {err}")
@@ -3757,6 +3892,15 @@ def main() -> int:
         _validate_conformance(report_path, failures, surface_patterns=_sp)
     if task_type == "implementation-planning":
         _validate_planning_conformance_declared(report_path, failures)
+        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
+        planning_brief = (
+            (project_root / brief_relative).resolve()
+            if brief_relative
+            else project_root / "__no-brief__"  # absent path → brief_headings returns set()
+        )
+        planning_data = _load_final_report_data(report_path)
+        _validate_requirement_provenance(planning_data, planning_brief, failures)
+        _validate_stage_has_requirement(planning_data, failures)
     if task_type == "improvement-discovery":
         brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
         brief_path = (
@@ -3767,8 +3911,14 @@ def main() -> int:
         run_dir = report_path.parent.parent
         _validate_improvement_discovery(report_path, run_dir, brief_path, failures)
     if task_type == "requirements-discovery":
+        brief_relative = str(task_manifest.get("taskBriefPath") or "").strip()
+        brief_path = (
+            (project_root / brief_relative).resolve()
+            if brief_relative
+            else project_root / "__no-brief__"  # absent path → brief_headings returns set()
+        )
         run_dir = report_path.parent.parent
-        _validate_requirements_discovery_fanout(run_dir, failures)
+        _validate_requirements_discovery_fanout(run_dir, failures, brief_path)
     # Phase-agnostic: convergence runs in every finding-producing phase.
     _validate_convergence_states(report_path.parent.parent, failures)
     validate_report_views(report_path, failures)

package/runtime/validators/validate_fanout.py

@@ -17,11 +17,67 @@ for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "
 
 from okstra_ctl.work_categories import WORK_CATEGORIES  # noqa: E402
 from okstra_ctl.fanout import topological_order, CycleError  # noqa: E402
+from okstra_ctl.scope_provenance import (  # noqa: E402
+    brief_headings,
+    normalize_heading,
+    parse_source,
+)
 
 _NEXT_PHASES = ("error-analysis", "implementation-planning")
 _UNIT_RE = re.compile(r"unit-\d{3}")
 # index.md 번호목록 항목에서만 unit-NNN 을 추출 — 내러티브 문장 중복 방지
 _INDEX_ENTRY_RE = re.compile(r"^\s*\d+\.\s+(unit-\d{3})\b", re.MULTILINE)
+# A `###` subsection inside the section still ends it: its prose is commentary,
+# not provenance, and parsing it as bullets rejects legitimate packets.
+_PROVENANCE_SECTION_RE = re.compile(
+    r"^##\s+Requirement Provenance\s*$(?P<body>.*?)(?=^#{2,}\s|\Z)",
+    re.MULTILINE | re.DOTALL,
+)
+_PROVENANCE_BULLET_RE = re.compile(r"^\s*[-*]\s+(?P<src>.+?)\s*$", re.MULTILINE)
+
+
+def _check_provenance(
+    pkt_name: str, text: str, errors: list[str], headings: set[str]
+) -> None:
+    """A fan-out unit must cite the brief line that demanded it.
+
+    `derived:` is not admissible here: cross-packet derivation cannot be
+    resolved from a single packet, so each unit anchors directly on the brief
+    or on an okstra contract rule.
+
+    `headings` empty means the brief was unavailable — the grammar still
+    applies, only the heading-existence half degrades to unverifiable.
+    """
+    section = _PROVENANCE_SECTION_RE.search(text)
+    if not section:
+        errors.append(
+            f"{pkt_name}: missing `## Requirement Provenance` section — a unit must "
+            "cite the brief line that demanded it"
+        )
+        return
+    bullets = [
+        b for b in _PROVENANCE_BULLET_RE.findall(section.group("body")) if b.strip()
+    ]
+    if not bullets:
+        errors.append(
+            f"{pkt_name}: `## Requirement Provenance` is empty — cite at least one "
+            "`brief:<heading>` or `contract:<rule>`"
+        )
+        return
+    for raw in bullets:
+        ref = parse_source(raw)
+        if ref.kind not in ("brief", "contract"):
+            errors.append(
+                f"{pkt_name}: unrecognized provenance `{raw}` — a fan-out unit's "
+                "source must be `brief:<heading>` or `contract:<rule>`"
+            )
+        elif ref.kind == "brief" and headings:
+            if normalize_heading(ref.value) not in headings:
+                errors.append(
+                    f"{pkt_name}: cites brief heading `{ref.value}` which does not "
+                    "exist in the brief. A fan-out unit becomes the brief for a whole "
+                    "downstream task — it must trace to a line the reporter wrote."
+                )
 
 
 @dataclass
@@ -54,16 +110,20 @@ def _parse_deps(raw: str) -> list[str]:
     return _UNIT_RE.findall(raw or "")
 
 
-def validate_fanout(run_dir: Path) -> ValidationResult:
+def validate_fanout(run_dir: Path, brief_path: Path | None = None) -> ValidationResult:
     run_dir = Path(run_dir)
     fo = run_dir / "fan-out"
     if not fo.is_dir():
         return ValidationResult(ok=True)
 
+    headings = brief_headings(brief_path) if brief_path is not None else set()
+
     errors: list[str] = []
     units: dict[str, list[str]] = {}
     for pkt in sorted(fo.glob("unit-*.md")):
-        fm = _frontmatter(pkt.read_text(encoding="utf-8"))
+        text = pkt.read_text(encoding="utf-8")
+        fm = _frontmatter(text)
+        _check_provenance(pkt.name, text, errors, headings)
         uid = fm.get("unit-id", "")
         if uid != pkt.stem:
             errors.append(f"{pkt.name}: unit-id {uid!r} != filename stem {pkt.stem!r}")