okstra 0.201.3 → 0.204.0

package/runtime/validators/validate-brief.py

@@ -47,6 +47,10 @@ Checks performed per brief file:
     it is checked by `okstra_ctl.group_context.validate_group_context` (four
     required sections, no template placeholder left, directory slug matches
     the frontmatter `task-group`). Any other `type` is a failure.
+16. No required section except `## Source Material` still carries the
+    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.
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -104,6 +108,10 @@ AUGMENTATION_LABELS = {
 
 REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 
+# okstra-manager `task split` renders the same brief contract for each project
+# it splits a tracker issue into.
+GENERATORS = {"okstra-brief-gen", "okstra-manager"}
+
 SCOPE_VALUES = {"reporter-input", "codebase"}
 
 TASK_GRAPH_HEADER = ["From", "Relation", "To", "Direction", "Source", "Impact"]
@@ -652,6 +660,71 @@ def check_variant_required_sections(
             )
 
 
+# 템플릿의 `<...>` 문구는 작성자가 바꿔 쓸 자리다. 그대로 남으면 다음 phase 가
+# 그 문구를 제보 내용으로 읽는다. 문구는 여러 줄에 걸친 한 문단이라 줄 단위
+# `is_template_example` 만으로는 잡히지 않는다 — 문단을 합쳐서 본다.
+_AUGMENTED_LABEL_SCAFFOLD_RE = re.compile(r"^>\s*augmented:\s*<label>")
+
+
+def _paragraphs_outside_fences(body: str) -> Iterable[list[str]]:
+    paragraph: list[str] = []
+    in_fence = False
+    for line in body.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("```"):
+            in_fence = not in_fence
+        if in_fence or stripped.startswith("```") or not stripped:
+            if paragraph:
+                yield paragraph
+                paragraph = []
+            continue
+        paragraph.append(stripped)
+    if paragraph:
+        yield paragraph
+
+
+def template_scaffold(body: str) -> list[str]:
+    """Template scaffolding left in a section body, one entry per leftover."""
+    found: list[str] = []
+    for paragraph in _paragraphs_outside_fences(body):
+        joined = " ".join(paragraph)
+        if joined.startswith("<") and joined.endswith(">"):
+            found.append(joined)
+            continue
+        found.extend(
+            line
+            for line in paragraph
+            if is_template_example(line) or _AUGMENTED_LABEL_SCAFFOLD_RE.match(line)
+        )
+    return found
+
+
+def check_template_scaffold(text: str, scope: str, errors: list[str]) -> None:
+    """Required sections must not keep the template's `<...>` scaffolding.
+
+    `## Source Material` is exempt: it holds the reporter's words verbatim,
+    and those can legitimately contain angle-bracketed text.
+    """
+    headings = [
+        REQUIREMENT_SECTION,
+        *ALWAYS_REQUIRED_SECTIONS,
+        _GATE_SECTION,
+        *(heading for heading, _prefix in _END_STATE_SECTIONS),
+    ]
+    if scope == "codebase":
+        headings += ["Scan Scope", "Priority Lenses"]
+    else:
+        headings.append("Problem / Symptom")
+    for heading in headings:
+        leftover = template_scaffold(section_body(text, heading))
+        if leftover:
+            errors.append(
+                f"'## {heading}' still carries template text {leftover[0][:60]!r} — "
+                "replace it with the brief's content, or _(none)_ when the section "
+                "is deliberately empty. Downstream phases read this section as written"
+            )
+
+
 def check_reporter_confirmations(
     rc_status: str | None, reporter_rows: list[str], errors: list[str]
 ) -> None:
@@ -693,9 +766,10 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     if fm.get("type") != "brief":
         errors.append(f"frontmatter type must be 'brief', got {fm.get('type')!r}")
 
-    if fm.get("generator") != "okstra-brief-gen":
+    if fm.get("generator") not in GENERATORS:
         errors.append(
-            f"frontmatter generator must be 'okstra-brief-gen', got {fm.get('generator')!r}"
+            f"frontmatter generator must be one of {sorted(GENERATORS)}, "
+            f"got {fm.get('generator')!r}"
         )
 
     if fm.get("reporter-confirmations") not in REPORTER_CONFIRMATION_VALUES:
@@ -719,6 +793,7 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     check_requirement_section(text, errors)
     check_end_state_sections(text, scope, errors)
     check_variant_required_sections(text, scope, errors)
+    check_template_scaffold(text, scope, errors)
 
     # 2. brief-id matches filename stem
     stem = path.stem

package/runtime/validators/validate-implementation-plan-stages.py

@@ -34,6 +34,7 @@ from okstra_ctl.stage_map import (  # noqa: E402
     parse_stage_dependencies,
     parse_stage_map_text,
     schema_v2_report,
+    stage_number_gap_message,
 )
 
 HARD_STEP_CAP = 8
@@ -86,7 +87,7 @@ def _stage_numbers_monotonic(
 ) -> List[ValidationError]:
     return [
         ValidationError("S2", r.stage_number,
-            f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}")
+            stage_number_gap_message(r.stage_number, i))
         for i, r in enumerate(stages, start=1)
         if r.stage_number != i
     ]

