okstra 0.172.0 → 0.174.0

package/runtime/templates/reports/report.js

@@ -44,6 +44,28 @@
     return String(s == null ? "" : s).replace(/^\s+|\s+$/g, "");
   }
 
+  var DIRECTION_IDENTITY_WHITESPACE = [
+    0x0009, 0x000A, 0x000B, 0x000C, 0x000D,
+    0x001C, 0x001D, 0x001E, 0x001F, 0x0020, 0x0085, 0x00A0, 0x1680,
+    0x2000, 0x2001, 0x2002, 0x2003, 0x2004, 0x2005, 0x2006, 0x2007,
+    0x2008, 0x2009, 0x200A, 0x2028, 0x2029, 0x202F, 0x205F, 0x3000,
+    0xFEFF,
+  ];
+
+  function trimDirectionIdentity(value) {
+    var start = 0;
+    var end = value.length;
+    while (
+      start < end &&
+      DIRECTION_IDENTITY_WHITESPACE.indexOf(value.charCodeAt(start)) !== -1
+    ) start += 1;
+    while (
+      end > start &&
+      DIRECTION_IDENTITY_WHITESPACE.indexOf(value.charCodeAt(end - 1)) !== -1
+    ) end -= 1;
+    return value.slice(start, end);
+  }
+
   // Read the user-supplied value and decision effect from one clarification
   // row. Returns null when the row has no usable input.
   function readRowInput(row) {
@@ -181,6 +203,58 @@
     });
   }
 
+  function validateDirectionSelection(selection) {
+    if (!selection) return null;
+    var optionId = String(selection.optionId == null ? "" : selection.optionId);
+    var optionName = String(selection.optionName == null ? "" : selection.optionName);
+    var normalizedId = trimDirectionIdentity(optionId);
+    var normalizedName = trimDirectionIdentity(optionName);
+    if (
+      !normalizedId ||
+      !normalizedName ||
+      /[\r\n]/.test(optionId) ||
+      /[\r\n]/.test(optionName)
+    ) {
+      throw new Error(
+        "DIRECTION SELECTION Option-ID and Option-Name must be " +
+        "non-empty single-line values"
+      );
+    }
+    if (selection.confirmed !== true) {
+      throw new Error("DIRECTION SELECTION requires Confirmed: true");
+    }
+    return {
+      optionId: normalizedId,
+      optionName: normalizedName,
+      confirmed: selection.confirmed,
+      selectionNote: selection.selectionNote,
+      constraints: selection.constraints,
+    };
+  }
+
+  function collectDirectionSelection() {
+    var controls = document.querySelectorAll(
+      'input[name="direction-selection-option"]'
+    );
+    if (!controls.length) return null;
+    var selected = document.querySelector(
+      'input[name="direction-selection-option"]:checked'
+    );
+    if (!selected) {
+      throw new Error("Select an implementation direction");
+    }
+    var confirmed = document.getElementById("direction-selection-confirmed");
+    var note = document.getElementById("direction-selection-note");
+    var constraints = document.getElementById("direction-selection-constraints");
+    return validateDirectionSelection({
+      optionId: selected.value,
+      optionName: selected.getAttribute("data-option-name") || "",
+      confirmed: !!(confirmed && confirmed.checked),
+      selectionNote: note ? trimMultiline(note.value) : "",
+      constraints: constraints ? trimMultiline(constraints.value) : "",
+    });
+  }
+
   // Toggle the visibility of the "기타" companion input next to each
   // select whose current value is "__other__". Wired at bind() time and
   // also called once for the initial state.
@@ -233,13 +307,34 @@
     return chunk;
   }
 
