okstra 0.141.3 → 0.142.0

package/runtime/schemas/final-report-v1.0.schema.json

@@ -400,7 +400,8 @@
         "planBodyVerification",
         "crossProjectDependencies",
         "decisionDrafts",
-        "skippedAdrCandidates"
+        "skippedAdrCandidates",
+        "variationPointAnalysis"
       ],
       "additionalProperties": false,
       "properties": {
@@ -426,6 +427,7 @@
           "items": { "$ref": "#/$defs/ImplementationPlanStage" }
         },
         "designPreparation": { "$ref": "#/$defs/DesignPreparation" },
+        "variationPointAnalysis": { "$ref": "#/$defs/VariationPointAnalysis" },
         "stepwiseExecution": {
           "description": "Legacy flat summary kept for compatibility only. New reports use stageMap/stages.",
           "type": "array",
@@ -1294,13 +1296,70 @@
 
     "RecommendedOption": {
       "type": "object",
-      "required": ["name", "coreReason", "rationale", "rejectedSummary"],
+      "required": ["name", "coreReason", "rationale", "rejectedSummary", "testSeams"],
       "additionalProperties": false,
       "properties": {
         "name": { "type": "string", "minLength": 1 },
         "coreReason": { "type": "string", "minLength": 1 },
         "rationale": { "type": "string", "minLength": 1 },
-        "rejectedSummary": { "type": "string", "minLength": 1 }
+        "rejectedSummary": { "type": "string", "minLength": 1 },
+        "testSeams": {
+          "type": "array",
+          "description": "Boundaries a test injects and replaces. An empty array is a deliberate declaration that no seam is needed (the plan body must justify it).",
+          "items": {
+            "type": "object",
+            "required": ["boundary", "injectedAs", "replacedInTest"],
+            "additionalProperties": false,
+            "properties": {
+              "boundary": { "type": "string", "minLength": 1 },
+              "injectedAs": { "type": "string", "minLength": 1 },
+              "replacedInTest": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+
+    "VariationPointAnalysis": {
+      "type": "object",
+      "required": ["hasMultipleImplementations", "noVariationRationale", "points"],
+      "additionalProperties": false,
+      "properties": {
+        "hasMultipleImplementations": { "type": "boolean" },
+        "noVariationRationale": {
+          "type": "string",
+          "description": "Why no variation point exists when hasMultipleImplementations is false. Empty string when it is true."
+        },
+        "points": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/VariationPoint" }
+        }
+      }
+    },
+
+    "VariationPoint": {
+      "type": "object",
+      "required": ["behavior", "implementations", "evidence", "extractionDecision"],
+      "additionalProperties": false,
+      "properties": {
+        "behavior": { "type": "string", "minLength": 1 },
+        "implementations": {
+          "type": "array",
+          "minItems": 2,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "evidence": { "type": "string", "minLength": 1 },
+        "extractionDecision": {
+          "type": "object",
+          "required": ["extract", "interfaceKind", "coveredBy", "rationale"],
+          "additionalProperties": false,
+          "properties": {
+            "extract": { "type": "boolean" },
+            "interfaceKind": { "type": "string" },
+            "coveredBy": { "type": "string" },
+            "rationale": { "type": "string", "minLength": 1 }
+          }
+        }
       }
     },
 
@@ -2157,7 +2216,7 @@
         "rollbackCommand": { "type": "string", "minLength": 1 },
         "verification": { "type": "string", "minLength": 1 },
         "result": {
-          "enum": ["ok", "unable — route back to planning"]
+          "enum": ["ok", "not-applicable", "advisory — human-run"]
         }
       }
     },

package/runtime/skills/okstra-run/SKILL.md

@@ -161,6 +161,8 @@ okstra config set pr-template-path "<value>" --scope global
 
 If an action has an unknown `command`, `key`, or `scope`, stop and report the wizard output instead of inventing a command.
 
+Before rendering the next phase's bundle, reclaim the prior phase's residual resources: run `okstra phase-cleanup --task-key <args.project-id>:<args.task-group>:<args.task-id> --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"`, then send `SendMessage(to: <name>, message: { type: "shutdown_request" })` to each `dismissible-teammates` name — only to teammates you have confirmed complete, never the lead and never an in-flight worker. `--fallback-team` takes the same `session-<lead.sessionId-prefix>` label the lead recorded in team-state, and must always be passed: after a resume or compaction the session id is re-issued, and without the label the reconcile finds no live roster and prints no teammate to dismiss. Assemble `--task-key` as the 3-token `project-id:task-group:task-id` literal from `outcome.renderArgs`; any other shape (a `<task-group>/<task-id>` pair, a bare task-id) is rejected and the whole cleanup — teammate reconcile included — is silently skipped. **This applies only when advancing to a different analysis phase.** The implementation stage chain (Step 7) does its own per-stage reclaim in its step 3 and does NOT run this `--task-key` form. `--run-dir` is unnecessary — the command auto-discovers the newest completed run across phases, including staged (implementation stage / single-stage final-verification) `runs/<type>/stage-N/` runs; pass `--run-dir` only to override that discovery with a specific prior run. A cleanup failure never blocks the next phase (the Python worker returns 0); only a malformed invocation exits non-zero.
+
 Build the `okstra render-bundle` invocation from `outcome.renderArgs`, passing each key as `--<key>` and the value verbatim (including empty strings — they are intentional `use phase default` markers).
 
 Step 3's empty-answer and escaping rules apply verbatim: every flag whose value is the empty string MUST still be passed explicitly as `--<key> ""` (e.g. `--workers ""`, `--directive ""`) — `render-bundle` distinguishes "flag absent" from "flag present with empty value", and the wizard's intent is always the latter.
@@ -258,7 +260,7 @@ Queue = the topologically-sorted stage list from splitting `chain-stages` on `,`
 
 1. Call Step 5's `render-bundle` with the same arguments but `--stage N` (the base commit is auto-computed by prepare from the predecessor's done `head_commit`, so do not pass it by hand). Step 5's blocking local conformance waiver offer·concurrent-run detection·git-reconcile gates apply identically to each stage's `render-bundle`.
 2. As in Step 6, become Claude lead and run that stage's Phase 1–7 inline. Phase 6's lead post-stage persistence appends that stage's `status:"done"` row to `runs/<plan-task-key>/consumers.jsonl` (per the implementation profile directive).
-3. After confirming that `done` row was written, move to the next stage. Clean up context at each stage boundary (leftover panes·finished teammates from the previous batch).
+3. After confirming that `done` row was written, run `okstra phase-cleanup --run-dir "<the run dir of the stage you just completed>" --project-root "<PROJECT_ROOT>" --fallback-team "session-<lead.sessionId-prefix>"`; for each `dismissible-teammates` name, send `SendMessage(to: <name>, message: { type: "shutdown_request" })` — only to teammates you have confirmed complete, never the lead and never an in-flight worker. Then move to the next stage.
 4. One-line report at each stage start/finish: `stage N/<total> start` / `stage N done → next K`.
 
 Once the whole queue is consumed, end the chain and report completion to the user.

package/runtime/skills/okstra-setup/SKILL.md

@@ -116,6 +116,9 @@ matching section:
   offered on the first release-handoff run.
 - **E. final report language** (`reportLanguage`) — default is auto (follows
   the brief's language).
+- **F. declared architecture style** (`architecture.style`) — `hexagonal` /
+  `layered` / `none`; hand-added, default `none`. Declaring one makes that
+  architecture's placement rules binding in planning + verification.
 
 ## Step 4: Verify
 

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

@@ -196,3 +196,50 @@ okstra config set report-language <en|ko|auto> --scope project
 
 Set the global default manually with `--scope global` as described in the
 README's "global config" guidance — this flow offers only project scope.
+
+## F. Declared architecture style (`architecture.style`)
+
+`architecture.style` declares the project's architecture — one of
+`hexagonal`, `layered`, or `none`. It is optional and defaults to `none`: an
+absent field, an unrecognized value, or an unreadable `project.json` all
+resolve to `none`
+(`scripts/okstra_project/resolver.py::resolve_architecture`), so a project
+that never declares one keeps today's behaviour unchanged.
+
+Like `worktreeSyncDirs` and `qaCommands`, `okstra setup` does NOT write this
+field — hand-add it to `project.json`. It is preserved across the runtime's
+auto-upserts (only `projectId`, `projectRoot`, `createdAt`, `updatedAt` are
+runtime-owned), so the manual edit survives every subsequent `okstra setup` /
+`okstra run` invocation.
+
+```json
+{
+  "projectId": "...",
+  "projectRoot": "...",
+  "architecture": { "style": "hexagonal" }
+}
+```
+
+Declaring `hexagonal` or `layered` promotes that architecture's placement
+rules from advisory to a binding planning + verification constraint:
+
+- `hexagonal` — extraction itself stays a free decision (`extract: false`
+  remains legal), but a variation point `implementation-planning` *does*
+  extract has to sit behind a port: an `extractionDecision` carrying
+  `extract: true` with any `interfaceKind` other than `"port"` fails
+  `validators/validate-run.py::_validate_variation_point_analysis`. The
+  implementation executor loads the `architectures/hexagonal.md` preflight
+  pack even when directory-shape detection did not match it, and the verifier
+  grades a service dependency the diff adds or modifies that injects a
+  concrete adapter instead of a port as a blocking `FAIL` rather than a
+  recommendation.
+- `layered` — no preflight pack resource. Its binding invariant is dependency
+  direction: an upper layer may import a lower one, never the reverse. A
+  reverse import is a blocking placement violation found by worker judgement,
+  because no machine check reads layer names.
+- `none` (or the field left out) — the style-agnostic planning rules still
+  run on every plan (variation-point analysis and test seams); only the
+  placement overlay stays advisory and detection-driven.
+
+The full two-layer model lives in `docs/architecture.md` § Project
+self-registration.

package/runtime/templates/reports/final-report.template.md

@@ -477,6 +477,31 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 {% endfor %}
 {%- endif %}
 
+### 5.5.11 Variation-Point Analysis{% if t("implementationPlanning.variationPointAnalysis.heading") != "Variation-Point Analysis" %} ({{ t("implementationPlanning.variationPointAnalysis.heading") }}){% endif %}
+
+- **{{ t("implementationPlanning.variationPointAnalysis.hasMultiple") }}:** `{% if implementationPlanning.variationPointAnalysis.hasMultipleImplementations %}yes{% else %}no{% endif %}`
+
+{% if not implementationPlanning.variationPointAnalysis.hasMultipleImplementations -%}
+- **{{ t("implementationPlanning.variationPointAnalysis.rationale") }}:** {{ implementationPlanning.variationPointAnalysis.noVariationRationale }}
+{% else %}
+{% for point in implementationPlanning.variationPointAnalysis["points"] %}
+- **{{ t("implementationPlanning.variationPointAnalysis.behavior") }}:** {{ point.behavior }}
+  - **{{ t("implementationPlanning.variationPointAnalysis.implementations") }}:** {{ point.implementations | join(", ") }}
+  - **{{ t("implementationPlanning.variationPointAnalysis.evidence") }}:** {{ point.evidence }}
+  - **{{ t("implementationPlanning.variationPointAnalysis.extract") }}:** `{% if point.extractionDecision.extract %}yes{% else %}no{% endif %}` — {{ point.extractionDecision.interfaceKind }} ({{ point.extractionDecision.coveredBy }}) — {{ point.extractionDecision.rationale }}
+{% endfor %}
+{% endif %}
+
+**{{ t("implementationPlanning.variationPointAnalysis.testSeams") }}:**
+
+{% if implementationPlanning.recommendedOption["testSeams"] | length == 0 -%}
+{{ t("implementationPlanning.variationPointAnalysis.seamEmpty") }}
+{% else %}
+{% for seam in implementationPlanning.recommendedOption["testSeams"] -%}
+- {{ seam.boundary }} — {{ seam.injectedAs }} → {{ seam.replacedInTest }}
+{% endfor %}
+{% endif %}
+
 {% endif %}
 {% if header.taskType == 'release-handoff' %}
 ## 5.6 Release Handoff Deliverables

package/runtime/templates/reports/i18n/en.json

@@ -112,7 +112,7 @@
     "planBodyGateLegend": "Gate values — `passed`: agreed, no dissent · `passed-with-dissent`: a minority dissent remains but the gate passes (a majority dissent would block approval) · `blocked-by-disagreement`: majority dissent blocks approval · `aborted-non-result`: verification itself produced no result.",
     "planBodyBlockedByLegend": "Which input blocked the gate — `majority-disagree`: a worker majority dissent · `coverage-gap`: a Requirement Coverage gap / blocked row, independent of worker votes · `non-result`: verification produced no result. Absent means nothing blocked.",
     "planBodyVerdictLegend": "Verdict — **AGREE**: executable as written and internally consistent with other items · **SUPPLEMENT**: item is sound but a dependency / edge case / precondition is missing · **DISAGREE**: has a defect (see Breakage kind) · **verification-error**: the worker produced no result.",
-    "planBodyBreakageLegend": "Breakage kind — a: cited file path/symbol mismatches another step or option · b: command is not executable or is ambiguous · c: validation signal is not observable · d: rollback violates commit/dependency order · e: contradicts the trade-off matrix · f: requirement-coverage row does not map to an option/stage/step that actually satisfies the requirement. (`--` = not applicable) Fixability: planner-fixable = correctable from code + plan + brief; needs-user-input = requires an external decision.",
+    "planBodyBreakageLegend": "Breakage kind — a: cited file path/symbol mismatches another step or option · b: command is not executable or is ambiguous · c: validation signal is not observable · d: rollback violates commit/dependency order (advisory — a rollback is human-run, so this never blocks the gate) · e: contradicts the trade-off matrix · f: requirement-coverage row does not map to an option/stage/step that actually satisfies the requirement. (`--` = not applicable) Fixability: planner-fixable = correctable from code + plan + brief; needs-user-input = requires an external decision.",
     "planBodySourceLabel": "source §",
     "planBodyBlockerLabel": "blocks approval →",
     "optionInterfacesLabel": "Affected interfaces / public contracts / downstream consumers",
@@ -168,6 +168,17 @@
       "notApplicableReason": "Not applicable reason",
       "none": "(none)",
       "empty": "No implementation design preparation items."
+    },
+    "variationPointAnalysis": {
+      "heading": "Variation-Point Analysis",
+      "hasMultiple": "Multiple implementations",
+      "rationale": "No-variation rationale",
+      "behavior": "Behavior",
+      "implementations": "Implementations",
+      "evidence": "Evidence",
+      "extract": "Extract as interface",
+      "testSeams": "Test seams",
+      "seamEmpty": "No seams declared."
     }
   },
   "releaseHandoff": {

package/runtime/templates/reports/i18n/ko.json

@@ -112,7 +112,7 @@
     "planBodyGateLegend": "게이트 결과 값 뜻 — `passed`: 이견 없이 통과 · `passed-with-dissent`: 소수 워커의 반대가 남았으나 통과(반대가 다수였다면 승인 차단) · `blocked-by-disagreement`: 다수 반대로 승인 차단 · `aborted-non-result`: 검증 자체가 결과를 내지 못함.",
     "planBodyBlockedByLegend": "게이트를 막은 입력 — `majority-disagree`: 워커 다수 반대 · `coverage-gap`: Requirement Coverage 의 gap / blocked 행(워커 반대와는 무관) · `non-result`: 검증 자체가 결과를 내지 못함. 이 항목이 없으면 차단 원인이 없다는 뜻이다.",
     "planBodyVerdictLegend": "판정(Verdict) — **AGREE**: 적힌 대로 실행 가능하고 다른 항목과 내부적으로 일관됨 · **SUPPLEMENT**: 항목 자체는 타당하나 의존성·엣지케이스·전제조건이 누락됨 · **DISAGREE**: 결함이 있음(결함 유형 참조) · **verification-error**: 워커 검증이 결과를 내지 못함.",
-    "planBodyBreakageLegend": "결함 유형(Breakage kind) — a: 인용한 파일 경로/심볼이 다른 스텝·옵션과 불일치 · b: 명령이 실행 불가하거나 모호함 · c: 검증 신호가 관측 불가 · d: 롤백이 커밋/의존성 순서를 위반 · e: 트레이드오프 매트릭스와 모순 · f: 요구사항 커버리지 행이 요구사항을 실제로 충족하는 옵션/스테이지/스텝에 매핑되지 않음. (`--` = 해당 없음) · 자가수정 가능 여부(Fixability) — planner-fixable: 코드·계획·브리프만으로 수정 가능 · needs-user-input: 외부 결정 필요",
+    "planBodyBreakageLegend": "결함 유형(Breakage kind) — a: 인용한 파일 경로/심볼이 다른 스텝·옵션과 불일치 · b: 명령이 실행 불가하거나 모호함 · c: 검증 신호가 관측 불가 · d: 롤백이 커밋/의존성 순서를 위반 (참고용 — 롤백은 사람이 수행하므로 게이트를 막지 않음) · e: 트레이드오프 매트릭스와 모순 · f: 요구사항 커버리지 행이 요구사항을 실제로 충족하는 옵션/스테이지/스텝에 매핑되지 않음. (`--` = 해당 없음) · 자가수정 가능 여부(Fixability) — planner-fixable: 코드·계획·브리프만으로 수정 가능 · needs-user-input: 외부 결정 필요",
     "planBodySourceLabel": "출처 §",
     "planBodyBlockerLabel": "승인 차단 →",
     "optionInterfacesLabel": "영향 인터페이스 / 공개 계약 / 다운스트림 소비자",
@@ -168,6 +168,17 @@
       "notApplicableReason": "해당 없음 이유",
       "none": "(없음)",
       "empty": "구현 설계 준비 항목이 없습니다."
+    },
+    "variationPointAnalysis": {
+      "heading": "변이점 분석",
+      "hasMultiple": "복수 구현",
+      "rationale": "변이점 없음 근거",
+      "behavior": "동작",
+      "implementations": "구현체",
+      "evidence": "근거",
+      "extract": "인터페이스로 추출",
+      "testSeams": "테스트 이음새",
+      "seamEmpty": "선언된 이음새가 없습니다."
     }
   },
   "releaseHandoff": {

package/runtime/templates/reports/implementation-input.template.md

@@ -80,8 +80,7 @@ taskType: "{{FM_TASK_TYPE}}"
 2. (Executor) Did any change touch a file or symbol that appears in `Out of Scope`? If yes, halt and report — do not silently include it.
 3. (Verifiers) Does the diff match the plan's File Structure and step ordering?
 4. (Verifiers) Does the validation evidence include actual command output and exit codes for every plan checkpoint?
-5. (Verifiers) Is the rollback path still valid after the changes?
-6. (Verifiers) Does the diff contain any "while I'm here" edits (rename, reformat, comment cleanup, adjacent refactor) that the plan did not authorise? Flag each such hunk explicitly.
+5. (Verifiers) Does the diff contain any "while I'm here" edits (rename, reformat, comment cleanup, adjacent refactor) that the plan did not authorise? Flag each such hunk explicitly.
 
 ## Phase Boundary
 

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

@@ -67,7 +67,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - If `Task Type` is `implementation`:
   - Which approved `implementation-planning` final report authorises this run, and is its frontmatter `approved: true` cited verbatim?
   - What is the authoritative file list and step order copied from that plan?
-  - Which validation, TDD, and rollback commands must be executed and recorded with actual output?
+  - Which validation and TDD commands must be executed and recorded with actual output? (Rollback is human-run — record the revert path for reference; do not require executing it.)
 - If `Task Type` is `final-verification`:
   - What was delivered?
   - What acceptance criteria must pass?

package/runtime/validators/validate-run.py

@@ -34,6 +34,7 @@ except ImportError:  # pragma: no cover — runtime guarantees this import
 
 from okstra_project import project_json_path  # noqa: E402
 from okstra_project.dirs import tasks_root as _okstra_tasks_root  # noqa: E402
+from okstra_project.resolver import resolve_architecture  # noqa: E402
 
 from okstra_ctl.conformance import (  # noqa: E402
     CAPABILITY_WHITELIST,
@@ -2343,6 +2344,11 @@ def validate_final_report_data(
         _validate_round_recorded_verdicts(data, failures)
         _validate_verdicts_match_current_subjects(data, failures)
         _validate_plan_item_extraction_completeness(data, failures)
+        _validate_variation_point_analysis(
+            (data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
+            resolve_architecture(_project_root_from_report(report_path)),
+            failures,
+        )
         _validate_plan_item_subject_substance(data, failures)
         _validate_plan_body_clarification_matching(data, failures)
         _validate_disagree_has_fixability(data, failures)
@@ -2524,10 +2530,16 @@ _PLAN_GATE_RANK = {
 
 # Breakage kinds where a single DISAGREE blocks the gate on its own (no majority
 # needed), because the defect is concrete, safety-critical, and adversarially
-# verifiable: `a` = cited path/symbol mismatch, `d` = rollback violates
-# commit/dependency order. `b`/`c`/`e` still need a majority — `b` in particular
-# is prone to planning-vs-implementation environment false positives.
-_SINGLE_VOTE_BLOCKING_KINDS = {"a", "d"}
+# verifiable: `a` = cited path/symbol mismatch. `b`/`c`/`e` still need a
+# majority — `b` in particular is prone to planning-vs-implementation
+# environment false positives.
+_SINGLE_VOTE_BLOCKING_KINDS = {"a"}
+
+# Rollback ordering (`d`) is executed by a human, not by okstra's workers or
+# verifiers, so a rollback-ordering dissent is recorded but never gates
+# approval: it is dropped from the blocking-disagree tally entirely, so an item
+# whose only DISAGREEs are advisory-only can never rise above `has-dissent`.
+_ADVISORY_ONLY_KINDS = {"d"}
 
 # Stop reasons that justify promoting a still-broken planner-fixable item to the
 # user: the self-fix budget ran out, or a round produced no net resolution so
@@ -2535,6 +2547,20 @@ _SINGLE_VOTE_BLOCKING_KINDS = {"a", "d"}
 _SELF_FIX_EXHAUSTED_REASONS = frozenset({"max-rounds-reached", "no-progress"})
 
 
+def _is_variation_point_item(item: dict) -> bool:
+    """Whether this is a `P-Var-*` variation-point item, which is majority-gated
+    (`prompts/lead/plan-body-verification.md` "`P-Var-<N>` … is majority-gated").
+    Whether a behavior has two implementations, and whether the plan extracted the
+    right interface for it, is a design judgement — it lacks the concrete certainty
+    of kind `a`, where a verifier points at two spelled-out references that
+    contradict each other. So kind `a` carries no extra weight on a P-Var item: it
+    neither single-vote-blocks nor counts as correctness-critical, exactly like the
+    `b` / `c` / `e` kinds the prompt routes P-Var defects to. Only a
+    `majority-disagree` gates it — that part is unchanged.
+    """
+    return str(item.get("id") or "").upper().startswith("P-VAR")
+
+
 def _classify_plan_item_gate(item: dict) -> str:
     """Recompute one plan item's gate class from its per-worker verdicts,
     per `prompts/lead/plan-body-verification.md` "Round protocol". Returns one of
@@ -2556,15 +2582,32 @@ def _classify_plan_item_gate(item: dict) -> str:
         return "all-non-result"
     disagree = [(vd, bk) for (vd, bk) in non_error if vd == "DISAGREE"]
     agree = [(vd, bk) for (vd, bk) in non_error if vd in ("AGREE", "SUPPLEMENT")]
-    disagree_kinds = {bk for (_vd, bk) in disagree if bk}
     if not disagree:
         return "full-consensus"
+    # Rollback is a human-run operation, so rollback dissent never blocks the
+    # gate — closed from two angles so a verifier cannot re-block it by relabelling:
+    #   (1) a whole rollback plan item (`P-Rb-*`) is advisory regardless of
+    #       breakage kind — otherwise a `DISAGREE(b)` "rollback command is
+    #       ambiguous" would sail past the kind-`d` exemption and block;
+    #   (2) a rollback-ordering dissent (`d`) is advisory on ANY item, since a
+    #       rollback-order defect raised against a non-rollback item is still a
+    #       human-run concern.
+    # Both are recorded as dissent and fold into `has-dissent`, never blocking.
+    if str(item.get("id") or "").upper().startswith("P-RB"):
+        return "has-dissent"
+    blocking_disagree = [(vd, bk) for (vd, bk) in disagree if bk not in _ADVISORY_ONLY_KINDS]
+    if not blocking_disagree:
+        return "has-dissent"
+    blocking_kinds = {bk for (_vd, bk) in blocking_disagree if bk}
     # Single-vote-blocking kinds: one confirmed DISAGREE on a concrete,
     # safety-critical, adversarially-verifiable defect is enough to block, even
     # in a two-worker roster — a lone correct dissent must not be outvoted here.
-    # `a`/`d` for any item; `f` only for P-Req items (requirement coverage).
+    # `a` for any item except `P-Var-*` (majority-gated, see
+    # `_is_variation_point_item`); `f` only for P-Req items (requirement coverage).
     is_req = str(item.get("id") or "").upper().startswith("P-REQ")
-    if disagree_kinds & _SINGLE_VOTE_BLOCKING_KINDS or (is_req and "f" in disagree_kinds):
+    if not _is_variation_point_item(item) and (
+        blocking_kinds & _SINGLE_VOTE_BLOCKING_KINDS or (is_req and "f" in blocking_kinds)
+    ):
         # "One confirmed DISAGREE" presupposes the item was actually
         # cross-verified. When the peer returned a non-result nothing confirmed
         # the dissent, so blocking here would reproduce the same
@@ -2577,7 +2620,7 @@ def _classify_plan_item_gate(item: dict) -> str:
     # two participating votes, so a lone surviving DISAGREE (its peer returned a
     # non-result) does NOT block. That fixes the paradox where a worker failure
     # made the gate stricter than a healthy roster would.
-    if len(non_error) >= 2 and len(disagree) > len(agree):
+    if len(non_error) >= 2 and len(blocking_disagree) > len(agree):
         return "majority-disagree"
     return "has-dissent"
 
@@ -2604,11 +2647,18 @@ def _has_planner_fixable_majority(item: dict) -> bool:
 
 def _is_correctness_critical(item: dict) -> bool:
     """Whether this item's defect would make `implementation` produce wrong or
-    unsafe code — the single-vote-blocking kinds `a` (cited path/symbol
-    mismatch) and `d` (rollback violates commit order) on any item, or `f`
-    (requirement-coverage mismatch) on a `P-Req-*` item. Kinds `b`/`c`/`e` are
-    plan-prose defects: they degrade the document, not the resulting code.
+    unsafe code — the single-vote-blocking kind `a` (cited path/symbol mismatch)
+    on any item but `P-Var-*`, or `f` (requirement-coverage mismatch) on a
+    `P-Req-*` item.
+    Kinds `b`/`c`/`e` are plan-prose defects: they degrade the document, not the
+    resulting code. Rollback ordering (`d`) is advisory — a human runs the
+    rollback — so it never counts as correctness-critical. A `P-Var-*` item is
+    majority-gated end to end, so a kind-`a` dissent on one is no more critical
+    than the `b`/`e` its defect should have been raised under; otherwise the same
+    mis-tag that no longer single-vote-blocks would still veto the downgrade.
     """
+    if _is_variation_point_item(item):
+        return False
     kinds = _disagree_breakage_kinds(item)
     is_req = str(item.get("id") or "").upper().startswith("P-REQ")
     return bool(kinds & _SINGLE_VOTE_BLOCKING_KINDS) or (is_req and "f" in kinds)
@@ -4131,6 +4181,87 @@ def _validate_plan_item_extraction_completeness(
         )
 
 
+def _validate_variation_point_analysis(
+    vpa: object,
+    architecture_style: str,
+    failures: list[str],
+) -> None:
+    """Conditional rules + architecture-style overlay for variation points.
+
+    The schema enforces shape only. Two layers of meaning sit on top:
+
+    Layer 1 is style-agnostic. Declaring "no variation exists" is a claim that
+    needs a written reason, and it must not be paired with declared points —
+    `plan_items._extract_variation_point_items` emits a lone `P-Var-0` in that
+    branch and drops them, so the contradiction would silently exempt every
+    declared point from per-point verification. `extract: true` is a claim in
+    the same way: it names the interface the next implementation plugs into and
+    the Stage Map stage that builds it, so both fields have to be filled. The
+    schema cannot carry this as a `minLength` — the empty string is the natural
+    shape of an `extract: false` decision.
+
+    Layer 2 fires only for a project that declares `architecture.style`
+    `hexagonal`: extracting a variation point there means introducing a port,
+    not a helper. An unconfigured project resolves to `none` and keeps layer-1
+    behaviour only.
+    """
+    if not isinstance(vpa, dict):
+        failures.append("variationPointAnalysis is missing or not an object")
+        return
+    # Schema violations are reported, not raised, so this check still runs on a
+    # malformed block. A type guard here keeps a bad field from aborting the
+    # whole validation and discarding every failure collected so far.
+    raw_points = vpa.get("points")
+    if raw_points is not None and not isinstance(raw_points, list):
+        failures.append("variationPointAnalysis: points must be an array")
+        return
+    points = raw_points or []
+    if not bool(vpa.get("hasMultipleImplementations")):
+        rationale = vpa.get("noVariationRationale")
+        if not isinstance(rationale, str) or not rationale.strip():
+            failures.append(
+                "variationPointAnalysis: hasMultipleImplementations=false "
+                "requires a non-empty noVariationRationale"
+            )
+        if points:
+            failures.append(
+                "variationPointAnalysis: hasMultipleImplementations=false but "
+                "points is non-empty — declared variation points would be "
+                "silently dropped"
+            )
+        return
+    if not points:
+        failures.append(
+            "variationPointAnalysis: hasMultipleImplementations=true requires "
+            "at least one point"
+        )
+        return
+    for index, point in enumerate(points, start=1):
+        if not isinstance(point, dict):
+            failures.append(
+                f"variationPointAnalysis point {index}: must be an object"
+            )
+            continue
+        decision = point.get("extractionDecision")
+        if not isinstance(decision, dict):
+            continue  # shape is the schema's job; don't double-report it.
+        if not decision.get("extract"):
+            continue
+        for field in ("interfaceKind", "coveredBy"):
+            value = decision.get(field)
+            if not isinstance(value, str) or not value.strip():
+                failures.append(
+                    f"variationPointAnalysis point {index}: extract=true "
+                    f"requires a non-empty {field}, got {value!r}"
+                )
+        if architecture_style == "hexagonal" and decision.get("interfaceKind") != "port":
+            failures.append(
+                f"variationPointAnalysis point {index}: architecture style "
+                f"'hexagonal' requires interfaceKind 'port', got "
+                f"{decision.get('interfaceKind')!r}"
+            )
+
+
 _DESIGN_PREP_CONTRACT = "implementation-design-prep-v1"
 _DESIGN_PREP_REQUEST_STATUSES = {"provisional", "blocked"}
 _DESIGN_PREP_TERMINAL_STATUSES = {"ready", "not-applicable"}

package/src/cli-registry.mjs

@@ -101,6 +101,16 @@ export const COMMAND_REGISTRY = [
     category: "admin",
     summary: ["stage 들을 task 브랜치에 통합 머지하고 stage worktree 를 정리"],
   },
+  {
+    name: "phase-cleanup",
+    module: "./commands/execute/phase-cleanup.mjs",
+    export: "run",
+    category: "admin",
+    summary: [
+      "Reclaim the prior phase/batch's completed panes and list dismissible",
+      "teammates for the lead to shut down (tmux-aware)",
+    ],
+  },
   {
     name: "paths",
     module: "./commands/lifecycle/paths.mjs",

package/src/commands/execute/phase-cleanup.mjs

@@ -0,0 +1,38 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra phase-cleanup — reclaim the prior phase/batch's completed panes and teammates
+
+Usage:
+  okstra phase-cleanup --project-root <dir> [--task-key <k>] [--run-dir <dir>]
+                       [--fallback-team <label>] [--json]
+
+--task-key   project-id:task-group:task-id — finds the newest completed run
+             across phases, including staged (implementation / final-
+             verification) stage-N runs.
+--run-dir    explicit prior run dir (wins over --task-key).
+--fallback-team
+             the live team label (session-<lead-session-prefix>) so teammate
+             reconcile still finds the roster after a session-id re-issue
+             (resume/compaction); omit and it resolves the current live
+             session only.
+
+Reclaims only completed tmux panes (lead pane and in-flight workers are preserved),
+and prints the dismissible-teammate names for the lead to shut down. In a non-tmux
+session no panes exist, so it skips pane reclaim and only reconciles teammates.
+A cleanup failure never blocks the next phase (the worker returns 0); a malformed
+invocation still exits non-zero.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.phase_cleanup",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}