okstra 0.82.1 → 0.84.0

package/runtime/templates/reports/settings.template.json

@@ -14,140 +14,31 @@
       "WebFetch",
       "WebSearch",
       "TodoWrite",
-
-      "Bash(pwd)",
-      "Bash(cd)",
-      "Bash(cd:*)",
-
-      "Bash(ls)",
-      "Bash(ls:*)",
-      "Bash(cat:*)",
-      "Bash(head:*)",
-      "Bash(tail:*)",
-      "Bash(wc:*)",
-
-      "Bash(git)",
-      "Bash(git:*)",
-      "Bash(gh)",
-      "Bash(gh:*)",
-
-      "Bash(rg:*)",
-      "Bash(grep:*)",
-      "Bash(find:*)",
-      "Bash(diff:*)",
-
-      "Bash(jq:*)",
-      "Bash(yq:*)",
-      "Bash(awk:*)",
-      "Bash(sed:*)",
-      "Bash(tr:*)",
-      "Bash(sort:*)",
-      "Bash(uniq:*)",
-      "Bash(xargs:*)",
-
-      "Bash(mkdir:*)",
-      "Bash(cp:*)",
-      "Bash(mv:*)",
-      "Bash(rm:*)",
-      "Bash(chmod:*)",
-
-      "Bash(printf:*)",
-      "Bash(echo)",
-      "Bash(echo:*)",
-      "Bash(export:*)",
-      "Bash(env)",
-      "Bash(env:*)",
-      "Bash(test:*)",
-      "Bash(true)",
-      "Bash(true:*)",
-      "Bash(false)",
-      "Bash(false:*)",
-
-      "Bash(bash:*)",
-      "Bash(sh:*)",
-      "Bash(eval:*)",
-
-      "Bash(python)",
-      "Bash(python:*)",
-      "Bash(python3)",
-      "Bash(python3:*)",
-      "Bash(pip)",
-      "Bash(pip:*)",
-      "Bash(pip3)",
-      "Bash(pip3:*)",
-      "Bash(uv:*)",
-      "Bash(poetry:*)",
-      "Bash(pytest:*)",
-
-      "Bash(node)",
-      "Bash(node:*)",
-      "Bash(npm)",
-      "Bash(npm:*)",
-      "Bash(npx)",
-      "Bash(npx:*)",
-      "Bash(pnpm)",
-      "Bash(pnpm:*)",
-      "Bash(yarn)",
-      "Bash(yarn:*)",
-      "Bash(tsc)",
-      "Bash(tsc:*)",
-
-      "Bash(cargo)",
-      "Bash(cargo:*)",
-      "Bash(rustc)",
-      "Bash(rustc:*)",
-
-      "Bash(go)",
-      "Bash(go:*)",
-      "Bash(java)",
-      "Bash(java:*)",
-      "Bash(javac)",
-      "Bash(javac:*)",
-      "Bash(mvn)",
-      "Bash(mvn:*)",
-      "Bash(gradle)",
-      "Bash(gradle:*)",
-      "Bash(./gradlew)",
-      "Bash(./gradlew:*)",
-      "Bash(make)",
-      "Bash(make:*)",
-
-      "Bash(docker)",
-      "Bash(docker:*)",
-      "Bash(docker compose)",
-      "Bash(docker compose:*)",
-      "Bash(docker-compose)",
-      "Bash(docker-compose:*)",
-      "Bash(kubectl)",
-      "Bash(kubectl:*)",
-      "Bash(helm)",
-      "Bash(helm:*)",
-
-      "Bash(curl:*)",
-      "Bash(wget:*)",
-
-      "Bash(codex)",
-      "Bash(codex:*)",
-      "Bash(codex exec:*)",
       "Bash(okstra)",
       "Bash(okstra:*)",
       "Bash(npx okstra@latest:*)",
       "Bash(npx -y okstra@latest:*)",
       "Bash($HOME/.okstra/bin/:*)",
-      "Bash(STATE_FILE=:*)",
-      "Bash(ROOT=:*)",
-
+      "Bash(codex)",
+      "Bash(codex:*)",
       "Bash(gemini)",
       "Bash(gemini:*)",
-
       "Bash(claude)",
-      "Bash(claude:*)",
-
-      "mcp__test-context7__resolve-library-id",
-      "mcp__test-context7__query-docs"
+      "Bash(claude:*)"
     ]
   },
   "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write|Edit|MultiEdit|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"$HOME/.okstra/prompts/okstra-coding-preflight/scripts/preedit-check.sh\""
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/runtime/templates/reports/task-brief.template.md

