okstra 0.82.1 → 0.84.0

package/runtime/python/okstra_ctl/paths.py

@@ -33,9 +33,15 @@ __all__ = [
     "next_run_seq",
     "task_dir",
     "task_runs_dir",
+    "okstra_home",
 ]
 
 
+def okstra_home() -> Path:
+    raw = os.environ.get("OKSTRA_HOME", "").strip()
+    return Path(raw).expanduser() if raw else Path.home() / ".okstra"
+
+
 def task_dir(project_root: Path, task_group: str, task_id: str) -> Path:
     """task root 경로: ``<project>/.okstra/tasks/<group-seg>/<id-seg>``.
 
@@ -188,6 +194,8 @@ def compute_run_paths(
     report_writer_worker_result = worker_results / f"report-writer-worker{suffixes['worker_results']}.md"
 
     run_errors_log = run_logs / f"errors-{task_type_segment}-{seqs['state']}.jsonl"
+    runtime_home = okstra_home()
+
     claude_worker_errors_sidecar = worker_results / f"claude-worker-errors{suffixes['worker_results']}.json"
     codex_worker_errors_sidecar = worker_results / f"codex-worker-errors{suffixes['worker_results']}.json"
     gemini_worker_errors_sidecar = worker_results / f"gemini-worker-errors{suffixes['worker_results']}.json"
@@ -209,7 +217,25 @@ def compute_run_paths(
         "OKSTRA_ROOT": str(okstra_root),
         "OKSTRA_TASKS_ROOT": str(tasks_root),
         "WORKER_PROMPT_PREAMBLE_PATH": str(
-            Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"
+            runtime_home / "templates" / "worker-prompt-preamble.md"
+        ),
+        "OKSTRA_LEAD_CONTRACT_PATH": str(
+            runtime_home / "prompts" / "lead" / "okstra-lead-contract.md"
+        ),
+        "OKSTRA_CONTEXT_LOADER_PATH": str(
+            runtime_home / "prompts" / "lead" / "context-loader.md"
+        ),
+        "OKSTRA_TEAM_CONTRACT_PATH": str(
+            runtime_home / "prompts" / "lead" / "team-contract.md"
+        ),
+        "OKSTRA_CONVERGENCE_PATH": str(
+            runtime_home / "prompts" / "lead" / "convergence.md"
+        ),
+        "OKSTRA_REPORT_WRITER_PATH": str(
+            runtime_home / "prompts" / "lead" / "report-writer.md"
+        ),
+        "OKSTRA_CODING_PREFLIGHT_DIR": str(
+            runtime_home / "prompts" / "coding-preflight"
         ),
         "OKSTRA_DISCOVERY_DIR": str(discovery_dir),
         "TASK_ROOT": str(task_root),

package/runtime/python/okstra_ctl/render.py

@@ -28,6 +28,7 @@ from okstra_project.dirs import OKSTRA_DIR_NAME, project_json_path
 # render_task_manifest 가 동일한 리스트/딕셔너리를 로컬에 중복 정의했는데,
 # 이는 silent drift 위험이 있어 SSOT import 로 통합한다.
 from . import fix_cycles
+from .paths import okstra_home
 from .lead_runtime import lead_runtime_info
 from .workflow import DEFAULT_NEXT_PHASE, PHASE_SEQUENCE
 
@@ -369,6 +370,14 @@ def _active_error_logs(ctx: dict) -> dict:
     }
 
 
+def _active_runtime_resources(ctx: dict) -> dict:
+    runtime_home = okstra_home()
+    return {
+        "codingPreflightDir": ctx.get("OKSTRA_CODING_PREFLIGHT_DIR")
+        or str(runtime_home / "prompts" / "coding-preflight"),
+    }
+
+
 def _active_executor_worktree(ctx: dict) -> dict:
     return {
         "status": ctx.get("EXECUTOR_WORKTREE_STATUS", ""),
@@ -419,6 +428,7 @@ def render_active_run_context(active_context_path: str, ctx: dict) -> None:
         "instructionSet": _active_instruction_set(ctx),
         "workers": _active_workers(ctx),
         "errorLogs": _active_error_logs(ctx),
+        "runtimeResources": _active_runtime_resources(ctx),
         "executorWorktree": _active_executor_worktree(ctx),
         "sourceArtifacts": _active_source_artifacts(ctx),
         "lazyReadPlan": _active_lazy_read_plan(),
@@ -1104,7 +1114,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
 def _build_convergence_block(ctx: dict) -> dict:
     """Resolve the `convergence` sub-tree written into task-manifest.json.
 
