okstra 0.151.1 → 0.152.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.151.1",
+  "version": "0.152.0",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.151.1",
-  "builtAt": "2026-08-05T07:39:18.187Z",
+  "package": "0.152.0",
+  "builtAt": "2026-08-05T09:28:14.647Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/implementation-planning.md

@@ -84,8 +84,12 @@
   - The plan lives in `data.json` under `implementationPlanning`, and `schemas/final-report-v2.0.schema.json` requires every one of these keys: `optionCandidates`, `tradeoffMatrix`, `recommendedOption`, `stageMap`, `stages`, `dependencyMigrationRisk`, `validationChecklist`, `rollbackStrategy`, `requirementCoverage`, `planBodyVerification`, `crossProjectDependencies`, `decisionDrafts`, `skippedAdrCandidates`, `variationPointAnalysis`, `userNarrative`. A missing block fails schema validation; there is nothing to satisfy by naming a heading. (Approval is not a body section — it is the YAML frontmatter `approved` field.)
   - Each `stages[]` entry requires `stage`, `title`, `sliceValue`, `acceptance`, `carryIn`, `stepwiseExecution` (1–6 rows), `exitContract`, and `stageValidation`. Each `stageMap[]` row requires `stage`, `title`, `dependsOn`, `stepCount`, `exitContractSummary`.
   - Beyond the schema, `validators/validate-run.py` reads the same data.json for `_validate_planning_conformance_declared`, `_validate_end_state_coverage`, `_validate_requirement_provenance`, `_validate_stage_has_requirement`, and `_validate_plan_body_state_file`. These run for every planning report regardless of schema version.
-  - **Do not chase English heading substrings.** `PLANNING_REQUIRED_SECTIONS` and the structural Stage Map scan (`validators/validate-implementation-plan-stages.py`) live inside `validate_phase_boundary`, which returns immediately when `schemaVersion == "2.0"` — they gate historical v1 Markdown only. The v2 AI-handoff template renders nine headings and serialises the plan as JSON beneath them, so those substrings cannot appear, and a report is not defective for lacking them.
-  - *Guideline, not gated:* write each `stepwiseExecution` row's `action` with a `RED:` / `GREEN:` prefix (or state a TDD exemption in `stageValidation`), and name the success / boundary / failure cases in `acceptance`. The v1 scan checked those tokens literally; v2 requires only that the fields be non-empty, so this is now review-enforced rather than validator-enforced.
+  - **Do not chase English heading substrings.** `PLANNING_REQUIRED_SECTIONS` and the Markdown scan in `collect_validation_errors` live inside `validate_phase_boundary`, which returns immediately when `schemaVersion == "2.0"` — they gate historical v1 Markdown only. The v2 AI-handoff template renders nine headings and serialises the plan as JSON beneath them, so those substrings cannot appear, and a report is not defective for lacking them.
+- Per-stage vertical slice and TDD contract (BLOCKING — enforced on the data, not on heading tokens):
+  - Every stage declares `sliceValue`, `acceptance`, and the three cases `testCaseSuccess` / `testCaseBoundary` / `testCaseFailure` — happy path, edge/boundary input, failure input. **Enforced:** the v2 schema's `if not tddExemption then require` conditional on `ImplementationPlanStage`.
+  - The first `stepwiseExecution` row's `action` starts with `RED:` and its `expected` reads FAIL; some later row's `action` starts with `GREEN:` and its `expected` reads PASS. **Enforced (S10c):** `collect_data_validation_errors` in `validators/validate-implementation-plan-stages.py`, run from `validate-run.py` `_append_stage_data_failures`.
+  - `tddExemption` waives both rules above, and only for `doc-only`, `config-only`, or `pure-rename` work. An empty or arbitrary reason waives nothing. **Enforced (S10e):** same function — the schema alone cannot reject it, because it types the field as a plain string and keys its conditional on the property merely being present.
+  - `stageMap[].dependsOn` must form a DAG (no self-dependency, no unknown stage, no cycle), each row's `stepCount` must equal its stage's actual `stepwiseExecution` row count, and two `(none)`-dependency stages must not name the same file in their `exitContract` — they run as concurrent implementation runs in separate worktrees. **Enforced (S8/S4/S9):** same function.
 - Required deliverable shape (final report, in addition to the standard sections):
   - at least two implementation options. **Each option must include**:
     - **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.

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