@@ -112,7 +112,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ### Standing Ticket-Tagging Rule (always applied by every worker)
 
-- 모든 항목 및 표 행에 ticket을 명시한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: <id>]` 태그를 사용한다. 채움 우선순위·폴백·다중 ticket 규칙은 `okstra-team-contract` SKILL의 Ticket Tagging 절을 따른다.
+- 모든 항목 및 표 행에 ticket을 명시한다. 표 형식은 `Ticket ID` 컬럼, bullet/번호목록·섹션 헤더는 `[TICKETID: <id>]` 태그를 사용한다. 채움 우선순위·폴백·다중 ticket 규칙은 `team-contract` SKILL의 Ticket Tagging 절을 따른다.
 
 ### Standing Scope-Discipline Questions (always answered by every worker)
 
@@ -138,7 +138,7 @@ taskType: "{{FM_TASK_TYPE}}"
 ## Phase Boundary
 
 - This okstra run executes the lifecycle phase named in `Task Type` and stops there. Outputs that belong to any other phase MUST NOT be produced inside this run.
-- Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`agents/SKILL.md`). The lead and every worker stay inside that boundary.
+- Allowed and forbidden actions for each task type are listed in `Lifecycle Phase Boundaries` of the okstra skill (`prompts/lead/okstra-lead-contract.md`). The lead and every worker stay inside that boundary.
 - "다음 단계 진행해" or any equivalent user phrase is interpreted as "complete the remaining outputs of the current phase," never as "start the next lifecycle phase." The next phase begins only via a fresh okstra invocation with the new `--task-type`.
 - For `implementation-planning` specifically: produce a plan document with the sections listed in `okstra-implementation-planning-input.template.md` `## Required Plan Deliverable`. Do not edit project source code, run builds/migrations/deployments, or write artifacts outside the run's own directories.
 - For `implementation` specifically: edits are bounded by the approved plan's file list (the `--approved-plan` reference). The run MUST refuse to start if the approved plan path is missing or its frontmatter `approved` field is not `true`. `git push`, publish, deploy, real migrations, and any third-party write API call remain forbidden; only local `git add`/`git commit` are allowed. Verifier roles stay read-only — they record fix recommendations rather than applying edits — and acceptance verdicts belong to `final-verification`, not this phase.

package/runtime/templates/worker-prompt-preamble.md

