okstra 0.171.0 → 0.173.0

package/runtime/skills/okstra-user-response/SKILL.md

@@ -73,7 +73,7 @@ okstra user-response show --report <reportPath>
 
 Returns `{reportPath, rows: [{id, kind, blocks, status, statement, expectedForm, options, contextRefs, resolvedRefs}]}`.
 
-Each entry of `options[]` is `{role, answer, rationale, scopeImpact, addedWork, directionChange}`. `role` is `recommended` for exactly one entry and `alternative` for the rest; `scopeImpact` is a token list drawn from `in-repo` / `cross-repo` / `new-schema` / `deferrable`; `addedWork` and `directionChange` are one sentence each. A schema-v1 report has nowhere to record impact, so those three arrive empty — the CLI reconstructs only the answers from the report's `Expected form` cell.
+Each entry of `options[]` is `{role, answer, rationale, scopeImpact, addedWork, directionChange, disposition}`. `role` is `recommended` for exactly one entry and `alternative` for the rest; `scopeImpact` is a token list drawn from `in-repo` / `cross-repo` / `new-schema` / `deferrable`; `addedWork` and `directionChange` are one sentence each. Activity-contract v1 approval options also carry the gate action in `disposition`. A legacy schema-v1 report has nowhere to record impact or a gate action, so those fields arrive empty — the CLI reconstructs only the answers from the report's `Expected form` cell.
 
 `resolvedRefs` is `[{ref, definition}]` — the CLI has already looked up what each internal token (`RB-002`, `FU-001`, `§4.7`, …) means in the report body; `definition` is `null` only when the report text alone could not resolve it (e.g. a `path:line` pointer).
 
@@ -127,7 +127,7 @@ Record one entry — `{id, kind, value, rationale?, disposition}`, `kind` copied
 
 | The user picks | `value` | `disposition` |
 |---|---|---|
