okstra 0.169.1 → 0.170.0

package/runtime/python/okstra_ctl/plan_derivations.py

@@ -0,0 +1,94 @@
+"""Find the statements an answered clarification may have just falsified.
+
+`_common-contract.md` §"Supersession" and `report-writer.md` §"Self-fix rewrite"
+both say the same thing: an answer does not merely add a decision, it invalidates
+whatever the plan wrote under the opposite assumption, so before editing you must
+"grep the constant, the symbol, the path, the requirement ID across the whole
+plan body". Both leave that grep to the author's diligence, and it is the step
+that gets skipped — in one observed run, 17 of 23 blocked plan items were a
+recorded decision whose derivations were never swept.
+
+This does the grep. It is deliberately advisory: it returns candidate locations,
+never a verdict about which ones are now false. Deciding that is the author's
+job, and a tool that guessed would be trading one silent failure for another.
+"""
+from __future__ import annotations
+
+import re
+from typing import Any, Iterator, Mapping, Sequence
+
+# A backticked span is how both contracts tell an author to write a symbol, a
+# path, or a constant, so it is the highest-signal thing to extract. Bare prose
+# words are deliberately not extracted: they match everywhere and would bury the
+# hits that matter.
+_BACKTICKED_RE = re.compile(r"`([^`\n]+)`")
+# Ids the plan carries in its own rows (`R-001`, `P-Step-3`, `VC-002`) and the
+# ticket ids the brief uses (`DEV-10174`, `PROD-1623`).
+_ID_RE = re.compile(r"\b(?:[A-Z][A-Za-z]*-[A-Za-z0-9]+(?:-[A-Za-z0-9]+)*)\b")
+# Below this length a token matches too much to be worth reading: `id`, `db`,
+# and `ko` each hit dozens of unrelated rows.
+_MIN_TOKEN_LENGTH = 3
+_EXCERPT_MAX = 160
+
+
+def extract_tokens(text: str) -> list[str]:
+    """The symbols, paths, and ids an answer names, longest first.
+
+    Longest first so a caller reading the report sees the specific token before
+    the general one it contains (`src/domains/font` before `src/domains`).
+    """
+    found: set[str] = set()
+    for raw in _BACKTICKED_RE.findall(text):
+        token = raw.strip()
+        # A backticked sentence is prose in code font, not a symbol.
+        if len(token) >= _MIN_TOKEN_LENGTH and " " not in token:
+            found.add(token)
+    for token in _ID_RE.findall(text):
+        if len(token) >= _MIN_TOKEN_LENGTH:
+            found.add(token)
+    return sorted(found, key=lambda token: (-len(token), token))
+
+
+def _string_leaves(node: Any, pointer: str = "") -> Iterator[tuple[str, str]]:
+    if isinstance(node, str):
+        yield pointer, node
+    elif isinstance(node, Mapping):
+        for key, value in node.items():
+            yield from _string_leaves(value, f"{pointer}/{key}")
+    elif isinstance(node, Sequence) and not isinstance(node, (str, bytes)):
+        for index, value in enumerate(node):
+            yield from _string_leaves(value, f"{pointer}/{index}")
+
+
+def _excerpt(text: str, token: str) -> str:
+    index = text.find(token)
+    if index < 0:
+        return text[:_EXCERPT_MAX]
+    start = max(0, index - _EXCERPT_MAX // 3)
+    excerpt = text[start:start + _EXCERPT_MAX]
+    return ("…" if start else "") + excerpt + ("…" if len(text) > start + _EXCERPT_MAX else "")
+
+
+def find_derivations(
+    plan: Mapping[str, Any],
+    tokens: Sequence[str],
+    *,
+    exclude_pointer_prefix: str = "",
+) -> list[dict[str, str]]:
+    """Every string in *plan* that mentions one of *tokens*.
+
+    One hit per (pointer, token): a row naming two affected symbols is two things
+    to re-check, not one.
+    """
+    hits: list[dict[str, str]] = []
+    for pointer, text in _string_leaves(plan):
+        if exclude_pointer_prefix and pointer.startswith(exclude_pointer_prefix):
+            continue
+        for token in tokens:
+            if token in text:
+                hits.append({
+                    "token": token,
+                    "pointer": pointer,
+                    "excerpt": _excerpt(text, token),
+                })
+    return hits

package/runtime/python/okstra_ctl/plan_items_cli.py

@@ -14,8 +14,15 @@ import sys
 from typing import Any
 
 from .convergence_store import write_json_atomic
+from .plan_derivations import extract_tokens, find_derivations
 from .plan_items import PlanItemContractError, extract_plan_items
-from .verdict_blocks import VerdictBlock, VerdictBlockError, parse_verdict_blocks
+from .user_response import parse_user_response_entries
+from .verdict_blocks import (
+    PLAN_ITEM_VERDICTS,
+    VerdictBlock,
+    VerdictBlockError,
+    parse_verdict_blocks,
+)
 
 
 def _load_json_object(path: Path) -> dict[str, Any]:
@@ -64,6 +71,20 @@ def _parser() -> argparse.ArgumentParser:
                          help="one worker's plan-verify result file (repeatable)")
     collect.add_argument("--items", type=Path, required=True)
     collect.add_argument("--output", type=Path, required=True)
