okstra 0.172.0 → 0.174.0

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

@@ -16,6 +16,17 @@ shared state. The built-in default is `.project-docs`, `.scratch`,
 okstra-owned context and writes still stay under `<PROJECT_ROOT>/.okstra/**`
 unless the task brief explicitly authorizes a non-okstra path.
 
+`.claude` is the one entry materialised as a real directory whose children are
+symlinked one by one, instead of a single symlink for the whole directory. git
+does not follow a symlink, so a symlinked directory is one file to it, and a
+project that ignores host config by its contents (`.claude/*`) matches every
+child but never the bare `.claude` path — the directory would be invisible in
+the main checkout and `?? .claude` in the task worktree. Linking the children
+reproduces the main checkout's shape, so the project's own ignore rules decide
+the outcome in both places. The other entries stay whole-directory symlinks
+because okstra writes into them, and the directory symlink is what makes a
+newly created top-level entry land in the main checkout.
+
 To override per-project, add a `worktreeSyncDirs` array to `project.json`.
 Empty array disables the feature; the field is preserved across the runtime's
 auto-upserts (only `projectId`, `projectRoot`, `createdAt`, `updatedAt` are

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

@@ -11,7 +11,11 @@ project-id: {{ frontmatter.projectId | yaml_scalar }}
 task-type: {{ frontmatter.taskType | yaml_scalar }}
 worker-id: {{ frontmatter.workerId | yaml_scalar }}
 approved: {{ "true" if frontmatter.approved else "false" }}
+{% if implementationPlanning is defined and implementationPlanning.get("planningContract") == "selected-direction" -%}
+selected-direction-ref: {{ frontmatter.selectedDirectionRef | yaml_scalar }}
+{% else -%}
 implementation-option: {{ frontmatter.implementationOption | default("") | yaml_scalar }}
+{% endif -%}
 schema-version: {{ schemaVersion | yaml_scalar }}
 ---
 {#

package/runtime/templates/reports/final-verification-input.template.md

@@ -40,7 +40,7 @@ taskType: "{{FM_TASK_TYPE}}"
 - Path (project-relative) to the originating `implementation` final-report:
 - Quoted `Commit list` / `Diff summary` excerpt from the implementation report:
 
-> If the report path is empty or points to a missing report, final-verification ends with status `blocked` and routes to `implementation` or `implementation-planning`. The verification target (worktree/base) is resolved automatically by okstra, so a mismatched manual entry cannot cause a block.
+> If the report path is empty or points to a missing report, final-verification ends with status `blocked`. Cause defects route to `error-analysis`, direction defects route to `implementation-option-selection`, and detailed-plan defects route to `implementation-planning`. The verification target (worktree/base) is resolved automatically by okstra, so a mismatched manual entry cannot cause a block.
 
 ## Requirement Coverage Source
 

package/runtime/templates/reports/html/base.template.html

@@ -87,18 +87,19 @@
     </section>
     {% endif %}
   </main>
-  <footer class="human-report-footer">
+  {% if approval is not defined or not (approval and approval.reentry_command) %}<footer class="human-report-footer">
     <button type="button" data-action="export-user-response">{{ t('base.export-my-answers') }}</button>
     <button type="button" data-action="copy-user-response">{{ t('base.copy') }}</button>
     <button type="button" data-action="dismiss-user-response" hidden>{{ t('base.dismiss') }}</button>
     <p class="user-response-hint">{{ t('base.export-downloads') }} <code>user-response-{{ runMeta.task_type }}-{{ runMeta.seq }}.md</code>{{ t('base.drop-that-file-into') }} <code>runs/{{ runMeta.task_type }}/user-responses/</code> {{ t('base.and-the-next-run-picks-your-answers-up-on-it') }}</p>
     <pre id="user-response-output" aria-live="polite"></pre>
-  </footer>
+  </footer>{% endif %}
   <script id="run-meta" type="application/json">{{ {
     "task-key": runMeta.task_key,
     "task-type": runMeta.task_type,
     "seq": runMeta.seq,
     "source-report": runMeta.source_report,
+    "source-data": sourceData,
     "source-data-sha256": dataSha256,
     "source-md-sha256": markdownSha256
   } | tojson }}</script>

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

@@ -159,7 +159,9 @@
       "request-changes-to-this-plan": "Send it back for changes",
       "reject-this-plan": "Reject this plan",
       "why-required-for-changes-or-rejection": "Why — required when you send it back or reject it",
-      "answer-the-blockers-then-regenerate": "Answer {ids}, export your answers, then regenerate the report with the clarification resume command."
+      "answer-the-blockers-then-regenerate": "Answer {ids}, export your answers, then regenerate the report with the clarification resume command.",
+      "selected-direction-invalidated": "Selected direction invalidated",
+      "return-to-option-selection": "This plan cannot be approved. Re-enter implementation option selection with:"
     },
     "visualizations": {
       "component": "Component",
@@ -250,6 +252,24 @@
       "release-path": "Release path",
       "the-current-verdict-does-not-allow-release-h": "The current verdict does not allow release-handoff to start. Clear the blocker or the condition first."
     },
+    "implementation-option-selection": {
+      "original-requirements": "Original requirement coverage",
+      "requirement-ids": "Requirement IDs:",
+      "leading-causes": "Leading causes:",
+      "ranked-options": "Ranked implementation directions",
+      "weighted-score": "Weighted score:",
+      "requirement": "Requirement",
+      "satisfaction": "How it is satisfied",
+      "verification": "Expected verification",
+      "no-valid-options": "No valid implementation direction is available.",
+      "recommended-direction": "Recommended direction",
+      "no-recommendation": "No direction can be recommended.",
+      "candidate-audit": "Candidate audit",
+      "candidate": "Candidate",
+      "disposition": "Disposition",
+      "reason": "Reason",
+      "no-audit-entries": "No candidate was merged or rejected."
+    },
     "implementation-planning": {
       "what-the-plan-is-for": "What the plan is for",
       "implementation-options-compared": "Implementation options compared",

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

@@ -159,7 +159,9 @@
       "request-changes-to-this-plan": "고쳐서 다시 가져오게 합니다",
       "reject-this-plan": "이 계획을 반려합니다",
       "why-required-for-changes-or-rejection": "사유 — 반려하거나 다시 고치게 할 때는 반드시 적어야 합니다",
-      "answer-the-blockers-then-regenerate": "{ids}에 답한 뒤 답변을 내보내고, clarification resume 명령으로 리포트를 다시 만드세요."
+      "answer-the-blockers-then-regenerate": "{ids}에 답한 뒤 답변을 내보내고, clarification resume 명령으로 리포트를 다시 만드세요.",
+      "selected-direction-invalidated": "선택 방향 무효화",
+      "return-to-option-selection": "이 계획은 승인할 수 없습니다. 다음 명령으로 구현 방향 선택 단계에 다시 진입하세요:"
     },
     "visualizations": {
       "component": "구성 요소",
@@ -250,6 +252,24 @@
       "release-path": "릴리스 경로",
       "the-current-verdict-does-not-allow-release-h": "현재 판정으로는 release-handoff 를 시작할 수 없습니다. 차단 항목이나 조건을 먼저 해소하세요."
     },
+    "implementation-option-selection": {
+      "original-requirements": "원본 요구사항 커버리지",
+      "requirement-ids": "요구사항 ID:",
+      "leading-causes": "주요 원인:",
+      "ranked-options": "구현 방향 순위",
+      "weighted-score": "가중 점수:",
+      "requirement": "요구사항",
+      "satisfaction": "충족 방식",
+      "verification": "예상 검증",
+      "no-valid-options": "유효한 구현 방향이 없습니다.",
+      "recommended-direction": "권장 방향",
+      "no-recommendation": "권장할 수 있는 방향이 없습니다.",
+      "candidate-audit": "후보 감사 기록",
+      "candidate": "후보",
+      "disposition": "처리",
+      "reason": "이유",
+      "no-audit-entries": "병합되거나 탈락한 후보가 없습니다."
+    },
     "implementation-planning": {
       "what-the-plan-is-for": "이 계획이 하려는 것",
       "implementation-options-compared": "구현 방식 비교",

package/runtime/templates/reports/html/macros/forms.html

@@ -18,21 +18,40 @@
 
 {% macro plan_approval(state) -%}
 <section id="plan-approval" data-report-section="plan-approval">
+  {% if state.reentry_command %}
+  <h2>{{ t('macros.forms.selected-direction-invalidated') }}</h2>
+  <p class="approval-disabled-reason">{{ t('macros.forms.return-to-option-selection') }} <code>{{ state.reentry_command }}</code></p>
+  {% else %}
   <h2>{{ t('macros.forms.decide-on-this-plan') }}</h2>
   <fieldset id="plan-decision"><legend>{{ t('macros.forms.verdict') }}</legend>
     <input id="plan-decision-approved" type="radio" name="plan-decision-status" value="approved"{% if state.disabled_reason %} disabled{% endif %}><label for="plan-decision-approved">{{ t('macros.forms.i-approve-this-plan') }}</label>
     <input id="plan-decision-revision-requested" type="radio" name="plan-decision-status" value="revision-requested"><label for="plan-decision-revision-requested">{{ t('macros.forms.request-changes-to-this-plan') }}</label>
     <input id="plan-decision-rejected" type="radio" name="plan-decision-status" value="rejected"><label for="plan-decision-rejected">{{ t('macros.forms.reject-this-plan') }}</label>
   </fieldset>
-  <label for="approval-option">{{ t('macros.forms.implementation-option') }}</label>
+  {% if state.show_option_selector %}<label for="approval-option">{{ t('macros.forms.implementation-option') }}</label>
   <select id="approval-option"{% if state.disabled_reason %} disabled{% endif %}>
       {% for name in state.option_names %}
       {% if name == state.recommended_option %}<option data-recommended="true" selected value="{{ name }}">{{ name | inline_code }} (recommended)</option>{% else %}<option value="{{ name }}">{{ name | inline_code }}</option>{% endif %}
       {% endfor %}
-  </select>
+  </select>{% endif %}
   <label for="plan-decision-reason">{{ t('macros.forms.why-required-for-changes-or-rejection') }}</label>
   <textarea id="plan-decision-reason" rows="4"></textarea>
   {% if state.disabled_reason %}<div class="approval-disabled-reason"><p>{{ t('macros.forms.approval-is-held') }} <strong>{{ state.disabled_reason }}</strong>.</p><p>{{ t('macros.forms.answer-the-blockers-then-regenerate') | replace('{ids}', state.blocker_ids | join(', ')) }}</p></div>{% endif %}
+  {% endif %}
+</section>
+{%- endmacro %}
+
+{% macro direction_selection(state) -%}
+<section id="direction-selection" data-report-section="direction-selection">
+  <h2>Select an implementation direction</h2>
+  <fieldset><legend>Direction</legend>
+    {% for option in state.rankedOptions %}
+    <input id="direction-selection-{{ option.id }}" type="radio" name="direction-selection-option" value="{{ option.id }}" data-option-name="{{ option.name }}" required><label for="direction-selection-{{ option.id }}">{{ option.id }} · {{ option.name | inline_code }}{% if option.id == state.recommendedOptionId %} (recommended){% endif %}</label>
+    {% endfor %}
+  </fieldset>
+  <input id="direction-selection-confirmed" type="checkbox" required><label for="direction-selection-confirmed">Confirmed</label>
+  <label for="direction-selection-note">Selection note</label><textarea id="direction-selection-note" rows="3"></textarea>
+  <label for="direction-selection-constraints">Constraints</label><textarea id="direction-selection-constraints" rows="3"></textarea>
 </section>
 {%- endmacro %}
 

package/runtime/templates/reports/html/tasks/implementation-option-selection.template.html

@@ -0,0 +1,49 @@
+{% extends "html/base.template.html" %}
+{% from "html/macros/layout.html" import narrative as render_narrative, summary_card, row_key %}
+{% from "html/macros/forms.html" import direction_selection %}
+
+{% block human_content %}
+<section data-report-section="selection-status">
+  <h2>Selection status</h2>
+  <dl><dt>Mode</dt><dd>{{ selection.mode }}</dd><dt>Routing</dt><dd>{{ selection.routing }}</dd></dl>
+  {{ render_narrative(narrative.selectionGuidance, "implementationOptionSelection.userNarrative.selectionGuidance") }}
+  {% if selection.mode == "preselected-validation" %}
+  <h3>Preselected direction</h3>
+  <dl><dt>Option ID</dt><dd>{{ selection.preselectedDirection.optionId }}</dd><dt>Direction</dt><dd>{{ selection.preselectedDirection.direction | inline_code }}</dd><dt>Confirmation evidence</dt><dd>{{ selection.preselectedDirection.confirmationEvidence | inline_code }}</dd><dt>Citation</dt><dd>{{ selection.preselectedDirection.citation | inline_code }}</dd></dl>
+  {% endif %}
+</section>
+
+{% if directionSelection %}{{ direction_selection(directionSelection) }}{% endif %}
+
+<section data-report-section="decision-context">
+  <h2>{{ t('tasks.implementation-option-selection.original-requirements') }}</h2>
+  <p>{{ humanSummary.outcome | inline_code }}</p>
+  {{ render_narrative(narrative.comparisonOverview, "implementationOptionSelection.userNarrative.comparisonOverview") }}
+  <p data-report-field="implementationOptionSelection.decisionContext.originalRequirementIds"><strong>{{ t('tasks.implementation-option-selection.requirement-ids') }}</strong> {{ selection.decisionContext.originalRequirementIds | join(", ") | inline_code }}</p>
+  {% if selection.decisionContext.leadingCauseRefs %}<p><strong>{{ t('tasks.implementation-option-selection.leading-causes') }}</strong> {{ selection.decisionContext.leadingCauseRefs | join(", ") | inline_code }}</p>{% endif %}
+</section>
+
+<section data-report-section="ranked-options" data-report-field="implementationOptionSelection.rankedOptions">
+  <h2>{{ t('tasks.implementation-option-selection.ranked-options') }}</h2>
+  {{ render_narrative(narrative.rankingExplanation, "implementationOptionSelection.userNarrative.rankingExplanation") }}
+  <div class="summary-grid">{% for row in selection.rankedOptions %}<article class="summary-card" id="id-{{ row.id }}">
+    <p class="eyebrow">#{{ loop.index }} · {{ row.id }}</p>
+    <h3>{{ row.name | inline_code }}</h3>
+    <p>{{ row.goal | inline_code }}</p>
+    <div data-report-field="implementationOptionSelection.rankedOptions.coverageSummary"><p><strong>coveragePercent</strong> <span data-report-metric="coveragePercent">{{ row.coverageSummary.coveragePercent }}</span></p>
+    <p><strong>scopePrecisionPercent</strong> <span data-report-metric="scopePrecisionPercent">{{ row.coverageSummary.scopePrecisionPercent }}</span></p></div>
+    <p><strong>{{ t('tasks.implementation-option-selection.weighted-score') }}</strong> {{ row.weightedScore }}</p>
+    <table data-report-field="implementationOptionSelection.rankedOptions.requirementCoverage"><thead><tr><th>{{ t('tasks.implementation-option-selection.requirement') }}</th><th>{{ t('tasks.implementation-option-selection.satisfaction') }}</th><th>{{ t('tasks.implementation-option-selection.verification') }}</th></tr></thead><tbody>{% for coverage in row.requirementCoverage %}<tr>{{ row_key(pairs=[("ID", coverage.requirementId), ("Status", coverage.status)]) }}<td>{{ coverage.satisfaction | inline_code }}</td><td>{{ coverage.expectedVerification | inline_code }}</td></tr>{% endfor %}</tbody></table>
+  </article>{% else %}<p>{{ t('tasks.implementation-option-selection.no-valid-options') }}</p>{% endfor %}</div>
+</section>
+
+<section data-report-section="recommendation" data-report-field="implementationOptionSelection.recommendedOptionId">
+  <h2>{{ t('tasks.implementation-option-selection.recommended-direction') }}</h2>
+  {% if recommendedOption %}{{ summary_card(recommendedOption.id ~ " · " ~ recommendedOption.name, recommendedOption.coreMechanism, "important") }}{% else %}<p>{{ t('tasks.implementation-option-selection.no-recommendation') }}</p>{% endif %}
+</section>
+
+<section data-report-section="candidate-audit" data-report-field="implementationOptionSelection.candidateAudit">
+  <h2>{{ t('tasks.implementation-option-selection.candidate-audit') }}</h2>
+  <table><thead><tr><th>{{ t('tasks.implementation-option-selection.candidate') }}</th><th>{{ t('tasks.implementation-option-selection.disposition') }}</th><th>{{ t('tasks.implementation-option-selection.reason') }}</th><th>coveragePercent</th><th>scopePrecisionPercent</th></tr></thead><tbody>{% for row in selection.candidateAudit %}<tr id="id-{{ row.id }}">{{ row_key(pairs=[("ID", row.id), ("Proposed by", row.proposedBy)]) }}<td>{{ row.disposition }}</td><td>{{ row.reason | inline_code }}</td><td>{{ row.coverageSummary.coveragePercent }}</td><td>{{ row.coverageSummary.scopePrecisionPercent }}</td></tr>{% else %}<tr><td colspan="6">{{ t('tasks.implementation-option-selection.no-audit-entries') }}</td></tr>{% endfor %}</tbody></table>
+</section>
+{% endblock %}

package/runtime/templates/reports/html/tasks/implementation-planning.template.html

@@ -4,12 +4,37 @@
 {% from "html/macros/visualizations.html" import figure %}
 
 {% block human_content %}
-<section data-report-section="planning-goal">
+<section data-report-section="planning-goal" data-report-field="implementationPlanning">
   <h2>{{ t('tasks.implementation-planning.what-the-plan-is-for') }}</h2>
   <p>{{ humanSummary.outcome | inline_code }}</p>
   <div class="summary-grid">{% for reason in humanSummary.whyItMatters %}{{ summary_card("", reason, "important") }}{% endfor %}</div>
 </section>
 
+{% if planning.get("planningContract") == "selected-direction" %}
+<section data-report-section="selected-direction" data-report-field="implementationPlanning.selectedDirectionRef">
+  <h2>Selected direction</h2>
+  <article class="summary-card tone-important"><h3>{{ planning.selectedDirectionRef.optionId | inline_code }}</h3><p><strong>Source report</strong> {{ planning.selectedDirectionRef.sourceReport | inline_code }}</p><p><strong>Snapshot</strong> {{ planning.selectedDirectionRef.snapshotPath | inline_code }}</p></article>
+</section>
+{% if planning.outcome == "plan-ready" %}
+<section data-report-section="direction-realization" data-report-field="implementationPlanning.directionRealization">
+  <h2>Direction realization</h2>
+  <article class="summary-card"><h3>{{ planning.directionRealization.goal | inline_code }}</h3><p><strong>Core mechanism</strong> {{ planning.directionRealization.coreMechanism | inline_code }}</p><p><strong>Interfaces</strong> {{ planning.directionRealization.interfaces | inline_code }}</p><p><strong>Blast radius</strong> {{ planning.directionRealization.blastRadius | inline_code }}</p><ul>{% for file in planning.directionRealization.fileStructure %}<li id="id-{{ file.id }}">{{ file.action }} <code>{{ file.path }}</code> — {{ file.summary | inline_code }}</li>{% endfor %}</ul></article>
+</section>
+<section data-report-section="plan-coverage" data-report-field="implementationPlanning.coverageSummary">
+  <h2>Plan coverage</h2>
+  <p><strong>coveragePercent</strong> <span data-report-metric="coveragePercent">{{ planning.coverageSummary.coveragePercent }}</span></p>
+  <p><strong>scopePrecisionPercent</strong> <span data-report-metric="scopePrecisionPercent">{{ planning.coverageSummary.scopePrecisionPercent }}</span></p>
+</section>
+{% else %}
+<section data-report-section="direction-invalidation" data-report-field="implementationPlanning.directionInvalidation">
+  <h2>Direction invalidated</h2>
+  <ul>{% for reason in planning.directionInvalidation.reasons %}<li>{{ reason | inline_code }}</li>{% endfor %}</ul>
+  <p><strong>Code evidence</strong></p>
+  <ul>{% for evidence in planning.directionInvalidation.codeEvidence %}<li>{{ evidence | inline_code }}</li>{% endfor %}</ul>
+  <p data-report-field="implementationPlanning.routing"><strong>Re-entry route</strong> {{ planning.routing | inline_code }}</p>
+</section>
+{% endif %}
+{% else %}
 <section data-report-section="option-comparison">
   <h2>{{ t('tasks.implementation-planning.implementation-options-compared') }}</h2>
   {{ render_narrative(narrative.optionExplanation, "implementationPlanning.userNarrative.optionExplanation") }}
@@ -22,10 +47,14 @@
   {{ render_narrative(narrative.recommendationExplanation, "implementationPlanning.userNarrative.recommendationExplanation") }}
   <article class="summary-card tone-important"><h3>{{ planning.recommendedOption.name | inline_code }}</h3><p>{{ planning.recommendedOption.coreReason | inline_code }}</p><p>{{ planning.recommendedOption.rationale | inline_code }}</p><p><strong>{{ t('tasks.implementation-planning.options-not-taken') }}</strong> {{ planning.recommendedOption.rejectedSummary | inline_code }}</p></article>
 </section>
+{% endif %}
 
+{% if planning.get("outcome") != "direction-invalidated" %}
 <section data-report-section="stage-map" data-report-field="implementationPlanning.stageMap">
   <h2>{{ t('tasks.implementation-planning.stage-map') }}</h2>
+  {% if narrative.get("stageStrategy") %}
   {{ render_narrative(narrative.stageStrategy, "implementationPlanning.userNarrative.stageStrategy") }}
+  {% endif %}
   {{ figure(stageFigure) }}
   <div class="summary-grid">{% for row in planning.stages %}<article class="summary-card"><h3>Stage {{ row.stage }} · {{ row.title | inline_code }}</h3><p>{{ row.sliceValue | inline_code }}</p><p><strong>{{ t('tasks.implementation-planning.exit-contract') }}</strong> {{ row.acceptance | inline_code }}</p><p><strong>{{ t('tasks.implementation-planning.verification') }}</strong> {{ row.stageValidation | inline_code }}</p></article>{% endfor %}</div>
 </section>
@@ -64,7 +93,11 @@
    actually do what the brief asked" is the approval question itself. #}
 <section data-report-section="requirement-coverage" data-report-field="implementationPlanning.requirementCoverage">
   <h2>{{ t('tasks.implementation-planning.how-each-requirement-gets-met') }}</h2>
+  {% if planning.get("planningContract") == "selected-direction" %}
+  <table><thead><tr><th>Original requirement</th><th>Stages</th><th>Status</th></tr></thead><tbody>{% for row in planning.requirementCoverage %}<tr><td>{{ row.originalRequirementId | inline_code }}</td><td>{{ row.stageRefs | join(", ") | inline_code }}</td><td>{{ row.status | inline_code }}</td></tr>{% endfor %}</tbody></table>
+  {% else %}
   <table><thead><tr><th>{{ t('tasks.implementation-planning.requirement') }}</th><th>{{ t('tasks.implementation-planning.body') }}</th><th>{{ t('tasks.implementation-planning.covered-by') }}</th></tr></thead><tbody>{% for row in planning.requirementCoverage %}<tr id="id-{{ row.id }}">{{ row_key(pairs=[("ID", row.id), ("Source", row.source)], status_name="Status", status_raw=row.status, status_text=row.status) }}<td>{{ row.requirement | inline_code }}</td><td>{{ row.coveredBy | inline_code }}</td></tr>{% endfor %}</tbody></table>
+  {% endif %}
 </section>
 
 {% if planning.get("supersessionLedger") is not none %}
@@ -90,12 +123,13 @@
 
 <section data-report-section="decision-drafts" data-report-field="implementationPlanning.decisionDrafts">
   <h2>{{ t('tasks.implementation-planning.decision-record-draft') }}</h2>
-  {% for row in planning.decisionDrafts %}
+  {% for row in planning.get("decisionDrafts", []) %}
   <article class="summary-card"><h3>{{ row.number }} · {{ row.slug | inline_code }} ({{ row.status | inline_code }})</h3><p><strong>{{ t('tasks.implementation-planning.context') }}</strong> — {{ row.context | inline_code }}</p><p><strong>{{ t('tasks.implementation-planning.decision') }}</strong> — {{ row.decision | inline_code }}</p><p><strong>{{ t('tasks.implementation-planning.result') }}</strong> — {{ row.consequences | inline_code }}</p></article>
   {% else %}<p>{{ t('tasks.implementation-planning.there-is-no-decision-draft-to-record') }}</p>{% endfor %}
   {% if planning.get("skippedAdrCandidates") %}<h3>{{ t('tasks.implementation-planning.what-was-deliberately-not-recorded') }}</h3>
   <table data-report-field="implementationPlanning.skippedAdrCandidates"><thead><tr><th>{{ t('tasks.implementation-planning.topic') }}</th><th>{{ t('tasks.implementation-planning.why') }}</th></tr></thead><tbody>{% for row in planning.skippedAdrCandidates %}<tr><td>{{ row.topic | inline_code }}</td><td>{{ row.reason | inline_code }}</td></tr>{% endfor %}</tbody></table>{% endif %}
 </section>
+{% endif %}
 
 {% if agentActivities %}
 <section data-report-section="agent-activity">

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

@@ -138,6 +138,19 @@
     "singleRoundPrefix": "Single round —",
     "noRoundsNote": "No reverify rounds executed (all findings reached consensus at grouping)."
   },
+  "implementationOptionSelection": {
+    "decisionContext": "Original Requirement Coverage",
+    "evaluationCriteria": "Evaluation Criteria",
+    "candidateAudit": "Candidate Audit",
+    "rankedOptions": "Ranked Options",
+    "recommendedOptionId": "Recommended Option",
+    "requirementCoverage": "Requirement Coverage",
+    "scopeCommitments": "Scope Commitments",
+    "coverageSummary": "Coverage Summary",
+    "criterionScores": "Criterion Scores",
+    "feasibilityVotes": "Feasibility Votes",
+    "planningInvariants": "Planning Invariants"
+  },
   "implementationPlanning": {
     "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.",

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

@@ -28,10 +28,12 @@ taskType: "{{FM_TASK_TYPE}}"
 
 - Approved plan path: `runs/implementation-planning/<run-id>/reports/final-report.md`
 - Approval evidence (quoted exactly from the plan's YAML frontmatter, e.g. `approved: true`):
-- Recommended option name selected from the plan:
+- Planning contract: `selected-direction` or `legacy-option-candidates`
+- Selected-direction reference and snapshot digest (required for `selected-direction`):
+- Legacy implementation option name (legacy plans only):
 - Plan's bite-sized step list (paste or reference by anchor):
 
-> The run MUST refuse to start (status `contract-violated`) if the approved plan path does not exist or does not contain an explicit user approval marker.
+> The run MUST refuse to start (status `contract-violated`) if the approved plan path does not exist or does not contain an explicit user approval marker. A selected-direction plan also requires `outcome: plan-ready`, exact plan coverage, and a valid selected-direction reference. It rejects `--implementation-option`; an existing approved legacy plan keeps that option-selection path.
 
 ## Scope From Plan
 

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

@@ -55,8 +55,8 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Planning Concerns
 
-- Possible implementation options:
-- Expected trade-offs:
+- Selected direction realization concerns:
+- Legacy-only implementation options and trade-offs:
 - Dependencies or migrations:
 - Validation approach:
 - Rollback approach:
@@ -76,6 +76,14 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Questions for Analysers
 
+When `selected-direction.json` is present:
+
+1. Which files, interfaces, and stages realize the snapshot without changing its direction?
+2. How does every file, stage, validation, and rollback link to the original requirements?
+3. Does current evidence require `direction-invalidated`?
+
+Legacy candidate-comparison questions apply only when the snapshot is absent:
+
 1. What is the safest implementation direction?
 2. What are the main trade-offs between options?
 3. What should be validated before, during, and after implementation?
@@ -84,7 +92,13 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Required Plan Deliverable
 
-The final report of an `implementation-planning` run MUST contain every section below. Missing any one of them is a contract violation.
+### Selected-direction input contract
+
+When `instruction-set/selected-direction.json` is present, read it and the original requirements first. Concretize only the selected direction's files, interfaces, stages, validation, and rollback. Link every file and stage bidirectionally to the original requirements. If code evidence invalidates the direction, return `direction-invalidated` and stop. Candidate comparison and user selection are outside this contract.
+
+### Legacy candidate-comparison input contract
+
+When no selected-direction snapshot exists on a compatibility rerun, the final report retains every section below.
 
 1. **Option Candidates** — at least two viable options, each with the exact list of files to create or modify and the principal change per file.
 2. **Trade-off Matrix** — comparison of the candidates across complexity, risk, reversibility, performance impact, scope, and required test surface.
@@ -94,7 +108,7 @@ The final report of an `implementation-planning` run MUST contain every section
 6. **Validation Checklist** — pre-execution, mid-execution, and post-execution checks (commands, expected outputs, observability points).
 7. **Rollback Strategy** — exact reverse procedure or compensating action for each significant step.
 8. **Scope Boundary** — an explicit list of adjacent areas, files, refactors, or quality improvements that this plan **does NOT** cover, each with a one-line reason (deferred, separate owner, separate decision, out of requirement). Any item the analysers were tempted to fold in but chose to exclude MUST appear here. An empty list is allowed only when the analysers explicitly state "no adjacent expansion was considered" — silence is not acceptable.
-9. **Approval frontmatter** — the final report's YAML frontmatter MUST emit `approved: false` and `implementation-option:`. Do NOT create a `User Approval Request` body block; the next `implementation` run reads only the frontmatter gate.
+9. **Approval frontmatter** — the legacy final report's YAML frontmatter MUST emit `approved: false` and `implementation-option:`. Do NOT create a `User Approval Request` body block; the next `implementation` run reads only the frontmatter gate.
 
 ## Phase Boundary
 

package/runtime/templates/reports/improvement-discovery-input.template.md

@@ -69,7 +69,7 @@ Workers MUST read the resolved values from the log the lead points to via the
 
 1. Within the resolved scope and priority lenses, what are the highest-impact improvement candidates?
 2. Which candidates have full cross-worker consensus, and which are worker-unique?
-3. For each candidate, what is the safest next phase (requirements-discovery / implementation-planning / error-analysis)?
+3. For each candidate, what is the safest next phase (requirements-discovery / implementation-option-selection / error-analysis)?
 4. Which candidates would you intentionally exclude despite being technically valid, and why?
 5. Are there any signals that the scope itself is mis-defined (and should be re-narrowed before discovery proceeds)?
 

package/runtime/templates/reports/md/tasks/implementation-option-selection.template.md

@@ -0,0 +1,13 @@
+{% import "md/macros/sections.md" as s with context -%}
+{# Coverage denominator and every selectable direction precede the recommendation. #}
+{{ s.section("implementationOptionSelection.decisionContext", "Original Requirement Coverage") }}
+
+Coverage metrics: `coveragePercent` and `scopePrecisionPercent`.
+
+{{ s.section("implementationOptionSelection.rankedOptions", "Ranked Options") }}
+{{ s.section("implementationOptionSelection.recommendedOptionId", "Recommended Option") }}
+{{ s.section("implementationOptionSelection.evaluationCriteria", "Evaluation Criteria") }}
+{{ s.section("implementationOptionSelection.candidateAudit", "Candidate Audit") }}
+{{ s.section("implementationOptionSelection.preselectedDirection", "Preselected Direction") }}
+{{ s.section("implementationOptionSelection.routing", "Routing") }}
+{{ md_rest("implementationOptionSelection", 3) }}

package/runtime/templates/reports/md/tasks/implementation-planning.template.md

@@ -5,6 +5,22 @@
   Option candidates and the trade-off matrix answer "why this one" and sit
   after that, in the closing sweep.
 -#}
+{% if implementationPlanning.get("planningContract") == "selected-direction" -%}
+{{ s.section("implementationPlanning.selectedDirectionRef", "Selected Direction Reference") }}
+{% if implementationPlanning.outcome == "plan-ready" -%}
+{{ s.section("implementationPlanning.directionRealization", "Direction Realization") }}
+{{ s.section("implementationPlanning.stageMap", "Stage Map") }}
+{{ s.section("implementationPlanning.stages", "Stages") }}
+{{ s.section("implementationPlanning.validationChecklist", "Validation Checklist") }}
+{{ s.section("implementationPlanning.rollbackStrategy", "Rollback Strategy") }}
+{{ s.section("implementationPlanning.requirementCoverage", "Requirement Coverage") }}
+{{ s.section("implementationPlanning.coverageSummary", "Coverage Summary") }}
+{% else -%}
+{{ s.section("implementationPlanning.directionInvalidation", "Direction Invalidation") }}
+{{ s.section("implementationPlanning.routing", "Re-entry Route") }}
+{% endif -%}
+{{ md_rest("implementationPlanning", 3) }}
+{% else -%}
 {{ s.section("implementationPlanning.recommendedOption", "Recommended Option") }}
 {{ s.section("implementationPlanning.stageMap", "Stage Map") }}
 {{ s.section("implementationPlanning.stages", "Stages") }}
@@ -13,3 +29,4 @@
 {{ s.section("implementationPlanning.rollbackStrategy", "Rollback Strategy") }}
 {{ s.section("implementationPlanning.requirementCoverage", "Requirement Coverage") }}
 {{ md_rest("implementationPlanning", 3) }}
+{% endif -%}