@@ -59,6 +59,30 @@ def _check_stage_map_present(text: str) -> List[ValidationError]:
     return []
 
 
+def _parse_depends_on_cell(raw: str) -> List[int] | None:
+    """Stage numbers in a `depends-on` cell; None when the cell is unparseable.
+
+    Schema v2 keeps the same literal cell text in `stageMap[].dependsOn`, so
+    both the Markdown scan and the data scan read it through here.
+    """
+    value = raw.strip()
+    if value in ("(none)", ""):
+        return []
+    try:
+        return [int(x.strip()) for x in value.split(",") if x.strip()]
+    except ValueError:
+        return None
+
+
+def _stage_numbers_monotonic(stages: List[StageMeta]) -> List[ValidationError]:
+    return [
+        ValidationError("S2", r.stage_number,
+            f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}")
+        for i, r in enumerate(stages, start=1)
+        if r.stage_number != i
+    ]
+
+
 def _parse_stage_map(text: str) -> Tuple[List[StageMeta], List[ValidationError]]:
     m = STAGE_MAP_HEADING.search(text)
     if not m:
@@ -80,29 +104,19 @@ def _parse_stage_map(text: str) -> Tuple[List[StageMeta], List[ValidationError]]
             n = int(cells[0])
         except ValueError:
             continue
-        depends_raw = cells[2].strip()
-        if depends_raw in ("(none)", ""):
-            depends = []
-        else:
-            try:
-                depends = [int(x.strip()) for x in depends_raw.split(",") if x.strip()]
-            except ValueError:
-                # 비정수 depends_on 셀 → 행 skip (비정수 stage_number 와 동일). raw
-                # ValueError 를 흘리면 _stage_map_reject_detail·handoff 의 except
-                # PrepareError 를 우회해 traceback 으로 죽으므로, 누락된 행을 하류
-                # S2(비단조) 검사가 잡게 한다.
-                continue
+        depends = _parse_depends_on_cell(cells[2])
+        if depends is None:
+            # 비정수 depends_on 셀 → 행 skip (비정수 stage_number 와 동일). raw
+            # ValueError 를 흘리면 _stage_map_reject_detail·handoff 의 except
+            # PrepareError 를 우회해 traceback 으로 죽으므로, 누락된 행을 하류
+            # S2(비단조) 검사가 잡게 한다.
+            continue
         try:
             step_count = int(cells[3])
         except ValueError:
             step_count = -1
         rows.append(StageMeta(n, cells[1], depends, step_count, cells[4]))
-    errors: List[ValidationError] = []
-    for i, r in enumerate(rows, start=1):
-        if r.stage_number != i:
-            errors.append(ValidationError("S2", r.stage_number,
-                f"stage numbers must be 1..N monotonic, got {r.stage_number} at row {i}"))
-    return rows, errors
+    return rows, _stage_numbers_monotonic(rows)
 
 
 def _slice_stage_section(text: str, stage_number: int) -> str:
@@ -358,16 +372,8 @@ def _extract_exit_contract_files(section: str) -> set:
     return set(PATH_TOKEN.findall(body))
 
 
-def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[ValidationError]:
-    """S9: two `depends-on (none)` stages must not predict the same file —
-    otherwise two parallel implementation runs would edit it concurrently."""
-    files = {
-        s.stage_number: _extract_exit_contract_files(
-            _slice_stage_section(text, s.stage_number)
-        )
-        for s in stages
-        if not s.depends_on
-    }
+def _report_shared_parallel_files(files: dict) -> List[ValidationError]:
+    """S9 over an already-extracted {stage_number: {path}} map."""
     errs: List[ValidationError] = []
     nums = sorted(files)
     for i in range(len(nums)):
