okstra 0.101.0 → 0.102.0

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

@@ -217,6 +217,22 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {% endfor %}
 {%- endif %}
 
+### Cross-Project Dependencies{% if t("sectionAside.crossProjectDependencies") != "Cross-Project Dependencies" %} ({{ t("sectionAside.crossProjectDependencies") }}){% endif %}
+
+{% if implementationPlanning.crossProjectDependencies | length == 0 -%}
+{{ t("emptyState.crossProjectDependencies") }}
+{%- else %}
+{% for xp in implementationPlanning.crossProjectDependencies %}
+**{{ xp.id }} — [{{ xp.direction }}] {{ xp.project }}**
+
+- {{ t("implementationPlanning.crossProjectFields.requiredWork") }}: {{ xp.requiredWork }}
+- {{ t("implementationPlanning.crossProjectFields.verificationSignal") }}: {{ xp.verificationSignal }}
+- {{ t("implementationPlanning.crossProjectFields.linkedWork") }}: {{ xp.linkedWork }}
+- {{ t("implementationPlanning.crossProjectFields.howToStart") }}: {{ xp.howToStart }}
+{% endfor %}
+{{ t("implementationPlanning.crossProjectRecognitionNote") }}
+{%- endif %}
+
 ### Validation Checklist{% if t("sectionAside.validationChecklist") != "Validation Checklist" %} ({{ t("sectionAside.validationChecklist") }}){% endif %}
 
 | ID | Phase | Ticket ID | Check | Command / Observation | Expected outcome |
@@ -241,6 +257,25 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.id | mdcell }} | `{{ row.source | mdcell }}` | {{ row.requirement | mdcell }} | {{ row.coveredBy | mdcell }} | `{{ row.status | mdcell }}` |
 {% endfor %}
 
+### Decision Drafts{% if t("sectionAside.decisionDrafts") != "Decision Drafts" %} ({{ t("sectionAside.decisionDrafts") }}){% endif %}
+
+{% if (implementationPlanning.decisionDrafts | length == 0) and (implementationPlanning.skippedAdrCandidates | length == 0) -%}
+{{ t("emptyState.decisionDrafts") }}
+{%- else %}
+{% for d in implementationPlanning.decisionDrafts %}
+#### {{ d.number }}-{{ d.slug }}
+
+- **{{ t("implementationPlanning.decisionDraftFields.status") }}:** {{ d.status }}
+- **{{ t("implementationPlanning.decisionDraftFields.context") }}:** {{ d.context }}
+- **{{ t("implementationPlanning.decisionDraftFields.decision") }}:** {{ d.decision }}
+- **{{ t("implementationPlanning.decisionDraftFields.consequences") }}:** {{ d.consequences }}
+- **{{ t("implementationPlanning.decisionDraftFields.alternativesConsidered") }}:** {{ d.alternativesConsidered }}
+{% endfor %}
+{% for s in implementationPlanning.skippedAdrCandidates %}
+- skipped adr-candidate: {{ s.topic }} — reason: {{ s.reason }}
+{% endfor %}
+{%- endif %}
+
 ## 5.5 Stage Map
 
 | stage | title | depends-on | step-count | exit-contract-summary |
@@ -482,7 +517,21 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 | {{ row.category | mdcell }} | `{{ row.rollbackCommand | mdcell }}` | {{ row.verification | mdcell }} | `{{ row.result | mdcell }}` |
 {% endfor %}
 
-### 5.7.9 Routing Recommendation
+### 5.7.9 Manual User Test (Draft)
+
+{% if implementation.manualUserTest.applicable -%}
+{% for item in implementation.manualUserTest.items %}
+- **{{ item.target }}**
+  - {{ t("manualUserTest.environmentSetup") }}: {{ item.environmentSetup }}
+  - {{ t("manualUserTest.steps") }}:
+{% for step in item.steps %}    {{ loop.index }}. {{ step }}
+{% endfor %}  - {{ t("manualUserTest.expectedResult") }}: {{ item.expectedResult }}
+{% endfor %}
+{%- else -%}
+- {{ t("manualUserTest.notApplicable") }}: {{ implementation.manualUserTest.exemptionReason }}
+{%- endif %}
+
+### 5.7.10 Routing Recommendation
 
 {{ implementation.routingRecommendation }}
 
@@ -565,7 +614,19 @@ implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 {% endfor %}
 {%- endif %}
 
