okstra 0.28.0 → 0.30.0

package/runtime/python/okstra_ctl/wizard.py

@@ -73,12 +73,93 @@ GEMINI_MODEL_OPTIONS = ["default", "gemini-3-pro-preview", "gemini-3-flash-previ
 # special pick value: start a brand-new task
 TASK_PICK_NEW_TOKEN = "__new__"
 
+# Pick-vs-free-text tokens shared by suggestion-aware prompts.
+PICK_USE_SUGGESTED = "__use_suggested__"
+PICK_TYPE_CUSTOM = "__free_input__"
+
+# Lines of `key: value` we pull from a brief markdown frontmatter. The
+# parser is intentionally lightweight (no yaml dep) and tolerant — a
+# malformed brief returns an empty dict.
+_BRIEF_FRONTMATTER_LINE_RE = re.compile(r"^([a-zA-Z0-9_\-]+)\s*:\s*(.*)$")
+
+
+def _parse_brief_frontmatter(path: Path) -> dict[str, str]:
+    """Read the YAML-style frontmatter at the top of a brief markdown file
+    and return a flat ``{key: value}`` map.
+
+    Returns ``{}`` if the file is unreadable, has no frontmatter, or the
+    frontmatter is malformed. Comments (``# ...``) and quoted values are
+    stripped. Placeholder values like ``<task-group>`` are kept verbatim;
+    callers decide whether to treat them as a real suggestion.
+    """
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return {}
+    if not text.startswith("---"):
+        return {}
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        return {}
+    out: dict[str, str] = {}
+    for line in lines[1:]:
+        if line.strip() == "---":
+            break
+        # strip trailing inline comment
+        comment_idx = line.find("#")
+        if comment_idx >= 0:
+            line = line[:comment_idx]
+        m = _BRIEF_FRONTMATTER_LINE_RE.match(line.strip())
+        if not m:
+            continue
+        key, val = m.group(1), m.group(2).strip()
+        # strip matching quotes
+        if (len(val) >= 2 and val[0] == val[-1] and val[0] in ("'", '"')):
+            val = val[1:-1]
+        out[key] = val
+    return out
+
+
+def _looks_like_template_placeholder(value: str) -> bool:
+    """Treat ``<task-group>``, ``<...>``, empty strings, and ``self`` as
+    non-suggestions. Anything else (a real slug-like value) is honored."""
+    v = (value or "").strip()
+    if not v:
+        return True
+    if v.startswith("<") and v.endswith(">"):
+        return True
+    if v.lower() in ("self", "tbd", "n/a", "na", "none"):
+        return True
+    return False
+
+
+def _brief_suggestions(path: Path) -> tuple[str, str]:
+    """Return ``(task_group_suggestion, task_id_suggestion)`` extracted from
+    the brief's frontmatter, or empty strings when no usable value exists.
+
+    - ``task_group`` ← frontmatter ``task-group``.
+    - ``task_id``    ← frontmatter ``brief-id`` (which matches the
+                       filename stem in okstra-brief output and is the
+                       strongest single identifier of the task).
+
+    A brief without frontmatter, or with placeholder values, yields two
+    empty strings — callers fall back to plain-text input.
+    """
+    fm = _parse_brief_frontmatter(path)
+    tg_raw = fm.get("task-group", "")
+    bid_raw = fm.get("brief-id", "")
+    tg = "" if _looks_like_template_placeholder(tg_raw) else tg_raw
+    tid = "" if _looks_like_template_placeholder(bid_raw) else bid_raw
+    return tg, tid
+
 
 # ---- Step IDs ------------------------------------------------------------
 
 S_TASK_PICK = "task_pick"
 S_TASK_GROUP = "task_group"
+S_TASK_GROUP_TEXT = "task_group_text"
 S_TASK_ID = "task_id"
+S_TASK_ID_TEXT = "task_id_text"
 S_TASK_TYPE = "task_type"
 S_BRIEF_KEEP = "brief_keep"
 S_BRIEF_PATH = "brief_path"
@@ -123,6 +204,13 @@ class WizardState:
     task_group: str = ""
     task_id: str = ""
     existing_brief_path: str = ""
+    # brief-derived suggestions (new-task flow only; set when brief is
+    # accepted, cleared if the user picks "type custom" so the next
+    # `_build_*` falls back to plain text input)
+    task_group_suggestion: str = ""
+    task_id_suggestion: str = ""
+    task_group_pending_text: bool = False
+    task_id_pending_text: bool = False
 
     # task-type + dependents
     task_type: str = ""
@@ -421,24 +509,98 @@ def _submit_task_pick(state: WizardState, value: str) -> Optional[str]:
 
 
 def _build_task_group(state: WizardState) -> Prompt:
+    sugg = state.task_group_suggestion
+    if sugg:
+        return Prompt(
+            step=S_TASK_GROUP, kind="pick",
+            label=f"Task group? (brief 추천: {sugg})",
+            options=[
+                _opt(PICK_USE_SUGGESTED, f"brief 값 사용: {sugg}"),
+                _opt(PICK_TYPE_CUSTOM, "다른 값 입력"),
+            ],
+            echo_template="task-group: {value}",
+        )
     return Prompt(step=S_TASK_GROUP, kind="text",
                   label="Task group 을 알려주세요 (예: backend-api, INV-1234, refactor)",
                   echo_template="task-group: {value}")
 
 
 def _submit_task_group(state: WizardState, value: str) -> Optional[str]:
+    if state.task_group_suggestion:
+        if value == PICK_USE_SUGGESTED:
+            state.task_group = _slug_or_die(
+                state.task_group_suggestion, "task_group"
+            )
+            state.task_group_pending_text = False
+            return f"task-group: {state.task_group} (brief)"
+        if value == PICK_TYPE_CUSTOM:
+            state.task_group_pending_text = True
+            return f"task-group: (직접 입력)"
+        raise WizardError(
+            f"expected {PICK_USE_SUGGESTED!r} or {PICK_TYPE_CUSTOM!r}, "
+            f"got: {value!r}"
+        )
+    state.task_group = _slug_or_die(value, "task_group")
+    state.task_group_pending_text = False
+    return f"task-group: {state.task_group}"
+
+
+def _build_task_group_text(state: WizardState) -> Prompt:
+    return Prompt(step=S_TASK_GROUP_TEXT, kind="text",
+                  label="Task group 을 입력해주세요 (예: backend-api, INV-1234, refactor)",
+                  echo_template="task-group: {value}")
+
+
+def _submit_task_group_text(state: WizardState, value: str) -> Optional[str]:
     state.task_group = _slug_or_die(value, "task_group")
+    state.task_group_pending_text = False
     return f"task-group: {state.task_group}"
 
 
 def _build_task_id(state: WizardState) -> Prompt:
+    sugg = state.task_id_suggestion
+    if sugg:
+        return Prompt(
+            step=S_TASK_ID, kind="pick",
+            label=f"Task id? (brief 추천: {sugg})",
+            options=[
+                _opt(PICK_USE_SUGGESTED, f"brief 값 사용: {sugg}"),
+                _opt(PICK_TYPE_CUSTOM, "다른 값 입력"),
+            ],
+            echo_template="task-id: {value}",
+        )
     return Prompt(step=S_TASK_ID, kind="text",
                   label="Task id 를 알려주세요 (예: login-error-analysis, dev-9043)",
                   echo_template="task-id: {value}")
 
 
 def _submit_task_id(state: WizardState, value: str) -> Optional[str]:
+    if state.task_id_suggestion:
+        if value == PICK_USE_SUGGESTED:
+            state.task_id = _slug_or_die(state.task_id_suggestion, "task_id")
+            state.task_id_pending_text = False
+            return f"task-id: {state.task_id} (brief)"
+        if value == PICK_TYPE_CUSTOM:
+            state.task_id_pending_text = True
+            return f"task-id: (직접 입력)"
+        raise WizardError(
+            f"expected {PICK_USE_SUGGESTED!r} or {PICK_TYPE_CUSTOM!r}, "
+            f"got: {value!r}"
+        )
     state.task_id = _slug_or_die(value, "task_id")
+    state.task_id_pending_text = False
+    return f"task-id: {state.task_id}"
+
+
+def _build_task_id_text(state: WizardState) -> Prompt:
+    return Prompt(step=S_TASK_ID_TEXT, kind="text",
+                  label="Task id 를 입력해주세요 (예: login-error-analysis, dev-9043)",
+                  echo_template="task-id: {value}")
+
+
+def _submit_task_id_text(state: WizardState, value: str) -> Optional[str]:
+    state.task_id = _slug_or_die(value, "task_id")
+    state.task_id_pending_text = False
     return f"task-id: {state.task_id}"
 
 
@@ -502,6 +664,14 @@ def _build_brief_path(state: WizardState) -> Prompt:
 def _submit_brief_path(state: WizardState, value: str) -> Optional[str]:
     p = _require_file(value, Path(state.project_root), "task brief")
     state.brief_path = str(p)
+    # When the user is starting a brand-new task, pull task-group /
+    # task-id candidates from the brief frontmatter so the next two
+    # prompts can offer them as a one-click pick instead of forcing a
+    # free-text retype of what the brief already declares.
+    if state.is_new_task and not state.task_group and not state.task_id:
+        tg, tid = _brief_suggestions(p)
+        state.task_group_suggestion = tg
+        state.task_id_suggestion = tid
     return f"brief: {p}"
 
 
@@ -1002,15 +1172,57 @@ STEPS: list[Step] = [
          applies=lambda s: s.is_new_task is None,
          build=_build_task_pick, submit=_submit_task_pick,
          owns=("is_new_task", "task_group", "task_id", "task_type",
-               "existing_brief_path", "profile_workers")),
+               "existing_brief_path", "profile_workers",
+               "task_group_suggestion", "task_id_suggestion",
+               "task_group_pending_text", "task_id_pending_text")),
+    Step(S_BRIEF_PATH,
+         applies=lambda s: (
+             not s.brief_path
+             and (
+                 # new-task flow: collect brief FIRST so task-group /
+                 # task-id can be offered as one-click picks from the
+                 # brief's frontmatter.
+                 (s.is_new_task is True)
+                 # existing-task flow: brief comes after task-type and
+                 # the optional brief-keep step (unchanged behavior).
+                 or (s.is_new_task is False
+                     and S_TASK_TYPE in s.answered
+                     and (s.keep_existing_brief is False
+                          or not s.existing_brief_path))
+             )
+         ),
+         build=_build_brief_path, submit=_submit_brief_path,
+         owns=("brief_path", "task_group_suggestion", "task_id_suggestion")),
     Step(S_TASK_GROUP,
-         applies=lambda s: bool(s.is_new_task) and not s.task_group,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and not s.task_group
+                            and not s.task_group_pending_text),
          build=_build_task_group, submit=_submit_task_group,
