okstra 0.225.0 → 0.226.0

package/runtime/schemas/final-report-v2.0.schema.json

@@ -10014,6 +10014,80 @@
             "implementation-option-selection",
             "implementation-planning"
           ]
+        },
+        "defectClass": {
+          "$ref": "#/$defs/DefectClass"
+        }
+      }
+    },
+    "DefectClass": {
+      "type": "object",
+      "description": "The defect class a blocker belongs to: the shared mechanism, every location x case cell swept for it, and whether an earlier final-verification run of the same target already blocked on it. Required on every final-verification acceptance blocker by `phases/final_verification/validation.py`.",
+      "required": [
+        "mechanism",
+        "cells",
+        "recurrence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "mechanism": {
+          "type": "string",
+          "minLength": 1
+        },
+        "cells": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/DefectClassCell"
+          }
+        },
+        "recurrence": {
+          "enum": [
+            "new",
+            "recurring"
+          ]
+        },
+        "priorBlockers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^final-verification-\\d{3,} AB-\\d{3,}$"
+          }
+        }
+      }
+    },
+    "DefectClassCell": {
+      "type": "object",
+      "required": [
+        "location",
+        "case",
+        "verdict",
+        "evidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "location": {
+          "type": "string",
+          "minLength": 1
+        },
+        "case": {
+          "type": "string",
+          "minLength": 1
+        },
+        "verdict": {
+          "enum": [
+            "defective",
+            "sound",
+            "unverified",
+            "not-applicable"
+          ]
+        },
+        "evidence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "regressionTest": {
+          "type": "string"
         }
       }
     },

package/runtime/schemas/final-report-v3.0.schema.json

@@ -3510,6 +3510,9 @@
             "$ref": "#/$defs/ImplementationOptionSafetyBlocker"
           }
         },
+        "splitAcceptance": {
+          "$ref": "#/$defs/ImplementationOptionSplitAcceptance"
+        },
         "unresolvedFeasibilityFacts": {
           "type": "array",
           "items": {
@@ -3608,6 +3611,9 @@
             "$ref": "#/$defs/ImplementationOptionSafetyBlocker"
           }
         },
+        "splitAcceptance": {
+          "$ref": "#/$defs/ImplementationOptionSplitAcceptance"
+        },
         "unresolvedFeasibilityFacts": {
           "type": "array",
           "items": {
@@ -3936,6 +3942,18 @@
         }
       }
     },
+    "ImplementationOptionSplitAcceptance": {
+      "type": "object",
+      "description": "The user's accept-risk answer that settles a split feasibility vote. Report assembly checks that clarificationRef names a blocks: approval row answered with accept-risk.",
+      "required": ["clarificationRef"],
+      "additionalProperties": false,
+      "properties": {
+        "clarificationRef": {
+          "type": "string",
+          "pattern": "^C-[0-9]{3}$"
+        }
+      }
+    },
     "ImplementationOptionUnresolvedFact": {
       "type": "object",
       "required": [
@@ -3947,8 +3965,13 @@
       "properties": {
         "resolutionKind": {
           "type": "string",
-          "enum": ["user-decision", "technical-verification"],
-          "description": "Optional for historical reads; blocked report publication requires explicit classification."
+          "enum": ["user-decision", "technical-verification", "deferred-gate"],
+          "description": "Optional for historical reads; blocked report publication requires explicit classification. deferred-gate marks a fact only a later gate can close (for example a deployed-environment measurement); it requires gate and does not block candidate validity."
+        },
+        "gate": {
+          "type": "string",
+          "minLength": 1,
+          "description": "For deferred-gate facts: the gate that closes the fact, such as a brief External Gates entry or final-verification user-owned external QA."
         },
         "clarificationRefs": {
           "type": "array",
@@ -10480,6 +10503,80 @@
             "implementation-option-selection",
             "implementation-planning"
           ]
+        },
+        "defectClass": {
+          "$ref": "#/$defs/DefectClass"
+        }
+      }
+    },
+    "DefectClass": {
+      "type": "object",
+      "description": "The defect class a blocker belongs to: the shared mechanism, every location x case cell swept for it, and whether an earlier final-verification run of the same target already blocked on it. Required on every final-verification acceptance blocker by `phases/final_verification/validation.py`.",
+      "required": [
+        "mechanism",
+        "cells",
+        "recurrence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "mechanism": {
+          "type": "string",
+          "minLength": 1
+        },
+        "cells": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/DefectClassCell"
+          }
+        },
+        "recurrence": {
+          "enum": [
+            "new",
+            "recurring"
+          ]
+        },
+        "priorBlockers": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^final-verification-\\d{3,} AB-\\d{3,}$"
+          }
+        }
+      }
+    },
+    "DefectClassCell": {
+      "type": "object",
+      "required": [
+        "location",
+        "case",
+        "verdict",
+        "evidence"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "location": {
+          "type": "string",
+          "minLength": 1
+        },
+        "case": {
+          "type": "string",
+          "minLength": 1
+        },
+        "verdict": {
+          "enum": [
+            "defective",
+            "sound",
+            "unverified",
+            "not-applicable"
+          ]
+        },
+        "evidence": {
+          "type": "string",
+          "minLength": 1
+        },
+        "regressionTest": {
+          "type": "string"
         }
       }
     },