-### 5.8.7 Routing Recommendation
+### 5.8.7 Manual User Test Results
+
+{% if finalVerification.manualUserTest.applicable -%}
+| {{ t("manualUserTest.performed") }} | {{ t("manualUserTest.result") }} | {{ t("manualUserTest.observed") }} |
+|---|---|---|
+{% for row in finalVerification.manualUserTest.results -%}
+| {{ row.target | mdcell }} — {{ row.performed | mdcell }} | `{{ row.result | mdcell }}` | {{ row.observed | mdcell }} |
+{% endfor %}
+{%- else -%}
+- {{ t("manualUserTest.notApplicable") }}: {{ finalVerification.manualUserTest.exemptionReaffirm }}
+{%- endif %}
+
+### 5.8.8 Routing Recommendation
 
 {{ finalVerification.routingRecommendation }}
 

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:
 
-> 보고서 경로가 비거나 누락된 보고서를 가리키면 final-verification 은 status `blocked` 으로 끝내고 `implementation` 또는 `implementation-planning` 으로 라우팅합니다. 검증 대상(worktree/base/head)은 okstra 가 자동 해소하므로 수동 기입이 어긋나 막히는 일은 없습니다.
+> 보고서 경로가 비거나 누락된 보고서를 가리키면 final-verification 은 status `blocked` 으로 끝내고 `implementation` 또는 `implementation-planning` 으로 라우팅합니다. 검증 대상(worktree/base)은 okstra 가 자동 해소하므로 수동 기입이 어긋나 막히는 일은 없습니다.
 
 ## Requirement Coverage Source
 
@@ -55,7 +55,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 - PR or change summary:
 - Test results:
-- Manual verification notes:
+- Manual verification notes (execute the source implementation report's §5.7.9 Manual User Test Draft and record results here):
 - Related code paths:
 - Release or rollout notes:
 - Previous reports in the same task history:
@@ -90,7 +90,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Questions for Analysers
 
-1. Did your analysis run against the injected `VERIFICATION_TARGET` (base / head SHA / worktree), and does the diff at that target fully cover the stage(s) under verification? (A head you cannot confirm against the injected target is a `tool-failure`, not a silent proceed.)
+1. Did your analysis run against the injected `VERIFICATION_TARGET` (base ref / worktree), and does the worktree's delivered diff fully cover the stage(s) under verification? (A worktree you cannot confirm against the injected target is a `tool-failure`, not a silent proceed.)
 2. For each requirement / acceptance criterion, what exact artifact (commit SHA, test output, log line, config value) proves coverage?
 3. Are there any acceptance blockers?
 4. What residual risks remain?

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

@@ -9,6 +9,8 @@
     "primaryEvidence": "- No primary evidence.",
     "secondaryEvidence": "- No secondary evidence or alternate interpretations.",
     "risks": "- No missing information or risks.",
+    "crossProjectDependencies": "- No upstream/downstream dependency on another project.",
+    "decisionDrafts": "- No decision drafts or skipped ADR candidates.",
     "dependencyRisk": "- No dependency / migration risks.",
     "dissent": "- No dissenting opinions.",
     "outOfPlanEdits": "- No out-of-plan edits.",
@@ -29,6 +31,8 @@
     "checkMethod": "How to check"
   },
   "sectionAside": {
+    "crossProjectDependencies": "Cross-Project Dependencies",
+    "decisionDrafts": "Decision Drafts",
     "dependencyRisk": "Dependency / Migration Risk",
     "validationChecklist": "Validation Checklist",
     "rollbackStrategy": "Rollback Strategy",
@@ -95,7 +99,21 @@
     "rationaleLabel": "Rationale (trade-off row / principle)",
     "rejectedSummaryLabel": "Summary of rejected options",
     "columnImpact": "Impact",
-    "columnMitigation": "Mitigation / prerequisite"
+    "columnMitigation": "Mitigation / prerequisite",
+    "crossProjectFields": {
+      "requiredWork": "Required work",
+      "verificationSignal": "Verification signal",
+      "linkedWork": "Linked work",
+      "howToStart": "How to start"
+    },
+    "crossProjectRecognitionNote": "Note: the other project's run is structurally independent — its done-set, stage numbers, and depends-on all resolve against its own repo, and this run's completed stages are NOT auto-recognized as done there. This section is narrative input that seeds the other run's planning only.",
+    "decisionDraftFields": {
+      "status": "Status",
+      "context": "Context",
+      "decision": "Decision",
+      "consequences": "Consequences",
+      "alternativesConsidered": "Alternatives Considered"
+    }
   },
   "releaseHandoff": {
     "auditNote": "Audit trail for the phase that ran git/gh mutating commands.",
@@ -145,6 +163,15 @@
     "verificationScope": "Verification scope",
     "stageReportsLabel": "Source implementation reports (per stage)"
   },