-         owns=("task_group",)),
+         owns=("task_group", "task_group_pending_text")),
+    Step(S_TASK_GROUP_TEXT,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and not s.task_group
+                            and s.task_group_pending_text),
+         build=_build_task_group_text, submit=_submit_task_group_text,
+         owns=("task_group", "task_group_pending_text")),
     Step(S_TASK_ID,
-         applies=lambda s: bool(s.is_new_task) and bool(s.task_group) and not s.task_id,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and bool(s.task_group)
+                            and not s.task_id
+                            and not s.task_id_pending_text),
          build=_build_task_id, submit=_submit_task_id,
-         owns=("task_id",)),
+         owns=("task_id", "task_id_pending_text")),
+    Step(S_TASK_ID_TEXT,
+         applies=lambda s: (bool(s.is_new_task)
+                            and bool(s.brief_path)
+                            and bool(s.task_group)
+                            and not s.task_id
+                            and s.task_id_pending_text),
+         build=_build_task_id_text, submit=_submit_task_id_text,
+         owns=("task_id", "task_id_pending_text")),
     Step(S_TASK_TYPE,
          applies=lambda s: (s.is_new_task is not None
                             and (s.is_new_task is False or bool(s.task_id))
@@ -1023,15 +1235,7 @@ STEPS: list[Step] = [
                             and s.keep_existing_brief is None
                             and S_TASK_TYPE in s.answered),
          build=_build_brief_keep, submit=_submit_brief_keep,
-         owns=("keep_existing_brief", "brief_path")),
-    Step(S_BRIEF_PATH,
-         applies=lambda s: (S_TASK_TYPE in s.answered
-                            and not s.brief_path
-                            and (s.is_new_task
-                                 or s.keep_existing_brief is False
-                                 or (not s.is_new_task and not s.existing_brief_path))),
-         build=_build_brief_path, submit=_submit_brief_path,
-         owns=("brief_path",)),
+         owns=("keep_existing_brief",)),
     Step(S_BASE_REF_PICK,
          applies=lambda s: (S_TASK_TYPE in s.answered
                             and s.reuse_worktree is False
@@ -1240,6 +1444,8 @@ def _reset_from(state: WizardState, target_step: str) -> None:
 _FIELD_DEFAULTS: dict[str, Any] = {
     "is_new_task": None, "task_group": "", "task_id": "",
     "existing_brief_path": "", "task_type": "",
+    "task_group_suggestion": "", "task_id_suggestion": "",
+    "task_group_pending_text": False, "task_id_pending_text": False,
     "profile_workers": [], "keep_existing_brief": None,
     "brief_path": "", "reuse_worktree": None, "base_ref": "",
     "base_ref_pending_text": False, "approved_plan_path": "",

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

@@ -648,11 +648,15 @@ reporter-confirmations: <complete | partial | pending | skipped>  # set by Step
 > 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)
+## 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.
+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>
 
@@ -665,30 +669,31 @@ must be annotated in the header meta.
 <Paste the raw source here without changing a single character.>
 ```
 
-### Source 2 — ...
-
-(Repeat as needed.)
+<!-- 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 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 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
-above.>
+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.>
+<Shape of success.>
+
+<!-- Do NOT prescribe a solution — that belongs to implementation-planning. -->
 
 ## Constraints
 
@@ -701,14 +706,18 @@ none.>
 
 ## 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`
+- `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`
+- `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`.
@@ -718,11 +727,14 @@ Use `_(none)_` only if every signal is empty. `intent-check:` and
 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.
+<!-- 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)_
 
@@ -737,6 +749,7 @@ _(none — pending or skipped)_
 
 ## 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.
@@ -744,44 +757,59 @@ 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
 
-Observations from Step 3b and the outcome of Step 4.5 (glossary
-applied vs. skipped). The actual glossary edits live in
+<!-- 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
+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.
+- `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)
 
-- `evidence-link: <reporter phrase> → <relative path>:<line>` /
-  `evidence-link: <reporter phrase> → <symbol> in <relative path>`
-- `_(none)_` if none.
+<!-- 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.
+<!-- 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. -->
 
-- `intent-inference: <reporter phrase> → <qualitative restatement>`
-  (qualitative only — never invent numeric thresholds)
-- `_(none)_` if none.
+- <fill in one entry per inference, or replace with `_(none)_`>
 
 ### Format conversions
 
-- `format-conversion: <ref> — <e.g. Jira ADF → Markdown, semantics preserved>`
-- `_(none)_` if none.
+<!-- 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)_`>
 ````
 
 ### Frontmatter rules
@@ -966,6 +994,16 @@ started.
   is allowed, and the conversion must be annotated in the `format:` meta.
   Augmentation / interpretation goes only into the `Augmentation` section
   or a `> augmented:` blockquote inside the required section.
+- **No template author-guidance in the artifact body.** The Step 5
+  template above carries author guidance in HTML comments
+  (`<!-- ... -->`); preserve those comments when writing the brief but do
+  NOT promote them to body prose. Section headings stay clean — never copy
+  parenthetical reviewer notes onto the heading itself (e.g. emit
+  `## Source Material`, not `## Source Material (verbatim — do not modify)`).
+  Placeholder prose inside angle brackets (`<Background / scope / why
+  now…>`) is intentional and is meant to be replaced with the reporter's
+  actual content; do not strip the angle-bracket placeholders, replace
+  them.
 - If the tracker MCP is not connected, do not guess — ask the user to paste
   the body or skip the source.
 - If a URL fetch fails or hits an auth wall, do not guess — ask for a

package/runtime/skills/okstra-report-writer/SKILL.md

@@ -83,7 +83,19 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    ```
 
    The 10 substituted placeholders: `{{LEAD_TOTAL_TOKENS}}`, `{{LEAD_BILLABLE_TOKENS}}`, `{{LEAD_COST_USD}}`, `{{WORKER_TOTAL_TOKENS}}`, `{{WORKER_BILLABLE_TOKENS}}`, `{{WORKER_COST_USD}}`, `{{GRAND_TOTAL_TOKENS}}`, `{{GRAND_BILLABLE_TOKENS}}`, `{{GRAND_COST_USD}}`, `{{CLI_COST_USD}}`. The final-report file MUST already exist (Phase 6 output).
-3. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 7 is non-empty). Turns the report's `## 7. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
+3. **Phase 7 step 1.5 — Render report views** (BLOCKING). Produces two derived artifacts from the now-substituted final-report MD:
+
+   ```bash
+   python3 scripts/okstra-render-report-views.py \
+     <runDirectoryPath>/reports/final-report-<task-type>-<seq>.md
+   ```
+
+   Outputs (idempotent — re-running overwrites):
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.slim.md` — token-saving AI-consumption copy.
+   - `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` — single-file self-contained human view. Section 5 `C-*` clarification rows with `Status` ∈ {`open`, `answered`} embed `<textarea>` controls; an `Export user response` button serialises form values to a markdown sidecar (schema in [`templates/reports/user-response.template.md`](../../templates/reports/user-response.template.md)) that the user pastes to `runs/<task-type>/user-responses/user-response-<task-type>-<seq>.md`. The original final-report MD is **never** mutated by user input — the sidecar is the single write target.
+
+   Must run AFTER step 1 (so token placeholders are substituted in both derived views) and BEFORE step 2 (so the slim/html artifacts exist for any validator step that checks them).
+4. **Phase 7 step 2 — Follow-up task spawner** (BLOCKING when Section 7 is non-empty). Turns the report's `## 7. Follow-up Tasks (후속 작업)` rows into `tasks/<task-group>/<new-task-id>/` stubs.
 
    ```bash
    python3 scripts/okstra-spawn-followups.py \
@@ -98,7 +110,7 @@ The four steps below MUST execute in this exact order. Reordering them is the re
    - Rows with `Auto-spawn? != yes` are reported as `skipped` and never written; surface them in Section 6 if manual action is still needed.
    - An invalid `Origin`, `Suggested task-type`, missing `Title`, or missing `Reason / Why deferred` exits `1`. The report-writer MUST refuse to ship a Section 7 with such rows.
    - **Canonical spawn rule (single source of truth):** the spawner runs when `task-type` ∈ {`implementation`, `final-verification`, `release-handoff`}, OR when Section 7 is non-empty for any other task-type. For the listed task-types Section 7 must be present in the report; an empty section renders as `- 후속 작업 없음.`. Missing / empty sections are no-ops (exit `0`). All other references to this rule (including the Persistence Checklist) defer to this statement.
-4. **Phase 7 step 3 — Update Section 6** after the spawner. The report-writer MUST append one row per newly spawned task-key with its entry command:
+5. **Phase 7 step 3 — Update Section 6** after the spawner. The report-writer MUST append one row per newly spawned task-key with its entry command:
 
    ```
    - Follow-up: `<task-group>/<new-task-id>` — Claude Code 세션 안 `/okstra-run task-key=<task-group>/<new-task-id> task-type=<suggested>` / 별도 터미널 `scripts/okstra.sh --task-key <task-group>/<new-task-id> --task-type <suggested>`
@@ -117,7 +129,8 @@ The final report follows the structure below. If `instruction-set/final-report-t
 - Date: <ISO 8601 timestamp>
 - Task Key: <task-key>
 - Task Type: <task-type>
-- Author: `<Report writer worker if in roster, else Claude lead>`
+- Report Owner: `Claude lead`
+- Report Author: `<Report writer worker if in roster, else Claude lead (release-handoff or recorded-fallback only)>`
 - Lead model: `<lead-model>`
 - Preparation Method: Final report authored by Report writer worker (or lead-authored fallback — record the documented dispatch failure reason here when applicable)
 ```
@@ -208,7 +221,7 @@ The final-report template `okstra-final-report.template.md` Section 2 already en
 
 ### Release-handoff section contract (release-handoff runs only)
 
-When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all seven sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Pull Request Outcome, `4.6.7` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
+When the run's `task-type` is `release-handoff`, the final report MUST include Section `## 4.6 Release Handoff Deliverables` with all eight sub-sections (`4.6.1` Source Verification Report, `4.6.2` Feature Branch & Working-Tree State, `4.6.3` User Selections, `4.6.4` Executed Commands, `4.6.5` Commit List, `4.6.6` Merge Conflict Probe, `4.6.7` Pull Request Outcome, `4.6.8` Routing Recommendation). Every entry is dictated by the lead's recorded git/gh command log and the user's verbatim answers to the H1/H2/H3 menu prompts. H1 choices are `local only`, `push + PR`, or `skip`; release-handoff records existing implementation commits and MUST NOT create new commits. If the user picked `skip` (H1) or `cancel` (H3), keep 4.6.3 populated but leave 4.6.4–4.6.6 explicitly empty per the template's empty-state lines.
 
 **Single-lead authorship (release-handoff only):** release-handoff has no worker roster (no `Report writer worker`, no `Claude worker` drafter). The Claude lead authors the final-report file directly — there is no `Report writer worker` dispatch to perform in Phase 6, no resume-safe dispatch concern, and no mandatory worker-results file for a report-writer role. The rest of this skill's dispatch / resume / fallback machinery applies ONLY when `Report writer worker` is in the roster (i.e. every task-type other than `release-handoff`).
 
@@ -278,6 +291,8 @@ Persistence steps that must be performed in Phase 7:
 - [ ] 6. **Generate final status file**: `runs/<task-type>/status/final-<task-type>-<seq>.status` (if necessary)
 - [ ] 7. **Save convergence state**: `runs/<task-type>/state/convergence-<task-type>-<seq>.json` (when convergence is enabled)
 - [ ] 8. **Spawn follow-up task stubs**: run `scripts/okstra-spawn-followups.py` against the final-report per the canonical spawn rule defined in "Phase 7 follow-up task spawner" above. Do not restate the trigger condition here — that section is the single source of truth. The script is idempotent across reruns.
+- [ ] 9. **Slim AI report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.slim.md` (produced by Phase 7 step 1.5 — see "Phase 6 → Phase 7 execution sequence" above)
+- [ ] 10. **Human HTML report**: `runs/<task-type>/reports/final-report-<task-type>-<seq>.html` (same step 1.5; self-contained, embeds `Export user response` button)
 
 ### Response after Persistence
 

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -213,7 +213,7 @@ Terminal statuses that can be recorded for a worker:
 
 **Authoritative source.** If other documents (SKILL.md, worker agent definitions) disagree with this section, this section wins.
 
-### Result Frontmatter (mandatory, precedes Section 0)
+### Result Frontmatter (mandatory, precedes Section 1)
 
 Every worker result file MUST begin with a YAML frontmatter block. The values are sourced from the corresponding fields of the input files' frontmatter (e.g. `analysis-material.md`, `task-brief.md`) — copy them verbatim; do NOT regenerate them. Only `workerId` and `title` are worker-specific.
 
@@ -260,11 +260,8 @@ The same frontmatter contract applies to the `Report writer worker`'s final-repo
 
 A successful worker result must include the following sections in this exact order, beneath the frontmatter block:
 
-0. **Reading Confirmation** — one short line per input file stating that the worker read it end-to-end. Each line takes the form `- Read <file-name> end-to-end (<line-count> lines).`. The enumerated files are audience-scoped — they MUST match the recipient's row in the "Audience-scoped enumeration" table above:
-   - **Claude / Codex / Gemini analysis workers**: `task-brief.md`, `analysis-profile.md`, `analysis-material.md` (if present), `reference-expectations.md`, `clarification-response.md` (if a carry-in was provided). Analysis workers MUST NOT include `final-report-template.md` — it is not in their `[Required reading]` block.
-   - **Report writer worker (Phase 6)**: all of the above **plus** `final-report-template.md`.
+> **Reading Confirmation lives in the audit sidecar, NOT in the main worker result.** Section 0 is intentionally absent from the main file. The worker writes Reading Confirmation to `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md` per the dispatch-prompt clause above; the validator FAILS any main worker-result file that contains a `## 0. Reading Confirmation` heading. If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5 — instead it records a `tool-failure` in the errors sidecar and stops.
 
-   If a file was skipped or only partially read, the worker MUST NOT produce sections 1–5; instead it records a `tool-failure` in the errors sidecar and stops. This section exists specifically to counteract the common failure mode where workers skim long inputs because they share structure with the file the run will eventually write into.
 1. Findings
 2. Missing Information or Assumptions
 3. Safe or Reasonable Areas