@@ -18,7 +18,7 @@ Different recipients need different files. Do NOT include `final-report-template
 |---|---|
 | Claude / Codex / Gemini analysis workers | analysis-packet.md as the primary compact input; task-brief, analysis-profile, analysis-material, reference-expectations, and clarification-response remain source/fallback paths, not automatic first-read files |
 | Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
-| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [okstra-convergence](../skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
+| Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [convergence](../prompts/lead/convergence.md) "Reverify prompt: required-reading suppression". |
 
 ### Reading rules
 
@@ -112,7 +112,7 @@ Every item in sections 1–5 (and any section 6) MUST carry a worker-internal it
 
 For task types `requirements-discovery`, `error-analysis`, `implementation-planning`, or `implementation`, every item in sections 1–5 MUST carry a ticket identifier. Use the `Ticket ID` column in table-form items and the `[TICKETID: <id>]` prefix in bullet/numbered items.
 
-See `skills/okstra-team-contract/SKILL.md` "Worker Output Contract" for the full frontmatter schema and section ordering rules. This preamble is consistent with that contract; the team-contract document is authoritative if the two ever diverge.
+See `prompts/lead/team-contract.md` "Worker Output Contract" for the full frontmatter schema and section ordering rules. This preamble is consistent with that contract; the team-contract document is authoritative if the two ever diverge.
 
 ## Return message to the lead (all workers)
 

package/runtime/validators/lib/validate-assets.sh

@@ -57,10 +57,18 @@ else:
             continue
         check(source_path, workers_target / source_path.name)
 
-# 2. Lead agent SKILL.md: agents/SKILL.md -> runtime/agents/SKILL.md
-lead_source = agents_source_root / "SKILL.md"
-if lead_source.is_file():
-    check(lead_source, runtime_root / "agents" / "SKILL.md")
+# 2. Lead contract + internal lead resources: prompts/lead/* + prompts/coding-preflight/*
+#    -> runtime/prompts/*. These ship as runtime resources (okstra install copies
+#    runtime/prompts -> ~/.okstra/prompts), no longer as agent skills.
+prompts_source_root = agents_source_root.parent / "prompts"
+for sub in ("lead", "coding-preflight"):
+    sub_root = prompts_source_root / sub
+    if not sub_root.is_dir():
+        errors.append(f"missing prompts source directory: {sub_root}")
+        continue
+    for source_path in sorted(sub_root.rglob("*.md")):
+        relative = source_path.relative_to(prompts_source_root)
+        check(source_path, runtime_root / "prompts" / relative)
 
 # 3. Skill packages: skills/<name>/SKILL.md -> runtime/skills/<name>/SKILL.md
 if not skills_source_root.is_dir():

package/runtime/validators/validate-brief.py

@@ -25,7 +25,13 @@ Checks performed per brief file:
    own `brief-id`.
 9. `reporter-confirmations` consistency: when `complete`, every
    `intent-check:` and `conversion-block:` row in Open Questions MUST
-   carry a `[CONFIRMED YYYY-MM-DD → RC-N]` marker.
+   carry a `[CONFIRMED YYYY-MM-DD → RC-N]` marker; when `partial`, at
+   least one such row MUST carry the marker (use `skipped` when nothing
+   was answered).
+10. `scope` is one of {reporter-input, codebase} (absent ⇒ reporter-input).
+11. codebase-scan variant (`scope: codebase`): the Scan Scope section is
+    non-empty and Priority Lenses lists 1–4 values from the lens whitelist
+    (`scripts/okstra_ctl/improvement_lenses.py` SSOT).
 
 Exit code 0 on PASS, 1 on FAIL.
 """
@@ -38,6 +44,19 @@ import sys
 from pathlib import Path
 from typing import Iterable
 
+# scripts/ (repo) or python/ (installed under ~/.okstra/lib) is not a package;
+# insert whichever exists so okstra_ctl is importable for the lens whitelist.
+_VALIDATORS_DIR = Path(__file__).resolve().parent
+for _ssot_dir in (_VALIDATORS_DIR.parent / "scripts", _VALIDATORS_DIR.parent / "python"):
+    if _ssot_dir.is_dir() and str(_ssot_dir) not in sys.path:
+        sys.path.insert(0, str(_ssot_dir))
+
+from okstra_ctl.improvement_lenses import (
+    LENSES,
+    MAX_PRIORITY_LENSES,
+    MIN_PRIORITY_LENSES,
+)
+
 REQUIRED_FRONTMATTER_KEYS = {
     "type",
     "brief-id",
@@ -68,6 +87,8 @@ AUGMENTATION_LABELS = {
 
 REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
 
+SCOPE_VALUES = {"reporter-input", "codebase"}
+
 
 def parse_frontmatter(text: str) -> tuple[dict[str, str], int]:
     """Return (frontmatter dict, line after closing `---`)."""
@@ -173,6 +194,68 @@ def parse_augmentation_label(entry: str) -> tuple[str | None, str]:
     return None, stripped
 
 
+def meaningful_bullets(text: str, heading: str) -> list[str]:
+    """Real `- ` bullets under a heading, excluding placeholders/template scaffold."""
+    body = section_body(text, heading)
+    out: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        content = stripped[2:].strip()
+        if is_placeholder(content) or is_template_example(content):
+            continue
+        out.append(content.strip("`"))
+    return out
+
+
+def priority_lens_values(text: str) -> list[str]:
+    """Lens tokens from the `## Priority Lenses` bullets (`- <lens>: <rationale>`)."""
+    return [
+        bullet.split(":", 1)[0].strip()
+        for bullet in meaningful_bullets(text, "Priority Lenses")
+    ]
+
+
+def check_codebase_scope(text: str, errors: list[str]) -> None:
+    """codebase-scan variant: Scan Scope non-empty, Priority Lenses ⊆ whitelist."""
+    if not meaningful_bullets(text, "Scan Scope"):
+        errors.append("scope is 'codebase' but the Scan Scope section has no entries")
+    lenses = priority_lens_values(text)
+    if not (MIN_PRIORITY_LENSES <= len(lenses) <= MAX_PRIORITY_LENSES):
+        errors.append(
+            f"Priority Lenses must list {MIN_PRIORITY_LENSES}–{MAX_PRIORITY_LENSES} "
+            f"lens(es), found {len(lenses)}"
+        )
+    unknown = [lens for lens in lenses if lens not in LENSES]
+    if unknown:
+        errors.append(
+            f"Priority Lenses contains values outside the lens whitelist: {unknown} "
+            f"(allowed: {sorted(LENSES)})"
+        )
+
+
+def check_reporter_confirmations(
+    rc_status: str | None, reporter_rows: list[str], errors: list[str]
+) -> None:
+    """`complete` ⇒ every reporter row confirmed; `partial` ⇒ at least one."""
+    confirmed = [row for row in reporter_rows if "[CONFIRMED" in row]
+    if rc_status == "complete":
+        unconfirmed = [row for row in reporter_rows if "[CONFIRMED" not in row]
+        if unconfirmed:
+            errors.append(
+                f"reporter-confirmations is 'complete' but {len(unconfirmed)} "
+                f"intent-check:/conversion-block: row(s) lack a [CONFIRMED …] "
+                f"marker (e.g. {unconfirmed[0]!r})"
+            )
+    elif rc_status == "partial" and reporter_rows and not confirmed:
+        errors.append(
+            "reporter-confirmations is 'partial' but no intent-check:/"
+            "conversion-block: row carries a [CONFIRMED …] marker "
+            "(use 'skipped' when nothing was answered)"
+        )
+
+
 def validate_brief(path: Path, briefs_root: Path) -> list[str]:
     text = path.read_text(encoding="utf-8")
     errors: list[str] = []