+  "manualUserTest": {
+    "environmentSetup": "Environment",
+    "steps": "Steps",
+    "expectedResult": "Expected result",
+    "notApplicable": "Manual user test not required",
+    "performed": "Performed",
+    "result": "Result",
+    "observed": "Observed"
+  },
   "index": {
     "heading": "Index",
     "sectionsLabel": "Sections",

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

@@ -9,6 +9,8 @@
     "primaryEvidence": "- 주 증거 없음.",
     "secondaryEvidence": "- 보조 증거 또는 대안 해석 없음.",
     "risks": "- 누락된 정보·위험 없음.",
+    "crossProjectDependencies": "- 다른 프로젝트에 대한 선행/후속 의존 없음.",
+    "decisionDrafts": "- 결정 기록 초안이나 스킵된 ADR 후보 없음.",
     "dependencyRisk": "- 의존성·마이그레이션 위험 없음.",
     "dissent": "- 반대 의견 없음.",
     "outOfPlanEdits": "- 계획 외 편집 없음.",
@@ -29,6 +31,8 @@
     "checkMethod": "확인 방법"
   },
   "sectionAside": {
+    "crossProjectDependencies": "프로젝트 간 의존성",
+    "decisionDrafts": "결정 기록 초안",
     "dependencyRisk": "의존성·마이그레이션 위험",
     "validationChecklist": "검증 체크리스트",
     "rollbackStrategy": "롤백 전략",
@@ -95,7 +99,21 @@
     "rationaleLabel": "근거 (Trade-off 행 / 원칙)",
     "rejectedSummaryLabel": "채택되지 않은 옵션 요약",
     "columnImpact": "영향",
-    "columnMitigation": "완화 / 선행 작업"
+    "columnMitigation": "완화 / 선행 작업",
+    "crossProjectFields": {
+      "requiredWork": "필요 작업",
+      "verificationSignal": "검증 신호",
+      "linkedWork": "연결된 작업",
+      "howToStart": "시작 방법"
+    },
+    "crossProjectRecognitionNote": "참고: 상대 프로젝트의 run 은 구조적으로 독립이다 — done-set·stage 번호·depends-on 이 모두 자기 repo 기준이며, 이 run 의 완료 stage 가 자동으로 done 으로 인식되지 않는다. 이 섹션은 상대 run 의 planning 을 seed 하는 narrative 입력일 뿐이다.",
+    "decisionDraftFields": {
+      "status": "상태",
+      "context": "맥락",
+      "decision": "결정",
+      "consequences": "결과",
+      "alternativesConsidered": "검토한 대안"
+    }
   },
   "releaseHandoff": {
     "auditNote": "git/gh mutating 명령이 실행된 phase 의 감사 기록.",
@@ -145,6 +163,15 @@
     "verificationScope": "검증 범위",
     "stageReportsLabel": "stage 별 구현 리포트"
   },