-| One of the `options[]` entries | that option's `answer` text, not its short label | `answer` |
+| One of the `options[]` entries | that option's `answer` text, not its short label | that option's `disposition` (`answer` only when absent on a legacy option) |
 | `Enter directly` → their own answer | the user's utterance verbatim (rationale into `rationale`) | `answer` |
 | Free text asking for the item to be re-asked | what the user wants re-asked, verbatim (empty → the raw statement) | `reframe` |
 

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 }}
 ---
 {#
@@ -110,6 +114,14 @@ schema-version: {{ schemaVersion | yaml_scalar }}
 {{ md_rest(aiTaskProperty, 3) }}
 {% endif %}
 
+{% if md_has("agentActivity") %}
+## {{ t("agentActivity.heading") }}
+
+{{ t("agentActivity.intro") }}
+
+{{ md("agentActivity", 3) }}
+{% endif %}
+
 ## Cross Verification Audit
 
 {{ md("crossVerification", 3) }}

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/assets/base.css

@@ -108,6 +108,13 @@ textarea, select { width: 100%; max-width: 60rem; padding: .55rem; font: inherit
 .clarification-expected dt { font-weight: 600; margin-bottom: .3rem; }
 .clarification-expected dd { margin: 0; }
 .clarification-item label { font-weight: 600; margin-bottom: .3rem; }
+.activity-list { display: grid; gap: .8rem; }
+.activity-card { padding: 1rem; border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); border-radius: 12px; }
+.activity-card > :first-child, .approval-context > :first-child { margin-top: 0; }
+.activity-card > :last-child, .approval-context > :last-child { margin-bottom: 0; }
+.activity-card details { margin-top: .8rem; }
+.approval-context { margin: .8rem 0; padding: .8rem 1rem; border-left: 4px solid color-mix(in srgb, Highlight 55%, GrayText); background: color-mix(in srgb, Highlight 7%, Canvas); }
+.clarification-option-disposition { color: GrayText; font-size: .85rem; }
 .user-response-hint { flex-basis: 100%; margin: 0; color: GrayText; font-size: .9rem; }
 button { padding: .5rem 1rem; border-radius: 8px; border: 1px solid color-mix(in srgb, CanvasText 28%, transparent); background: color-mix(in srgb, CanvasText 5%, Canvas); color: CanvasText; font: inherit; cursor: pointer; }
 button:hover { background: color-mix(in srgb, CanvasText 12%, Canvas); }

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

@@ -150,6 +150,7 @@
       "questions-waiting-on-you": "Questions waiting on you",
       "count-questions-waiting-on-you": "{count} questions waiting on you",
       "your-answer-to-id": "Your answer to {id}",
+      "choose-one": "Choose one",
       "recommended": "Recommended",
       "scope-impact": "Scope",
       "added-work": "Added work",
@@ -158,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",
@@ -249,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",
@@ -322,7 +343,11 @@
       "open-decisions-before-approval": "Open decisions before approval",
       "no-open-decision-is-holding-approval": "No open decision is holding approval.",
       "uniform-verifier-label": "Uniform verifier",
-      "uniform-verifier-legend": "This verifier answered the same verdict to every item it voted on, so this round's refutation signal came from its peers alone — the gate above reads as a wider cross-check than it was. A unanimous round is a legitimate outcome; confirm from the worker's audit sidecar that it actually opened the cited evidence."
+      "uniform-verifier-legend": "This verifier answered the same verdict to every item it voted on, so this round's refutation signal came from its peers alone — the gate above reads as a wider cross-check than it was. A unanimous round is a legitimate outcome; confirm from the worker's audit sidecar that it actually opened the cited evidence.",
+      "what-each-agent-did": "What each agent did",
+      "commands-and-evidence": "Commands and evidence",
+      "unblock-condition": "Unblock condition:",
+      "agent-evidence": "Agent evidence:"
     },
     "implementation": {
       "what-was-delivered": "What was delivered",

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

@@ -150,6 +150,7 @@
       "questions-waiting-on-you": "답변을 기다리는 질문",
       "count-questions-waiting-on-you": "답변을 기다리는 질문 {count}건",
       "your-answer-to-id": "{id}에 대한 답변",
+      "choose-one": "하나를 선택하세요",
       "recommended": "권장",
       "scope-impact": "범위",
       "added-work": "추가 작업",
@@ -158,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": "구성 요소",
@@ -249,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": "구현 방식 비교",
@@ -322,7 +343,11 @@
       "open-decisions-before-approval": "승인 전에 남은 결정",
       "no-open-decision-is-holding-approval": "승인을 막는 미결 결정이 없습니다.",
       "uniform-verifier-label": "단일 판정 검증자",
-      "uniform-verifier-legend": "이 검증자는 자기가 투표한 모든 항목에 같은 판정을 냈습니다. 그래서 이번 라운드의 반증 신호는 나머지 검증자에게서만 나왔고, 위의 게이트 값은 실제보다 넓은 교차 검증처럼 읽힙니다. 만장일치도 정당한 결과이므로, 그 워커의 audit 사이드카에서 인용한 근거를 실제로 열어봤는지 확인하십시오."
+      "uniform-verifier-legend": "이 검증자는 자기가 투표한 모든 항목에 같은 판정을 냈습니다. 그래서 이번 라운드의 반증 신호는 나머지 검증자에게서만 나왔고, 위의 게이트 값은 실제보다 넓은 교차 검증처럼 읽힙니다. 만장일치도 정당한 결과이므로, 그 워커의 audit 사이드카에서 인용한 근거를 실제로 열어봤는지 확인하십시오.",
+      "what-each-agent-did": "에이전트별 수행 내용",
+      "commands-and-evidence": "명령과 근거",
+      "unblock-condition": "승인 해제 조건:",
+      "agent-evidence": "에이전트 근거:"
     },
     "implementation": {
       "what-was-delivered": "무엇을 만들었나",

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 %}
 
@@ -42,15 +61,27 @@
   <h2>{{ t('macros.forms.count-questions-waiting-on-you') | replace('{count}', items | length) }}</h2>
   <p class="clarification-lede">{{ t('macros.forms.the-code-alone-could-not-settle-these-fill-i') }} <strong>{{ t('macros.forms.export-my-answers') }}</strong> {{ t('macros.forms.at-the-foot-of-the-page') }}</p>
   {% for row in items %}
-  <article class="clarification-item" id="id-{{ row.id }}" data-response-id="{{ row.id }}" data-kind="{{ row.kind }}">
+  {% set is_closed = row.status in ['resolved', 'obsolete'] %}
+  {% set approval_context = row.approvalContext | default(None) %}
+  <article class="clarification-item" id="id-{{ row.id }}" data-response-id="{{ row.id }}" data-kind="{{ row.kind }}" data-status="{{ row.status }}">
     <p class="eyebrow">{{ row.id }} · {{ row.kind }}</p>
     {{ row.statement | paragraphs }}
     <dl class="clarification-expected"><dt>{{ t('macros.forms.answer-as') }}</dt><dd>{{ row.expectedForm | inline_code }}</dd></dl>