@@ -202,6 +285,15 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
             f"{fm.get('reporter-confirmations')!r}"
         )
 
+    scope = fm.get("scope", "reporter-input")
+    if scope not in SCOPE_VALUES:
+        errors.append(
+            f"frontmatter scope must be one of {sorted(SCOPE_VALUES)} "
+            f"(or absent ⇒ reporter-input), got {scope!r}"
+        )
+    if scope == "codebase":
+        check_codebase_scope(text, errors)
+
     # 2. brief-id matches filename stem
     stem = path.stem
     if fm.get("brief-id") and fm["brief-id"] != stem:
@@ -306,21 +398,12 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
                 f"({brief_id!r})"
             )
 
-    # 9. reporter-confirmations consistency
-    rc_status = fm.get("reporter-confirmations")
-    if rc_status == "complete":
-        unconfirmed = [
-            row
-            for row in (intent_check_rows + conversion_block_rows)
-            if "[CONFIRMED" not in row
-        ]
-        if unconfirmed:
-            sample = unconfirmed[0]
-            errors.append(
-                f"reporter-confirmations is 'complete' but {len(unconfirmed)} "
-                f"intent-check:/conversion-block: row(s) lack a [CONFIRMED …] "
-                f"marker (e.g. {sample!r})"
-            )
+    # 9. reporter-confirmations consistency (complete / partial)
+    check_reporter_confirmations(
+        fm.get("reporter-confirmations"),
+        intent_check_rows + conversion_block_rows,
+        errors,
+    )
 
     return errors
 

package/runtime/validators/validate-run.py