+  "manualUserTest": {
+    "environmentSetup": "환경 기동",
+    "steps": "확인 스텝",
+    "expectedResult": "기대 결과",
+    "notApplicable": "사용자 테스트 불필요",
+    "performed": "수행",
+    "result": "결과",
+    "observed": "관찰값"
+  },
   "index": {
     "heading": "목차",
     "sectionsLabel": "섹션",

package/runtime/templates/reports/report.css

@@ -197,6 +197,16 @@ button[data-action]:hover { background: color-mix(in srgb, Highlight 20%, Button
 }
 #user-response-output:empty { display: none; }
 
+.user-response-dismiss {
+  position: absolute;
+  top: 0.35em;
+  right: 0.5em;
+  padding: 0 0.45em;
+  line-height: 1.5;
+  font-size: 1.05rem;
+  font-weight: 600;
+}
+
 #plan-approval {
   max-width: 120ch;
   margin: 1.5rem auto;

package/runtime/templates/reports/report.js

@@ -187,6 +187,7 @@
     var md = buildUserResponseMarkdown(runMeta, entries, isoNowUtc(), approval);
     var out = document.getElementById("user-response-output");
     if (out) out.textContent = md;
+    showDismiss(true);
     // Nothing answered yet — show the empty serialisation as feedback but
     // don't download a useless file.
     if (entries.length > 0 || approval) downloadUserResponse(md, runMeta);
@@ -196,6 +197,7 @@
   function copyUserResponse() {
     var out = document.getElementById("user-response-output");
     if (!out || !out.textContent) return;
+    showDismiss(true);
     var text = out.textContent;
     if (navigator.clipboard && navigator.clipboard.writeText) {
       navigator.clipboard.writeText(text).catch(function () {
@@ -217,6 +219,17 @@
     document.body.removeChild(ta);
   }
 
+  function showDismiss(show) {
+    var btn = document.querySelector('button[data-action="dismiss-user-response"]');
+    if (btn) btn.hidden = !show;
+  }
+
+  function dismissUserResponse() {
+    var out = document.getElementById("user-response-output");
+    if (out) out.textContent = "";
+    showDismiss(false);
+  }
+
   function bind() {
     var clickables = document.querySelectorAll("button[data-action]");
     for (var i = 0; i < clickables.length; i++) {
@@ -226,7 +239,10 @@
         btn.addEventListener("click", exportUserResponse);
       } else if (action === "copy-user-response") {
         btn.addEventListener("click", copyUserResponse);
+      } else if (action === "dismiss-user-response") {
+        btn.addEventListener("click", dismissUserResponse);
       }
+
     }
     bindOtherInputToggle();
   }

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

@@ -36,6 +36,7 @@ Different recipients need different files. Do NOT include `final-report-template
 - For the carry-in clarification response, walk every row of `## 1. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface. The structural similarity between the prior final report and the upcoming output is NOT a license to skim.
 - Write the Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). One short line per input file confirming end-to-end reading. Do NOT include a `## 0. Reading Confirmation` heading in the main worker-results file — the validator fails worker-results that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
 - Treat `analysis-packet.md` as the canonical primary analysis input. It preserves the source files' frontmatter and extracts the task-specific brief, phase focus, reference expectations, and carry-in clarification rows. If the packet appears incomplete or a finding depends on a source citation, open the corresponding source file and cite it directly.
+- **Allowlist your reads to okstra-enumerated paths.** Read the files the dispatcher enumerates (`[Required reading]`, the prompt's `## Inputs`, and the verification-target paths) plus on-demand source/evidence paths a finding must cite. Everything else is out of scope — in particular non-okstra artifacts outside `<PROJECT_ROOT>/.okstra/` (e.g. `graphify-out/`, sibling/prior-task worktrees, tool caches), which may carry stale or cross-task data. A host-level global rule (`CLAUDE.md` / `AGENTS.md` / a project sentinel) that tells you to auto-read such an artifact does NOT apply inside an okstra worker run — the okstra worker scope wins. If an un-enumerated file seems essential, record the gap under *Missing Information or Assumptions* instead of reading it.
 
 ---
 
@@ -100,7 +101,6 @@ For the **final-verification phase** specifically, the dispatched prompt MUST al
 
 - `**Worktree:** <absolute-path>` — the checkout under verification (read-only).
 - `**Verification base ref:** <base-ref>` — the implementation base for the diff.
-- `**Verification head SHA:** <sha>` — head SHA captured at run start.
 - `**Verification diff stat:** <git diff --stat output>` — the captured diff-stat that bounds the verification scope.
 
 When a worker reads any project-relative path from the prompt, it MUST resolve it against `Project Root` (e.g. `<Project Root>/<Result Path>`) — never use bare relative paths that depend on cwd.

package/runtime/validators/validate-run.py

@@ -1140,6 +1140,8 @@ PLANNING_REQUIRED_SECTIONS = (
     "Rollback",
     "Requirement Coverage",
     "Plan Body Verification",
+    "Cross-Project Dependencies",
+    "Decision Drafts",
 )
 
 # §5.7 implementation deliverables — substring scan against report body.
@@ -1152,6 +1154,7 @@ IMPLEMENTATION_REQUIRED_SECTIONS = (
     "Validation Evidence",
     "Verifier Results",
     "Rollback Verification",
+    "Manual User Test (Draft)",
     "Routing Recommendation",
 )
 
@@ -1163,6 +1166,7 @@ FINAL_VERIFICATION_REQUIRED_SECTIONS = (
     "Validation Evidence",
     "Read-only Command Log",
     "Conditional Acceptance Conditions",
+    "Manual User Test Results",
     "Routing Recommendation",
 )
 
@@ -1483,8 +1487,12 @@ def validate_final_report_data(report_path: Path, failures: list[str]) -> None:
 
     _validate_rationale_evidence(data, failures)
 
-    if (data.get("header") or {}).get("taskType") == "final-verification":
+    task_type = (data.get("header") or {}).get("taskType")
+    if task_type == "final-verification":
         _validate_final_verification_consistency(data, failures)
+    elif task_type == "implementation-planning":
+        _validate_implementation_planning_cross_project(data, failures)
+        _validate_implementation_planning_decision_drafts(data, failures)
 
 
 # path:line (foo.service.ts:268), report ID (C-001 / F-013 / G-crit-002 / RC-1),
@@ -1525,6 +1533,67 @@ def _validate_rationale_evidence(data: dict, failures: list[str]) -> None:
         )
 
 
+def _validate_implementation_planning_cross_project(data: dict, failures: list[str]) -> None:
+    """타 프로젝트 의존을 DM 행(`kind == 'cross-project'`)으로 선언했다면
+    `crossProjectDependencies` 에 `direction == 'upstream-precondition'` 행이
+    반드시 있어야 한다 — 실제 선행 필수 의존이 soft `recommendedNextSteps`
+    추천으로 새어나가지 못하게 강제한다. 각 XP 행의 필드 비-빈은 스키마가
+    보장하고, 이 검사는 cross-project DM 신호가 있을 때 XP 행이 *존재*하는지를 본다.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    dm_rows = ip.get("dependencyMigrationRisk") or []
+    has_cross_project_dm = any(
+        isinstance(r, dict) and r.get("kind") == "cross-project" for r in dm_rows
+    )
+    if not has_cross_project_dm:
+        return
+    xp_rows = ip.get("crossProjectDependencies") or []
+    has_upstream = any(
+        isinstance(r, dict) and r.get("direction") == "upstream-precondition"
+        for r in xp_rows
+    )
+    if not has_upstream:
+        failures.append(
+            "final-report data.json: a dependencyMigrationRisk row has "
+            "kind='cross-project' but crossProjectDependencies carries no "
+            "direction='upstream-precondition' entry. Record the cross-project "
+            "dependency as a mandatory precondition (concrete requiredWork / "
+            "verificationSignal / howToStart) — not a soft Recommended Next Step."
+        )
+
+
+def _validate_implementation_planning_decision_drafts(data: dict, failures: list[str]) -> None:
+    """`decisionDrafts` 가 비어있지 않으면 어느 stage 의 stepwiseExecution step 이
+    `.okstra/decisions/` 파일을 생성하는 materialization step 을 포함해야 한다.
+    프로파일 Decision-record evaluation 의 "approved plan stepwise MUST include
+    Create .okstra/decisions/<NNNN>-<slug>.md" 를 실제 강제한다. draft 존재 자체가
+    trigger 이므로 self-contained 하다.
+    """
+    ip = data.get("implementationPlanning")
+    if not isinstance(ip, dict):
+        return
+    if not (ip.get("decisionDrafts") or []):
+        return
+    has_materialization = any(
+        ".okstra/decisions/" in (step.get("files") or "")
+        or ".okstra/decisions/" in (step.get("action") or "")
+        for stage in (ip.get("stages") or [])
+        if isinstance(stage, dict)
+        for step in (stage.get("stepwiseExecution") or [])
+        if isinstance(step, dict)
+    )
+    if not has_materialization:
+        failures.append(
+            "final-report data.json: implementationPlanning.decisionDrafts is "
+            "non-empty but no stage's stepwiseExecution creates a "
+            "`.okstra/decisions/<NNNN>-<slug>.md` file. The approved plan must "
+            "materialize each decision draft via a stepwise step (profile "
+            "Decision-record evaluation)."
+        )
+
+
 def _validate_final_verification_consistency(data: dict, failures: list[str]) -> None:
     """Enforce verdict ↔ blocker/condition/routing consistency on the
     final-verification data.json (SSOT). The schema guarantees field SHAPE;