package/runtime/skills/okstra-brief-gen/SKILL.md

@@ -185,6 +185,23 @@ for every variant and every source type below.
    missing and where it lives. A bracketed note inside the captured block
    helps the reader, but it does not replace that row: the row is what a later
    phase sees when it asks whether the source arrived complete.
+4. **Every local document the brief is derived from is its own Source.** A
+   spec, plan or note under the project root that you read while drafting —
+   one the reporter named, or one you opened because a ticket or the
+   conversation pointed at it — gets its own `### Source N — file` entry,
+   not only a mention in Context. When git does not track the file (a
+   `.project-docs/` spec, for example), write the entry with
+   `- format: by-reference`, a project-relative `ref`, and an empty fence:
+   the task worktree is a checkout without that file, and prepare copies it
+   read-only into the analysis packet's `## Cited Local Documents` on every
+   run, so later revisions of the document reach the next phase. A tracked
+   file is in the worktree; capture it as-is per rule 1.
+
+   **Enforced:** `validators/validate-brief.py`
+   (`check_cited_local_documents`) refuses a brief that names a git-untracked
+   document under the project root outside `## Source Material` without such
+   an entry. `okstra brief-sources attach --project-root <PROJECT_ROOT>
+   --brief <path>` appends the missing entries by reference.
 
 ### 1.0. brief variant
 
@@ -235,6 +252,9 @@ each source's raw content **separately** under the `Source Material
 Take an absolute or project-relative path via free-text. Read the entire
 file. Re-ask if it doesn't exist. Captured content is preserved **verbatim**
 in Source Material.
+When the file is under the project root and git does not track it, record
+it by reference instead (capture contract rule 4): the entry's `ref` is the
+project-relative path, `format: by-reference`, and the fence stays empty.
 
 ### 1b. `Issue tracker ticket`
 
