okstra 0.36.0 → 0.36.2

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

@@ -676,218 +676,9 @@ Use the same template per brief file. In tracker mode producing a parent
 plus N children, you write **N+1 files** (each carries only its own Source
 Material).
 
-Use this exact template. Leave a section's body as `_(none)_` rather than
-fabricating content. (The outer fence uses 4 backticks so it does not
-collide with the inner 3-backtick code block.)
+[`templates/reports/brief.template.md`](../../templates/reports/brief.template.md) is the byte-for-byte SSOT for the brief shape — frontmatter keys, top-header blockquote, section ordering, and inline `<!-- author guidance -->` HTML comments. Render that file with the per-brief values substituted; leave any section's body as `_(none)_` rather than fabricating content. Preserve the template's HTML comments verbatim (they are part of the contract) but do NOT promote them to body prose.
 
-````markdown
----
-type: brief
-brief-id: <ticket-id>-<file-title>          # equals the filename stem
-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
-# codebase-scan variant frontmatter (omit for reporter-input briefs):
-scope: <reporter-input | codebase>              # 'codebase' for codebase-scan variant; omit for reporter-input variant
-priority-lenses: []                              # codebase-scan only: lens enum subset, size 1..4
-scan-scope: []                                   # codebase-scan only: 1+ paths
-out-of-scope: []                                 # codebase-scan only: optional
-candidate-cap: 8                                 # codebase-scan only: 1..12, default 8
----
-
-# Task Brief: <task_group>/<filename-without-ext>
-
-> Generated: okstra-brief · <YYYY-MM-DD>
-> Source type: <file | linear | jira | github | notion | url | user-input>
-> 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
-
-<!-- author guidance — strip out at fill-in time:
-Paste each source separately and as-is. No paraphrasing, summarizing, or
-restructuring. Format conversion (e.g. Jira ADF → Markdown) is allowed and
-must be annotated in the header meta. Heading was originally
-"Source Material (verbatim — do not modify)" — the parenthetical is a
-reviewer note, not body text.
--->
-
-### Source 1 — <type: file | linear | jira | github | notion | url | user-input>
-
-- 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">
-
-```
-<Paste the raw source here without changing a single character.>
-```
-
-<!-- Repeat `### Source N — …` blocks as needed. -->
-
-## Context
-
-<Background / scope / why now. If self-evident from Source Material, quote
-it briefly and stop. Use the blockquote below when augmentation is needed.>
-
-> 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 the `> augmented:` blockquote. -->
-
-## Problem / Symptom
-
-<Current state. For bugs: repro / observed / expected. For greenfield: gap
-between current and desired.>
-
-<!-- Same source-quote + `> augmented:` rule as the Context section. -->
-
-## Desired Outcome
-
-<Shape of success.>
-
-<!-- Do NOT prescribe a solution — that belongs to implementation-planning. -->
-
-## Constraints
-
-<Deadlines, compatibility, technical/operational limits. Use _(none)_ if
-none.>
-
-## Scan Scope
-
-<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
-<!-- Author guidance: one bullet per `scan-scope` path with a short description of what lives there. -->
-
-- <path>: <one-line description of contents / responsibility>
-
-## Priority Lenses
-
-<!-- codebase-scan variant only — omit this section for reporter-input briefs. -->
-<!-- Author guidance: one bullet per priority lens explaining why it is a priority for THIS scope. -->
-
-- <lens>: <short rationale tying this lens to the scope's risk surface>
-
-## Related Artifacts
-
-- <file path / URL / issue / prior task-key>
-
-## Open Questions
-
-<!-- author guidance — strip out at fill-in time:
-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:`.
-
-Allowed signals:
-- `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`.
--->
-
-- <fill in one row per signal, or replace with `_(none)_`>
-
-## 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
-
-<!-- author guidance — strip out at fill-in time:
-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.
-
-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
-
-<!-- author guidance — strip out at fill-in time:
-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/`).
-
-Allowed entry shapes:
-- `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.
--->
-
-- <fill in one entry per alignment, or replace with `_(none)_`>
-
-### Evidence links (file / symbol resolution)
-
-<!-- Allowed entry shapes:
-`evidence-link: <reporter phrase> → <relative path>:<line>` or
-`evidence-link: <reporter phrase> → <symbol> in <relative path>`.
-Use `_(none)_` if none. -->
-
-- <fill in one entry per link, or replace with `_(none)_`>
-
-### Intent inferences
-
-<!-- Every entry here is an unverified hypothesis. Each one MUST have a
-paired `intent-check:` row under Open Questions.
-
-Allowed entry shape:
-`intent-inference: <reporter phrase> → <qualitative restatement>`
-(qualitative only — never invent numeric thresholds).
-Use `_(none)_` if none. -->
-
-- <fill in one entry per inference, or replace with `_(none)_`>
-
-### Format conversions
-
-<!-- Allowed entry shape:
-`format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`.
-Use `_(none)_` if none. -->
-
-- <fill in one entry per conversion, or replace with `_(none)_`>
-````
-
-**Variant note:** The template above is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, ADD `## Scan Scope` and `## Priority Lenses` sections (already present in the template above, marked with HTML comments). The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to both variants.
+**Variant note:** The template file is the canonical reporter-input shape. For the codebase-scan variant (`scope: codebase` in frontmatter), OMIT the `## Source Material` and `## Problem / Symptom` headings entirely — do NOT include them with `_(none)_` bodies. Instead, KEEP the `## Scan Scope` and `## Priority Lenses` sections (already present in the template file, marked with HTML comments). The remaining sections (Context / Desired Outcome / Constraints / Related Artifacts / Open Questions / Reporter Confirmations / Augmentation) apply to both variants.
 
 ### Required sections by variant