okstra 0.141.3 → 0.143.0

package/runtime/python/okstra_ctl/worker_heartbeat.py

@@ -33,17 +33,27 @@ SINGLE_WRITE_STAGES = frozenset({
 })
 SINGLE_WRITE_MAX_GAP_SECONDS = 20 * 60 + 60
 
+# report-writer 가 도구 호출 없이 모든 입력을 정독(required-reading-complete)하거나
+# 종합(synthesis-start)하는 구간. 그 사이에는 `in-stage:` 라인조차 append 할 수 없어
+# 5분 예산으로는 살아 있는 워커가 stalled 로 판정된다 (실측: synthesis-start gap 41건
+# 중 24%가 5분+60s 초과, 최대 14.9분). 단일 Write 만큼 길지는 않으므로 15분 예산.
+SYNTHESIS_STAGES = frozenset({
+    "required-reading-complete",
+    "synthesis-start",
+})
+SYNTHESIS_MAX_GAP_SECONDS = 15 * 60 + 60
+
 
 def max_gap_seconds_after(stage: str) -> int:
     """*stage* 를 알린 뒤 다음 하트비트까지 허용되는 최대 공백(초).
 
     간격이 재는 것은 직전에 선언된 단계의 작업 시간이므로, 예산은 언제나
     구간을 *여는* 단계에서 고른다."""
-    return (
-        SINGLE_WRITE_MAX_GAP_SECONDS
-        if stage in SINGLE_WRITE_STAGES
-        else HEARTBEAT_MAX_GAP_SECONDS
-    )
+    if stage in SINGLE_WRITE_STAGES:
+        return SINGLE_WRITE_MAX_GAP_SECONDS
+    if stage in SYNTHESIS_STAGES:
+        return SYNTHESIS_MAX_GAP_SECONDS
+    return HEARTBEAT_MAX_GAP_SECONDS
 
 
 @dataclass(frozen=True)

package/runtime/python/okstra_ctl/workflow.py

@@ -87,7 +87,7 @@ PHASE_RULES: dict[str, dict[str, str]] = {
             '  - validation evidence: actual stdout/stderr and exit code for every pre / mid / post command from the plan (no paraphrased "tests pass")\n'
             "  - TDD evidence for TDD-applicable steps: failing-test output before implementation commit and passing-test output after, with framing SHAs\n"
             "  - per-verifier sections for every verifier in the resolved roster (`Claude verifier`, `Codex verifier`, plus `Antigravity verifier` when opted in) with independent verdict (PASS / CONCERNS / FAIL) and cited diff snippets; dissent is preserved by `Claude lead`\n"
-            "  - rollback verification (revert SHA reachable, feature flag toggle works, migration down step valid; dry-run preferred)\n"
+            "  - rollback verification (advisory, never blocks — record the revert path for a human; `result` is ok / not-applicable / advisory — human-run)\n"
             "  - routing recommendation for `final-verification` (ready / needs new error-analysis or planning loop)"
         ),
     },

package/runtime/python/okstra_project/resolver.py

@@ -83,6 +83,31 @@ def resolve_project_root(*, explicit_root: str = "",
         "프로젝트 루트 또는 그 하위에서 실행하거나, git 작업 트리 안에서 실행해 주십시오.)")
 
 