@@ -1047,6 +1067,12 @@ Lenses` rules.
 2. If it exits non-zero, **fix the offending brief(s) and re-run**. Do NOT
    print the Step 7 message until the validator passes.
 
+   A `local document ... has no ### Source N — file entry` failure is fixed
+   by `okstra brief-sources attach --project-root <PROJECT_ROOT> --brief
+   <path>`, which appends the entry and changes no other line. For a brief
+   other than the one you just wrote, show the user the listed path and ask
+   before running it.
+
 3. If neither validator copy is present, fall back to a manual checklist:
    confirm each brief has all ten required frontmatter keys (`type`,
    `brief-id`, `parent-id`, `ticket-id`, `source-type`, `task-group`,

package/runtime/skills/okstra-code-review/SKILL.md

@@ -195,6 +195,8 @@ The command reuses the existing completion verification boundary and refuses mix
 
 For missing checks, dispatch one gap-fill invocation per reviewer on that reviewer's original slot, carrying only its incomplete grouped cells, their shared catalog entries, the same range and rule paths. Ask for one complete row for each such cell, not separate replies per missing rule. Use a new invocation ID and repeat the full materialize → verify → dispatch → materialize-result → complete → verify-completion boundary. Re-run the audit with that reviewer's initial and gap-fill markers. Earlier usable verdicts remain unchanged. An invocation with unknown IDs is invalid; record its rejection and request a corrected new invocation before auditing the retained valid completions. Do not silently relabel IDs.
 
+Before accepting a clean general cell, open its G2/G3/G5 observations and verify the result-meaning trace, the downstream workload and pre-work bound, and the applicable documented convention checks. If opened code contradicts a clean observation, record the semantic rejection and exclude that completion from the final coverage audit. Request a full corrected invocation on the same reviewer slot and audit the retained valid completion only; otherwise first-usable preservation would keep the disproved claim. Keep the rejected artifacts immutable for the audit trail. Ordinary missing-row or formatting gaps still use targeted gap-fill with retained valid completions. The parser enforces presence and source locations; the lead checks truth. Keep these observations inside the existing Evidence column, without adding verdict rows.
+
 The Checked/N/A/Findings fields must account for every expected rule ID exactly once; a generic clean or all-checked statement never covers an omitted rule. Do not start Step 3.6 until every reviewer passes the audit. If evidence remains unavailable, report the specific blocker and incomplete coverage instead of writing a completed review.
 
 ## Step 3.6 — Check every citation

package/runtime/skills/okstra-code-review/references/census-rules.md

@@ -19,11 +19,11 @@ Use these named review criteria. Each criterion includes the relevant subconditi
 | Group | Rule IDs and scope |
 |---|---|
 | `structural` | `S1` reuse/DRY; `S2` simplicity/KISS; `S3` responsibilities/SOLID; `S4` current scope/YAGNI; when an architecture pack is routed: `S5` thin ports, `S6` I/O-only adapters, `S7` domain-object placement, `S8` dependency direction, `S9` boundary ports, `S10` domain-owned business rules |
-| `semantic` | `M1` truthful and specific names; `M2` single-purpose readable flow, including size and nesting; `M3` comments and explanatory values |
+| `semantic` | `M1` truthful and specific names, including result tags and diagnostic values; `M2` single-purpose readable flow, including size and nesting; `M3` comments and explanatory values |
 | `state-and-tests` | `T1` state and mutation boundaries; `T2` no self-mocking; `T3` behavioral outcome assertions; `T4` discriminating fixtures, test titles and branch coverage |
 | `general` | `G1` correctness and regressions; `G2` error handling and third-party wrappers; `G3` untrusted-input and resource bounds; `G4` performance; `G5` routed language/framework and project conventions |
 
-Write the selected IDs with their absolute pack/section references under `## Rules`. Multiple references for a criterion go in the same Reference field, separated by semicolons. Do not turn every heading, bullet, formatter instruction or example into another rule. Read the original references rather than restating their bodies.
+Write the selected IDs with their absolute pack/section references under `## Rules`. Multiple references for a criterion go in the same Reference field, separated by semicolons. Include the observed-fact error guidance with G2, and list the routed normative clause locations together under G5 instead of citing only a pack's first line. Do not turn every heading, bullet, formatter instruction or example into another rule. Read the original references rather than restating their bodies.
 
 Write targets under `## Cells`; each has a stable `C-CR-...` ID, the target and its group. A function target includes its path and position, e.g. `src/orders/pricing.py:42 calculate_price`. Distinguish same-line anonymous functions with their columns. Targets are repository-relative; no absolute or parent-traversal paths.
 
@@ -45,6 +45,20 @@ The example is abbreviated; the actual catalog includes the named criteria above
 
 Do not omit a cell because a rule seems inapplicable. Record that criterion under `N/A` with its reason in the compact row. The normal case lists checked rule IDs once with one inspected source anchor for the cell. This preserves rule-level omission checks without repeating paths and explanations for every rule.
 
+## Inspection before compression
+
+Keep discovery separate from output accounting. Read the changed constructs and applicable canonical clauses, trace their dependencies, identify findings, then compress the result into the existing grouped rows. The table is the output format, not the inspection procedure.
+
+Use these inspection guides for general cells:
+
+| Criterion | Inspection guide |
+|---|---|
+| G2 | Enumerate the dependency's possible outcomes and compare their meanings with the returned tags, diagnostic values and error text. Trace existing callees and types when the changed mapping depends on them. |
+| G3 | Identify each input dimension and the work performed inside changed loops or repeated calls. Follow existing callees to account for scans, parsing and allocation; a type-only callee diff does not remove newly amplified work at its caller. Locate the enforcing bound before the expensive work, or report the unbounded path. |
+| G5 | Inspect every applicable normative clause of the routed language, framework and project policy for the changed constructs. Name those clauses and observed conformance. Evaluate explicit conventions independently of formatter, linter and behavioral-test results. |
+
+For checked G2/G3/G5, retain a short source-cited observation in the existing Evidence column as defined by `review-calibration.md`. Format and source existence are enforced by `code_review_coverage.py::_checked_rule_evidence` and the standalone completion tests. The truth and completeness of the observation remain review judgments; the lead checks them before accepting clean coverage.
+
 ## The one principle
 
 **Membership is mechanical; judgment only ever decides a cell's verdict.**

package/runtime/skills/okstra-code-review/references/review-calibration.md

@@ -61,7 +61,13 @@ Return exactly one row per assigned cell under `## Coverage Verdicts`. Keep deta
 
 The example uses the base structural and state-and-tests catalogs. `Checked` means inspected and no actionable finding for those rules. A criterion includes all applicable subconditions in its references; one inapplicable subcondition does not make the entire criterion N/A. Explicitly list the IDs; `all`, counts and ID ranges are not verdicts. `N/A` assigns `rule=reason`; `Findings` assigns `rule=finding-id`. Separate assignments with semicolons and multiple finding IDs for one rule with commas. Use `-` for an empty field. Every expected rule appears exactly once across the three status fields. Never infer an omitted rule as clean.
 
-Every row supplies one literal repository-relative source `path:line` for that cell's target file. Do not substitute a rule-pack citation such as `cc:5`, a global alias such as `E01`, or another target's path. The checker verifies that the file and line exist inside the project. Additional definitions and evidence remain in finding bodies.
+Every row supplies one literal repository-relative source `path:line` for that cell's target file. The citation may be backtick-quoted and followed by ` — ` and a short observation before any ` :: ` rule observations. Do not substitute a rule-pack citation such as `cc:5`, a global alias such as `E01`, or another target's path. The checker verifies that the file and line exist inside the project. Additional definitions and evidence remain in finding bodies.
+
+For `general` cells, checked G2, G3 and G5 each carry a compact observation in that same Evidence field: `target/path:line :: G2=source/path:line observed outcome mapping; G3=source/path:line observed workload and bound; G5=source/path:line applicable clauses and observed conformance`. Each observation begins with an existing project-source citation; it may cite a relevant callee. Keep rule-pack references in the catalog or the observation text, not in the project-source citation slot. Separate assignments with semicolons; use commas within an observation. Findings and reasoned N/A already explain their criteria and need no duplicate clean observation.
+
+For example, `jobs/dispatch.py:18 :: G2=jobs/client.py:25 returned states preserve the dependency outcomes; G3=jobs/dispatch.py:9 validated batch limit bounds work before parsing; G5=jobs/dispatch.py:18 public typing and exception-chaining clauses hold` records three observations in one row. `checked`, `clean` and `no issues` alone are verdict labels, not observations. The checker rejects missing observations, notes for unchecked criteria, aliases and invalid source locations. It cannot establish whether a written observation is true.
+
+Complete discovery before producing clean rows. Follow dependency results and diagnostic meanings for G2, downstream workload and pre-work bounds for G3, and each applicable documented convention for G5. A documented convention violation can be a `nit` with a concrete fix even when outputs are correct. Trace the shared predicates and algorithms before treating similar orchestration as duplicated rules.
 
 A finding ID names a body outside this section, in this reviewer's original or gap-fill result. N/A reasons are short inline applicability explanations, not aliases or rule references. Missing sources, unread rules and blocked inspection remain unaccounted checks and name their blocker. A partial row is rejected with the missing rule IDs; gap-fill rechecks that grouped cell, not every individual rule as a separate output row.
 

package/runtime/skills/okstra-manager/SKILL.md

@@ -69,9 +69,11 @@ Use this when one Linear project, or one parent issue, covers work in several re
 3. For each issue, propose target projects from evidence: labels, team, repository names or paths in the body. Confirm with `prompt_user` (multi-select, recommended projects first, reason in each description).
 4. For each (issue, project) pair, draft the scope: the part of the issue this project implements. Confirm it with `prompt_user` offering one or two drafts plus a custom-input option. A pair without scope is rejected by the CLI.
 5. Author each pair's brief fields under the okstra-brief-gen brief contract: bodies verbatim, `EB-NNN` / `PB-NNN` / `EO-NNN` items as `<id> <observable condition> — verify: <how>`, anything without an observation method under `externalGates`, and `openQuestions` rows prefixed `general:`, `terminology:`, `intent-check:`, `conversion-block:` or `adr-candidate:`.
+   List in `localSources` every local document under that project's root you read to author the pair (a spec, a plan, a note), as a path relative to the project root. Each becomes a `### Source N — file` entry with `format: by-reference`, so every run of the child copies the current file into its analysis packet; a task worktree is a checkout and lacks an untracked `.project-docs/` file. A path outside the project root or a missing file rejects the plan, and a brief whose text names an untracked document that `localSources` does not list fails `validate-brief`.
 6. Write the plan JSON below with the Write tool to a scratch path outside the project roots, then run `okstra manager task split ... --plan <path>`.
    - `split plan rejected` or `rendered briefs failed validate-brief`: fix the named fields and run it again. Nothing was written.
-   - `briefs already exist with different content`: show the listed paths and ask before adding `--overwrite`, which replaces hand edits. Adding issues to an earlier split changes every brief's Related Task Graph, so existing briefs are listed too.
+   - To add issues or projects to an earlier split, add them to the kept `split-plan.json` content and run the split again without `--overwrite`. Each brief's status is `created`, `unchanged`, `refreshed` or `overwritten`. The CLI renders each existing brief from the kept plan and from the new plan, both with the brief's original `created` date. When the two differ only in `### Out of scope`, `## Related Artifacts` and `## Related Task Graph`, it removes and appends just the changed lines in those sections (`refreshed`) and keeps every other line, hand edits included. An edit to the pair's own `outOfScope` list is applied the same way. A brief the new plan does not change stays `unchanged`, even with hand edits.
+   - `briefs already exist with content this plan would change`: the plan changes a listed brief outside those sections, for example its own scope or Context. Show the listed paths and ask before adding `--overwrite`, which re-renders only those briefs and replaces their hand edits. A brief with no kept plan to compare against is also listed when its text differs.
 7. Each `Brief N task key` is `<project-id>:<task-group>:<child-task-id>`. Start one with `okstra manager task run ... --project-id <project-id> --child-task-id <child-task-id>` and follow the Child Launch Rule. The packet already carries `--task-brief`, and `--task-type` until the child task exists.
 
 Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommendedPhase` is `requirements-discovery` (default), `error-analysis` or `improvement-discovery`; `relations[].relation` uses the brief Related Task Graph values; list fields may be omitted.
@@ -90,7 +92,8 @@ Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommend
           "recommendedPhase": "requirements-discovery",
           "context": "<text>", "problem": "<text>", "desiredOutcome": "<text>",
           "expectedBehavior": [], "preservedBehavior": [], "expectedOutcome": [],
-          "externalGates": [], "constraints": [], "openQuestions": []
+          "externalGates": [], "constraints": [], "openQuestions": [],
+          "localSources": [".project-docs/specs/<spec>.md"]
         }
       ]
     }
@@ -100,6 +103,16 @@ Plan JSON (`schemaVersion` 1). `source.kind` is `project` or `issue`; `recommend
 
 The CLI writes each brief to `<projectRoot>/.okstra/briefs/<group-slug>/<ticketId>-<file-title>.md` (`<group-slug>` is the task group lowercased, with each run of characters other than `a-z` and `0-9` replaced by `-`, so `Upload V2` becomes `upload-v2`) with a `## Project Scope` section: this project's scope, `outOfScope`, and the scope of every other project the same issue went to. It validates every brief with the brief validator before writing any file, registers the child tasks, and keeps the plan at `split-plan.json` in the manager task directory.
 
+## Upgrading an Existing Brief
+
+A brief written before `localSources` existed may name a local document only in Context; `validate-brief` and every prepare of that child then refuse it. Do not hand-edit the brief and do not re-split to fix it: `--overwrite` re-renders the brief and replaces later edits. Run
+
+```bash
+okstra brief-sources attach --project-root <project-root> --brief <brief-path>
+```
+
+It appends one `### Source N — file` entry (`format: by-reference`) per cited untracked document at the end of Source Material and changes no other line, so `EB-` / `PB-` / `EO-` ids, External Gates and later edits stay. Show the user the printed paths. Add the same paths to the pair's `localSources` in the kept `split-plan.json` before any later re-split, so the re-rendered brief carries them.
+
 ## Overview Page
 
 When the user wants to see a manager at a glance, run `okstra manager task sync ...` for each task listed by `okstra manager list tasks ...` whose snapshot must be current, then run `okstra manager view --manager-id <manager-id>` and give the user the returned `View URL`. The page reads manager files only, so each task shows the state of its last sync and prints its own sync command.

package/runtime/skills/okstra-pr-gen/SKILL.md

@@ -12,7 +12,7 @@ For authored questions, `prompt_user` means the current host's available questio
 Register PR body templates and generate PR descriptions. Templates live in the
 user home at `~/.okstra/template/pr/`. This skill is **global** — it does not
 require `<PROJECT_ROOT>/.okstra/project.json`. PR generation additionally
-requires the current directory to be a git repository.
+requires a git repository: the current directory, or the one `--repo` names.
 
 ## Step 0: Check CLI availability
 
@@ -31,6 +31,13 @@ If `okstra` is not on PATH, tell the user:
 `$(...)`, leading `VAR=`, or wrap in `if`/`eval`/`||`/`&&` — keep arguments literal and follow the current host's
 execution-permission guidance. Paste literal values emitted by a prior call.
 
+**Target repository:** when the PR's repository is not the session's working
+directory — a sibling repository or another worktree — never `cd` into it. Add
+`--repo <absolute path>` to every `okstra pr branches`, `okstra pr gen` and
+`okstra pr check` call instead; omit it when the working directory is the PR's
+repository. `--template-file` and `--body-file` paths still resolve against the
+working directory, so pass them as absolute paths.
+
 ## Step 1: Pick the mode (always first)
 
 Present a 3-option picker (`prompt_user`):
@@ -78,6 +85,8 @@ Carry the chosen template name as `<template>` (`default` for the bundled one).
 okstra pr branches
 ```
 
+With a target repository: `okstra pr branches --repo <absolute path>`.
+
 It prints the recommended base branches one per line, current branch excluded, or `(no branches)`.
 Present a 3-option base picker from the first two printed branches plus `Enter directly` last; with
 `(no branches)`, ask for the base directly. Carry the choice as `<base>`.
@@ -88,6 +97,8 @@ Present a 3-option base picker from the first two printed branches plus `Enter d
 okstra pr gen --base <base> --template <template>
 ```
 
+With a target repository, add `--repo <absolute path>`.
+
 To describe a branch other than the checkout — a stage branch whose worktree is gone — add
 `--head <branch>`; nothing is checked out.
 
@@ -105,6 +116,9 @@ Write the title and body to a temp file and check them:
 okstra pr check --body-file <path-to-body>
 ```
 
+With a target repository, add `--repo <absolute path>`: the check skips terms that
+repository's tracked files use.
+
 Each printed `L<line>: <pattern>: <match>` row is an okstra identifier a reviewer cannot open:
 restate that line in the reviewer's terms and check again. `clean` means none is left.
 

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

@@ -43,6 +43,15 @@ attachment returned as a link, an opaque embed node) gets a
 `conversion-block:` row in Open Questions naming what is missing. Heading was
 originally "Source Material (verbatim — do not modify)" — the parenthetical
 is a reviewer note, not body text.