-    Defaults follow `skills/okstra-convergence/SKILL.md`:
+    Defaults follow `prompts/lead/convergence.md`:
     - `enabled` default True
     - `maxRounds` default 1 for `requirements-discovery`, 2 otherwise
     - `verificationMode` default "lightweight"
@@ -1667,6 +1677,35 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     lead_agent_label = _lead_agent_label(ctx)
     lead_model = ctx.get("LEAD_MODEL", "")
     lead_model_execution = ctx.get("LEAD_MODEL_EXECUTION_VALUE", "")
+    home_prompts = okstra_home() / "prompts"
+    lead_contract_path = ctx.get("OKSTRA_LEAD_CONTRACT_PATH") or str(
+        home_prompts / "lead" / "okstra-lead-contract.md"
+    )
+    context_loader_path = ctx.get("OKSTRA_CONTEXT_LOADER_PATH") or str(
+        home_prompts / "lead" / "context-loader.md"
+    )
+    team_contract_path = ctx.get("OKSTRA_TEAM_CONTRACT_PATH") or str(
+        home_prompts / "lead" / "team-contract.md"
+    )
+    convergence_path = ctx.get("OKSTRA_CONVERGENCE_PATH") or str(
+        home_prompts / "lead" / "convergence.md"
+    )
+    report_writer_path = ctx.get("OKSTRA_REPORT_WRITER_PATH") or str(
+        home_prompts / "lead" / "report-writer.md"
+    )
+    coding_preflight_dir = ctx.get("OKSTRA_CODING_PREFLIGHT_DIR") or str(
+        home_prompts / "coding-preflight"
+    )
+    okstra_runtime_resources_block = (
+        "## Okstra Runtime Resources\n"
+        "\n"
+        f"- Lead contract: `{lead_contract_path}`\n"
+        f"- Context loader: `{context_loader_path}`\n"
+        f"- Team contract: `{team_contract_path}`\n"
+        f"- Convergence contract: `{convergence_path}`\n"
+        f"- Report writer contract: `{report_writer_path}`\n"
+        f"- Coding preflight pack: `{coding_preflight_dir}`"
+    )
 
     def fmt_assignment(role: str, model: str, execution: str) -> str:
         if execution and execution != model:
@@ -1852,7 +1891,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "## Team Creation Gate (BLOCKING)\n"
             "\n"
             "Before any `Agent` dispatch for workers, you MUST perform Phase 3 of the\n"
-            '`okstra` skill (`agents/SKILL.md` → "Phase 3 — Team creation"). Skipping\n'
+            f'okstra lead contract (`{lead_contract_path}` \u2192 "Phase 3 \u2014 Team creation"). Skipping\n'
             "this gate silently degrades the run to in-process background dispatch and\n"
             "loses the Teams split-pane observability surface, even though worker\n"
             "outputs may still appear correct on disk.\n"
@@ -1861,7 +1900,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "for this run (roster comes from `resultContract.requiredWorkerRoles` in\n"
             "`task-manifest.json` — it may be 1, 2, 3, or more workers):\n"
             "\n"
