okstra 0.25.1 → 0.27.0

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

@@ -9,11 +9,34 @@ Generate a single `task brief` markdown file under the okstra project domain
 (`.project-docs/okstra/briefs/<task-group>/<task-id>.md`) so it can be fed to
 [`okstra-run`](../okstra-run/SKILL.md) as `--task-brief`.
 
-This skill produces **only the brief** — a structured "request slip". It does
-NOT write a PRD, decompose work into vertical slices, or decide modules.
-Those belong to later okstra phases (`requirements-discovery`,
-`implementation-planning`) which use cross-verification and would conflict
-with anything decided here.
+**Purpose — pre-discovery artifact.** A brief is the **pre-discovery** stage
+of an okstra task: it absorbs domain alignment, codebase evidence
+collection, and reporter intent capture so that the downstream expert
+phases (`requirements-discovery` / `error-analysis` /
+`implementation-planning`) can run with **zero fill-in questions** to the
+operator. A brief is written from a report by a domain reporter (PM, CS,
+ops, QA, end-user, …) **or** by a developer themselves — the input
+provenance does not change the output contract.
+
+This is a **labelled-handoff** to the next phase, built on two
+non-negotiables:
+
+- **Verbatim-preserving capture** — the reporter's words are kept
+  byte-for-byte under `Source Material`. Format-only transformations
+  (e.g. Jira ADF → Markdown) and codebase cross-references are mechanical
+  and reversible; they are recorded with the `format-conversion` and
+  `evidence-link` Augmentation labels.
+- **Labelled interpretation** — anywhere the skill resolves a reporter
+  word to a project-canonical term or infers reporter meaning that was
+  not literally stated, the addition lives in `Augmentation` with the
+  `terminology-mapping` or `intent-inference` label. Unlabelled
+  augmentation is forbidden — the label is what makes the interpretation
+  auditable and (for `intent-inference`) verifiable against the reporter.
+
+A brief still does NOT write a PRD, decompose work into vertical slices,
+or decide modules. Those belong to later okstra phases
+(`requirements-discovery`, `implementation-planning`) which use
+cross-verification and would conflict with anything decided here.
 
 ## Intended chain
 
@@ -37,11 +60,33 @@ okstra-brief
 ## When NOT to use
 
 - The user already has a brief file at a known path → skip to `okstra-run`.
-- The user wants to write a full PRD with user stories and implementation
-  decisions → that's `to-prd`, not this. okstra phases will generate the
-  equivalent artifacts with cross-verification.
-- The user wants to split work into issues → that's `to-issues`, and within
-  okstra it's the job of `implementation-planning`.
+- The user wants a full PRD with user stories and implementation decisions
+  — that's beyond a brief; okstra phases generate the equivalent artifacts
+  with cross-verification.
+- The user wants to split work into issues — within okstra that's the job
+  of `implementation-planning`.
+
+## Artifact-home rule (okstra-wide)
+
+**All okstra-generated artifacts live under `<PROJECT_ROOT>/.project-docs/okstra/`.**
+This includes briefs, run manifests, reports, worker results, status,
+sessions, and any other run output. okstra itself never writes to `.scratch/`
+or other project paths.
+
+All writes by this skill stay inside `.project-docs/okstra/`. When domain
+alignment (Step 3b / Step 4.5) yields a glossary change that the user
+approves inline, the change is written to:
+
+- `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` — okstra's internal
+  glossary. Created if absent; appended to a `## Glossary` section
+  otherwise.
+
+External `<PROJECT_ROOT>/CONTEXT.md` / `<PROJECT_ROOT>/CONTEXT-MAP.md` /
+`<PROJECT_ROOT>/docs/adr/` are read-only references; this skill never
+writes to them. Decision files (when raised by `implementation-planning`)
+also live inside okstra's subtree at
+`<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`, never
+at external `docs/adr/`.
 
 ## Authority files
 
@@ -53,9 +98,12 @@ okstra-brief
   (tracker child ticket; at depth N, `sub/` is nested N times) — output
   location for this skill. `<ticket-id>` is the raw issue-id when the source
   is a tracker, otherwise free-text supplied by the user. `<file-title>` is
-  auto-slugified from the tracker title, otherwise from user input. Never
-  write outside this tree. Never use `.scratch/` (that belongs to `to-prd` /
-  `to-issues`).
+  auto-slugified from the tracker title, otherwise from user input.
+- okstra-internal glossary (write target of Step 4.5):
+  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`. Created if absent.
+- okstra-internal decisions (write target of `implementation-planning`
+  via `implementation`):
+  `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
 
 ## Step 0: Resolve project root
 
@@ -65,6 +113,11 @@ Reuse the same disk-only resolution rule as `okstra-run`:
 if command -v okstra >/dev/null 2>&1; then
   OKSTRA_CMD="okstra"
 else