+`format: by-reference` applies only to a `file` source whose `ref` is a path
+under the project root (absolute, or relative to the project root): leave
+the fence empty, and prepare copies the file read-only into the analysis
+packet's `## Cited Local Documents` on every run. Use it for an untracked
+local document such as a `.project-docs/` spec, which the task worktree does
+not contain. A file only mentioned in Context is not read, and
+`validators/validate-brief.py` refuses a brief that names an untracked
+document outside Source Material without its own `file` entry;
+`okstra brief-sources attach` appends the missing entries.
 -->
 
 ### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
@@ -50,7 +59,7 @@ is a reviewer note, not body text.
 - ref: <abs file path | LIN-1234 | https://... | "conversation synthesis">
 - fetched-via: <Read | mcp__linear__getIssue | mcp__notion__... | gh issue view | WebFetch | user-paste>
 - fetched-at: <YYYY-MM-DD HH:MM>
-- format: <as-is | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
+- format: <as-is | by-reference | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
 
 ```
 <Paste the raw source here without changing a single character.>

package/runtime/templates/reports/html/i18n/en.json

@@ -451,6 +451,12 @@
       "what-blocks-acceptance": "What blocks acceptance",
       "nothing-is-holding-acceptance": "Nothing is holding acceptance.",
       "follow-up": "Follow-up:",
+      "defect-mechanism": "Mechanism:",
+      "recurring-class": "Recurring — an earlier run blocked on this class:",
+      "location": "Location",
+      "case": "Case",
+      "verdict": "Verdict",
+      "regression-test": "Regression test",
       "residual-risk": "Residual risk",
       "owner": "Owner:",
       "escalation-condition": "Escalation condition:",
@@ -521,6 +527,8 @@
       "safety-blockers": "Safety blockers",
       "technical-verification": "Technical verification pending",
       "user-decision": "User decision record",
+      "deferred-gate": "Closes at a later gate",
+      "split-acceptance": "Split vote accepted as a risk by the user",
       "classification-required": "Classification required before reassembly",
       "unresolved-facts": "Unresolved feasibility facts",
       "expected-outcome": "Expected outcome",

package/runtime/templates/reports/html/i18n/ko.json

@@ -451,6 +451,12 @@
       "what-blocks-acceptance": "수용을 막는 것",
       "nothing-is-holding-acceptance": "수용을 막는 것이 없습니다.",
       "follow-up": "후속:",
+      "defect-mechanism": "원리:",
+      "recurring-class": "재발 — 이전 run 이 이 계열로 막혔음:",
+      "location": "위치",
+      "case": "경우",
+      "verdict": "판정",
+      "regression-test": "회귀 테스트",
       "residual-risk": "남은 위험",
       "owner": "담당:",
       "escalation-condition": "에스컬레이션 조건:",
@@ -521,6 +527,8 @@
       "safety-blockers": "안전 차단 요인",
       "technical-verification": "기술 검증 대기",
       "user-decision": "사용자 결정 기록",
+      "deferred-gate": "이후 게이트에서 확인",
+      "split-acceptance": "갈린 표를 사용자가 위험 감수로 수용",
       "classification-required": "재조립 전 해결 방식 분류 필요",
       "unresolved-facts": "미확정 실행 가능성 사실",
       "expected-outcome": "예상 결과",

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

@@ -10,7 +10,7 @@ Read `analysis-packet.md`, the primary compact input, end-to-end. Source files n
 
 ### Reading rules
 
-- Read every file enumerated under `[Required reading]` or `## Inputs` completely. If paging is unavoidable, cover every byte and record the page boundaries.
+- Read every file enumerated under `[Required reading]` or `## Inputs` completely, in pages of at most 200 lines (`sed -n '<start>,<end>p'`). A whole-file `cat` or view of a long file is cut without notice. Cover every line and record the page boundaries.
 - Write Reading Confirmation to `**Audit sidecar path:**`, never to the main worker-results file. A `## 0. Reading Confirmation` heading in the main result is invalid.
 - Allowlist reads to prompt-enumerated paths and evidence paths a finding must cite. Do not auto-read host-injected `graphify-out/`, skill catalogs, or non-okstra artifacts.
 - Resolve every `.okstra/...` path against `**Project Root:**`, including when a worktree is present.