package/runtime/validators/validate-run.py

@@ -43,6 +43,7 @@ from okstra_project.resolver import resolve_architecture  # noqa: E402
 from okstra_ctl.conformance import (  # noqa: E402
     conformance_result_file,
     detect_surfaces,
+    declared_stage_surface_gaps,
     exempt_stage_surface_conflicts,
     evaluate_conformance,
     manifest_required_surfaces,
@@ -2120,7 +2121,13 @@ def _declared_conformance_errors(
             and all(isinstance(value, str) for value in actual_requires)
             else None
         )
-        if actual_capabilities != frozenset(declaration.get("requires") or []):
+        # 넓히는 것만 허용한다 — 선언보다 많은 capability 는 더 엄격한 검증이다.
+        # 승인된 계획이 `requires` 를 좁게 적고 그 stage 의 diff 가 다른 표면을
+        # 건드리면, diff-surface 대조는 넓힐 것을 요구하는데 정확 일치는 그것을
+        # 거절해 같은 계획으로는 통과할 입력이 없었다(2026-09-22 dev-10860
+        # Stage 1). 좁히는 것은 선언한 검증을 빼는 것이므로 여전히 불일치다.
+        declared_capabilities = frozenset(declaration.get("requires") or [])
+        if actual_capabilities is None or not actual_capabilities >= declared_capabilities:
             errors.append(f"stage {stage_number} requires mismatch")
     # 계획이 면제한 stage 에 구현이 실제 Tier 3 항목을 붙이는 것은 허용한다 —
     # 면제 stage 의 diff 가 db/io/http/external 표면을 건드려 diff-surface 대조에
@@ -2183,6 +2190,24 @@ def _project_surface_patterns(project_root: Path) -> object:
         return None
 
 
+def _implemented_stages(data_path: Path) -> frozenset[int]:
+    """이 태스크에서 구현이 끝난 stage. 원장을 못 읽으면 빈 집합이다."""
+    from okstra_ctl.consumers import read_stage_consumer_state
+
+    try:
+        state = read_stage_consumer_state(data_path.parent.parent)
+    except (OSError, UnicodeError, ValueError):
+        return frozenset()
+    return frozenset(state.done_stages)
+
+
+def _is_implemented_stage(stage: object, implemented: frozenset[int]) -> bool:
+    number = stage.get("stage") if isinstance(stage, dict) else None
+    return isinstance(number, int) and not isinstance(number, bool) and (
+        number in implemented
+    )
+
+
 def _validate_planning_conformance_declared(
     report_path: Path,
     failures: list[str],
@@ -2209,7 +2234,17 @@ def _validate_planning_conformance_declared(
     ip = data.get("implementationPlanning")
     if not isinstance(ip, dict):
         return
-    _planning_conformance_declarations(ip.get("stages"), failures)
+    # 구현이 끝난 stage 는 이 게이트의 대상이 아니다. 그 본문은 다음 계획 run 에
+    # 그대로 이월되고(ADR-0015), 이월된 본문은 고칠 수 없다 — 규칙이 그 사이에
+    # 넓어졌다면 통과 가능한 값이 없는 요구가 된다(2026-09-24, dev-10860: 이월된
+    # stage 2·3·5 가 오늘의 표면 패턴으로 `requires` 누락 판정).
+    implemented = _implemented_stages(data_path)
+    stages = [
+        stage
+        for stage in ip.get("stages") or ()
+        if not _is_implemented_stage(stage, implemented)
+    ]
+    _planning_conformance_declarations(stages, failures)
     if ip.get("planningContract") != "selected-direction":
         from okstra_ctl.implementation_direction import (
             stage_validation_executability_errors,
@@ -2217,6 +2252,8 @@ def _validate_planning_conformance_declared(
 
         failures.extend(stage_validation_executability_errors(ip))
     for conflict in exempt_stage_surface_conflicts(data, surface_patterns):
+        if conflict["stage"] in implemented:
+            continue
         failures.append(
             "conformance gate BLOCKING: stage "
             f"{conflict['stage']} declares `Conformance exemption:` but its "
@@ -2229,6 +2266,19 @@ def _validate_planning_conformance_declared(
             "blocks the same stage after the work is done, where the approved "
             "plan can no longer be corrected."
         )
+    for gap in declared_stage_surface_gaps(data, surface_patterns):
+        if gap["stage"] in implemented:
+            continue
+        failures.append(
+            "conformance gate BLOCKING: stage "
+            f"{gap['stage']} declares `Conformance tests:` with "
+            f"requires={gap['requires']} but its planned paths touch surface(s) "
+            f"{gap['surfaces']}: {', '.join(gap['paths'])} — add "
+            f"{gap['surfaces']} to that stage's `requires`, or move those paths "
+            "out of it. The implementation run's diff-surface check demands "
+            "the wider set after the work is done, where the approved plan can "
+            "no longer be corrected."
+        )
 
 
 def _validate_conformance_surfaces(
@@ -8065,19 +8115,19 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "`blocksReleaseHandoff: false`."
         )
 
+    if routing_token == "final-verification" and token == "accepted":
+        failures.append(
+            "final-verification: routingRecommendation cites `final-verification` "
+            "but the verdict is `accepted` — an accepted verdict carries no blocker "
+            "to re-verify. Route to release-handoff or done."
+        )
+
     scope = data.get("verificationScope", "whole-task")
     if scope not in ("whole-task", "single-stage"):
         failures.append(
             f"final-verification: verificationScope must be `whole-task` or "
             f"`single-stage`, got {scope!r}."
         )
-    if scope == "single-stage" and routing_token == "release-handoff":
-        failures.append(
-            "final-verification: verificationScope `single-stage` cannot recommend "
-            "plain release-handoff routing — a single-stage accepted verdict may "
-            "only route to `release-handoff(stage-group)` (partial-PR mode); "
-            "whole-task release-handoff requires whole-task verification."
-        )
 
 
 def validate_report_views(report_path: Path, failures: list[str]) -> None:

package/runtime/validators/validate-schedule.py

@@ -441,6 +441,15 @@ def _validate_format(path: Path) -> list[str]:
                     f"{why}; a stage block is Steps plus Exit criteria"
                 )
 
+    # 9b. The At a Glance work column is titled in the schedule's language.
+    glance_header = (
+        f"| # | {labels['glance_work_column']} | Category | Priority | Effort | Days | Risk |"
+    )
+    if "## At a Glance" in section_positions and glance_header not in text:
+        violations.append(
+            f"`## At a Glance` requires the header literal {glance_header!r}"
+        )
+
     # 10. Days total format inside At a Glance: `**N tasks total / estimated effort: X.X ~ Y.Y days (Effort sum)**`
     if "## At a Glance" in section_positions:
         start = section_positions["## At a Glance"]

package/docs/for-ai/README.md

@@ -1,68 +0,0 @@
-# Okstra Skills AI Manuals
-
-This directory is a compressed manual for an AI to quickly select and precisely run okstra public skills. The authoritative contract is `skills/*/SKILL.md`; this document is the operational guide for the AI. When the source skills, templates, validators, or CLI registry conflict, prefer the source skills and the actual validator/CLI implementation.
-
-## Verified Sources
-
-- Public skill list: [`src/lib/skill-catalog.mjs`](../../src/lib/skill-catalog.mjs)
-- Skill sources: [`skills/`](../../skills/)
-- CLI command surface: [`src/cli-registry.mjs`](../../src/cli-registry.mjs)
-- brief template: [`templates/reports/brief.template.md`](../../templates/reports/brief.template.md)
-- schedule template: [`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md)
-- brief validator: [`validators/validate-brief.py`](../../validators/validate-brief.py)
-- schedule validator: [`validators/validate-schedule.py`](../../validators/validate-schedule.py)
-
-## Skill Routing
-
-| User intent | Skill to use | Manual |
-|---|---|---|
-| Install/initialize okstra on a new project or a new machine | `okstra-setup` | [`skills/okstra-setup.md`](skills/okstra-setup.md) |
-| Turn requirements, tickets, links, a codebase scan, or an error-zip into an okstra input brief | `okstra-brief-gen` | [`skills/okstra-brief-gen.md`](skills/okstra-brief-gen.md) |
-| Start an okstra run or execute the next phase in the current Claude Code session | `okstra-run` | [`skills/okstra-run.md`](skills/okstra-run.md) |
-| Manage okstra tasks across multiple projects — bundling, assignment, sync snapshots, child launch packets | `okstra-manager` | [`skills/okstra-manager.md`](skills/okstra-manager.md) |
-| Check status, history, report, time, logs, cost, errors, error-zip, run-audit, recap | `okstra-inspect` | [`skills/okstra-inspect.md`](skills/okstra-inspect.md) |
-| Collect and aggregate the results of multiple task runs across a task-group (or the whole project) into a synthesized summary | `okstra-rollup` | [`skills/okstra-rollup.md`](skills/okstra-rollup.md) |
-| Project-wide recent run coverage, tokens, known cost, CPU, and wall-clock usage by task type | `okstra-usage` | [`skills/okstra-usage.md`](skills/okstra-usage.md) |
-| Generate a client-facing work schedule for a whole task-group | `okstra-schedule-gen` | [`skills/okstra-schedule-gen.md`](skills/okstra-schedule-gen.md) |
-| Store or search conversations/decisions/preferences/requirements in the global Memory Book | `okstra-memory` | [`skills/okstra-memory.md`](skills/okstra-memory.md) |
-| Create or join a global room and send or read addressed messages across host sessions | `okstra-chat` | [`skills/okstra-chat.md`](skills/okstra-chat.md) |
-| Manage the implementation-task worktree-based docker compose user-test environment | `okstra-container-build` | [`skills/okstra-container-build.md`](skills/okstra-container-build.md) |
-| Answer the unresolved clarification questions an okstra run left behind in-session and record the approval gate | `okstra-user-response` | [`skills/okstra-user-response.md`](skills/okstra-user-response.md) |
-| Register a PR body template or generate a PR description from a branch diff (global, git repository) | `okstra-pr-gen` | [`skills/okstra-pr-gen.md`](skills/okstra-pr-gen.md) |
-| Review the changed code of one okstra `implementation` stage or of any branch against the coding-preflight rules, and write the result to a file | `okstra-code-review` | [`skills/okstra-code-review.md`](skills/okstra-code-review.md) |
-
-## Shared Execution Rules
-
-1. Run commands as separate Bash calls whenever the source skill requires it. In particular, do not wrap `okstra preflight --runtime claude-code`, `okstra wizard ...`, or `okstra container ...` calls in `&&`, `||`, `$(...)`, a leading variable assignment, `eval`, or `export`.
-2. An `okstra <subcmd>` call bootstraps its own Python path. Unless a skill states otherwise, do not build `okstra paths --shell` or `export PYTHONPATH=...`.
-3. Most skills except `okstra-setup` do not use an `npx` fallback. If the runtime is missing, tell the user to run `/okstra-setup` and stop. But if it fails with `unknown command: <cmd>`, the `okstra` binary on PATH is older than the skill — point the user to `npm i -g okstra@latest` rather than `/okstra-setup`, and stop.
-4. Project artifacts go under `<PROJECT_ROOT>/.okstra/` by default. The exceptions are `okstra-memory` (`~/.okstra/memory-book/`) and `okstra-chat` (`~/.okstra/chat/`).
-5. `runtime/` is build output. When fixing a source skill or template, edit the source under `skills/`, `templates/`, `validators/`, `scripts/`, `src/` and apply it via a build.
-6. Do not guess the contents of a tracker, URL, file, report, log, zip, template, or validator. Use only what you have confirmed by reading or running with a tool.
-7. Read-side skills also produce some artifacts. `okstra-inspect errors` produces an error report Markdown and `okstra-inspect error-zip` produces an anonymized zip. Even in these cases, keep the purpose-specific fixed CLI fields as the source of truth.
-
-## The Order the AI Reads In
-
-1. Pick a skill in this file.
-2. Read only the matching `docs/for-ai/skills/<skill>.md`.
-3. If the skill requires actual execution, confirm the relevant step in the source [`skills/<skill>/SKILL.md`](../../skills/).
-4. When writing a brief or schedule, also confirm the template and the validator.
-
-## Public Skill List
-
-The public skills listed in this AI manual are the following 14:
-
-- `okstra-setup`
-- `okstra-brief-gen`
-- `okstra-run`
-- `okstra-manager`
-- `okstra-memory`
-- `okstra-chat`
-- `okstra-inspect`
-- `okstra-rollup`
-- `okstra-usage`
-- `okstra-schedule-gen`
-- `okstra-container-build`
-- `okstra-user-response`
-- `okstra-pr-gen`
-- `okstra-code-review`

package/docs/for-ai/skills/okstra-brief-gen.md

@@ -1,262 +0,0 @@
-# okstra-brief-gen AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-brief-gen/SKILL.md`](../../../skills/okstra-brief-gen/SKILL.md)
-- brief template: [`templates/reports/brief.template.md`](../../../templates/reports/brief.template.md)
-- brief validator: [`validators/validate-brief.py`](../../../validators/validate-brief.py)
-- lens enum SSOT: [`scripts/okstra_ctl/improvement_lenses.py`](../../../scripts/okstra_ctl/improvement_lenses.py)
-
-## Purpose
-
-`okstra-brief-gen` produces a task brief to feed into the okstra pipeline. A brief is a pre-discovery artifact. It is not a document that turns requirements into an implementation plan; it is a handoff document that separates the reporter's verbatim material from the AI-verified evidence/interpretation using labels, so the next phase can start without questions.
-
-Output location:
-
-```text
-<PROJECT_ROOT>/.okstra/briefs/<task-group>/<brief-id>.md
-<PROJECT_ROOT>/.okstra/briefs/<task-group>/sub/.../<brief-id>.md
-```
-
-## Three variants
-
-| Variant | Input | Recommended next phase |
-|---|---|---|
-| Reporter input | files, tickets, URLs, conversation/free text | `requirements-discovery` or `error-analysis` |
-| Codebase scan | scan scope, priority lenses, candidate cap, context | `improvement-discovery` |
-| Error feedback | a single error cluster from the zip produced by `okstra error-zip` | `error-analysis` |
-
-## Core invariants
-
-1. Source Material is a verbatim-preservation area. Do not paraphrase, summarize, or reorder.
-2. The AI's interpretation, file links, terminology mapping, and format conversion all go under `Augmentation` or a `> augmented:` blockquote.
-3. An augmentation carries one of four labels: `evidence-link`, `format-conversion`, `terminology-mapping`, `intent-inference`.
-4. `intent-inference` is paired with `intent-check:` in `Open Questions`. This relationship is checked by `validators/validate-brief.py`.
-5. A `terminology-mapping` augmentation is paired with `terminology:` in `Open Questions` (validator-checked). Exception: the Step 4.5 result markers `applied glossary:` / `skipped glossary:` need no paired row.
-6. Questions only the reporter can answer are collected in Step 6.5 and recorded verbatim under `## Reporter Confirmations`.
-7. Ticket split/link/order relations go in the structured table of `## Related Task Graph`. Do not infer work order from parent-id alone.
-8. Every okstra-owned write stays inside `<PROJECT_ROOT>/.okstra/`. External files are read only when the reporter explicitly cited them as source.
-9. Every row in `Open Questions` starts with one of five prefixes: `general:`, `terminology:`, `intent-check:`, `conversion-block:`, `adr-candidate:` (validator-enforced). `adr-candidate:` is only a signal — the decision file is written by `implementation-planning` into `<PROJECT_ROOT>/.okstra/decisions/`.
-
-## Preflight
-
-Run as a single call.
-
-```bash
-okstra preflight --runtime claude-code
-```
-
-On `Okstra preflight: ready`, carry the fixed `Project root` line. On
-`Okstra preflight: failed`, show `Reason` and `Recovery`, then stop. This skill
-does not use an `npx` fallback.
-
-## Input collection
-
-### Reporter input
-
-More than one source type is allowed, but each source is stored as a separate block under `Source Material`.
-
-- File: read the entire file and insert it as-is.
-- Issue tracker ticket: detect Linear/Jira/GitHub/Notion and use MCP or the `gh` CLI. If no access tool is available, ask the user to paste the body or skip.
-- Link URL: fetch it. On failure / login wall / body truncation, ask the user to paste.
-- User input: if conversation context is sufficient, use conversation synthesis; if thin, take a single free-text input.
-
-If a ticket has children/sub-tasks, ask once at the parent how to handle the tree.
-
-- Full tree: generate a brief per descendant.
-- Parent only: put child keys/URLs in Related Artifacts and leave a `parent-of` edge in `Related Task Graph`.
-- Selected: recurse only into the chosen direct-child branch.
-
-During recursion, manage the visited set as `<tracker>:<ticket-id>`, and on re-run reseed from the existing brief frontmatter's `ticket-id` + `source-type`.
-When Full tree or Selected produces multiple briefs, copy the same `Related Task Graph` into every generated brief. That way, even if only one child brief is passed to a downstream phase, the split topology, predecessor/successor relations, and de-duplication signals are preserved.
-
-`Related Task Graph` table schema:
-
-| Column | Meaning |
-|---|---|
-| From | task key, brief id, tracker id, or URL |
-| Relation | `parent-of`, `child-of`, `depends-on`, `blocks`, `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to` |
-| To | task key, brief id, tracker id, or URL |
-| Direction | `directed` or `undirected` |
-| Source | tracker linked issue, task-list checkbox, reporter statement, manual split, prior okstra task |
-| Impact | meaning the downstream phase must preserve |
-
-`depends-on`, `blocks`, parent/child, follow-up, and split relations are `directed`. `duplicates` and `related-to` are `undirected`. Do not create a relation with no source.
-
-### Codebase scan
-
-Collected values:
-
-- `scan_scope`: a list of real paths inside the project.
-- `priority_lenses`: 1–4 of the `LENSES` enum.
-- `out_of_scope`: optional.
-- `candidate_cap`: 1–12, default 8.
-- context, desired outcome, constraints.
-
-Verify path existence, the lens enum subset, and the candidate-cap range before writing. Final validation is done by `validate-brief.py`, which checks `scope: codebase`, `Scan Scope`, and `Priority Lenses`.
-
-### Error feedback
-
-The input is the zip produced by `okstra error-zip --out <path>`.
-
-Processing:
-
-1. Confirm the zip contains `report.md` and `errors/anonymized.jsonl`.
-2. Pick exactly one cluster from the frequent-cluster table.
-3. Move only the chosen cluster's anonymized records into Source Material.
-4. Do not mix different errorTypes into one brief.
-5. Set the next-step guidance to `error-analysis`.
-
-## task-group and filename
-
-For task-group, show existing-group recommendations first. Call `okstra task-list --text`, read the distinct fixed `Task group` values in `Updated at` order, and offer the 2 most recent + enter-directly. If `Status` is `error`, report `Failure stage` and `Failure reason`, then stop. If `Task count` is `0`, ask for free text. In tracker recursion, task-group must be obtained before building any child path.
-
-File path rule:
-
-```text
-depth 0: .okstra/briefs/<task-group>/<ticket-id>-<file-title>.md
-depth 1: .okstra/briefs/<task-group>/sub/<ticket-id>-<file-title>.md
-depth N: .okstra/briefs/<task-group>/<sub/ repeated N>/<ticket-id>-<file-title>.md
-```
-
-The frontmatter's `depth` must equal the number of `sub/` segments in the path. The validator checks this.
-
-On collision, the default is Skip. You may offer Append suffix or Overwrite. Do not silently perform a bulk overwrite in tracker multi-generation.
-
-## Domain alignment
-
-First look at okstra's internal memory.
-
-- `<PROJECT_ROOT>/.okstra/glossary.md`
-- `<PROJECT_ROOT>/.okstra/decisions/`
-- the related task's `history/fix-cycles.jsonl`
-
-Read external domain docs only when the reporter explicitly cited them as source material. Record conflicting/ambiguous terms under `Augmentation > Domain alignment` with `terminology-mapping`, and put a `terminology:` row in `Open Questions`.
-
-When a file path or symbol is mentioned, find the actual in-repo reference with `Read`/`Grep` and record it as `evidence-link`. If it cannot be mapped, do not guess — leave a `conversion-block:` row.
-
-## Sharpening pass
-
-Do not run a full interview. Ask only about gaps that source and codebase cannot fill.
-
-Default budget:
-
-- at most 1 question per section the source skill designates as fill-in.
-- at most 2 questions for terminology/fuzzy disambiguation.
-- at most 6 questions overall.
-- codebase-scan up to 8 questions.
-
-Prefer codebase-first checks over questions. Put remaining gaps in `_(none)_` or `Open Questions`.
-
-## template writing rules
-
-The template `templates/reports/brief.template.md` is the SSOT. Follow the section order, frontmatter keys, top blockquote shape, and HTML comment guidance.
-
-Reporter input and Error feedback:
-
-- keep `## Source Material`.
-- keep `## Problem / Symptom`.
-- omit `## Scan Scope`, `## Priority Lenses`.
-
-Codebase scan:
-
-- `scope: codebase` in frontmatter.
-- omit `## Source Material`, `## Problem / Symptom`.
-- keep `## Scan Scope`, `## Priority Lenses`.
-
-Do not fabricate empty sections. When there is no value, use `_(none)_`.
-
-## frontmatter key
-
-Every brief carries the following keys. The key set is checked by `validate-brief.py`.
-
-- `type`
-- `brief-id`
-- `parent-id`
-- `ticket-id`
-- `source-type`
-- `task-group`
-- `depth`
-- `created`
-- `generator`
-- `reporter-confirmations`
-
-`brief-id` must equal the filename stem. At depth 0 the `parent-id` is `self`; a descendant's `parent-id` is its direct parent's `brief-id`.
-
-## Recommended next phase
-
-Write it into the `Recommended next phase:` of the brief body's top blockquote.
-
-- observable error, repro, stack trace, error-zip record: `error-analysis`
-- a requirement with ambiguity or large Open Questions: `requirements-discovery`
-- `scope: codebase`: `improvement-discovery`
-- if ambiguous: `requirements-discovery`
-
-Do not auto-start `okstra-run`.
-
-## Reporter Confirmations
-
-Collect the rows in `Open Questions` that only the reporter can answer.
-
-- `intent-check:`
-- `conversion-block:`
-
-If a `[CONFIRMED <date> → RC-N]` marker already exists, exclude it from pending. Ask the user whether to answer now; if they answer, record it verbatim under `## Reporter Confirmations`. Do not delete the row — attach a marker.
-
-At most 12 questions per run. If pending exceeds 12, ask only the top 12 in `conversion-block:` → `intent-check:` order, leave the rest as `partial`, then tell the user which rows remain.
-
-Status values:
-
-- `complete`: all pending reporter-only rows are answered. The validator checks that every `intent-check:`/`conversion-block:` row has a `[CONFIRMED …]` marker.
-- `partial`: only some are answered. The validator checks that at least one row has a `[CONFIRMED …]` marker (if nothing was received, `skipped`).
-- `skipped`: the user chose to defer to a downstream phase.
-- `pending`: treated as a pre-handoff state; do not proceed.
-
-## Validation
-
-After writing, run the validator before emitting the handoff message.
-
-Installed copy:
-
-```bash
-~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
-```
-
-repo checkout:
-
-```bash
-validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
-```
-
-On failure, fix the cited brief and re-run. Fall back to a manual checklist only when the validator is absent.
-When a `Related Task Graph` is present, the validator also checks the table header, relation enum, direction enum, and directed/undirected mismatch.
-
-## Completion message
-
-Single brief:
-
-```text
-brief saved: <abs-path>
-next: /okstra-run  (recommended task-type: <phase>)
-```
-
-Multi-brief:
-
-```text
-briefs saved (N):
-  - <abs>/<task-group>/<brief>.md (depth 0, parent, recommended: <phase>)
-  - <abs>/<task-group>/sub/<brief>.md (depth 1, child, recommended: <phase>)
-next: /okstra-run
-```
-
-Before the hand-off block, once per task-group (Step 7a): if `<PROJECT_ROOT>/.okstra/briefs/<task-group>/group-context.md` is absent, ask whether to create the skeleton (`okstra group-context init --project-root <PROJECT_ROOT> --task-group <task-group>`; recommended for a new group) or skip. Never fill it from the tickets. When created, add `group context skeleton: <abs>/<task-group>/group-context.md   (fill before /okstra-run)` to the block — preparation refuses the group's tasks while a `<...>` placeholder line remains. The file's trailing `## Task Memory` region is okstra's (rewritten by `report-finalize` with the group's start order and each task's latest conclusion); `init` inserts the human sections above an existing region. Brief ordinals (`<TICKET>-<n>-<slug>`) are the start order okstra reads; `Related Task Graph` edges are quoted beside it as `waits for`.
-
-## Forbidden patterns
-
-- Summarizing or tidying Source Material before inserting it.
-- Guessing tracker/URL content without tool verification.
-- Writing unlabelled augmentation.
-- Leaving `intent-inference` without `intent-check:`.
-- Writing a decision file into external docs/ADR. okstra decisions belong only in `<PROJECT_ROOT>/.okstra/decisions/`.
-- Silently overwriting an entire child tree.
-- Auto-starting `okstra-run` right after brief generation.

package/docs/for-ai/skills/okstra-chat.md

@@ -1,34 +0,0 @@
-# okstra-chat AI Manual
-
-## Source
-
-- Skill source: [`skills/okstra-chat/SKILL.md`](../../../skills/okstra-chat/SKILL.md)
-- CLI: [`src/commands/chat/chat.mts`](../../../src/commands/chat/chat.mts)
-
-## Purpose
-
-Global rooms under the okstra home so host sessions from different providers can send and read messages. Not a project `.okstra/` artifact.
-
-## CLI
-
-```bash
-okstra chat rooms
-okstra chat create --room <name>
-okstra chat join --room <name> --name <display>
-okstra chat members --room <name>
-okstra chat send --room <name> --as <display> (--to <all|name> | --reply-to <id>) (--body <text> | --body-file <path>)
-okstra chat unread --room <name> --as <display>
-okstra chat inbox --room <name> --as <display>
-okstra chat log --room <name> --as <display>
-okstra chat ack --room <name> --as <display> --through <id>
-```
-
-Display names are typed. The CLI does not generate them.
-
-Unread is the inbox after the read cursor minus messages whose `from` equals `--as`. It does not move the cursor. `inbox` and `log` keep those messages. Rows are `id @from YYYY-MM-DD HH:MM body`. A reply inserts `↑parentId` after the time. Recipient is not on the line. A body with several lines continues on rows indented by two spaces; those rows carry no id.
-
-`send --to` may equal `--as`. `--to` and `--reply-to` are exactly one. `--body` and `--body-file` are exactly one; either may hold several lines, and only an all-blank body is rejected. A reply inherits `to` from the parent. `members` is the full roster. `ack --through` rejects an id behind the current cursor. `.` and `..` are reserved names. A stale `.lock` (dead owner pid, or older than 5 s) is reclaimed by the next writer.
-
-The skill picker is `all` plus `members` minus the current display name. Skill send and reply use `--body`, not `--body-file`. Before joining an existing room the skill runs `members`; if the typed display name is already listed, it asks whether this session is already in the room under that name (a re-entry after context loss) and, if so, continues with `--as` without joining. After showing unread rows, the skill runs `ack --through` with the id of the last row that starts with an id, unless the output is `no unread`. The Step 3 menu is send, unread, inbox, log, reply, done. Reply takes a free-input id and body; there is no recipient picker and no `okstra chat reply` subcommand.
-
-Read the fixed text rows. Do not parse JSON.