+    derivations = commands.add_parser(
+        "derivations",
+        help="list plan statements an answered clarification may have falsified",
+    )
+    derivations.add_argument("--data", type=Path, required=True)
+    derivations.add_argument("--response", type=Path, required=True,
+                             help="the user-responses sidecar for this run")
+    derivations.add_argument("--clarification", default=None,
+                             help="only this C-id (default: every answered one)")
+    seed = commands.add_parser(
+        "seed",
+        help="create the planBodyVerification.planItems[] rows a round lands in",
+    )
+    seed.add_argument("--data", type=Path, required=True)
     apply_verdicts = commands.add_parser(
         "apply-verdicts",
         help="overwrite planBodyVerification.planItems[].verdicts in data.json",
@@ -112,8 +133,18 @@ def _assigned_item_ids(items_path: Path) -> list[str]:
 
 def _verdict_row(worker: str, block: VerdictBlock) -> dict[str, Any]:
     """One `planItems[].verdicts[]` row. Optional fields stay absent when empty
-    so the recorded table shows what the worker actually said."""
-    row: dict[str, Any] = {"worker": worker, "verdict": block.verdict}
+    so the recorded table shows what the worker actually said.
+
+    The verdict crosses a vocabulary boundary here: a worker answers
+    `UNVERIFIABLE`, and the schema persists that as `verification-error`
+    (`PLAN_ITEM_VERDICTS`). Writing the worker's token straight through produced
+    a data.json its own schema rejects, and the mapping the contract prescribes
+    had to be applied by hand every round.
+    """
+    row: dict[str, Any] = {
+        "worker": worker,
+        "verdict": PLAN_ITEM_VERDICTS[block.verdict],
+    }
     for key, value in (
         ("breakageKind", block.breakage_kind),
         ("fixability", block.fixability),
@@ -194,6 +225,84 @@ def _plan_body_items(data: dict[str, Any], data_path: Path) -> list[dict[str, An
     return items
 
 
+def _derivations(args: argparse.Namespace) -> dict[str, Any]:
+    """Candidate statements each answered clarification may have falsified.
+
+    Advisory by construction: it reports where a decision's subject is mentioned
+    and never which mentions are now wrong. Both contracts require the author to
+    enumerate before editing; this supplies the enumeration, which is the half
+    that was being skipped, and leaves the judgement where it belongs.
+    """
+    try:
+        sidecar = args.response.read_text(encoding="utf-8")
+    except (OSError, UnicodeError) as exc:
+        raise PlanItemContractError(
+            f"cannot read user-response sidecar {args.response}: {exc}"
+        ) from exc
+    planning = _planning(_load_json_object(args.data))
+    entries = [
+        entry for entry in parse_user_response_entries(sidecar)
+        if args.clarification is None or entry.response_id == args.clarification
+    ]
+    if args.clarification is not None and not entries:
+        raise PlanItemContractError(
+            f"{args.response} has no response block for {args.clarification}"
+        )
+    clarifications = []
+    for entry in entries:
+        tokens = extract_tokens(f"{entry.value}\n{entry.rationale or ''}")
+        clarifications.append({
+            "id": entry.response_id,
+            "disposition": entry.disposition,
+            "tokens": tokens,
+            "candidates": find_derivations(planning, tokens),
+        })
+    return {
+        "ok": True,
+        "operation": "derivations",
+        "advisory": True,
+        "clarifications": clarifications,
+    }
+
+
+def _seed(args: argparse.Namespace) -> dict[str, Any]:
+    """Create the `planBodyVerification.planItems[]` rows a round lands in.
+
+    `apply-verdicts` refuses a verdict whose item has no row — correctly, since
+    the gate is re-derived from that table and a verdict with nowhere to land
+    would score as never cast. But nothing created the rows: the report writer
+    leaves `planItems: []` (§5.5.9 is a lead substep that runs after it), and
+    there was no step, in code or in the contract, that filled them. Every round
+    had to be hand-seeded before the CLI would accept its own output.
+
+    Idempotent by id. An existing row keeps everything it carries — verdicts
+    already applied, `carriedForwardFromSeq`, `selfFixNote` — because a re-seed
+    between rounds must not erase the round before it.
+    """
+    extracted = _envelope(_load_json_object(args.data))["items"]
+    data = _load_json_object(args.data)
+    recorded = _plan_body_items(data, args.data)
+    known = {
+        item.get("id")
+        for item in recorded
+        if isinstance(item, Mapping)
+    }
+    added = [
+        {**item, "verdicts": []}
+        for item in extracted
+        if item["id"] not in known
+    ]
+    recorded.extend(added)
+    write_json_atomic(args.data, data)
+    return {
+        "ok": True,
+        "operation": "seed",
+        "path": str(args.data),
+        "seeded": len(added),
+        "existing": len(known),
+    }
+
+
 def _apply_verdicts(args: argparse.Namespace) -> dict[str, Any]:
     data = _load_json_object(args.data)
     incoming = _load_json_object(args.verdicts).get("planItems")
@@ -226,6 +335,8 @@ _HANDLERS = {
     "extract": _extract,
     "validate": _validate,
     "collect-verdicts": _collect_verdicts,
+    "derivations": _derivations,
+    "seed": _seed,
     "apply-verdicts": _apply_verdicts,
 }
 

package/runtime/python/okstra_ctl/run.py

@@ -68,6 +68,7 @@ from .domain.host import (
     ProviderUnavailable,
 )
 from .model_discovery import normalize_execution_for_dispatch
+from .worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE
 from .models import (
     ModelAssignment,
     UnknownProviderError,
@@ -2523,7 +2524,12 @@ def _allowed_agent_audiences(
     elif inp.task_type == "final-verification":
         audiences.add("acceptance-verifier")
     else:
-        audiences.add("analysis-worker")
+        # Same map the prompt policy resolves the duty from. Allowing a
+        # different audience here than the one the policy will ask for makes
+        # every worker prompt in the phase fail materialization.
+        audiences.add(
+            ANALYSIS_DUTY_BY_TASK_TYPE.get(inp.task_type, "analysis-worker")
+        )
     if models.critic_choice not in {"", "off"}:
         audiences.update({"scope-critic", "acceptance-critic"})
     return sorted(audiences)

package/runtime/python/okstra_ctl/schema_excerpt.py

@@ -23,6 +23,7 @@ from __future__ import annotations
 
 import json
 import re
+from pathlib import Path
 
 from .report_contract import TASK_TYPE_DATA_PROPERTY
 
@@ -78,6 +79,39 @@ def excerpt_cut_from_version(excerpt: dict) -> str:
     return value if isinstance(value, str) else ""
 
 
+def excerpt_version_skew(excerpt_path: Path, installed: str) -> str:
+    """The version the bundle excerpt was cut from, when it is not *installed*.
+
+    Empty means no actionable skew: the file is absent or unreadable, carries no
+    stamp, or matches. A non-empty return is the older version, which the caller
+    turns into its own message.
+
+    The comparison used to live only in the renderer's error decorator, so it ran
+    in Phase 6 — after a worker had already authored a whole report against a
+    stale excerpt. The same two values are available much earlier, and the fix
+    (re-prepare the bundle) is the same either way.
+    """
+    if not installed:
+        return ""
+    try:
+        excerpt = json.loads(excerpt_path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return ""
+    if not isinstance(excerpt, dict):
+        return ""
+    cut_from = excerpt_cut_from_version(excerpt)
+    return cut_from if cut_from and cut_from != installed else ""
+
+
+def bundle_excerpt_path(start: Path) -> Path | None:
+    """The task bundle's schema excerpt, found by walking up from *start*."""
+    for ancestor in Path(start).resolve().parents:
+        candidate = ancestor / "instruction-set" / "final-report-schema.json"
+        if candidate.is_file():
+            return candidate
+    return None
+
+
 def build_schema_excerpt(schema: dict, task_type: str, cut_from_version: str = "") -> dict:
     """Return a task-type-scoped copy of *schema*.
 

package/runtime/python/okstra_ctl/verdict_blocks.py

@@ -38,6 +38,23 @@ ADVERSARIAL_VERDICTS = {
     "UNVERIFIABLE": "unverifiable",
     "VERIFICATION-ERROR": "verification-error",
 }
+# Plan-body verdicts persist in their own vocabulary, which is NOT the
+# convergence one above: the schema keeps the first three tokens uppercase
+# (`$defs/PlanBodyVerification/properties/planItems/items/properties/verdicts/
+# items/properties/verdict`) and has no `UNVERIFIABLE` member at all.
+# `plan-body-verification.md` §"Planning-time environment gap" states the
+# mapping — "Recording `UNVERIFIABLE` is the honest outcome — it is persisted as
+# `verification-error`" — and it lives here rather than inside the transcription
+# CLI so the worker-facing token and the persisted token are decided in one
+# place. Writing the raw token through put a value in data.json that its own
+# schema rejects.
+PLAN_ITEM_VERDICTS = {
+    "AGREE": "AGREE",
+    "DISAGREE": "DISAGREE",
+    "SUPPLEMENT": "SUPPLEMENT",
+    "UNVERIFIABLE": "verification-error",
+    "VERIFICATION-ERROR": "verification-error",
+}
 DISAGREE_BASES = frozenset({"counter-evidence", "burden-not-met"})
 
 _ITEM_RE = re.compile(r"^###[ \t]+(?P<id>[^\s:]+)[ \t]*:?.*$", re.MULTILINE)

package/runtime/python/okstra_ctl/worker_prompt_policy.py

@@ -58,6 +58,17 @@ SUPPORTED_TASK_TYPES = frozenset({
     "release-handoff",
     *ANALYSIS_TASK_TYPES,
 })
+# One duty per analysis ROLE, not per phase. Phases that ask their worker for the
+# same kind of judgement share a contract — requirements- and improvement-discovery
+# both hand over candidates they do not start — and a phase whose worker decides
+# something else gets its own. A task type absent from this map takes the
+# observational default below: describe the area, do not design for it.
+ANALYSIS_DUTY_BY_TASK_TYPE: dict[str, AgentAudience] = {
+    "requirements-discovery": "discovery-worker",
+    "improvement-discovery": "discovery-worker",
+    "error-analysis": "diagnosis-worker",
+    "implementation-planning": "planning-worker",
+}
 WORKER_PREAMBLE_FILENAME_BY_AUDIENCE = {
     "analysis": "worker-prompt-preamble.md",
     "implementation-executor": "implementation-worker-preamble.md",
@@ -113,7 +124,7 @@ def resolve_prompt_plan(
         if dispatch_kind == "critic"
         else "acceptance-verifier"
         if task_type == "final-verification"
-        else "analysis-worker"
+        else ANALYSIS_DUTY_BY_TASK_TYPE.get(task_type, "analysis-worker")
     )
     if task_type == "implementation" and not executor_worker_id:
         raise ValueError("implementation executor worker ID is required")

package/runtime/python/okstra_project/resolver.py

@@ -108,6 +108,40 @@ def resolve_architecture(project_root: Path | str) -> str:
     return style if style in _ARCHITECTURE_STYLES else "none"
 
 
+def resolve_review_rule_packs(project_root: Path | str) -> tuple[str, ...]:
+    """Return the project's declared review rule pack paths, else ``()``.
+
+    A review rule pack is a project's own review standard — the file a phase
+    reads before judging a diff. It used to reach a run only when the task
+    brief cited its exact path, so a team standard applied or not depending on
+    who wrote the brief. Declaring it here makes it apply to every run in the
+    project; the brief citation still works and the two are a union.
+
+    Mirrors resolve_architecture's failure posture: any read/parse problem or a
+    non-list value degrades to "none declared" rather than raising inside a run.
+    An entry that is not an absolute path is dropped, because workers run with
+    a worktree as cwd — a relative path would resolve against a tree that does
+    not contain the pack, and would mean a different file per worker.
+    """
+    try:
+        payload = json.loads(project_json_path(Path(project_root)).read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return ()
+    if not isinstance(payload, dict):
+        return ()
+    declared = payload.get("reviewRulePacks")
+    if not isinstance(declared, list):
+        return ()
+    packs = []
+    for entry in declared:
+        if not isinstance(entry, str) or not entry.strip():
+            continue
+        candidate = Path(entry.strip()).expanduser()
+        if candidate.is_absolute():
+            packs.append(str(candidate))
+    return tuple(dict.fromkeys(packs))
+
+
 def upsert_project_json(project_root: Path, project_id: str, *,
                          now: Optional[str] = None) -> dict:
     """project.json 을 읽거나 새로 만든다.

package/runtime/skills/okstra-setup/references/project-config.md

@@ -252,3 +252,41 @@ rules from advisory to a binding planning + verification constraint:
 
 The full two-layer model lives in `docs/architecture.md` § Project
 self-registration.
+
+## G. Project review rule packs (`reviewRulePacks`)
+
+`reviewRulePacks` declares the review standards this project's phases read
+before they judge a plan or a diff — a team PR-review skill's `SKILL.md`, for
+example. Without it a pack reaches a run only when the task brief cites its
+exact path, so whether the team standard applied came down to who wrote the
+brief. A declared pack applies to every run in the project; the brief citation
+keeps working, and the two channels are a union.
+
+`okstra setup` never writes it. Hand-add it to `project.json` and the upsert
+preserves it:
+
+```json
+{
+  "reviewRulePacks": [
+    "/Users/me/.claude/skills/team-pr-reviewer/SKILL.md"
+  ]
+}
+```
+
+- **Absolute paths only.** A worker runs with a task worktree as its cwd, so a
+  relative path names a different file there — relative entries are dropped by
+  `scripts/okstra_project/resolver.py::resolve_review_rule_packs`, which also
+  falls back to "none declared" on an unreadable or malformed `project.json`.
+  A leading `~` is expanded.
+- **Who reads it.** `implementation-planning` (to plan away the findings before
+  the code exists), the implementation executor's coding-conventions preflight,
+  and the static review passes of the implementation verifier and
+  `final-verification`. Each reads only the declared file and the
+  `references/*.md` files it directly names — never a parent directory or a
+  host skill catalog.
+- **What is machine-checked.** `okstra doctor --phase <phase>` fails its
+  `review rule packs` check when a declared path is not a readable file,
+  because a stale path otherwise costs the whole pack in silence: the phase
+  records that it read no rules and the run still passes. Whether a pack that
+  does resolve was actually read and applied stays the phase's own
+  `project-review-rules:` record — no machine check reads a worker's reasoning.

package/runtime/validators/lib/fixtures.sh

@@ -544,6 +544,14 @@ if WORKSPACE_ROOT:
         link_agent_dispatch_result,
         record_verified_agent_dispatch,
     )