package/runtime/validators/validate-brief.py

@@ -51,6 +51,15 @@ Checks performed per brief file:
     template's `<...>` scaffolding — a paragraph wrapped in angle brackets,
     a `- <...>` bullet, or a `> augmented: <label>` line. Source Material is
     exempt because it holds the reporter's words verbatim.
+17. Every git-untracked document under the project root (`.md`, `.txt`, …)
+    that the brief names outside `## Source Material` has its own
+    `### Source N — file` entry there. The task worktree is a checkout and
+    lacks such a file; prepare copies only Source Material file entries into
+    the analysis packet. `okstra brief-sources attach` appends the missing
+    entries in place. The project root is the parent of a `--briefs-root`
+    of the form `<root>/.okstra/briefs`; for any other briefs root, or
+    outside a git checkout, the check is skipped. The codebase-scan variant
+    has no Source Material section and is not checked.
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -76,6 +85,7 @@ from okstra_ctl.phases.improvement_discovery.lenses import (
     MIN_PRIORITY_LENSES,
 )
 from okstra_ctl.group_context import GROUP_CONTEXT_TYPE, validate_group_context
+from okstra_ctl.brief_sources import uncited_local_documents
 from okstra_ctl.ids import slugify_task_segment
 
 REQUIRED_FRONTMATTER_KEYS = {
@@ -747,7 +757,32 @@ def check_reporter_confirmations(
         )
 
 
-def validate_brief(path: Path, briefs_root: Path) -> list[str]:
+def project_root_of(briefs_root: Path) -> Path | None:
+    """`<root>/.okstra/briefs` 이면 `<root>`, 아니면 None."""
+    resolved = briefs_root.resolve()
+    if resolved.name == "briefs" and resolved.parent.name == ".okstra":
+        return resolved.parent.parent
+    return None
+
+
+def check_cited_local_documents(
+    text: str, scope: str, project_root: Path | None, errors: list[str]
+) -> None:
+    if project_root is None or scope == "codebase":
+        return
+    for relative in uncited_local_documents(text, project_root):
+        errors.append(
+            f"local document {relative!r} is cited in the brief but has no "
+            "`### Source N — file` entry in Source Material; it is untracked, "
+            "so the task worktree lacks it and no run will show it to workers. "
+            f"Run `okstra brief-sources attach --project-root {project_root} "
+            "--brief <this brief>` to append it by reference"
+        )
+
+
+def validate_brief(
+    path: Path, briefs_root: Path, project_root: Path | None = None
+) -> list[str]:
     text = strip_html_comments(path.read_text(encoding="utf-8"))
     errors: list[str] = []
 
@@ -795,6 +830,9 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     check_end_state_sections(text, scope, errors)
     check_variant_required_sections(text, scope, errors)
     check_template_scaffold(text, scope, errors)
+    check_cited_local_documents(
+        text, scope, project_root or project_root_of(briefs_root), errors
+    )
 
     # 2. brief-id matches filename stem
     stem = path.stem

package/runtime/validators/validate-run.py

@@ -242,6 +242,7 @@ from okstra_ctl.report_routing import technical_verification_routing_errors
 from okstra_ctl.phases.implementation_option_selection.validation import (  # noqa: E402
     validate_blocked_answer_channel,
     validate_implementation_option_selection,
+    validate_split_acceptance,
 )
 from okstra_ctl.phases.implementation_planning.validation import (
     _validate_requirement_provenance, _validate_stage_has_requirement,
@@ -3197,6 +3198,10 @@ def validate_final_report_data(
             f"implementation-option-selection: {error}"
             for error in validate_blocked_answer_channel(data)
         )
+        failures.extend(
+            f"implementation-option-selection: {error}"
+            for error in validate_split_acceptance(data)
+        )
     elif task_type == "implementation":
         _validate_stage_carry_sidecar_exists(data, report_path, failures)
         _validate_lead_fixes(data, failures)