-            "1. Invoke the `okstra-team-contract` skill and verify the selected worker\n"
+            f"1. Read the team-contract resource (`{team_contract_path}`) and verify the selected worker\n"
             "   roster against `task-manifest.json`'s `resultContract.requiredWorkerRoles`.\n"
             f'2. Call `TeamCreate(team_name: "{team_name}", description: ...)`.\n'
             "3. Record the outcome in team-state under\n"
@@ -1943,8 +1982,10 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     else:
         lead_intro_line = f"You are `{lead_role}` for project `{ctx.get('PROJECT_ID', '')}`."
         lead_bootstrap_instruction = (
-            "Invoke the `okstra` skill now. Read the manifests below for all task "
-            "metadata, paths, model assignments, and worker roster."
+            f"Read the Okstra lead contract at `{lead_contract_path}` now, then read "
+            "the manifests below for all task metadata, paths, model assignments, and "
+            "worker roster. Follow the contract's lazy-read rules for support resources; "
+            "do not invoke hidden/internal skills."
         )
         lead_session_block = (
             "## Session\n"
@@ -1957,9 +1998,9 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
             "\n"
             "- The `runs/<phase>/prompts/<worker>-worker-prompt-*.md` files referenced in `task-manifest.json → artifacts.workerPromptPathByWorkerId` are **NOT** rendered by the okstra runtime. Those paths are the *assigned* locations where the prompt history MUST be written at dispatch time.\n"
             "- Therefore: at the start of every phase the prompts/ directory is normally empty (or contains only previously-dispatched workers' files). This is expected. Do NOT narrate it as \"missing\", \"누락\", or \"not yet rendered\" — it just means dispatch has not happened yet.\n"
-            "- Before dispatching any required worker, **you (the lead) construct the worker prompt and persist it to the assigned absolute path using `Write`** (per `okstra-team-contract` rule 6). Only after persisting do you call the worker subagent (Agent tool / Codex / Gemini wrapper). The wrapper subagents will also re-write the same file on their end; the double-write is intentional and idempotent.\n"
+            "- Before dispatching any required worker, **you (the lead) construct the worker prompt and persist it to the assigned absolute path using `Write`** (per `team-contract` rule 6). Only after persisting do you call the worker subagent (Agent tool / Codex / Gemini wrapper). The wrapper subagents will also re-write the same file on their end; the double-write is intentional and idempotent.\n"
             "- Do not \"check if the file exists and skip dispatch\" — file presence is not a signal to skip. Worker selection and skipping rules come from team-state, never from prompts/ directory contents.\n"
-            f"- **Worker Preamble Path (single anchor — replaces inlined `[Required reading]` and `[Error reporting]` blocks).** Every worker prompt you construct MUST include the anchor header `**Worker Preamble Path:** {ctx.get('WORKER_PROMPT_PREAMBLE_PATH', str(Path.home() / '.okstra' / 'templates' / 'worker-prompt-preamble.md'))}`. The file at that path is the canonical SSOT for Required Reading + Error Reporting + Output sections; workers Read it end-to-end before producing output. Do NOT re-inline those blocks into worker prompt bodies — that is the legacy ~80-line dispatch boilerplate that this anchor is designed to replace."
+            f"- **Worker Preamble Path (single anchor — replaces inlined `[Required reading]` and `[Error reporting]` blocks).** Every worker prompt you construct MUST include the anchor header `**Worker Preamble Path:** {ctx.get('WORKER_PROMPT_PREAMBLE_PATH', str(okstra_home() / 'templates' / 'worker-prompt-preamble.md'))}`. The file at that path is the canonical SSOT for Required Reading + Error Reporting + Output sections; workers Read it end-to-end before producing output. Do NOT re-inline those blocks into worker prompt bodies — that is the legacy ~80-line dispatch boilerplate that this anchor is designed to replace."
         )
 
     # Compute results (deterministic from ctx, 덮어쓰기)