+  # `~/.okstra/bin/okstra.sh` exists on every installed machine but it is
+  # the bash run-wrapper, NOT the Node CLI — it does not implement
+  # `check-project`. Do not branch into it as a fallback. Go straight to
+  # `npx` so the user always reaches a working `check-project` even when
+  # the Node CLI is off-$PATH.
   OKSTRA_CMD="npx -y okstra@latest"
 fi
 $OKSTRA_CMD check-project --cwd "$(pwd)"
@@ -104,6 +157,15 @@ in Source Material.
 
 Order of operations:
 
+0. **Task-group precondition (REQUIRED before any recursion)** — if the
+   tracker fetch may yield child tickets (which is always possible until the
+   first fetch proves otherwise), acquire `task_group` first by running Step
+   2a now. Step 2a is otherwise re-entered later for non-tracker sources;
+   when reached again it MUST reuse the value collected here without asking
+   again. Rationale: the recursion in sub-step 6 records descendant brief
+   paths under `<task-group>/sub.../`, and those paths cannot be formed
+   until `task_group` is known. Without this preflight the recursive walk
+   would either stall mid-collection or invent a placeholder group.
 1. `AskUserQuestion` (free text):
    `"Ticket key or URL (e.g. LIN-1234, PROJ-42, https://linear.app/..., https://your.atlassian.net/browse/...)"` →
    `ticket_ref`.
@@ -140,26 +202,54 @@ Order of operations:
    - Look at child references in the fetched ticket response:
      - Linear: `children` / `subIssues` field
      - Jira: `subtasks` (or `issuelinks` with the `is parent of` relation)
-     - GitHub: task-list checkbox `#NNN` references + `tracked_issues`
-       (when present)
+     - GitHub: `gh issue view --json title,body,comments,labels,state` only
+       returns the issue body and comments — child relations are NOT in that
+       JSON. Resolve children via two paths:
+       1. **task-list parsing** — scan the fetched body and comments for
+          markdown task-list checkboxes referencing other issues
+          (`- [ ] #NNN`, `- [x] owner/repo#NNN`, `- [ ] https://github.com/...`).
+          Capture each as a child candidate.
+       2. **tracked / sub-issue GraphQL** — for GitHub Projects v2
+          "tracked issues" / sub-issue relations, the REST `gh issue view`
+          response does NOT carry them. Query GraphQL explicitly, e.g.
+          `gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){trackedIssues(first:50){nodes{number repository{nameWithOwner}}} subIssues:trackedInIssues(first:50){nodes{number repository{nameWithOwner}}}}}}' -f o=<owner> -f r=<repo> -F n=<num>`.
+          If the GraphQL request fails (auth scope missing, feature
+          unavailable on this repo, network error), **do NOT silently
+          continue with full recursion**. Disable the "Generate the full
+          tree recursively" option for this branch, default to
+          `Parent only; list children in Related Artifacts`, and surface the
+          GraphQL failure to the user in one line so they can decide whether
+          to paste child bodies manually.
      - Notion: child pages / sub-pages
    - If there is **one or more** child, ask **once at the top parent**:
      - `AskUserQuestion` (single-select)
        - **Label**: `"This ticket has sub-tickets. How should the child tree be handled?"`
        - **Options**:
-         1. `Generate the full tree recursively (recommended)` — walk
-            children, grandchildren, … via BFS/DFS and emit one brief per
-            node.
-         2. `Parent only; list children in Related Artifacts` — single
-            brief. Children are not fetched, only their keys/URLs are
-            recorded.
-         3. `Generate selected children only` — multi-select the direct
-            children; for each chosen child, apply option-1 policy
-            recursively to that branch.
+         1. `Full tree` (recommended) — walk children, grandchildren, …
+            via BFS/DFS and emit one brief per node.
+         2. `Parent only` — single brief. Children are not fetched; their
+            keys/URLs are recorded under Related Artifacts.
+         3. `Selected` — multi-select the direct children; for each chosen
+            child, apply option-1 policy recursively to that branch.
    - For options 1 / 3, **recurse into Step 1b sub-steps 3–5** for every
      descendant. No depth limit. Maintain a visited set of
      `<tracker>:<ticket-id>` to prevent cycles; on revisit, do not emit a
      new brief — only add a link back to the existing brief.
+   - **Visited-set across re-runs (rebuild from disk)** — the in-memory
+     visited set is per-run and disappears between invocations. When this
+     skill runs again over a tree that already has briefs on disk, it MUST
+     reseed the visited set by scanning
+     `<PROJECT_ROOT>/.project-docs/okstra/briefs/<task-group>/` recursively
+     and reading each brief's frontmatter `ticket-id` + `source-type`.
+     Reseed precedence:
+     1. On-disk frontmatter (`ticket-id` ≠ "") populates visited entries
+        as `<source-type>:<ticket-id>` — these win.
+     2. Step 2c collision policy (`Skip` / `Append timestamp` /
+        `Overwrite`) applies to any node whose path is already taken.
+     3. The fresh in-memory walk fills any gaps for tickets not yet on
+        disk.
+     A ticket present on disk is NOT refetched unless the user explicitly
+     answers `Overwrite` for that path.
    - Each descendant's brief file at depth N is created under
      `<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md` per
      Step 2b.