+_ARCHITECTURE_STYLES = frozenset({"hexagonal", "layered", "none"})
+
+
+def resolve_architecture(project_root: Path | str) -> str:
+    """Return the declared architecture style, else ``"none"``.
+
+    Mirrors resolve_build_tool_tokens: any read/parse failure or an
+    unrecognised value falls back to the neutral ``"none"`` so an
+    unconfigured project keeps the layer-1 behaviour only.
+    """
+    try:
+        payload = json.loads(project_json_path(Path(project_root)).read_text(encoding="utf-8"))
+    # ValueError covers json.JSONDecodeError and UnicodeDecodeError alike — a
+    # project.json hand-saved in a non-UTF-8 encoding must fall back, not raise.
+    except (OSError, ValueError):
+        return "none"
+    if not isinstance(payload, dict):
+        return "none"
+    architecture = payload.get("architecture")
+    style = architecture.get("style") if isinstance(architecture, dict) else None
+    if not isinstance(style, str):
+        return "none"
+    return style if style in _ARCHITECTURE_STYLES else "none"
+
+
 def upsert_project_json(project_root: Path, project_id: str, *,
                          now: Optional[str] = None) -> dict:
     """project.json 을 읽거나 새로 만든다.

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

@@ -384,6 +384,8 @@
       "items": { "$ref": "#/$defs/RiskRow" }
     },
 
+    "errorAnalysis": { "$ref": "#/$defs/ErrorAnalysis" },
+
     "implementationPlanning": {
       "type": "object",
       "description": "RENDER_IF taskType == implementation-planning. §5.5 deliverables.",
@@ -400,7 +402,8 @@
         "planBodyVerification",
         "crossProjectDependencies",
         "decisionDrafts",
-        "skippedAdrCandidates"
+        "skippedAdrCandidates",
+        "variationPointAnalysis"
       ],
       "additionalProperties": false,
       "properties": {
@@ -426,6 +429,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",
@@ -812,6 +816,16 @@
   },
 
   "allOf": [
+    {
+      "description": "error-analysis task-type requires a structured diagnosis block.",
+      "if": {
+        "properties": { "header": { "properties": { "taskType": { "const": "error-analysis" } } } },
+        "required": ["header"]
+      },
+      "then": {
+        "required": ["errorAnalysis"]
+      }
+    },
     {
       "description": "implementation-planning task-type requires §5.5 block.",
       "if": {
@@ -950,6 +964,7 @@
     "Direction": {
       "enum": [
         "continue-investigation",
+        "begin-planning",
         "begin-implementation",
         "approve",
         "reject",
@@ -957,6 +972,92 @@
       ]
     },
 
+    "ErrorAnalysis": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "symptomVerbatim",
+        "observableFailure",
+        "reproduction",
+        "causeCandidates",
+        "nextDiagnostic",
+        "routing"
+      ],
+      "properties": {
+        "symptomVerbatim": { "type": "string" },
+        "observableFailure": { "type": "string" },
+        "reproduction": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "evidence", "blockedReason"],
+          "properties": {
+            "status": {
+              "enum": ["reproduced", "not-reproduced", "blocked-before-repro"]
+            },
+            "evidence": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "type": "string" }
+            },
+            "blockedReason": { "type": "string" }
+          }
+        },
+        "causeCandidates": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "id",
+              "statement",
+              "supportingEvidence",
+              "falsifyingEvidenceChecked",
+              "confidence",
+              "disproveWith"
+            ],
+            "properties": {
+              "id": { "type": "string", "pattern": "^EA-\\d{3,}$" },
+              "statement": { "type": "string" },
+              "supportingEvidence": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string" }
+              },
+              "falsifyingEvidenceChecked": {
+                "type": "array",
+                "minItems": 1,
+                "items": { "type": "string" }
+              },
+              "confidence": { "enum": ["low", "medium", "high"] },
+              "disproveWith": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "nextDiagnostic": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["action", "confirmingSignal", "rejectingSignal"],
+          "properties": {
+            "action": { "type": "string", "minLength": 1 },
+            "confirmingSignal": { "type": "string", "minLength": 1 },
+            "rejectingSignal": { "type": "string", "minLength": 1 }
+          }
+        },
+        "routing": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["nextTaskType", "leadingCauseId", "rationale"],
+          "properties": {
+            "nextTaskType": {
+              "enum": ["error-analysis", "implementation-planning"]
+            },
+            "leadingCauseId": { "type": "string" },
+            "rationale": { "type": "string", "minLength": 1 }
+          }
+        }
+      }
+    },
+
     "TicketId": {
       "type": "string",
       "minLength": 1,
@@ -1294,13 +1395,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 +2315,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

@@ -171,6 +171,32 @@ Carried-forward plan items retain their prior verdicts verbatim; each such item
 
 {% endif %}
 
+{% if header.taskType == 'error-analysis' %}
+### 2.4 Error Analysis Result{% if t("errorAnalysis.heading") != "Error Analysis Result" %} ({{ t("errorAnalysis.heading") }}){% endif %}
+
+- **{{ t("errorAnalysis.symptomVerbatim") }}:** {{ errorAnalysis.symptomVerbatim }}
+- **{{ t("errorAnalysis.observableFailure") }}:** {{ errorAnalysis.observableFailure }}
+- **{{ t("errorAnalysis.reproductionStatus") }}:** `{{ errorAnalysis.reproduction.status }}`
+- **{{ t("errorAnalysis.reproductionEvidence") }}:** {{ errorAnalysis.reproduction.evidence | join(", ") }}
+{% if errorAnalysis.reproduction.blockedReason %}- **{{ t("errorAnalysis.blockedReason") }}:** {{ errorAnalysis.reproduction.blockedReason }}
+{% endif %}
+
+{% if errorAnalysis.causeCandidates | length == 0 -%}
+{{ t("emptyState.errorAnalysisCauseCandidates") }}
+{%- else %}
+| ID | {{ t("errorAnalysis.candidate") }} | {{ t("errorAnalysis.supportingEvidence") }} | {{ t("errorAnalysis.falsifyingEvidence") }} | {{ t("errorAnalysis.confidence") }} | {{ t("errorAnalysis.disproveWith") }} |
+|---|---|---|---|---|---|
+{% for row in errorAnalysis.causeCandidates -%}
+| {{ row.id | mdcell }} | {{ row.statement | mdcell }} | {{ row.supportingEvidence | join(", ") | mdcell }} | {{ row.falsifyingEvidenceChecked | join(", ") | mdcell }} | `{{ row.confidence | mdcell }}` | {{ row.disproveWith | mdcell }} |
+{% endfor %}
+{%- endif %}
+
+- **{{ t("errorAnalysis.nextDiagnostic") }}:** {{ errorAnalysis.nextDiagnostic.action }}
+- **{{ t("errorAnalysis.confirmingSignal") }}:** {{ errorAnalysis.nextDiagnostic.confirmingSignal }}
+- **{{ t("errorAnalysis.rejectingSignal") }}:** {{ errorAnalysis.nextDiagnostic.rejectingSignal }}
+- **{{ t("errorAnalysis.route") }}:** `{{ errorAnalysis.routing.nextTaskType }}`{% if errorAnalysis.routing.leadingCauseId %} — `{{ errorAnalysis.routing.leadingCauseId }}`{% endif %} — {{ errorAnalysis.routing.rationale }}
+{% endif %}
+
 ## 3. Recommended Next Steps
 
 {% if recommendedNextSteps | length == 0 -%}
@@ -477,6 +503,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

@@ -19,7 +19,8 @@
     "lingeringRisks": "- No tracked lingering risks.",
     "noClarification": "- No additional information requested. The Section 7 verdict stands as-is.",
     "noFollowUp": "- No follow-up tasks. The next phase for this run is in §3 (Recommended Next Steps).",
-    "endStateCoverage": "No end-state coverage recorded for this phase."
+    "endStateCoverage": "No end-state coverage recorded for this phase.",
+    "errorAnalysisCauseCandidates": "No evidence-backed cause candidate yet."
   },
   "columns": {
     "recordMeta": "Record",
@@ -97,8 +98,25 @@
     "columnSections": "Sections",
     "columnRelatedIds": "Related item IDs"
   },
+  "errorAnalysis": {
+    "heading": "Error Analysis Result",
+    "symptomVerbatim": "Symptom Verbatim",
+    "observableFailure": "Observable Failure",
+    "reproductionStatus": "Reproduction Status",
+    "reproductionEvidence": "Reproduction Evidence",
+    "blockedReason": "Blocked Reason",
+    "candidate": "Cause Candidate",
+    "supportingEvidence": "Supporting Evidence",
+    "falsifyingEvidence": "Falsifying Evidence",
+    "confidence": "Confidence",
+    "disproveWith": "Disprove With",
+    "nextDiagnostic": "Next Diagnostic",
+    "confirmingSignal": "Confirming Signal",
+    "rejectingSignal": "Rejecting Signal",
+    "route": "Route"
+  },
   "finalVerdict": {
-    "intro": "This run's final conclusion and next action. **`Direction`** is the recommended next action — one of `continue-investigation`, `begin-implementation`, `approve`, `reject`, or `hold` — and is present for every task-type. **`Verdict Token`** is meaningful only for the `final-verification` task-type, where it is one of `accepted`, `conditional-accept`, or `blocked` and serves as the `release-handoff` entry gate. For every other task-type, `Verdict Token` is always `not-applicable`."
+    "intro": "This run's final conclusion and next action. **`Direction`** is the recommended next action — one of `continue-investigation`, `begin-planning`, `begin-implementation`, `approve`, `reject`, or `hold` — and is present for every task-type. `begin-planning` means the diagnosis is ready to enter `implementation-planning`. **`Verdict Token`** is meaningful only for the `final-verification` task-type, where it is one of `accepted`, `conditional-accept`, or `blocked` and serves as the `release-handoff` entry gate. For every other task-type, `Verdict Token` is always `not-applicable`."
   },
   "evidence": {
     "sourceItemsColumnNote": "The `Source items` column is described in §6.1."
@@ -112,7 +130,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 +186,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

@@ -19,7 +19,8 @@
     "lingeringRisks": "- 추적 대상 잔존 위험 없음.",
     "noClarification": "- 추가 정보 요청 없음. Section 7 의 최종 판단이 그대로 유효합니다.",
     "noFollowUp": "- 후속 작업 없음. 본 run 의 다음 phase 는 §3 (Recommended Next Steps) 참고.",
-    "endStateCoverage": "이번 phase 에 기록된 종료 상태 처리가 없습니다."
+    "endStateCoverage": "이번 phase 에 기록된 종료 상태 처리가 없습니다.",
+    "errorAnalysisCauseCandidates": "근거가 뒷받침하는 원인 후보가 아직 없습니다."
   },
   "columns": {
     "recordMeta": "항목",
@@ -97,8 +98,25 @@
     "columnSections": "등장 섹션",
     "columnRelatedIds": "관련 항목 IDs"
   },
+  "errorAnalysis": {
+    "heading": "오류 분석 결과",
+    "symptomVerbatim": "증상 원문",
+    "observableFailure": "관측된 실패",
+    "reproductionStatus": "재현 상태",
+    "reproductionEvidence": "재현 근거",
+    "blockedReason": "차단 사유",
+    "candidate": "원인 후보",
+    "supportingEvidence": "지지 근거",
+    "falsifyingEvidence": "반증 확인",
+    "confidence": "신뢰도",
+    "disproveWith": "반증 방법",
+    "nextDiagnostic": "다음 진단",
+    "confirmingSignal": "확인 신호",
+    "rejectingSignal": "기각 신호",
+    "route": "라우팅"
+  },
   "finalVerdict": {
-    "intro": "이 run 의 최종 결론과 다음 행동입니다. **`Direction`** 은 권장 다음 행동으로 `continue-investigation`(조사 계속) · `begin-implementation`(구현 시작) · `approve`(승인) · `reject`(반려) · `hold`(보류) 중 하나이며, 모든 task-type 에 존재합니다. **`Verdict Token`** 은 `final-verification` task-type 에서만 의미를 가집니다 — `accepted` · `conditional-accept` · `blocked` 중 하나로 `release-handoff` 진입 게이트로 쓰입니다. 그 외 task-type 에서 `Verdict Token` 은 항상 `not-applicable`(해당 없음) 입니다."
+    "intro": "이 run 의 최종 결론과 다음 행동입니다. **`Direction`** 은 권장 다음 행동으로 `continue-investigation`(조사 계속) · `begin-planning`(계획 시작) · `begin-implementation`(구현 시작) · `approve`(승인) · `reject`(반려) · `hold`(보류) 중 하나이며, 모든 task-type 에 존재합니다. `begin-planning`은 진단이 `implementation-planning`에 진입할 준비가 됐음을 뜻합니다. **`Verdict Token`** 은 `final-verification` task-type 에서만 의미를 가집니다 — `accepted` · `conditional-accept` · `blocked` 중 하나로 `release-handoff` 진입 게이트로 쓰입니다. 그 외 task-type 에서 `Verdict Token` 은 항상 `not-applicable`(해당 없음) 입니다."
   },
   "evidence": {
     "sourceItemsColumnNote": "`Source items` 열 설명은 §6.1 과 동일합니다."
@@ -112,7 +130,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 +186,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-brief.py

@@ -841,6 +841,10 @@ def validate_brief(path: Path, briefs_root: Path) -> list[str]:
 
 
 def find_briefs(root: Path) -> Iterable[Path]:
+    if root.is_file():
+        if root.suffix == ".md":
+            yield root
+        return
     yield from root.rglob("*.md")
 
 
@@ -849,7 +853,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument(
         "briefs_dir",
         type=Path,
-        help="Directory containing brief markdown files (recursed).",
+        help="Brief markdown file or directory containing brief files.",
     )
     parser.add_argument(
         "--briefs-root",