@@ -1968,6 +2009,7 @@ def inject_lead_prompt_computed_tokens(ctx: dict) -> None:
     ctx["LEAD_SESSION_BLOCK"] = lead_session_block
     ctx["TEAM_CREATION_GATE"] = team_creation_gate_block
     ctx["WORKER_DISPATCH_GUIDANCE"] = worker_dispatch_guidance
+    ctx["OKSTRA_RUNTIME_RESOURCES"] = okstra_runtime_resources_block
     ctx["WORKER_RESULT_PATH_LINES"] = "\n".join(worker_result_lines)
     ctx["MODEL_ASSIGNMENT_LINES"] = "\n".join(model_assignment_lines)
     ctx["TEAM_ROLE_LINES"] = "\n".join(team_role_lines)
@@ -2001,9 +2043,21 @@ def apply_lead_prompt_defaults(ctx: dict) -> None:
     # Empty for non-final-verification runs; the final-verification prepare
     # path overwrites it with the resolved verification target block.
     ctx.setdefault("VERIFICATION_TARGET", "")
+    runtime_home = okstra_home()
     ctx.setdefault(
         "WORKER_PROMPT_PREAMBLE_PATH",
-        str(Path.home() / ".okstra" / "templates" / "worker-prompt-preamble.md"),
+        str(runtime_home / "templates" / "worker-prompt-preamble.md"),
+    )
+    # Lead resource paths the launch template references directly. paths.py
+    # seeds the production values; setdefault backfills callers that render the
+    # template without the full path ctx (mirrors WORKER_PROMPT_PREAMBLE_PATH).
+    ctx.setdefault(
+        "OKSTRA_LEAD_CONTRACT_PATH",
+        str(runtime_home / "prompts" / "lead" / "okstra-lead-contract.md"),
+    )
+    ctx.setdefault(
+        "OKSTRA_TEAM_CONTRACT_PATH",
+        str(runtime_home / "prompts" / "lead" / "team-contract.md"),
     )
     if "AVAILABLE_MCP_SERVERS" not in ctx:
         ctx["AVAILABLE_MCP_SERVERS"] = build_available_mcp_servers_block(

package/runtime/python/okstra_ctl/run.py

@@ -79,6 +79,7 @@ from .session import (
 from .pr_template import PrTemplateError, resolve_pr_template_path
 from .workers import (
     normalize_workers,
+    resolve_optional_workers,
     resolve_profile_workers,
     validate_workers_against_profile,
 )
@@ -1067,7 +1068,7 @@ class _ResolvedAssets:
     prompt_template: Path
     task_index_template: Path
     final_report_template: Path
-    source_skill: Path
+    lead_contract: Path
     run_validator: Path
 
 
@@ -1090,19 +1091,19 @@ def _resolve_runtime_assets(workspace_root: Path, inp: PrepareInputs) -> _Resolv
     final_report_template = (
         workspace_root / "templates" / "reports" / "final-report.template.md"
     )
-    source_skill = workspace_root / "agents" / "SKILL.md"
+    lead_contract = workspace_root / "prompts" / "lead" / "okstra-lead-contract.md"
     run_validator = workspace_root / "validators" / "validate-run.py"
-    for required in (task_index_template, final_report_template, run_validator, source_skill):
+    for required in (task_index_template, final_report_template, run_validator, lead_contract):
         if not required.is_file():
             raise PrepareError(
-                f"required okstra template or source skill missing: {required}.{_INSTALL_HINT}"
+                f"required okstra template or lead contract missing: {required}.{_INSTALL_HINT}"
             )
     return _ResolvedAssets(
         profile_file=profile_file,
         prompt_template=prompt_template,
         task_index_template=task_index_template,
         final_report_template=final_report_template,
-        source_skill=source_skill,
+        lead_contract=lead_contract,
         run_validator=run_validator,
     )
 
@@ -1402,10 +1403,11 @@ def _resolve_roster(inp: PrepareInputs, profile_file: Path) -> tuple[list[str],
     if inp.task_type == "release-handoff":
         return [], ""
     profile_workers = resolve_profile_workers(profile_file)
+    optional_workers = resolve_optional_workers(profile_file)
     profile_workers_csv = ",".join(profile_workers)
     workers = normalize_workers(inp.workers_override or profile_workers_csv)
     if inp.workers_override.strip():
-        validate_workers_against_profile(workers, profile_workers)
+        validate_workers_against_profile(workers, profile_workers, optional_workers)
     if not workers:
         raise PrepareError(f"no workers resolved for profile: {inp.task_type}")
     return workers, ",".join(workers)

package/runtime/python/okstra_ctl/worker_prompt_headers.py

@@ -0,0 +1,126 @@
+"""Shared worker prompt anchor header rendering."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Mapping
+
+from .paths import okstra_home
+
+
+class WorkerPromptHeaderError(Exception):
+    """Raised when worker prompt anchor headers cannot be rendered."""
+
+
+def worker_prompt_headers(
+    *,
+    project_root: Path,
+    prompt_rel: str,
+    result_rel: str,
+    worker_id: str,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> list[str]:
+    """Render the team-contract worker prompt anchor headers."""
+    prompt_path = _resolve_project_path(project_root, prompt_rel)
+    return [
+        f"**Project Root:** {project_root}",
+        f"**Prompt History Path:** {prompt_rel}",
+        f"**Result Path:** {result_rel}",
+        f"Assigned worker prompt history path: {prompt_path}",
+        f"**Worker Preamble Path:** {_worker_preamble_path()}",
+        f"**Coding preflight pack:** {_coding_preflight_pack_path(active_context)}",
+        f"**Errors log path:** {_errors_log_path(project_root, manifest, active_context)}",
+        (
+            f"**Errors sidecar path:** "
+            f"{_worker_errors_sidecar_path(project_root, manifest, active_context, worker_id)}"
+        ),
+    ]
+
+
+def _worker_preamble_path() -> Path:
+    return okstra_home() / "templates" / "worker-prompt-preamble.md"
+
+
+def _coding_preflight_pack_path(active_context: Mapping[str, Any]) -> Path:
+    runtime_resources = active_context.get("runtimeResources")
+    if isinstance(runtime_resources, Mapping):
+        value = _string_value(runtime_resources.get("codingPreflightDir"))
+        if value:
+            return Path(value)
+    return okstra_home() / "prompts" / "coding-preflight"
+
+
+def _errors_log_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        value = _string_value(error_logs.get("runErrorsLogPath"))
+        if value:
+            return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    task_type = _require_string(manifest, "taskType")
+    seq = _sequence(manifest, "state")
+    return run_dir / "logs" / f"errors-{task_type}-{seq}.jsonl"
+
+
+def _worker_errors_sidecar_path(
+    project_root: Path,
+    manifest: Mapping[str, Any],
+    active_context: Mapping[str, Any],
+    worker_id: str,
+) -> Path:
+    error_logs = active_context.get("errorLogs")
+    if isinstance(error_logs, Mapping):
+        sidecars = error_logs.get("sidecarsByWorkerId")
+        if isinstance(sidecars, Mapping):
+            value = _string_value(sidecars.get(worker_id))
+            if value:
+                return _resolve_project_path(project_root, value)
+    run_dir = _run_directory_path(project_root, manifest)
+    task_type = _require_string(manifest, "taskType")
+    seq = _sequence(manifest, "workerResults")
+    return run_dir / "worker-results" / f"{worker_id}-worker-errors-{task_type}-{seq}.json"
+
+
+def _run_directory_path(project_root: Path, manifest: Mapping[str, Any]) -> Path:
+    value = _string_value(manifest.get("runDirectoryPath"))
+    if value:
+        return _resolve_project_path(project_root, value)
+    team_state_path = _resolve_project_path(
+        project_root,
+        _require_string(manifest, "teamStatePath"),
+    )
+    return team_state_path.parent.parent
+
+
+def _sequence(manifest: Mapping[str, Any], key: str) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if isinstance(seqs, Mapping):
+        return _string_value(seqs.get(key)) or _run_seq(manifest)
+    return _run_seq(manifest)
+
+
+def _run_seq(manifest: Mapping[str, Any]) -> str:
+    seqs = manifest.get("runSequencesByCategory")
+    if not isinstance(seqs, Mapping):
+        raise WorkerPromptHeaderError("run manifest has no runSequencesByCategory object")
+    return _require_string(seqs, "manifests")
+
+
+def _resolve_project_path(project_root: Path, value: str) -> Path:
+    path = Path(value)
+    return path if path.is_absolute() else project_root / path
+
+
+def _require_string(payload: Mapping[str, Any], key: str) -> str:
+    value = payload.get(key)
+    if not isinstance(value, str) or not value.strip():
+        raise WorkerPromptHeaderError(f"missing required string field: {key}")
+    return value
+
+
+def _string_value(value: Any) -> str:
+    return value.strip() if isinstance(value, str) else ""

package/runtime/python/okstra_token_usage/claude.py

@@ -9,7 +9,7 @@ from pathlib import Path
 from .cursor import MAX_NEEDLES, fresh_cache, load_cache, save_cache
 from .paths import claude_project_dir, ts_in_window
 
-# lead 의 단계 체크포인트 라인(agents/SKILL.md "Progress reporting") — phase id 가
+# lead 의 단계 체크포인트 라인(prompts/lead/okstra-lead-contract.md "Progress reporting") — phase id 가
 # `phase-<digit>` 로 시작하는 라인만 마커로 인정해 일반 대화의 오탐을 줄인다.
 _PROGRESS_RE = re.compile(r"^PROGRESS:\s+(phase-\d\S*(?:[ \t].*)?)$", re.MULTILINE)
 _PROGRESS_MARKER_MAX_CHARS = 160

package/runtime/python/okstra_token_usage/collect.py

@@ -159,7 +159,7 @@ def _wall_ms(start_iso: str | None, end_iso: str | None) -> int | None:
 
 
 def phase_timeline(markers: list[dict]) -> dict:
-    """lead 의 PROGRESS 체크포인트(agents/SKILL.md "Progress reporting")로
+    """lead 의 PROGRESS 체크포인트(prompts/lead/okstra-lead-contract.md "Progress reporting")로
     run 내부 단계 경계 wall-clock 을 복원한다 (perf plan v2 P0 계측).
 
     phase id = marker 의 첫 토큰(`phase-5.5-convergence` 등). 같은 phase 의

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

@@ -145,7 +145,7 @@ If the user picked `Reporter input`, proceed to Step 1.A's sub-flow below — th
 - **Label**: "Source of this brief?"
 - **Options** (single-select):
   1. `File` — path to an existing markdown / txt / issue-export file
-  2. `Issue tracker ticket` — Linear / Jira / GitHub Issue / Notion key or URL
+  2. `Issue tracker ticket` — Linear URL/ Jira URL/ GitHub Issue URL/ Notion key or URL
   3. `Link URL` — general web page, blog, spec doc, design doc, etc.
   4. `User input` — synthesize from the current conversation context, or
      accept a short free-text from the user
@@ -678,7 +678,7 @@ 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).
 
-[`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.
+The installed template `~/.okstra/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.
 
 **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.
 
@@ -710,6 +710,22 @@ Material).
   frontmatter.
 - `ticket-id` is populated only for tracker sources; leave it as an empty
   string otherwise.
+- `source-type` records the input origin (`file | linear | jira | github |
+  notion | url | user-input`).
+- `task-group` echoes the Step 2a value.
+- `created` is the brief's creation date (`YYYY-MM-DD`).
+- `generator: okstra-brief` is a fixed value.
+- `reporter-confirmations` is set by Step 6.5 (`complete | partial | pending |
+  skipped`).
+- `scope` is `codebase` for the codebase-scan variant; omit it (⇒
+  `reporter-input`) for the reporter-input variant.
+
+The required-key set (`type`, `brief-id`, `parent-id`, `ticket-id`,
+`source-type`, `task-group`, `depth`, `created`, `generator`,
+`reporter-confirmations`) and every consistency rule above are enforced by
+`~/.okstra/lib/validators/validate-brief.py` — run in
+Step 6.6. The byte-for-byte field shape remains the job of
+`~/.okstra/templates/reports/brief.template.md`.
 
 Echo the file path back on one line. Show the rendered brief to the user
 inline and ask:
@@ -750,8 +766,17 @@ 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.
+**Re-run reseed (rebuild from disk).** A prior run may have left this brief at
+`reporter-confirmations: partial` with some rows already answered. Before
+building the pending list, exclude every `intent-check:` / `conversion-block:`
+row that already carries a `[CONFIRMED <date> → RC-N]` marker — those were
+resolved in an earlier run and their answers already live under `## Reporter
+Confirmations`. Only the unmarked rows are pending this run. This mirrors the
+visited-set rebuild rule in Step 1b: confirmation state lives on disk, not in
+memory.
+
+If the resulting pending 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
 
@@ -839,6 +864,37 @@ 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 6.6: Self-validate before hand-off
+
+After every brief is written (Step 5) and its `reporter-confirmations` state
+is set (Step 6.5), and **before** printing the Step 7 hand-off message, you
+MUST validate every brief produced this run. The validator enforces the
+labelled-handoff contract — required frontmatter keys, Augmentation labels,
+`intent-inference ↔ intent-check:` auto-mirroring, `parent-id`/`depth`
+consistency, `reporter-confirmations` markers, and the codebase-scan
+`scope`/`Scan Scope`/`Priority Lenses` rules.
+
+1. Run the validator over the briefs directory:
+
+   ```bash
+   ~/.okstra/lib/validators/validate-brief.sh "<PROJECT_ROOT>/.okstra/briefs" --briefs-root "<PROJECT_ROOT>/.okstra/briefs"
+   ```
+
+   If you are working from a repo checkout instead of an install, the dev
+   copy is at `validators/validate-brief.sh`.
+
+2. If it exits non-zero, **fix the offending brief(s) and re-run**. Do NOT
+   print the Step 7 message until the validator passes.
+
+3. If neither validator copy is present, fall back to a manual checklist:
+   confirm each brief has all ten required frontmatter keys (`type`,
+   `brief-id`, `parent-id`, `ticket-id`, `source-type`, `task-group`,
+   `depth`, `created`, `generator`, `reporter-confirmations`); every
+   Augmentation entry carries one of the four labels; every `intent-inference`
+   has a paired `intent-check:` row; `parent-id` is `self` at depth 0 and a
+   real parent id below; and for `scope: codebase` briefs, `Scan Scope` is
+   non-empty and `Priority Lenses` lists 1–4 whitelist lenses.
+
 ## Step 7: Hand off
 
 Single brief:
@@ -866,13 +922,10 @@ started.
 
 ## Output Rules
 
-- All okstra-generated artifacts live under
-  `<PROJECT_ROOT>/.okstra/`. This skill's brief files go
-  under `.okstra/briefs/`; its glossary writes go to
-  `.okstra/glossary.md` (Step 4.5 approval flow).
-- Paths outside `<PROJECT_ROOT>/.okstra/**` are read-only
-  source material only when explicitly cited by the reporter. This skill
-  never writes outside okstra's subtree.
+- **Artifact-home** (see the "Artifact-home rule" section above): every write
+  stays under `<PROJECT_ROOT>/.okstra/` — briefs in `.okstra/briefs/`, glossary
+  in `.okstra/glossary.md` (Step 4.5). Paths outside that subtree are read-only
+  source material, and only when the reporter cited them.
 - **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.
@@ -910,3 +963,4 @@ started.
 | URL fetch fails or 401 / login wall | intranet, paywall, JS-rendered page | Ask the user to paste the core body. Never guess. |
 | Tracker body is in non-MD format (ADF / HTML) | Jira description, Notion blocks | Convert format only, preserve semantics. Annotate the conversion in the `format:` meta. |
 | Brief comes out skeletal after synthesis | source too thin AND user picked `User input` with little context | Switch to inline input mode and ask one or two targeted questions. |
+| `validate-brief` exits non-zero in Step 6.6 | missing frontmatter key, unlabelled augmentation, broken auto-mirroring, or codebase-scan lens out of whitelist | Read the validator's per-row message, fix the cited brief, re-run. Never print the Step 7 hand-off until it passes. |

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

@@ -360,7 +360,7 @@ If a run never reached Phase 7, its `team-state` lacks `durationMs`. Mark such r
 3. Multiple matches → list candidates (`taskKey`, `taskType`, `updatedAt`) and ask the user to pick.
 4. Read `historyTimelinePath` from the chosen entry.
 
-If `task-catalog.json` is missing: `No okstra history found. Run scripts/okstra.sh first.`
+If `task-catalog.json` is missing: `No okstra history found. Run /okstra-run first.`
 
 ### time.2 — Walk runs and collect durations
 

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

@@ -236,7 +236,7 @@ The validator rejects any of these patterns.
 
 ## Section Contract (required)
 
-The canonical template lives at `templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
+The canonical template lives at `~/.okstra/templates/reports/schedule.template.md`. **Read it before writing the schedule** and follow it byte-for-byte for headings.
 
 ### MUST — exact ordered heading list
 
@@ -441,14 +441,14 @@ After writing the file and before printing the completion message in Step 7, you
 1. **Re-read the file** you just wrote.
 2. **Run the validator**:
    ```bash
-   python3 validators/validate-schedule.py <output-path>
+   python3 ~/.okstra/lib/validators/validate-schedule.py <output-path>
    ```
 3. If the validator exits non-zero, **fix the file and re-validate**. Do not print the completion message until the validator passes.
-4. If `validators/validate-schedule.py` is not present in the repo, fall back to a manual checklist: confirm each of the 11 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
+4. If `~/.okstra/lib/validators/validate-schedule.py` is not present, fall back to a manual checklist: confirm each of the 11 mandatory headings from `### MUST — exact ordered heading list` (above) appears in the file with that exact spelling, the title ends with `— Work Schedule`, and the metadata `> Generated:` block is present.
 
 ## Schedule Document Template
 
-[`templates/reports/schedule.template.md`](../../templates/reports/schedule.template.md) is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
+The installed template `~/.okstra/templates/reports/schedule.template.md` is the byte-for-byte SSOT for section ordering, heading spelling, table columns, and per-section HTML-comment guidance (Dependency Graph Shape A/B, Gantt rules, optional Glossary gate). Do not omit sections; if data is unavailable, render the section with `_없음_` rather than skipping it.
 
 The two rules below complement the template — they encode COMPUTATION that the template scaffold cannot carry inline.
 

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

@@ -250,8 +250,8 @@ back it up as `.bak.<timestamp>` rather than overwriting silently.
 ## Step 4.8 (optional, opt-in): register a project PR body template
 
 `release-handoff` fills the PR body from a template. By default it uses the
-bundled skill template at
-`~/.claude/skills/templates/prd/pr-body.template.md`. Most projects
+installed template at
+`~/.okstra/templates/prd/pr-body.template.md`. Most projects
 want their own — e.g. the repo's `.github/PULL_REQUEST_TEMPLATE.md` — to
 keep PRs consistent with what the team already merges manually.