+    # The analysis duty depends on the task type, exactly as it does in a real
+    # run — a fixture that assumed one audience for every phase would be
+    # rejected by the manifest's own allowlist.
+    from okstra_ctl.worker_prompt_policy import ANALYSIS_DUTY_BY_TASK_TYPE
+
+    analysis_audience = ANALYSIS_DUTY_BY_TASK_TYPE.get(
+        str(run_manifest.get("taskType") or ""), "analysis-worker"
+    )
 
     lead_record = record_verified_agent_dispatch(
         project_root=project_root,
@@ -580,7 +588,7 @@ if WORKSPACE_ROOT:
             worker_id=worker_id,
             audience=(
                 "report-writer" if worker_id == "report-writer"
-                else "analysis-worker"
+                else analysis_audience
             ),
             assignment_ref=assignment_ref,
             purpose=None,

package/runtime/validators/validate-run.py

@@ -5470,6 +5470,27 @@ def _plan_verify_result_workers(report_path: Path, task_type: str) -> set[str] |
     return workers
 
 
+def _plan_verify_seq_near_misses(report_path: Path, task_type: str) -> list[str]:
+    """Plan-verify results in the directory that this run's seq filter excluded.
+
+    The seq comes from the report filename, and a run whose `reports` and
+    `workerResults` sequences differ makes the other one look equally plausible
+    to a lead naming the file by hand. Naming a near miss is the difference
+    between "the file is missing" and "the file is there under a different seq"
+    — the first sends a lead to re-dispatch two workers that already ran.
+    """
+    seq = _report_run_seq(report_path)
+    if not seq:
+        return []
+    directory = report_path.parent.parent / "worker-results"
+    matched = set(directory.glob(f"*-plan-verify-r*-{task_type}-{seq}.md"))
+    return sorted(
+        path.name
+        for path in directory.glob(f"*-plan-verify-r*-{task_type}-*.md")
+        if path not in matched
+    )
+
+
 def _validate_plan_body_verdict_provenance(
     data: dict,
     report_path: Path,
@@ -5514,14 +5535,28 @@ def _validate_plan_body_verdict_provenance(
             "final-report data.json: planBodyVerification records verdicts from "
             f"{unbacked} but no matching plan-body reverify result file exists "
             f"under `runs/{task_type}/worker-results/` "
-            f"(expected `<worker>-plan-verify-r<N>-{task_type}-<seq>.md`). "
-            "A vote the gate is computed from MUST trace back to a dispatch "
+            f"(globbed `*-plan-verify-r*-{task_type}-"
+            f"{_report_run_seq(report_path) or '*'}.md`, where the seq is the "
+            f"report's own — `final-report-{task_type}-<seq>` — not this run's "
+            f"`workerResults` sequence)"
+            + _near_miss_clause(report_path, task_type)
+            + ". A vote the gate is computed from MUST trace back to a dispatch "
             "that actually returned — otherwise the round can be skipped and "
             'the gate still read `passed` (plan-body-verification.md §"Round '
             'protocol" step 3).'
         )
 
 
+def _near_miss_clause(report_path: Path, task_type: str) -> str:
+    near = _plan_verify_seq_near_misses(report_path, task_type)
+    if not near:
+        return ""
+    return (
+        f"; the directory does hold {near}, which the seq filter excluded — "
+        f"rename to this run's report seq rather than re-dispatching"
+    )
+
+
 _UNIFORM_VERIFIER_MIN_ITEMS = 5