-  function buildUserResponseMarkdown(runMeta, entries, createdAt, planDecision, analysisReview) {
+  function serialiseDirectionSelection(selection) {
+    selection = validateDirectionSelection(selection);
+    return (
+      "\n## DIRECTION SELECTION\n" +
+      "- Status: selected\n" +
+      "- Option-ID: " + selection.optionId + "\n" +
+      "- Option-Name: " + selection.optionName + "\n" +
+      "- Confirmed: true\n" +
+      quotedReviewField("Selection-Note", selection.selectionNote) +
+      quotedReviewField("Constraints", selection.constraints)
+    );
+  }
+
+  function buildUserResponseMarkdown(
+    runMeta, entries, createdAt, planDecision, analysisReview, directionSelection
+  ) {
     var head =
       "---\n" +
       "task-key: " + (runMeta["task-key"] || "") + "\n" +
       "task-type: " + (runMeta["task-type"] || "") + "\n" +
       "seq: " + (runMeta["seq"] || "") + "\n" +
       "source-report: " + (runMeta["source-report"] || "") + "\n" +
+      (runMeta["source-data"]
+        ? "source-data: " + runMeta["source-data"] + "\n"
+        : "") +
+      (runMeta["source-data-sha256"]
+        ? "source-data-sha256: " + runMeta["source-data-sha256"] + "\n"
+        : "") +
       "created-by: user\n" +
       "created-at: " + createdAt + "\n" +
       "---\n" +
@@ -249,6 +344,7 @@
     entries = entries || [];
     var hasPlanDecision = !!planDecision;
     var hasAnalysisReview = !!analysisReview;
+    var hasDirectionSelection = !!directionSelection;
     var chunks = "";
     for (var i = 0; i < entries.length; i++) {
       var e = entries[i];
@@ -265,7 +361,12 @@
       }
       chunks += chunk;
     }
-    if (entries.length === 0 && !hasPlanDecision && !hasAnalysisReview) {
+    if (
+      entries.length === 0 &&
+      !hasPlanDecision &&
+      !hasAnalysisReview &&
+      !hasDirectionSelection
+    ) {
       chunks += "\n_(No user responses recorded.)_\n";
     }
     if (hasPlanDecision) {
@@ -274,6 +375,9 @@
     if (hasAnalysisReview) {
       chunks += serialiseAnalysisReview(analysisReview);
     }
+    if (hasDirectionSelection) {
+      chunks += serialiseDirectionSelection(directionSelection);
+    }
     return head + chunks;
   }
 
@@ -308,22 +412,24 @@
     var out = document.getElementById("user-response-output");
     var planDecision;
     var analysisReview;
+    var directionSelection;
     try {
       planDecision = collectPlanDecision();
       analysisReview = collectAnalysisReview();
+      directionSelection = collectDirectionSelection();
     } catch (e) {
       showOutput(out, e.message || String(e));
       showDismiss(true);
       return "";
     }
     var md = buildUserResponseMarkdown(
-      runMeta, entries, isoNowUtc(), planDecision, analysisReview
+      runMeta, entries, isoNowUtc(), planDecision, analysisReview, directionSelection
     );
     showOutput(out, md);
     showDismiss(true);
     // Nothing answered yet — show the empty serialisation as feedback but
     // don't download a useless file.
-    if (entries.length > 0 || planDecision || analysisReview) {
+    if (entries.length > 0 || planDecision || analysisReview || directionSelection) {
       downloadUserResponse(md, runMeta);
     }
     return md;
@@ -455,6 +561,7 @@
       collectEntries: collectEntries,
       collectPlanDecision: collectPlanDecision,
       collectAnalysisReview: collectAnalysisReview,
+      collectDirectionSelection: collectDirectionSelection,
       exportUserResponse: exportUserResponse,
       setReaderMode: setReaderMode,
     };

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

@@ -52,36 +52,12 @@
     "SessionEnd": [
       {
         "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.okstra/bin/okstra-trace-cleanup.sh --reap"
-          },
           {
             "type": "command",
             "command": "$HOME/.okstra/bin/okstra-team-reconcile.sh --session-end"
           }
         ]
       }
-    ],
-    "SubagentStop": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
-          }
-        ]
-      }
-    ],
-    "TaskCompleted": [
-      {
-        "hooks": [
-          {
-            "type": "command",
-            "command": "$HOME/.okstra/bin/okstra-subagent-reclaim.sh"
-          }
-        ]
-      }
     ]
   }
 }

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

@@ -60,9 +60,14 @@ taskType: "{{FM_TASK_TYPE}}"
   - What is the visible symptom?
   - What are the expected vs actual results?
   - What are the current hypotheses and missing evidence?