+    {% if approval_context %}
+    <div class="approval-context" data-approval-classification="{{ approval_context.classification }}">
+      <p class="eyebrow">{{ approval_context.classification }}</p>
+      <p><strong>{{ t('tasks.implementation-planning.unblock-condition') }}</strong> {{ approval_context.unblockCondition | inline_code }}</p>
+      <p><strong>{{ t('tasks.implementation-planning.agent-evidence') }}</strong>
+        {% for activity_id in approval_context.activityIds %}<a href="#id-{{ activity_id }}">{{ activity_id }}</a>{% if not loop.last %}, {% endif %}{% endfor %}
+      </p>
+    </div>
+    {% endif %}
     {% if row.options %}
     <ol class="clarification-options">
       {% for option in row.options %}
       <li class="clarification-option{% if option.role == 'recommended' %} is-recommended{% endif %}">
         <p class="clarification-option-answer">{{ option.answer }}{% if option.role == 'recommended' %} <span class="badge">{{ t('macros.forms.recommended') }}</span>{% endif %}</p>
+        {% if option.disposition | default(None) %}<p class="clarification-option-disposition"><code>{{ option.disposition }}</code></p>{% endif %}
         <p class="clarification-option-rationale">{{ option.rationale }}</p>
         <dl class="clarification-option-impact">
           <dt>{{ t('macros.forms.scope-impact') }}</dt><dd>{{ option.scopeImpact | join(', ') }}</dd>
@@ -62,7 +93,14 @@
     </ol>
     {% endif %}
     <label for="response-{{ row.id }}">{{ t('macros.forms.your-answer-to-id') | replace('{id}', row.id) }}</label>
-    <textarea id="response-{{ row.id }}" data-response-id="{{ row.id }}" rows="4">{{ row.userInput | default('') }}</textarea>
+    {% if row.kind == 'decision' and approval_context and row.options %}
+    <select id="response-{{ row.id }}" data-response-id="{{ row.id }}"{% if is_closed %} disabled{% endif %}>
+      <option value="">{{ t('macros.forms.choose-one') }}</option>
+      {% for option in row.options %}<option value="{{ option.answer }}" data-disposition="{{ option.disposition }}"{% if option.role == 'recommended' %} data-recommended="true"{% endif %}{% if row.userInput | default('') == option.answer %} selected{% endif %}>{{ option.answer }}</option>{% endfor %}
+    </select>
+    {% else %}
+    <textarea id="response-{{ row.id }}" data-response-id="{{ row.id }}" rows="4"{% if is_closed %} disabled{% endif %}>{{ row.userInput | default('') }}</textarea>
+    {% endif %}
   </article>
   {% endfor %}
 </section>

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,38 @@
 
 <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">
+  <h2>{{ t('tasks.implementation-planning.what-each-agent-did') }}</h2>
+  <div class="activity-list">
+    {% for row in agentActivities %}
+    <article class="activity-card" id="id-{{ row.activityId }}">
+      <p class="eyebrow">{{ row.activityId }} · {{ row.agent }}</p>
+      <h3>{{ row.summary | inline_code }}</h3>
+      <p>{{ t('tasks.implementation-planning.result') }}: {{ row.outcome | inline_code }}</p>
+      <details>
+        <summary>{{ t('tasks.implementation-planning.commands-and-evidence') }}</summary>
+        <p><code>{{ row.kind }}</code></p>
+        {% if row.planItemIds %}<p>{{ row.planItemIds | join(', ') | inline_code }}</p>{% endif %}
+        {% for command in row.commands %}
+        <p><code>{{ command.command }}</code> · exit {{ command.exitCode }} · {{ command.outputSummary | inline_code }}</p>
+        {% endfor %}
+        {% if row.evidenceRefs %}<p>{{ row.evidenceRefs | join(', ') | inline_code }}</p>{% endif %}
+        {% if row.resultPath %}<p><code>{{ row.resultPath }}</code></p>{% endif %}
+      </details>
+    </article>
+    {% endfor %}
+  </div>
+</section>
+{% endif %}
 
 <section data-report-section="open-decisions">
   <h2>{{ t('tasks.implementation-planning.open-decisions-before-approval') }}</h2>

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

@@ -60,6 +60,10 @@
       "readerSummary": "The shortest reader path: what was decided, what a human must do next, and which audit details can wait until a deeper review.",
       "endStateCoverage": "One row per end-state id the brief pinned, and how this phase accounted for it. A row that is not `addressed` must say why."
     },
+  "agentActivity": {
+    "heading": "Agent Activity Audit",
+    "intro": "Structured lead activity projected from this run's canonical event log."
+  },
   "analysis": {
     "basisIntro": "Immutable run snapshot, bounded scan scope, current-code facts, inferences, unknowns, and review disposition for this analysis.",
     "projectIntro": "Project components, boundaries, entry points, dependencies, stores, external systems, and the shallow feature index.",
@@ -134,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) }}