@@ -381,6 +387,18 @@ def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[Validatio
     return errs
 
 
+def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+    """S9: two `depends-on (none)` stages must not predict the same file —
+    otherwise two parallel implementation runs would edit it concurrently."""
+    return _report_shared_parallel_files({
+        s.stage_number: _extract_exit_contract_files(
+            _slice_stage_section(text, s.stage_number)
+        )
+        for s in stages
+        if not s.depends_on
+    })
+
+
 def collect_validation_errors(text: str) -> List[ValidationError]:
     """All S1–S11 checks against the report text; empty list means valid.
 
@@ -404,6 +422,130 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     return errors
 
 
+def _data_stage_metas(
+    stage_map: List[dict],
+) -> Tuple[List[StageMeta], List[ValidationError]]:
+    rows = []
+    for row in stage_map:
+        if not isinstance(row, dict) or not isinstance(row.get("stage"), int):
+            continue
+        depends = _parse_depends_on_cell(str(row.get("dependsOn") or ""))
+        if depends is None:
+            continue
+        rows.append(StageMeta(
+            row["stage"],
+            str(row.get("title") or ""),
+            depends,
+            row.get("stepCount") if isinstance(row.get("stepCount"), int) else -1,
+            str(row.get("exitContractSummary") or ""),
+        ))
+    return rows, _stage_numbers_monotonic(rows)
+
+
+def _check_data_slice_tdd(stage: dict) -> List[ValidationError]:
+    """S10c / S10e over one schema-v2 `stages[]` entry.
+
+    The schema already requires `sliceValue`, `acceptance`, and — through its
+    `if not tddExemption then testCase*` conditional — the three test cases, so
+    S10a/S10b/S10d are covered declaratively. Two rules a JSON Schema cannot
+    state are left: the RED→GREEN ordering across `stepwiseExecution` rows, and
+    that a `tddExemption` naming no allowed category cannot waive them. The
+    schema types `tddExemption` as a plain string, so `""` currently satisfies
+    the conditional and drops all three test cases with no reason given.
+    """
+    number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
+    if "tddExemption" in stage:
+        reason = str(stage.get("tddExemption") or "").lower()
+        if not any(cat in reason for cat in TDD_EXEMPTION_ALLOWED):
+            return [ValidationError("S10", number,
+                "S10e: 'tddExemption' reason must be one of "
+                + " / ".join(TDD_EXEMPTION_ALLOWED)
+                + " — an empty or arbitrary reason cannot waive RED/GREEN "
+                "and the three test cases")]
+        return []
+
+    steps = [s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)]
+    actions = [str(s.get("action") or "") for s in steps]
+    if not (actions and actions[0].startswith("RED:")
+            and any(a.startswith("GREEN:") for a in actions)):
+        return [ValidationError("S10", number,
+            "S10c: first stepwiseExecution action must start with 'RED:' and "
+            "some action with 'GREEN:', or declare a 'tddExemption'")]
+
+    errs: List[ValidationError] = []
+    for step in steps:
+        action = str(step.get("action") or "")
+        expected = str(step.get("expected") or "")
+        if action.startswith("RED:") and "FAIL" not in expected.upper():
+            errs.append(ValidationError("S10", number,
+                f"S10c: 'RED:' step's expected must read FAIL, got '{expected}'"))
+        elif action.startswith("GREEN:") and "PASS" not in expected.upper():
+            errs.append(ValidationError("S10", number,
+                f"S10c: 'GREEN:' step's expected must read PASS, got '{expected}'"))
+    return errs
+
+
+def _check_data_step_counts(
+    stage_map: List[StageMeta], stages: List[dict]
+) -> List[ValidationError]:
+    """The Stage Map row is the plan's own index of its stage body. A row
+    claiming a step count the body does not have makes the map unusable for
+    sizing a stage, which is the only reason the cell exists."""
+    by_number = {
+        s.get("stage"): s for s in stages
+        if isinstance(s, dict) and isinstance(s.get("stage"), int)
+    }
+    errs: List[ValidationError] = []
+    for meta in stage_map:
+        stage = by_number.get(meta.stage_number)
+        if stage is None:
+            errs.append(ValidationError("S3", meta.stage_number,
+                "stageMap row has no matching stages[] entry"))
+            continue
+        actual = len([
+            s for s in (stage.get("stepwiseExecution") or []) if isinstance(s, dict)
+        ])
+        if meta.step_count != actual:
+            errs.append(ValidationError("S4", meta.stage_number,
+                f"stageMap stepCount {meta.step_count} != "
+                f"{actual} stepwiseExecution rows"))
+    for number in sorted(n for n in by_number if n not in {m.stage_number for m in stage_map}):
+        errs.append(ValidationError("S3", number,
+            "stages[] entry has no matching stageMap row"))
+    return errs
+
+
+def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
+    """The S-checks that schema v2 cannot express, over `implementationPlanning`.
+
+    `collect_validation_errors` scans rendered v1 Markdown, and
+    `validate_phase_boundary` returns before calling it for a v2 report — so on
+    the current schema nothing enforced the depends-on DAG, parallel-stage file
+    safety, RED→GREEN ordering, or the TDD-exemption vocabulary. The schema
+    covers presence and cardinality; this covers the relationships between
+    fields, which is what a JSON Schema has no way to say.
+    """
+    stage_map, errors = _data_stage_metas(planning.get("stageMap") or [])
+    stages = [s for s in (planning.get("stages") or []) if isinstance(s, dict)]
+    if not stage_map and not stages:
+        return errors
+
+    errors.extend(_check_data_step_counts(stage_map, stages))
+    errors.extend(_check_depends_on(stage_map))
+    errors.extend(_report_shared_parallel_files({
+        meta.stage_number: set(PATH_TOKEN.findall(
+            str((next(
+                (s for s in stages if s.get("stage") == meta.stage_number), {}
+            )).get("exitContract") or "")
+        ))
+        for meta in stage_map
+        if not meta.depends_on
+    }))
+    for stage in stages:
+        errors.extend(_check_data_slice_tdd(stage))
+    return errors
+
+
 def main(argv: List[str]) -> int:
     p = argparse.ArgumentParser()
     p.add_argument("--plan", required=True)

package/runtime/validators/validate-run.py

@@ -6177,6 +6177,31 @@ def _load_stage_validator():
     return mod
 
 
+def _append_stage_data_failures(data: Mapping[str, Any], failures: list[str]) -> None:
+    """Run the stage relationship checks that schema v2 cannot express.
+
+    `_append_stage_structure_failures` scans rendered Markdown and sits after
+    the v2 early return in `validate_phase_boundary`, so for a v2 report the
+    depends-on DAG, parallel-stage file safety, RED→GREEN ordering, and the
+    TDD-exemption vocabulary had nothing enforcing them. The same validator
+    owns both modes so the rule vocabulary stays defined once.
+    """
+    if (data or {}).get("schemaVersion") != "2.0":
+        return  # v1 reports are covered by the Markdown scan.
+    planning = (data or {}).get("implementationPlanning")
+    if not isinstance(planning, Mapping):
+        return  # Schema validation already reported the missing block.
+    mod = _load_stage_validator()
+    if mod is None:  # pragma: no cover — repo/runtime always ship the file
+        failures.append(f"cannot load Stage Map validator at {_STAGE_VALIDATOR_PATH}")
+        return
+    for e in mod.collect_data_validation_errors(dict(planning)):
+        failures.append(
+            f"implementation-planning stage contract invalid "
+            f"[{e.code} stage={e.stage}]: {e.message}"
+        )
+
+
 def _append_stage_structure_failures(content: str, failures: list[str]) -> None:
     """Enforce the Stage Map structural contract at the implementation-planning
     boundary. Without this, a plan missing `## 5.5 Stage Map` passes the
@@ -7420,6 +7445,7 @@ def main() -> int:
                     validation_data, brief_path, failures
                 )
                 _validate_stage_has_requirement(validation_data, failures)
+                _append_stage_data_failures(validation_data, failures)
         if task_type == "improvement-discovery":
             run_dir = report_path.parent.parent
             _validate_improvement_discovery(report_path, run_dir, brief_path, failures)