okstra 0.169.1 → 0.170.1

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/schemas/final-report-v2.0.schema.json

@@ -7746,6 +7746,11 @@
                     },
                     "note": {
                       "type": "string"
+                    },
+                    "round": {
+                      "description": "The plan-body verification round this verdict was cast in. A self-fix round rewrites the plan after a verification round, so a verdict whose round is at or before `selfFixRoundsApplied` judged text that has since changed. Without it there is no way to tell how many rewrites a surviving verdict predates, and a gate can pass on judgements two generations stale.",
+                      "type": "integer",
+                      "minimum": 1
                     }
                   }
                 }

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

@@ -5351,6 +5351,76 @@ def _validate_round_recorded_verdicts(data: dict, failures: list[str]) -> None:
     )
 
 
+def _validate_verdict_rounds_outlive_self_fix(
+    data: dict,
+    failures: list[str],
+) -> None:
+    """A verdict must judge the plan the gate is about to pass.
+
+    Rounds interleave with rewrites: round 1, self-fix 1, round 2, self-fix 2 …
+    so a verdict cast in round R judged the text as it stood after self-fix
+    R-1. If any self-fix ran afterwards — `selfFixRoundsApplied >= R` — that
+    text has changed and the verdict is stale by construction. No semantic
+    analysis is needed to know that; the arithmetic settles it.
+
+    The sibling `_validate_verdicts_match_current_subjects` cannot see this. It
+    compares each row's own recorded `subject`, which catches a positional shift
+    but not the case that matters here: an item whose own wording never changed
+    while the stage it points at was rewritten under it. Observed on a real run
+    — the gate read `passed-with-dissent` with zero blockers, and re-running one
+    round flipped 3 of 27 items to `majority-disagree`, all correctness-critical,
+    because their surviving verdicts predated two self-fix rounds.
+
+    Scoped to items this run verified: a `carriedForwardFromSeq` row belongs to
+    the prior run's record and is judged by that run's seq, not this one's
+    rounds.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    pbv = ip.get("planBodyVerification")
+    if not isinstance(pbv, dict):
+        return
+    applied = pbv.get("selfFixRoundsApplied")
+    if not isinstance(applied, int) or applied < 1:
+        # With no rewrite after any round there is nothing a verdict can be
+        # stale against, and an unstamped row is then simply unremarkable.
+        return
+
+    stale: list[str] = []
+    unstamped: list[str] = []
+    for item in pbv.get("planItems") or []:
+        if not isinstance(item, dict) or item.get("carriedForwardFromSeq"):
+            continue
+        item_id = str(item.get("id") or "").strip()
+        for verdict in item.get("verdicts") or []:
+            if not isinstance(verdict, dict):
+                continue
+            round_number = verdict.get("round")
+            if not isinstance(round_number, int) or isinstance(round_number, bool):
+                unstamped.append(item_id)
+            elif round_number <= applied:
+                stale.append(item_id)
+    if unstamped:
+        failures.append(
+            f"final-report data.json: plan item(s) {sorted(set(unstamped))} carry "
+            f"a verdict with no `round`, and {applied} self-fix round(s) rewrote "
+            "the plan. Without the round there is no way to tell whether the "
+            "verdict judged the current text or a version two rewrites old. "
+            "Re-record the round's votes with `okstra plan-items apply-verdicts "
+            "--round <N>`."
+        )
+    if stale:
+        failures.append(
+            f"final-report data.json: plan item(s) {sorted(set(stale))} carry a "
+            f"verdict from a round at or before self-fix round {applied}, so the "
+            "text they judged has since been rewritten. The gate is computed "
+            "from these votes, so passing on them declares a plan verified that "
+            "nobody verified. Re-verify those items in a round after the last "
+            'self-fix (plan-body-verification.md §"Round protocol" step 7).'
+        )
+
+
 def _validate_verdicts_match_current_subjects(
     data: dict,
     failures: list[str],
@@ -5470,6 +5540,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 +5605,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
 
 
@@ -6332,6 +6437,7 @@ def validate_plan_body_section(
     _validate_aborted_gate_has_clarification(data, failures)
     _validate_round_recorded_verdicts(data, failures)
     _validate_verdicts_match_current_subjects(data, failures)
+    _validate_verdict_rounds_outlive_self_fix(data, failures)
     _validate_plan_item_extraction_completeness(data, failures)
     _validate_plan_item_subject_substance(data, failures)
     _validate_plan_body_clarification_matching(data, failures)