@@ -181,20 +271,21 @@ Order of operations:
 3. On fetch failure or auth required (login wall, intranet-only, etc.):
    - Ask the user via `AskUserQuestion` to paste the body.
    - Never invent URL content.
-4. Preserve the core content (title + body + quotes/examples) **verbatim**
-   in Source Material. For very large pages, respect the ~400-line per-brief
-   guideline and **excerpt key paragraphs only**, but do not modify or
-   summarize the excerpted text by a single character. Annotate the excerpt
-   with `[excerpt — full: <URL>]`.
+4. Preserve the fetched content (title + body + quotes/examples) **verbatim**
+   in Source Material. Do not excerpt or summarize long pages to fit a line
+   budget. If the fetch tool returns truncated content or cannot expose the
+   full body, ask the user to paste/provide the missing body before writing
+   the brief, or record the fetched text exactly and add a
+   `conversion-block:` row that names the missing portion.
 
 ### 1d. `User input`
 
 Two sub-modes combined under one option.
 
 - **Conversation synthesis**: do not re-interview. Synthesize from the
-  current conversation (mirrors `to-prd`'s "synthesize, don't interview").
-  Label Source Material as `conversation synthesis` and quote key
-  utterances verbatim wherever possible.
+  current conversation ("synthesize, don't interview"). Label Source
+  Material as `conversation synthesis` and quote key utterances verbatim
+  wherever possible.
 - **Inline input**: if conversation context is empty or thin, take one
   free-text `AskUserQuestion`. The received text is preserved in Source
   Material without changing a character.
@@ -213,6 +304,9 @@ Material.
 Slug rule: same as `okstra-run` Step 3 — slugify, must have at least one
 alphanumeric character.
 
+If `task_group` was already collected by Step 1b sub-step 0 (tracker
+preflight), reuse that value silently — do NOT ask again.
+
 ### 2b. Filename per source type
 
 Final brief path rule (fixed; one extra `sub/` per depth):
@@ -242,13 +336,16 @@ relations are also tracked via the brief's `parent-id` frontmatter
   - `"Ticket / identifier (e.g. dev-9043, INV-1234, login-error)"` →
     `ticket_id`
 
-`<file-title>` resolution:
+`<file-title>` resolution (filename slug only — the verbatim rule applies
+to Source Material body, not to the filename):
 
 - **Issue-tracker sources**: auto-generated from the ticket title / summary —
   do not ask the user.
   1. Keep alphanumerics, spaces, Hangul; drop everything else
   2. Replace spaces with `-`
-  3. Lowercase (Hangul untouched)
+  3. Lowercase (Hangul untouched) — **filename normalization only**.
+     The Source Material section MUST preserve the original title's case
+     byte-for-byte; lowercase applies strictly to the on-disk filename.
   4. Cut to 60 chars at a word boundary (hard-cut at 60 if no boundary)
   5. Trim leading/trailing `-`
   - Example: Linear `LIN-1234 "Fix flaky login retry on 5xx"` →
@@ -263,44 +360,168 @@ alphanumeric character after slugification. Apply Step 2c on collision.
 
 ### 2c. Collision handling
 
-If a brief file already exists, `AskUserQuestion` with (`Skip if exists` /
-`Append timestamp suffix` / `Overwrite`). Default recommendation: `Skip if
-exists` — protects briefs the user has already edited.
+If a brief file already exists, `AskUserQuestion` with (`Skip` /
+`Append suffix` / `Overwrite`). Default recommendation: `Skip` —
+protects briefs the user has already edited. `Append suffix` adds a
+timestamp suffix to the filename stem.
 
 When multiple collisions occur in tracker multi-generation mode:
 
 - First echo the colliding file list to the user.
 - Ask **once** with `AskUserQuestion` for a bulk policy.
 - **Even when `Overwrite` is selected, confirm one more time for each
-  colliding file**, or warn that downgrading to `Append timestamp suffix`
-  is safer. Silent bulk overwrite is forbidden.
-
-## Step 3: Light context scan (optional but recommended)
+  colliding file**, or warn that downgrading to `Append suffix` is safer. Silent bulk overwrite is forbidden.
 
-Only when the source material references project-specific terms or files:
+## Step 3: Domain alignment scan (recommended)
 
-- Read `CONTEXT.md` / `docs/adr/` at repo root if present (domain vocabulary).
-- Resolve any file paths or symbols mentioned in the source so the brief uses
-  the project's domain language, not generic phrasing.
+Always check whether the project carries a domain context, then compare the
+Source Material's terminology against it. This step exists to *surface*
+mismatches — it never edits user-owned domain docs and never rewrites Source
+Material.
 
-Skip this step for purely external request material.
+### 3a. Locate domain assets
+
+Read in this order — absent files are the normal state; skip silently and
+never error:
+
+1. **okstra-internal (authoritative)** — always check first:
+   - `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` if present
+   - `<PROJECT_ROOT>/.project-docs/okstra/decisions/` titles if present
+2. **External (supplementary read-only reference)** — read if present:
+   - `<PROJECT_ROOT>/CONTEXT.md` (or `CONTEXT-MAP.md` → per-context
+     `CONTEXT.md`)
+   - `<PROJECT_ROOT>/docs/adr/` titles
+   - `<PROJECT_ROOT>/.scratch/CONTEXT.md` (output of external skills like
+     grill-with-docs, if any)
+
+If none of these exist, skip 3b/3c silently.
+
+### 3b. Term comparison
+
+For each domain-significant noun in Source Material, classify:
+
+- **conflict** — the source uses a term that `CONTEXT.md` defines
+  differently. Example: source says "cancellation" meaning refund, glossary
+  says "cancellation" means order-state transition.
+- **fuzzy / overloaded** — a term that has no canonical definition yet but
+  is being used in ≥ 2 different senses in the source(s).
+- **aligned** — matches the glossary; no action.
+
+### 3c. Output — translation as a first-class duty
+
+The pre-discovery skill's job is to land every external-vocabulary noun
+on a project-internal concrete object whenever possible.
+
+- Each `conflict` or `fuzzy` term becomes:
+  - One entry under `Open Questions` with the prefix `terminology:`
+    (so the next phase can resolve it during `requirements-discovery`).
+  - One line under `Augmentation > Domain alignment` with the
+    `terminology-mapping` label (Step 4 label rules), recording the
+    observation (what the source said vs. what CONTEXT.md says).
+- **File paths and symbols are resolved to absolute, in-repo references.**
+  When the source mentions a module / class / endpoint / config key, run
+  `Read` / `Grep` to locate the concrete file path (relative to
+  `<PROJECT_ROOT>`) and the canonical symbol name. Record the resolution
+  under `Augmentation > Domain alignment` with the `evidence-link` label,
+  and link the absolute path from `Related Artifacts`. This is what makes
+  the brief portable across downstream workers (Claude / Codex / Gemini)
+  that may operate in separate worktrees and need to point at the same
+  object.
+- **Conversion-block signal** — when a reporter statement cannot be
+  mapped to project vocabulary even after codebase exploration (e.g. the
+  reporter names a UI element that does not exist by that name, or
+  describes behavior no module currently implements), do **not** guess
+  the target. Emit a `conversion-block:` entry under `Open Questions`
+  describing exactly what could not be translated, so the next phase
+  knows to query the reporter directly rather than infer.
+- See Step 4.5 for the approval-gated path to actually write the
+  okstra-internal glossary at
+  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`. External
+  `CONTEXT.md` / `CONTEXT-MAP.md` / `docs/adr/` are never edited.
+
+Skip 3b/3c for purely external request material with no overlap to the
+project's domain.
 
 ## Step 4: Fill in missing fields (NO full interview)
 
 > **Verbatim-source rule**: Source Material collected in Step 1 must never
 > be paraphrased, summarized, or restructured. When supplementing missing
 > information, write only into the dedicated `Augmentation` section (see
-> Step 5); never modify Source Material by a single byte.
+> Step 5); never modify Source Material by a single byte. **Anything
+> learned by grilling in this step lands in `Augmentation` or `Open
+> Questions` only.** brief is a pre-discovery artifact, not a PRD —
+> decisions belong to later phases.
 
 Inspect the synthesized brief draft. For each REQUIRED section below that is
 empty or trivially thin **after** reading Source Material verbatim, ask **at
-most one** `AskUserQuestion` (free text) to fill it. Never ask about sections
-already covered by the source material.
+most one** `AskUserQuestion` to fill it. Never ask about sections already
+covered by the source material.
+
+### Sharpening pass (bounded grill)
+
+The following rules absorb the useful parts of `grill-me` /
+`grill-with-docs` without turning brief into a decision-making interview.
+
+1. **Codebase-first** — if a gap can be answered by `Read` / `Grep` / file
+   inspection (e.g. "does this symbol exist?", "what does this endpoint
+   return today?"), do that **instead of** asking the user. Only ask when
+   the codebase cannot answer.
+2. **Question carries a recommended answer** — every `AskUserQuestion`
+   issued in this step must put the recommended option **first** with the
+   suffix `(Recommended)`. Free-text fallbacks are still allowed, but the
+   recommendation must be visible.
+3. **One at a time** — never batch multiple questions into one
+   `AskUserQuestion` call. Ask, wait for the answer, fold it into the
+   draft, then ask the next.
+4. **Bounded budget** — at most **1** sharpening question per empty
+   required section, plus **at most 2** disambiguation questions arising
+   from Step 3b (terminology conflicts / fuzzy terms). Hard cap: **6
+   questions total** across the whole brief. Anything beyond the cap is
+   recorded under `Open Questions` instead of asked.
+5. **Scenario probe (optional)** — when `Desired Outcome` is empty or one
+   thin line, you may use **one** of the budgeted questions to pose a
+   single boundary scenario ("if X happens, is that in scope?") with a
+   recommended yes/no. Do not run a full edge-case sweep.
+6. **Stop conditions** — exit the sharpening pass when any of these holds:
+   (a) every required section has Source content or one Augmentation
+   entry, (b) the budget is exhausted, (c) the user signals "enough".
+   Remaining gaps → `_(none)_` for that section; remaining ambiguities →
+   `Open Questions`.
 
 Augmentation content must always be confined to the `Augmentation` section
-or to a `> augmented:` blockquote inside the required section, so it is
-clear that the content is the skill's / user's added interpretation rather
-than the original source.
+or to a `> augmented: <label>` blockquote inside the required section, so
+it is clear that the content is the skill's / user's added interpretation
+rather than the original source.
+
+### Augmentation labels (REQUIRED — no unlabelled augmentation)
+
+Every augmentation — both inline `> augmented: …` blockquotes and
+`Augmentation` section bullet points — must carry exactly one of these
+labels. Unlabelled augmentation is rejected as half-formed translation.
+
+| Label | When to use | Downstream treatment |
+|---|---|---|
+| `evidence-link` | Cross-reference / file path / symbol resolved from the source against the actual codebase. Pure fact, verified by `Read` / `Grep`. | Trust without verification. |
+| `format-conversion` | Format-only transform (Jira ADF → Markdown, HTML → Markdown, etc.). Semantics unchanged. | Trust without verification. |
+| `terminology-mapping` | Reporter's word mapped to a project-canonical term (from `CONTEXT.md` or resolved during Step 3b). | Verify against `CONTEXT.md`; if mismatch, treat as a clarification candidate. |
+| `intent-inference` | Reporter did NOT literally state this — the skill inferred meaning from context (e.g. classifying "가끔 안 됨" as "intermittent failure on a specific path"). Qualitative only — **never** invent quantitative thresholds (numbers, latencies, percentages, counts). | **Verify with the reporter before acting.** Auto-mirrored into `Open Questions`. |
+
+**Inline form** — `> augmented: intent-inference — <one line>`.
+**Section form** — `- intent-inference: <one line>` under `Augmentation`.
+
+### Auto-mirroring rule
+
+Every `intent-inference` entry must have a paired entry in `Open Questions`
+with the prefix `intent-check:` describing what the reporter must confirm.
+This is what makes the inference auditable end-to-end: the inference is
+visible (Augmentation), and the verification need is visible (Open
+Questions). If a downstream worker resolves the inference without going
+back to the reporter, the `intent-check:` row stays open as a record of
+unverified translation.
+
+`terminology-mapping` and `conversion-block:` follow the same dual-record
+discipline (Augmentation observation ↔ `Open Questions` `terminology:` /
+`conversion-block:` row).
 
 ### Step 4 policy under multi-brief (tracker recursion) mode
 
@@ -334,6 +555,66 @@ Sections **deliberately omitted** (do NOT add them, do NOT prompt for them):
 
 Those belong to later okstra phases.
 
+## Step 4.5: Domain proposals (with approval-gated edits)
+
+For each `conflict` / `fuzzy` term collected in Step 3b that *was not*
+resolved by a budgeted Step 4 question, draft a glossary proposal and
+offer it to the user. This step writes to the **okstra-internal
+glossary** at `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` only —
+external `<PROJECT_ROOT>/CONTEXT.md` / `CONTEXT-MAP.md` are never edited
+by this skill.
+
+> **Decision scope**: this skill does NOT evaluate decision candidates
+> and does NOT draft decision files. Decision creation requires context
+> that brief lacks (the recommended option, named alternatives,
+> trade-off analysis). Brief only emits the signal — every candidate
+> goes to `Open Questions` with the `adr-candidate:` prefix and is
+> evaluated by `implementation-planning` against the three-criteria
+> gate. Approved decision files land at
+> `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`,
+> never at external `<PROJECT_ROOT>/docs/adr/`.
+
+### 4.5a. Draft glossary proposals
+
+- **Glossary entry**: `proposed glossary entry: <term> = <one-line definition>`
+  — destined for `<PROJECT_ROOT>/.project-docs/okstra/glossary.md`.
+
+### 4.5b. Approval flow (per entry)
+
+For each draft, **first echo the target absolute path on one line** (so
+the user sees the exact file that will be written), then `AskUserQuestion`:
+
+- **Label**: `"Apply glossary entry?"` (keep the label short — absolute
+  paths belong in the echo line above, not in the option chip)
+- **Options**:
+  1. `Apply (Recommended)` — write the change now.
+  2. `Skip — keep as Augmentation note only` — leave the proposal in the
+     brief's `Augmentation > Domain alignment` section, do not edit the
+     file.
+  3. `Edit first` — show the rendered content and accept a free-text
+     correction, then re-confirm.
+
+Ask once per entry. Never batch. If the user picks `Apply`:
+
+- Append the entry to
+  `<PROJECT_ROOT>/.project-docs/okstra/glossary.md` under an existing
+  relevant heading, or create a `## Glossary` section if none exists. If
+  the file does not exist, create it with a `## Glossary` heading and
+  the entry. Preserve all existing content byte-for-byte.
+
+### 4.5c. Brief record
+
+Regardless of Apply / Skip, record the outcome under `Augmentation >
+Domain alignment`:
+
+- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md` or
+- `terminology-mapping: skipped glossary: <term> = <definition>`
+
+Decision candidates are recorded under `Open Questions` as
+`adr-candidate: <topic>` (targeting
+`<PROJECT_ROOT>/.project-docs/okstra/decisions/`) — not here. This keeps
+the brief itself self-documenting about what side effects it caused.
+
 ## Step 5: Write the brief(s)
 
 Use the same template per brief file. In tracker mode producing a parent
@@ -348,13 +629,14 @@ collide with the inner 3-backtick code block.)
 ---
 type: brief
 brief-id: <ticket-id>-<file-title>          # equals the filename stem
-parent-id: self                              # `self` at root, otherwise parent's brief-id
+parent-id: self                              # always `self` at root; child briefs use parent's brief-id
 ticket-id: <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12 | "">
 source-type: <file | linear | jira | github | notion | url | user-input>
 task-group: <task-group>
 depth: 0                                     # 0=parent/single, 1=child, 2=grandchild, ...
 created: <YYYY-MM-DD>
 generator: okstra-brief
+reporter-confirmations: <complete | partial | pending | skipped>  # set by Step 6.5
 ---
 
 # Task Brief: <task_group>/<filename-without-ext>
@@ -364,6 +646,7 @@ generator: okstra-brief
 > Tracker key (if any): <LIN-1234 | PROJ-42 | gh-repo-123 | notion-abcdef12>
 > Parent brief (child briefs only): <relative path>
 > Recommended next phase: <requirements-discovery | error-analysis>  ← from Step 6
+> Handoff contract: see `prompts/profiles/_common-contract.md` § "Brief handoff contract"
 
 ## Source Material (verbatim — do not modify)
 
@@ -376,7 +659,7 @@ must be annotated in the header meta.
 - 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)" | "excerpt — full: <URL>">
+- format: <as-is | "Jira ADF → Markdown (semantics preserved)" | "tool-truncated — missing body requested from reporter">
 
 ```
 <Paste the raw source here without changing a single character.>
@@ -391,8 +674,10 @@ must be annotated in the header meta.
 <Background / scope / why now. If self-evident from Source Material, quote
 it briefly and stop. Use the blockquote below when augmentation is needed.>
 
-> augmented: <Interpretation added by the skill or user. Do NOT add any
-> extra interpretation outside this blockquote.>
+> augmented: <label> — <Interpretation added by the skill or user. Label
+> MUST be one of: `evidence-link` / `format-conversion` /
+> `terminology-mapping` / `intent-inference`. Do NOT add any extra
+> interpretation outside this blockquote.>
 
 ## Problem / Symptom
 
@@ -416,7 +701,39 @@ none.>
 
 ## Open Questions
 
-- <Unresolved questions the user flagged. _(none)_ if none.>
+Prefix every row with one of these signals so the next phase knows how to
+handle it. Free-form rows are allowed only as `general:`.
+
+- `general: <unresolved question the user flagged>`
+- `terminology: <reporter word> — needs canonical resolution against <PROJECT_ROOT>/.project-docs/okstra/glossary.md`
+- `intent-check: <restated inference> — confirm with reporter`
+  (auto-paired with every `intent-inference` augmentation)
+- `conversion-block: <reporter statement> — could not be mapped to project vocabulary; reporter query required`
+- `adr-candidate: <topic>` — signal only; `implementation-planning`
+  evaluates and, if accepted, drafts a decision file at
+  `<PROJECT_ROOT>/.project-docs/okstra/decisions/<NNNN>-<slug>.md`.
+
+Use `_(none)_` only if every signal is empty. `intent-check:` and
+`conversion-block:` rows that are answered in Step 6.5 are NOT removed
+from this list — they receive a `[CONFIRMED <YYYY-MM-DD> → RC-N]`
+marker that links to the corresponding entry under
+`## Reporter Confirmations`.
+
+## Reporter Confirmations
+
+Populated by Step 6.5. Each subsection records one reporter answer
+verbatim, with a link back to the originating `Open Questions` row.
+
+_(none — pending or skipped)_
+
+<!-- when populated, the shape is:
+### RC-1 — <intent-check: or conversion-block: row id / topic>
+- asked: <YYYY-MM-DD HH:MM>
+- linked-row: `<exact Open Questions row text>`
+- answer (verbatim):
+
+  > <reporter's answer, byte-for-byte>
+-->
 
 ## Augmentation
 
@@ -424,7 +741,47 @@ Cross-references / interpretation / context added by the user or skill that
 is not in the original source. May be empty. Keep this section visually
 separated from Source Material — never inline it inside Source Material.
 
-- _(none)_ or `- <augmentation>`
+Every entry below must start with one of the four labels:
+`evidence-link` / `format-conversion` / `terminology-mapping` /
+`intent-inference`. Unlabelled entries are forbidden.
+
+### Domain alignment
+
+Observations from Step 3b and the outcome of Step 4.5 (glossary
+applied vs. skipped). The actual glossary edits live in
+`<PROJECT_ROOT>/.project-docs/okstra/glossary.md` when applied; this
+section records what happened. Decision candidates are NOT recorded
+here — they flow through `Open Questions` as `adr-candidate:` rows for
+`implementation-planning` to evaluate (and, if accepted, draft into
+`<PROJECT_ROOT>/.project-docs/okstra/decisions/`).
+
+- `terminology-mapping: <reporter word> → <okstra glossary canonical>` —
+  routine glossary alignment, paired with `terminology:` in Open Questions
+  when unresolved.
+- `terminology-mapping: applied glossary: <term> → <PROJECT_ROOT>/.project-docs/okstra/glossary.md` /
+  `terminology-mapping: skipped glossary: <term> = <definition>` — Step
+  4.5 outcomes.
+- Use `_(none)_` if every alignment entry is empty.
+
+### Evidence links (file / symbol resolution)
+
+- `evidence-link: <reporter phrase> → <relative path>:<line>` /
+  `evidence-link: <reporter phrase> → <symbol> in <relative path>`
+- `_(none)_` if none.
+
+### Intent inferences
+
+Every entry here is an unverified hypothesis. Each one MUST have a paired
+`intent-check:` row under Open Questions.
+
+- `intent-inference: <reporter phrase> → <qualitative restatement>`
+  (qualitative only — never invent numeric thresholds)
+- `_(none)_` if none.
+
+### Format conversions
+
+- `format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`
+- `_(none)_` if none.
 ````
 
 ### Frontmatter rules
@@ -434,7 +791,7 @@ separated from Source Material — never inline it inside Source Material.
 - `brief-id` must match the filename stem (`<ticket-id>-<file-title>`)
   exactly. If the file is moved/renamed, update both.
 - `parent-id`:
-  - The root (depth 0) brief uses `self` (or its own `brief-id`).
+  - The root (depth 0) brief always uses the literal string `self`.
   - Descendant briefs use the direct parent's `brief-id`.
 - `depth` must equal the number of `sub/` segments in the path (consistency
   check point). On mismatch, the file location wins — correct the
@@ -465,6 +822,110 @@ Write the chosen recommendation into the `Recommended next phase:` header
 line of the brief file (Step 5). Do NOT auto-spawn `okstra-run` — leave the
 trigger to the user.
 
+## Step 6.5: Reporter batch confirmation (option B precondition)
+
+This is the boundary between brief and the downstream phases: every
+question that only the reporter can answer is collected and answered
+**here, once**, so the next phase runs without operator fill-ins.
+
+### 6.5a. Collect reporter-only rows
+
+Scan the finalized brief's `Open Questions` and gather every row prefixed
+with one of these signals — these are the only rows that the codebase
+cannot resolve:
+
+- `intent-check:` (auto-mirrored from `intent-inference` augmentations)
+- `conversion-block:` (translation failed in Step 3c)
+
+If the resulting list is empty, set `reporter-confirmations: complete` in
+the brief's frontmatter and skip the rest of this step.
+
+### 6.5b. Ask once: collect now or later
+
+If the list is non-empty, run **one** `AskUserQuestion`:
+
+- **Label**: `"This brief has <N> question(s) only the reporter can answer. Collect their answers now?"`
+- **Options**:
+  1. `Yes — collect now (Recommended)` — proceed to 6.5c.
+  2. `No — leave for the downstream phase` — set
+     `reporter-confirmations: skipped`. The phase will promote each
+     pending row into its own `## 5. Clarification Items` as
+     `Blocks=next-phase` (`Blocks=approval` only in
+     `implementation-planning`); see each phase profile's "Brief
+     consumption" addendum.
+
+### 6.5c. Batch the questions
+
+For each pending row, formulate one question. Because the
+`AskUserQuestion` tool caps options at 4 per call and questions per call
+also at 4, split into batches of ≤ 4 questions.
+
+**Hard cap — 12 questions per Step 6.5 run.** When the pending list
+exceeds 12 rows, sort by priority and ask only the top 12 this round:
+
+1. `conversion-block:` rows first (translation failure — highest
+   downstream risk).
+2. `intent-check:` rows next, in the order they appear in `Open
+   Questions`.
+
+Any rows beyond the cap are left unanswered in this run; set
+`reporter-confirmations: partial` in the frontmatter and tell the user
+which rows remain. The next `okstra-brief` re-run (or the downstream
+phase that consumes `Blocks=next-phase`) handles the remainder.
+
+Each question carries:
+
+- The reporter-facing phrasing (plain language, no jargon).
+- A recommended answer drawn from the brief's `intent-inference` /
+  `conversion-block:` content, marked `(Recommended)`.
+- 2–3 alternative options when the answer space is naturally enumerable;
+  otherwise a free-text fallback.
+
+### 6.5d. Record verbatim
+
+Create a new top-level section `## Reporter Confirmations` in the brief
+(if not present) with one subsection per answered row:
+
+```markdown
+## Reporter Confirmations
+
+### RC-1 — <intent-check: or conversion-block: row id / topic>
+- asked: <YYYY-MM-DD HH:MM>
+- linked-row: `<exact Open Questions row text>`
+- answer (verbatim):
+
+  > <reporter's answer, byte-for-byte>
+```
+
+Mark the linked `Open Questions` row by appending `[CONFIRMED <YYYY-MM-DD> → RC-N]` to the end of the row's line. Do NOT delete the row — the
+`CONFIRMED` marker keeps the audit trail intact.
+
+For every `intent-inference` augmentation whose paired `intent-check:`
+was confirmed, add one new line directly below the `> augmented:
+intent-inference …` blockquote:
+
+```
+> confirmed-by-reporter: RC-N — <one-line summary of confirmation>
+```
+
+This converts the inference from "unverified hypothesis" to "verified
+hypothesis" without rewriting the original augmentation.
+
+### 6.5e. Frontmatter state
+
+Update `reporter-confirmations` in the brief frontmatter:
+
+- `complete` — every pending row was answered.
+- `partial` — some rows answered, some skipped within this run.
+- `skipped` — user picked option 2 in 6.5b.
+- `pending` — should never appear at this point; if it does, treat the
+  brief as not yet handed off and refuse to proceed.
+
+Step 6.5 ends here. The brief now has either zero pending reporter-only
+rows (`complete` / `partial` with remainder in the same file) or an
+explicit `skipped` signal that downstream phases consume per the
+"Brief consumption" addendum in `_common-contract.md`.
+
 ## Step 7: Hand off
 
 Single brief:
@@ -492,8 +953,14 @@ started.
 
 ## Output Rules
 
-- Never write outside `<PROJECT_ROOT>/.project-docs/okstra/briefs/`.
-- Never write to `.scratch/` — that path belongs to `to-prd` / `to-issues`.
+- All okstra-generated artifacts live under
+  `<PROJECT_ROOT>/.project-docs/okstra/`. This skill's brief files go
+  under `.project-docs/okstra/briefs/`; its glossary writes go to
+  `.project-docs/okstra/glossary.md` (Step 4.5 approval flow).
+- External paths (`<PROJECT_ROOT>/CONTEXT.md`,
+  `<PROJECT_ROOT>/CONTEXT-MAP.md`, `<PROJECT_ROOT>/docs/adr/`,
+  `<PROJECT_ROOT>/.scratch/`) are read-only references. This skill
+  never writes to them. Absent external files are the normal state.
 - **Verbatim source**: never paraphrase, summarize, restructure, or reorder
   the Source Material section. Only format conversion (ADF → MD, HTML → MD)
   is allowed, and the conversion must be annotated in the `format:` meta.
@@ -505,10 +972,10 @@ started.
   paste.
 - Never fabricate content for empty sections; use `_(none)_`.
 - Echo each `AskUserQuestion` outcome on one short line.
-- Aim for ~400 lines per brief total. If the source body is longer, **do
-  not modify** it — instead excerpt key paragraphs with the
-  `[excerpt — full: <URL>]` marker and record the original location in
-  `Related Artifacts`.
+- No line budget overrides the verbatim-source rule. If source content is
+  large, preserve it exactly as separate `Source Material` entries; if a
+  tool only returns a truncated body, ask the user for the missing content
+  or emit a `conversion-block:` row. Never silently excerpt or summarize.
 
 ## Failure Modes