@@ -436,7 +436,7 @@ def validate_team_state(
                     "team-state.teamCreate.attempted must be true once any worker has "
                     "been dispatched (status in completed/timeout/error/in-progress). "
                     "Phase 3 (TeamCreate) was skipped — workers ran in-process without "
-                    "the Teams split-pane surface. See agents/SKILL.md Phase 3. "
+                    "the Teams split-pane surface. See prompts/lead/okstra-lead-contract.md Phase 3. "
                     "(The no-team concurrent-run path is legal ONLY when the "
                     "run-manifest carries prepare-recorded `concurrentRun.detected: "
                     'true` AND team-state records `teamCreate: { attempted: false, '
@@ -1373,7 +1373,7 @@ def _validate_verdict_card_consistency(content: str, failures: list[str]) -> Non
     """Verdict Card is a non-authoritative index of §7. If both blocks
     carry a Verdict Token row, the values MUST byte-match (modulo case
     and surrounding whitespace) — divergence is a contract violation per
-    `okstra-report-writer` SKILL.md "Authoring Contract".
+    `report-writer` SKILL.md "Authoring Contract".
     """
     card_value = _extract_verdict_card_token(content)
     final_value = _extract_final_verdict_token(content)
@@ -1828,7 +1828,7 @@ def _validate_session_conformance(
     claude_projects_dir: str | None,
     failures: list[str],
 ) -> None:
-    """agents/SKILL.md BLOCKING 계약 3종(PROGRESS 체크포인트 / claude-worker
+    """prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종(PROGRESS 체크포인트 / claude-worker
     heartbeat / implementation entry guard)의 post-hoc 검사를 위임하고 실패를
     ``session-conformance: `` 접두로 folding 한다. 설계:
     docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md

package/runtime/validators/validate_session_conformance.py

@@ -1,12 +1,12 @@
-"""agents/SKILL.md BLOCKING 계약 3종의 post-hoc conformance 검사.
+"""prompts/lead/okstra-lead-contract.md BLOCKING 계약 3종의 post-hoc conformance 검사.
 
 설계: docs/superpowers/specs/2026-06-10-blocking-contract-posthoc-conformance-design.md
 
 | 검사 | 선언 위치 | 증거 |
 |------|----------|------|
-| 1. lead PROGRESS 체크포인트 라인 | agents/SKILL.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
+| 1. lead PROGRESS 체크포인트 라인 | prompts/lead/okstra-lead-contract.md "Progress reporting (BLOCKING)" | lead 세션 jsonl 의 assistant text 블록 |
 | 2. claude-worker 5분 heartbeat | agents/workers/claude-worker.md "Heartbeat" | audit 사이드카의 `- PROGRESS: <stage> <ISO>` 라인 |
-| 3. implementation sidecar entry guard | agents/SKILL.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
+| 3. implementation sidecar entry guard | prompts/lead/okstra-lead-contract.md "Entry guard (BLOCKING)" | lead 세션 jsonl 의 Read tool_use |
 
 스캔 규칙 (false-pass 방지가 핵심):
 - `type == "assistant"` 레코드만 본다 — Skill 호출 시 SKILL.md 본문(체크포인트
@@ -336,7 +336,7 @@ def _check_worker_checkpoint_lines(
             errors.append(
                 f"PROGRESS checkpoint missing: no `phase-4-dispatch worker=<role>` "
                 f"line names worker `{role}` — one line per dispatched worker, "
-                "agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
         if status == "completed" and not _phase_mentions_worker(
             by_phase.get("phase-5-collect", []), needles
@@ -344,7 +344,7 @@ def _check_worker_checkpoint_lines(
             errors.append(
                 f"PROGRESS checkpoint missing: no `phase-5-collect worker=<role>` "
                 f"line names completed worker `{role}` — one line per collected "
-                "result, agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "result, prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
 
 
@@ -363,19 +363,19 @@ def _check_progress_checkpoints(
         if condition and phase not in by_phase:
             errors.append(
                 f"PROGRESS checkpoint missing: `{phase}` ({detail}) — "
-                "agents/SKILL.md 'Progress reporting (BLOCKING)'."
+                "prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
             )
 
     intake = by_phase.get("phase-1-intake", [])
     if not any("complete" not in line.lower() for _ts, line in intake):
         errors.append(
             "PROGRESS checkpoint missing: `phase-1-intake reading task bundle` "
-            "(start-of-Phase-1 line) — agents/SKILL.md 'Progress reporting (BLOCKING)'."
+            "(start-of-Phase-1 line) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
     if not any("complete" in line.lower() for _ts, line in intake):
         errors.append(
             "PROGRESS checkpoint missing: `phase-1-intake complete` "
-            "(after all intake reads) — agents/SKILL.md 'Progress reporting (BLOCKING)'."
+            "(after all intake reads) — prompts/lead/okstra-lead-contract.md 'Progress reporting (BLOCKING)'."
         )
 
     workers = [w for w in (team_state.get("workers") or []) if isinstance(w, dict)]
@@ -427,7 +427,7 @@ def _check_heartbeat_sidecar(path: Path, errors: list[str]) -> None:
             f"`{rel}` has no `- PROGRESS: <stage> <ISO-8601-UTC>` heartbeat lines — "
             "the claude-worker MUST write `started` immediately and append one "
             "line per stage at <= 5-minute cadence (agents/workers/claude-worker.md "
-            "'Heartbeat', agents/SKILL.md Common Mistakes)."
+            "'Heartbeat', prompts/lead/okstra-lead-contract.md Common Mistakes)."
         )
         return
     if entries[0][0] != "started":
@@ -498,7 +498,7 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
                 f"implementation entry guard: no `Read` of `{basename}` found in "
                 f"the lead session jsonl within this run's window — the sidecar "
                 f"MUST be read fresh at {read_at} every implementation run "
-                "(agents/SKILL.md 'Entry guard (BLOCKING)')."
+                "(prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
             )
             continue
         anchor_ts = anchors.get(anchor_phase)
@@ -507,7 +507,7 @@ def _check_implementation_sidecar_reads(evidence: _LeadEvidence, errors: list[st
                 f"implementation entry guard: `{basename}` was first Read at "
                 f"{min(ts_list)}, not before the first `PROGRESS: {anchor_phase}` "
                 f"line ({anchor_ts}) — it must be loaded at {read_at}, before "
-                "that checkpoint (agents/SKILL.md 'Entry guard (BLOCKING)')."
+                "that checkpoint (prompts/lead/okstra-lead-contract.md 'Entry guard (BLOCKING)')."
             )