+- If `Task Type` is `implementation-option-selection`:
+  - Is this a comparison among possible directions or validation of one preselected direction?
+  - Which stable `EB-NNN`, `PB-NNN`, and `EO-NNN` requirements form the coverage denominator?
+  - Which mechanism, architecture boundary, preservation rule, or implementation constraint must each direction address?
 - If `Task Type` is `implementation-planning`:
-  - What implementation options are under consideration?
-  - What trade-offs, dependencies, or migrations matter?
+  - Which validated selection report and `selectedDirectionRef` authorise this new plan?
+  - Which mechanism, architecture boundary, invariants, and user constraints must the plan preserve?
+  - Which dependencies or migrations matter while realizing that one direction?
   - What validation and rollback approach is expected?
 - If `Task Type` is `implementation`:
   - Which approved `implementation-planning` final report authorises this run, and is its frontmatter `approved: true` cited verbatim?
@@ -141,6 +146,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - 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.
 - "proceed to the next step" 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-option-selection` specifically: compare or validate implementation directions without editing source, running tests/builds, or writing exact file lists, stage maps, and test commands. Only directions with 100% requirement coverage and 100% scope precision may be displayed.
 - 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.
 
 ## Available MCP Servers
@@ -157,7 +163,7 @@ How to invoke (worker-by-worker):
 
 Usage policy:
 
-- **Allowed phases**: `requirements-discovery`, `error-analysis`, `implementation-planning`, `final-verification`. Use only when local schema/data evidence improves the answer. Always cite the server, table, and the SELECT used as evidence in worker output.
+- **Allowed phases**: `requirements-discovery`, `error-analysis`, `implementation-option-selection`, `implementation-planning`, `final-verification`. Use only when local schema/data evidence improves the answer. Always cite the server, table, and the SELECT used as evidence in worker output.
 - **`implementation` phase**: read-only MCP queries are permitted as cross-checks; MCP MUST NOT be used as a write path even if a write tool becomes available — schema/data mutations belong in the codebase migration files reviewed by humans.
 - **CLI-wrapper workers**: can use these MCP servers only if their provider CLI configuration mirrors the same servers. If not configured, the worker should record `MCP not available in this CLI` in `Missing Information or Assumptions` rather than guessing.
 - **Forbidden**: connecting to non-listed databases, running anything that mutates state (server is read-only — flagged write attempts are a contract violation), persisting query results outside the run's own artifact directories.

package/runtime/templates/reports/user-response.template.md

@@ -9,9 +9,11 @@ This file defines the standard format of the markdown produced by the **Export u
 
 ```yaml
 task-key: <task-group>/<task-id>
-task-type: <requirements-discovery | error-analysis | implementation-planning | implementation | final-verification | release-handoff | project-analysis | feature-analysis | change-impact-analysis>
+task-type: <requirements-discovery | error-analysis | implementation-option-selection | implementation-planning | implementation | final-verification | release-handoff | improvement-discovery | project-analysis | feature-analysis | change-impact-analysis>
 seq: <3-digit zero-padded run sequence>
 source-report: <project-relative path to the final-report .md the HTML was derived from>
+source-data: <project-relative path to the final-report data.json; omit for legacy reports without one>
+source-data-sha256: <SHA-256 of the exact source-data bytes; omit when source-data is omitted>
 created-by: user
 created-at: <ISO 8601 UTC timestamp>
 ```
@@ -72,15 +74,16 @@ When you pick a verdict in the Plan Decision widget and Export, the following bl
 ```markdown
 ## PLAN DECISION
 - Status: <approved | revision-requested | rejected>
-- Implementation-Option: <the name exactly as in Option Candidates>
+- Implementation-Option: <legacy plans only: the name exactly as in Option Candidates>
 - Reason:
   > <one quoted line per input line>
 ```
 
 - `revision-requested` and `rejected` require a reason: a plan sent back without one leaves the next run guessing at what to change, so Export refuses to serialise it.
-- `Implementation-Option:` is emitted only for `approved`, and only when you moved off the recommended default — otherwise implementation falls back to the plan's Recommended Option.
+- A `planningContract: selected-direction` plan never emits `Implementation-Option:`. The direction was confirmed before planning, and this block decides only whether the detailed plan is approved, revised, or rejected.
+- A legacy candidate plan emits `Implementation-Option:` only for `approved`, and only when you moved off the recommended default. Otherwise implementation falls back to the legacy plan's Recommended Option.
 - `Reason:` is optional for `approved`, and the line is omitted when empty.
-- The consumer of an `approved` block is the approve-confirm step of the implementation start wizard (`scripts/okstra_ctl/wizard.py`). After user confirmation the wizard applies it through the existing `--approve` / `--implementation-option` path; the sidecar itself does not bypass approval-gate validation. A non-approved status is ignored there — that step only ever looks for an approval.
+- The consumer of an `approved` block is the approve-confirm step of the implementation start wizard (`scripts/okstra_ctl/wizard.py`). After user confirmation the wizard applies `--approve`; it applies `--implementation-option` only for a legacy plan. The sidecar itself does not bypass approval-gate validation. A non-approved status is ignored there — that step only ever looks for an approval.
 - The parser is `parse_plan_decision` in `scripts/okstra_ctl/user_response.py`, and it accepts only the lowercase statuses that are byte-identical to the producer output (hand-edited values such as `Approved` are rejected fail-closed).
 - `--resume-clarification` attaches the sidecar verbatim, so the PLAN DECISION block reaches the next planning run — which is how a rejection and its reason get acted on.
 
@@ -102,6 +105,24 @@ The Analysis Review control appends one decision block. `revision-requested` and
 
 The block is the review decision's sole storage location. Export never changes the source final-report markdown. A later analysis rerun receives the sidecar through `--clarification-response` and records one `analysisReviewResolution` row for each imported affected ID.
 
+## DIRECTION SELECTION block (implementation-option-selection comparison only)
+
+Selecting one ranked direction and checking `Confirmed` appends this block. `Selection-Note` and `Constraints` keep their field lines when empty, but do not emit empty quote lines.
+
+```markdown
+## DIRECTION SELECTION
+- Status: selected
+- Option-ID: IO-002
+- Option-Name: Adapter boundary
+- Confirmed: true
+- Selection-Note:
+  > Use the existing port.
+- Constraints:
+  > Keep PB-001 unchanged.
+```
+
+The parser accepts exactly one block, lowercase `selected`, and lowercase `true`. A `preselected-validation` report displays its confirmed upstream direction read-only and does not export a new selection block.
+
 ## Compatibility Rules
 
 - If `Kind` has an unknown value, the form renders with a `<textarea>` fallback, and the received `Kind` string is preserved as-is during serialization.

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

@@ -61,6 +61,14 @@ Every analysis result starts with YAML frontmatter containing the task identity
 
 Every item has a worker-local ID and file:line evidence where code evidence exists. Sections 1–5 are the common core: feasibility, requirement interpretation, hidden assumptions, alternatives, and execution risk. Section 6 is the only legal home for specialization and is not consensus input.
 
+### Selected-direction planning ownership
+
+For `implementation-planning` with `selected-direction.json`, sections 1–5 read that snapshot and the original requirements, then assess only its realization into files, interfaces, stages, validation, rollback, bidirectional requirement links, and `direction-invalidated` evidence. Direction selection remains upstream of this prompt.
+
+### Legacy candidate-comparison ownership
+
+For an implementation-planning compatibility rerun without the snapshot, sections 1–5 retain candidate comparison, trade-off, recommendation, and `P-Opt-*` evidence.
+
 ### Ticket Tagging
 
 For `requirements-discovery`, `error-analysis`, and `implementation-planning`, tag every section 1–5 item with its related ticket. Use `Issue / Ticket`, fall back to Task ID, then `unknown`; comma-separate multiple tickets.

package/runtime/validators/lib/fixtures.sh

@@ -428,7 +428,7 @@ if WORKSPACE_ROOT:
     task_type = str(task_manifest.get("taskType", ""))
     sample_path = (
         Path(WORKSPACE_ROOT)
-        / "tests" / "fixtures" / "final-report-data"
+        / "tests" / "fixtures" / "final-report-data-v2"
         / f"{task_type}-001.data.json"
     )
     if sample_path.is_file():
@@ -439,6 +439,25 @@ if WORKSPACE_ROOT:
         sample["frontmatter"]["projectId"] = str(task_manifest.get("projectId", ""))
         sample["header"]["taskKey"] = str(task_manifest.get("taskKey", ""))
         sample["header"]["taskType"] = task_type
+        # The shipped fixture carries its own roster; this run's contract names
+        # a different one, and the validator compares the report's agent rows
+        # against that contract. Restate the rows under the contract's names so
+        # the fixture exercises the check instead of tripping over it.
+        _required = (
+            (run_manifest.get("teamContract") or {}).get("requiredAgentStatusEntries")
+            or (task_manifest.get("resultContract") or {}).get(
+                "requiredAgentStatusEntries"
+            )
+            or []
+        )
+        _rows = sample.get("executionStatus") or []
+        if _required and _rows:
+            # `agent` is the runtime (a schema enum); `role` carries the label the
+            # validator looks for in the rendered markdown.
+            sample["executionStatus"] = [
+                {**_rows[min(i, len(_rows) - 1)], "role": role}
+                for i, role in enumerate(_required)
+            ]
         name = report_path.name
         data_path = (
             report_path.with_name(name[:-3] + ".data.json")
@@ -452,23 +471,36 @@ if WORKSPACE_ROOT:
 
     import sys as _sys
     _sys.path.insert(0, str(Path(WORKSPACE_ROOT) / "scripts"))
-    try:
-        from okstra_ctl.report_views import RunMeta, render_html_view
-        css = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.css").read_text(encoding="utf-8")
-        js = (Path(WORKSPACE_ROOT) / "templates" / "reports" / "report.js").read_text(encoding="utf-8")
-        render_html_view(
-            report_path,
-            run_meta=RunMeta(
-                task_key=str(task_manifest.get("taskKey", "validation/fixture")),
-                task_type=str(task_manifest.get("taskType", "validation")),
-                seq="001",
-                source_report=report_path.name,
-            ),
-            css=css,
-            js=js,
+    # The markdown seeded above this block predates the data.json contract, so
+    # re-render it from the data.json the fixture just wrote. Otherwise the pair
+    # disagrees and the validator's AI-handoff heading scan fails on a fixture
+    # that never claimed to be hand-authored.
+    if sample_path.is_file():
+        try:
+            from okstra_ctl.render_final_report import render_to_file
+
+            render_to_file(data_path, report_path)
+        except Exception as exc:  # pragma: no cover — fixture path only
+            raise SystemExit(f"failed to render final report in fixture: {exc}")
+    # Go through the same CLI the run uses, so the fixture picks the schema's
+    # own view (v2 task template) rather than a second copy of that choice.
+    import subprocess as _subprocess
+    _views = _subprocess.run(
+        [
+            _sys.executable,
+            str(Path(WORKSPACE_ROOT) / "scripts" / "okstra-render-report-views.py"),
+            str(report_path),
+            "--task-key", str(task_manifest.get("taskKey", "validation/fixture")),
+            "--task-type", str(task_manifest.get("taskType", "validation")),
+            "--seq", "001",
+        ],
+        capture_output=True,
+        text=True,
+    )
+    if _views.returncode != 0:
+        raise SystemExit(
+            f"failed to render report views in fixture: {_views.stderr or _views.stdout}"
         )
-    except Exception as exc:  # pragma: no cover — fixture path only
-        raise SystemExit(f"failed to render report views in fixture: {exc}")
 
 if final_status_path.exists():
     final_status_path.unlink()

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""S1–S11 checks for the Stage Map structure of an approved
+"""S1–S13 checks for the Stage Map structure of an approved
 implementation-planning final-report.md. Run from prepare_task_bundle
 of `implementation` task or standalone."""
 
@@ -8,6 +8,7 @@ from __future__ import annotations
 import argparse
 import re
 import sys
+from collections import Counter
 from dataclasses import dataclass
 from pathlib import Path
 from typing import List, Tuple
@@ -42,9 +43,26 @@ EXIT_CONTRACT_HEADING = re.compile(r"^###\s+Stage Exit Contract\b", re.M)
 PATH_TOKEN = re.compile(r"(?:[\w.@-]+/)+[\w.@-]+")
 
 
+# S12 — a step command that reads an okstra artifact back out of a git object
+# (`git cat-file -e <rev>:.okstra/...`, `git show <rev>:.okstra/...`). `.okstra/**`
+# is never committed: `_implementation-executor.md` forbids `git add -f` and makes
+# a staged ignored path abort the commit, and `_implementation-verifier.md` reports
+# a committed `.okstra` path as a branch defect. A verification step built on such
+# a read can never pass, whatever the stage does.
+GIT_OBJECT_OKSTRA_READ = re.compile(
+    r"\bgit\b[^&|;]*?\b(?:cat-file|show|ls-tree|archive|grep)\b[^&|;]*?"
+    r"(?<![\w./@'\"-])[\w./@{}~^-]+:\.okstra/"
+)
+# S13 — a clean-worktree assertion built on a bare `git status`. okstra provisions
+# `.okstra`, the configured sync entries, and (for implementation) a nested stage
+# worktree into every task worktree, so a bare status is never empty there.
+BARE_GIT_STATUS = re.compile(r"\bgit\b[^&|;]*?\bstatus\b[^&|;]*?--(?:porcelain|short)\b")
+CLEAN_GATE_COMMAND = "okstra worktree-status --check-clean"
+
+
 @dataclass
 class ValidationError:
-    code: str   # S1..S11
+    code: str   # S1..S13
     stage: int  # 0 = global
     message: str
 
@@ -91,10 +109,14 @@ def _slice_stage_section(text: str, stage_number: int) -> str:
     return text[start: start + nxt.start()] if nxt else text[start:]
 
 
+STEP_COMMAND_CELL = 3
+
+
 def _effective_step_rows(section: str) -> List[List[str]]:
     """Effective (non header/divider/comment) rows of the `### Stepwise
     Execution Order` table, each as a list of stripped cells. Columns are
-    `step | action | files | command | expected`, so action is index 1."""
+    `step | action | files | command | outcome | expected`, so action is
+    index 1, command index 3, outcome index 4."""
     m = re.search(r"^###\s+Stepwise Execution Order\b", section, re.M)
     if not m:
         return []
@@ -266,6 +288,40 @@ def _check_red_green_steps(section: str, stage_number: int) -> List[ValidationEr
     return errs
 
 
+def _check_step_command(command: str, stage_number: int) -> List[ValidationError]:
+    """S12 / S13 over one step's `command` cell.
+
+    The command cell is what actually closes a step, so it has to be runnable
+    inside the worktree layout okstra provisions. Both rules reject a command
+    that can never pass there, regardless of what the stage implements.
+    """
+    errs: List[ValidationError] = []
+    if GIT_OBJECT_OKSTRA_READ.search(command):
+        errs.append(ValidationError("S12", stage_number,
+            "S12: step command reads an `.okstra/` path out of a git object — "
+            "`.okstra/**` is gitignored and never committed, so the read can "
+            "never resolve. Pass the artifact forward through the stage carry "
+            "sidecar / verifier result, or read it from the working tree"))
+    if BARE_GIT_STATUS.search(command):
+        errs.append(ValidationError("S13", stage_number,
+            "S13: step command asserts a clean worktree with a bare `git status` — "
+            "okstra provisions `.okstra`, the synced entries, and any nested stage "
+            f"worktree there, so it is never empty. Use `{CLEAN_GATE_COMMAND}`"))
+    return errs
+
+
+def _check_markdown_step_commands(
+    text: str, stages: List[StageMapStage]
+) -> List[ValidationError]:
+    """S12 / S13 over the rendered `### Stepwise Execution Order` rows."""
+    errs: List[ValidationError] = []
+    for s in stages:
+        for row in _effective_step_rows(_slice_stage_section(text, s.stage_number)):
+            if len(row) > STEP_COMMAND_CELL:
+                errs.extend(_check_step_command(row[STEP_COMMAND_CELL], s.stage_number))
+    return errs
+
+
 def _check_conformance_declaration(
     text: str, stages: List[StageMapStage]
 ) -> List[ValidationError]:
@@ -382,6 +438,7 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
         errors.extend(_check_slice_tdd(text, stages))
+        errors.extend(_check_markdown_step_commands(text, stages))
         errors.extend(_check_conformance_declaration(text, stages))
         errors.extend(_check_depends_on(stages))
         errors.extend(_check_parallel_safety(text, stages))
@@ -472,6 +529,99 @@ def _check_data_step_counts(
     return errs
 
 
+def _check_data_stage_identities(
+    raw_stage_map: List[dict], stages: List[dict]
+) -> List[ValidationError]:
+    """Reject ambiguous schema-v2 identities before building stage indexes."""
+    errs: List[ValidationError] = []
+    stage_map_numbers = [
+        row["stage"]
+        for row in raw_stage_map
+        if isinstance(row, dict) and isinstance(row.get("stage"), int)
+    ]
+    stage_numbers = [
+        row["stage"]
+        for row in stages
+        if isinstance(row, dict) and isinstance(row.get("stage"), int)
+    ]
+    duplicate_stage_map = {
+        number for number, count in Counter(stage_map_numbers).items() if count > 1
+    }
+    duplicate_stages = {
+        number for number, count in Counter(stage_numbers).items() if count > 1
+    }
+    errs.extend(
+        ValidationError("S3", number, f"stageMap duplicate stage {number}")
+        for number in sorted(duplicate_stage_map)
+    )
+    errs.extend(
+        ValidationError("S3", number, f"stages[] duplicate stage {number}")
+        for number in sorted(duplicate_stages)
+    )
+
+    stage_map_set = set(stage_map_numbers)
+    stage_set = set(stage_numbers)
+    errs.extend(
+        ValidationError(
+            "S3",
+            number,
+            f"stageMap is missing stages[] stage {number}",
+        )
+        for number in sorted(stage_set - stage_map_set)
+    )
+    errs.extend(
+        ValidationError(
+            "S3",
+            number,
+            f"stages[] is missing stageMap stage {number}",
+        )
+        for number in sorted(stage_map_set - stage_set)
+    )
+
+    stage_map_by_number = {
+        row["stage"]: row
+        for row in raw_stage_map
+        if isinstance(row, dict)
+        and isinstance(row.get("stage"), int)
+        and row["stage"] not in duplicate_stage_map
+    }
+    stages_by_number = {
+        row["stage"]: row
+        for row in stages
+        if isinstance(row, dict)
+        and isinstance(row.get("stage"), int)
+        and row["stage"] not in duplicate_stages
+    }
+    errs.extend(
+        ValidationError(
+            "S3",
+            number,
+            f"stageMap and stages[] stage {number} title must match",
+        )
+        for number in sorted(stage_map_by_number.keys() & stages_by_number.keys())
+        if stage_map_by_number[number].get("title")
+        != stages_by_number[number].get("title")
+    )
+
+    for stage in stages:
+        number = stage.get("stage")
+        step_numbers = [
+            step["step"]
+            for step in stage.get("stepwiseExecution") or []
+            if isinstance(step, dict) and isinstance(step.get("step"), int)
+        ]
+        errs.extend(
+            ValidationError(
+                "S4",
+                number if isinstance(number, int) else 0,
+                f"stages[] stage {number} step {step} is duplicate",
+            )
+            for step, count in sorted(Counter(step_numbers).items())
+            if count > 1
+        )
+    return errs
+
+
 def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     """The S-checks that schema v2 cannot express, over `implementationPlanning`.
 
@@ -482,11 +632,22 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     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 [])
+    if (
+        planning.get("planningContract") == "selected-direction"
+        and planning.get("outcome") == "direction-invalidated"
+    ):
+        return []
+
+    raw_stage_map = planning.get("stageMap") or []
+    stage_map, errors = _data_stage_metas(raw_stage_map)
     stages = [s for s in (planning.get("stages") or []) if isinstance(s, dict)]
     if not stage_map and not stages:
         return errors
 
+    identity_errors = _check_data_stage_identities(raw_stage_map, stages)
+    errors.extend(identity_errors)
+    if identity_errors:
+        return errors
     errors.extend(_check_data_step_counts(stage_map, stages))
     errors.extend(_check_depends_on(stage_map))
     errors.extend(_report_shared_parallel_files({
@@ -500,6 +661,10 @@ def collect_data_validation_errors(planning: dict) -> List[ValidationError]:
     }))
     for stage in stages:
         errors.extend(_check_data_slice_tdd(stage))
+        number = stage.get("stage") if isinstance(stage.get("stage"), int) else 0
+        for step in stage.get("stepwiseExecution") or []:
+            if isinstance(step, dict):
+                errors.extend(_check_step_command(str(step.get("command") or ""), number))
     return errors