okstra 0.234.0 → 0.235.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (109) hide show
  1. package/dist/cli-registry.mjs +7 -0
  2. package/dist/cli-registry.mjs.map +1 -1
  3. package/dist/commands/implementation-report/implementation-report.d.mts +1 -0
  4. package/dist/commands/implementation-report/implementation-report.mjs +73 -0
  5. package/dist/commands/implementation-report/implementation-report.mjs.map +1 -0
  6. package/dist/commands/trace/comparison.d.mts +39 -0
  7. package/dist/commands/trace/comparison.mjs +138 -0
  8. package/dist/commands/trace/comparison.mjs.map +1 -0
  9. package/dist/commands/trace/document.d.mts +8 -0
  10. package/dist/commands/trace/document.mjs +37 -0
  11. package/dist/commands/trace/document.mjs.map +1 -0
  12. package/dist/commands/trace/line-counts.d.mts +15 -0
  13. package/dist/commands/trace/line-counts.mjs +107 -0
  14. package/dist/commands/trace/line-counts.mjs.map +1 -0
  15. package/dist/commands/trace/model.d.mts +2 -1
  16. package/dist/commands/trace/model.mjs +13 -1
  17. package/dist/commands/trace/model.mjs.map +1 -1
  18. package/dist/commands/trace/progression.mjs +12 -7
  19. package/dist/commands/trace/progression.mjs.map +1 -1
  20. package/dist/commands/trace/task-link.d.mts +3 -0
  21. package/dist/commands/trace/task-link.mjs.map +1 -1
  22. package/dist/commands/trace/trace.mjs +66 -46
  23. package/dist/commands/trace/trace.mjs.map +1 -1
  24. package/dist/lib/python-helper.d.mts +1 -1
  25. package/dist/lib/python-helper.mjs +11 -5
  26. package/dist/lib/python-helper.mjs.map +1 -1
  27. package/dist/lib/types.d.mts +1 -0
  28. package/docs/architecture/storage-model.md +50 -0
  29. package/docs/cli.md +31 -15
  30. package/docs/project-structure-overview.md +6 -1
  31. package/package.json +1 -1
  32. package/runtime/BUILD.json +2 -2
  33. package/runtime/agents/operations/trace-tests-review.json +6 -0
  34. package/runtime/prompts/duties/test-reviewer.json +32 -0
  35. package/runtime/prompts/lead/report-writer.md +13 -1
  36. package/runtime/python/okstra_ctl/agent/invocation.py +109 -56
  37. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +17 -0
  38. package/runtime/python/okstra_ctl/attempt_evidence.py +5 -2
  39. package/runtime/python/okstra_ctl/code_review_census.py +38 -0
  40. package/runtime/python/okstra_ctl/code_review_coverage.py +15 -4
  41. package/runtime/python/okstra_ctl/code_review_prepare.py +15 -3
  42. package/runtime/python/okstra_ctl/code_review_scope.py +3 -2
  43. package/runtime/python/okstra_ctl/code_review_target.py +16 -6
  44. package/runtime/python/okstra_ctl/conformance_evidence.py +44 -21
  45. package/runtime/python/okstra_ctl/consumers.py +6 -1
  46. package/runtime/python/okstra_ctl/design_review.py +6 -26
  47. package/runtime/python/okstra_ctl/design_review_evidence.py +6 -26
  48. package/runtime/python/okstra_ctl/dispatch_core.py +9 -2
  49. package/runtime/python/okstra_ctl/dispatch_state.py +5 -0
  50. package/runtime/python/okstra_ctl/domain/role.py +1 -0
  51. package/runtime/python/okstra_ctl/execution_manifest.py +8 -0
  52. package/runtime/python/okstra_ctl/implementation_comparison/__init__.py +12 -0
  53. package/runtime/python/okstra_ctl/implementation_comparison/__main__.py +129 -0
  54. package/runtime/python/okstra_ctl/implementation_comparison/assembly.py +340 -0
  55. package/runtime/python/okstra_ctl/implementation_comparison/baseline.py +254 -0
  56. package/runtime/python/okstra_ctl/implementation_comparison/business_reuse.py +118 -0
  57. package/runtime/python/okstra_ctl/implementation_comparison/commit_source.py +113 -0
  58. package/runtime/python/okstra_ctl/implementation_comparison/html.py +49 -0
  59. package/runtime/python/okstra_ctl/implementation_comparison/inputs.py +348 -0
  60. package/runtime/python/okstra_ctl/implementation_comparison/model.py +47 -0
  61. package/runtime/python/okstra_ctl/implementation_comparison/preparation.py +195 -0
  62. package/runtime/python/okstra_ctl/implementation_comparison/publication.py +317 -0
  63. package/runtime/python/okstra_ctl/implementation_comparison/run_evidence.py +208 -0
  64. package/runtime/python/okstra_ctl/implementation_comparison/run_integration.py +198 -0
  65. package/runtime/python/okstra_ctl/implementation_comparison/source.py +342 -0
  66. package/runtime/python/okstra_ctl/implementation_comparison/target.py +144 -0
  67. package/runtime/python/okstra_ctl/implementation_comparison/task_assembly.py +333 -0
  68. package/runtime/python/okstra_ctl/implementation_comparison/task_selection.py +309 -0
  69. package/runtime/python/okstra_ctl/implementation_generation_evidence.py +134 -0
  70. package/runtime/python/okstra_ctl/implementation_outcome.py +2 -2
  71. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +1 -0
  72. package/runtime/python/okstra_ctl/json_boundary.py +28 -8
  73. package/runtime/python/okstra_ctl/paths.py +7 -4
  74. package/runtime/python/okstra_ctl/plan_run_root.py +8 -4
  75. package/runtime/python/okstra_ctl/qa_procedures.py +33 -2
  76. package/runtime/python/okstra_ctl/render.py +4 -0
  77. package/runtime/python/okstra_ctl/report_execution_evidence.py +88 -15
  78. package/runtime/python/okstra_ctl/report_finalize.py +18 -4
  79. package/runtime/python/okstra_ctl/report_html/render.py +46 -7
  80. package/runtime/python/okstra_ctl/report_html/validation.py +32 -0
  81. package/runtime/python/okstra_ctl/report_synthesis_packet.py +37 -3
  82. package/runtime/python/okstra_ctl/report_view_artifacts.py +12 -0
  83. package/runtime/python/okstra_ctl/review_verdicts.py +9 -0
  84. package/runtime/python/okstra_ctl/run.py +16 -0
  85. package/runtime/python/okstra_ctl/stage_done.py +11 -3
  86. package/runtime/python/okstra_ctl/stage_ledger.py +2 -2
  87. package/runtime/python/okstra_ctl/stage_map.py +3 -3
  88. package/runtime/python/okstra_ctl/trace_review.py +1 -0
  89. package/runtime/python/okstra_ctl/trace_tasks.py +22 -7
  90. package/runtime/python/okstra_ctl/verification_dispatch.py +32 -0
  91. package/runtime/python/okstra_ctl/verification_evidence.py +23 -3
  92. package/runtime/python/okstra_ctl/verification_generation.py +3 -2
  93. package/runtime/python/okstra_ctl/verification_inputs.py +3 -2
  94. package/runtime/python/okstra_ctl/verification_invocation.py +7 -3
  95. package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +17 -0
  96. package/runtime/skills/okstra-brief-gen/SKILL.md +52 -6
  97. package/runtime/skills/okstra-code-review/SKILL.md +1 -1
  98. package/runtime/skills/okstra-code-review/references/census-rules.md +1 -1
  99. package/runtime/skills/okstra-code-review/references/review-calibration.md +1 -1
  100. package/runtime/skills/okstra-run/SKILL.md +31 -0
  101. package/runtime/skills/okstra-tdd/SKILL.md +75 -11
  102. package/runtime/templates/reports/html/assets/implementation-comparison.css +39 -0
  103. package/runtime/templates/reports/html/assets/implementation-comparison.js +55 -0
  104. package/runtime/templates/reports/html/i18n/en.json +113 -0
  105. package/runtime/templates/reports/html/i18n/ko.json +113 -0
  106. package/runtime/templates/reports/html/implementation-comparison.template.html +77 -0
  107. package/runtime/templates/reports/implementation-comparison-notes.md +72 -0
  108. package/runtime/templates/trace/trace.template.md +2 -0
  109. package/runtime/validators/validate-report-views.py +4 -36
@@ -19,6 +19,28 @@ Trace publication and task projection are separate recoverable operations;
19
19
  `trace_tasks.py` enforces these boundaries; `tests/run/test_trace_tasks.py` and
20
20
  `tests/run/test_prepare.py` verify retries, ownership and preservation.
21
21
 
22
+ 새 구현 실행은 첫 리더 지침 발행 전에 실제 단계 작업 공간의 시작 자료를 보존한다. 실행 매니페스트의 `implementationComparison`은 실행 소유 비교 디렉터리와 최초 작업 기준을 별도로 가리킨다. 비교 선언은 첫 전체 매니페스트에 기존 실행 계약과 함께 저장한다. 여러 신규 준비의 미발행 선언은 서로를 과거 실행으로 취급하지 않으며, 작업 소유 잠금 안에서 최초 수집 시도를 먼저 기록한다. 기존 참조·실패·이미 게시된 지침이 있으면 현재 소스를 새 작업 기준으로 수집하지 않는다. 새 추적 시도는 문서를 저장한 직후, 첫 구현 지시를 반환하기 전에 문서 옆 `<attempt-stem>.comparison/`에 같은 기준을 보존한다. 추적 문서의 frontmatter 버전과 기존 완료 기록은 변경하지 않는다.
23
+
24
+ 공통 `implementation_comparison` 모듈이 `baseline.json`, 한도 안의 텍스트 내용, Git 목록·상태·인덱스 출력을 소유한다. 기준 커밋과 실제 시작 작업 파일을 구분하며, 기존 스테이징·미추적 파일도 수집한다. 경로 10,000개, 파일당 실제 읽기 1 MiB·합계 64 MiB, Git 명령당 표준 출력·오류 합계 4 MiB·수집 합계 8 MiB를 적용한다. 링크 대상을 따라가지 않으며, 전체 내용을 읽지 못한 파일에 완전한 내용 해시를 부여하지 않는다. 누락·수집 중 변경·제외 범위는 기준의 제한으로 남긴다.
25
+
26
+ 내용 보존의 범위는 실제 시작 작업 파일의 텍스트다. 기준 커밋 전체 트리와 인덱스의 모든 파일 내용은 별도로 복제하지 않으며, 인덱스는 객체 식별자·모드·단계와 한도 안의 패치로 보존한다. 기준 자료의 `scope`가 이 차이를 기록한다. 객체 식별자만 남은 과거 파일의 전체 내용을 산출물에 보존했다고 해석하지 않는다.
27
+
28
+ 소유 비교 디렉터리의 잠금과 최초 실패 표식이 재개 중 기준 교체를 막는다. 상태 조회는 저장 자료의 정체성과 내용 해시를 검사하며 현재 소스를 다시 수집하지 않는다. 새 계약이 없는 과거 실행·시도에 기준을 소급 생성하지 않는다. 비교 자료 실패는 기존 준비·추적 상태를 되돌리지 않으며, 수집 결과와 제한을 별도로 반환한다. 전체 제한 사유는 기준 자료에 보존하고 명령 응답은 JSON·개행을 합쳐 64 KiB 이내의 요약과 전체 개수·생략 여부를 반환한다. Python이 비교 위치를 선택하며, 위치 계획과 실제 파일 접근의 링크 거부를 구분하므로 선택적 비교 경로 오류를 기존 준비 실패로 바꾸지 않는다. 수집 경계는 `implementation_comparison/source.py`와 `baseline.py`, 준비 선언·수집 정책은 `preparation.py`, 호출 연결은 `run.py`와 `src/commands/trace/comparison.mts`가 소유한다. 공통 경계는 `tests/report/test_implementation_comparison.py`, 준비 순서는 `tests/run/test_prepare.py`, 추적 명령은 `tests-js/trace.test.mjs`가 검증한다.
29
+
30
+ 공통 종료 대상은 비교 디렉터리의 `targets/<generation>/target.json`과 내용 파일에 보존하고 `target-current.json`으로 가리킨다. 세대는 확정된 입력의 SHA-256이며 같은 세대의 실패·중단도 다시 수집하지 않는다. 추적 시도는 최초 세대를 고정하고 실행의 수정 라운드만 새 세대를 사용할 수 있다. 추적 전용 수집 경계는 저장 원본 지문과 세대의 일치 및 통합 완료를 확인하며, 완료 판정은 기존 추적 이력과 공유한다. `assembly.py`는 원본 바이트 지문·소유 정체성에 결합한 정규화 자료와 `notes.json`의 주장별 근거 참조를 조립한다. 작성자가 명령 종료 코드나 검증 판정을 대체할 수 없으며, 세션 기록의 실행 대상 귀속을 자동으로 인정하지 않는다. 소스 발췌는 80줄·8 KiB, 합계 1 MiB, 파생 자료는 8 MiB로 제한한다. 원본이 읽는 도중 바뀌면 `stale`, 설명 누락·잘못된 연결·수집 누락은 부분 자료로 남긴다. `html.py`는 이 자료를 네트워크 자원이 없는 HTML 문자열로 표시하며 한국어 외 고정 문구는 영어로 대체한다. 원문 설명의 언어는 유지한다. 공통 자료 검사는 `tests/report/test_implementation_comparison.py`, 표시 검사는 `tests/report/test_implementation_comparison_html.py`가 소유한다.
31
+
32
+ `inputs.py`는 같은 실행 매니페스트 바이트에서 소유자·비교 위치·선택 원본을 해소한다. 원본 보고서와 매니페스트는 각각 16 MiB, 정규화 전달 자료는 공백 없는 ASCII JSON으로 1 MiB까지 읽는다. 검증 행은 변환 전에 개수를 제한하며, 큰 원본의 설명·행을 생략하면 그 사유를 부분 자료에 남긴다. 실행 원본은 해당 `RunRef.reports_dir`의 직속 파일만 허용한다. 과거 매니페스트에 카테고리 순번이 없으면 선언된 원본 파일명에서 보고서 순번을 읽으며 실행 순번으로 대체하지 않는다. 기존 보고서의 명령은 세션 기록으로 표시하고 근거 출처나 종료 대상 귀속을 자동 승격하지 않는다. 추적 기록의 단계·검사 종류·기록 시각·실패 원인도 유지하며, RED와 기존 사용자 동작의 결함 재현을 구분한다.
33
+
34
+ `publication.py`는 소유 범위의 `.report-publication.lock` 안에서 최신 원본을 읽고 판 번호를 결정한다. 같은 입력의 정상 판은 생성 시각까지 재사용한다. 추적 시도의 판은 비교 디렉터리의 `report-NNN.data.json`·`.html`, 실행의 판은 선택 원본과 나란한 `implementation-comparison-<report-seq>-rNNN.data.json`·`.html`이다. 실행 순번과 보고서 순번을 혼용하지 않는다. 새 자료·HTML을 검사하고 모든 입력 지문을 다시 대조한 뒤 `current.json`을 마지막에 교체한다. 실패하면 이전 포인터를 보존하고, 이미 저장된 고아 판의 번호도 재사용하지 않는다. 자료·HTML은 각각 8 MiB, 현재 포인터는 16 MiB로 제한한다. 상태 조회는 포인터·산출물·소비 입력을 검사하되 게시 잠금 파일을 만들지 않는다. 이 경계는 `tests/report/test_comparison_publication.py`가 검사한다.
35
+
36
+ 기존 구현 HTML의 선택적 링크 갱신은 같은 게시 잠금과 기존 HTML 지문을 대조한다. 최초 HTML 읽기는 8 MiB, 교체 직전 원본과 HTML의 재읽기는 각각 16 MiB로 제한한다. 독립 비교 판과 기존 HTML 링크는 별도 결과이며 링크 실패가 앞서 게시한 판을 삭제하지 않는다. 공개 `implementation-report render`는 저장 추적 원본 또는 실행 매니페스트를 읽어 같은 게시기를 사용한다. TDD는 통합 성공 저장 뒤 종료 대상을 보존하며 현재 세션이 설명을 쓴 다음 명시적으로 HTML을 생성한다. `status`·`sync`는 종료 대상을 다시 수집하지 않는다. 실행의 `run_integration.py`는 작성자 전달 전에 현재 완료 세대의 종료 대상을 보존하고 합성 자료에 정확한 선택적 설명 경로·공통 안내·실제 검사 기록을 전달한다. 권한 생산자 두 곳은 해당 실행의 보고서 작성자에게 그 파일 하나만 추가하며, 필수 완료 산출물에는 넣지 않는다. 정상 검증 뒤 자동 게시와 기존 HTML 링크 갱신을 각각 반환한다. 완전히 결합된 종료 대상 이후 실제 소스의 변경을 발견하면 자동 게시를 보류하고 이전 포인터를 유지한다. 공개 재생성과 상태 조회는 현재 작업 공간을 요구하지 않는다. 작업 전체는 `task_selection.py`와 `task_assembly.py`가 선택된 단계의 저장 자료를 조립하며 같은 게시기·소유 잠금을 사용한다. 기존 최종 보고서·추적 문서·작업 이력 포인터는 계속 각 원본이 소유한다.
37
+
38
+ 작업 전체 비교의 읽기 전용 기반은 `implementation_comparison/task_selection.py`의 `read_task_comparison_selection`이다. 최신 계획의 숫자 순번·활성 단계, 기존 소비 원장의 순수 상태 투영, 정본 이월의 성공 등급과 계획 재번호 대조를 재사용한다. 선택한 완료 보고서를 실행 매니페스트의 실제 선언과 결합하며 보고서 순번으로 실행 순번을 추측하지 않는다. 결과는 필수 단계·선택된 단계·기존 생명주기·저장된 `phaseOutcome.implementation`·선택 정체성·실제 입력 지문·한계를 포함한다. 반환된 선택 과정의 `complete`는 구현 완료 판정이 아니며 이 API는 완료 기록을 쓰거나 이월을 복구하지 않는다.
39
+
40
+ 파일별 16 MiB·공유 읽기 예산 192 MiB, 경로와 필터 전 원시 항목 10,000개, 확장 전 원장 행과 계획 단계 수의 한도, 선택 JSON 1 MiB를 적용한다. 실제 읽기·한도 오류에서 접두의 단계 집합을 완전한 선택으로 반환하지 않으며, 오류 결과에도 선택 JSON 한도를 적용한다. 파일 지문과 후보·선택 정체성은 분리한다. 뒤의 게시 소비자는 새 후보 파일도 다시 선택해야 하며 잠금·임시 파일을 가짜 입력 지문으로 넣지 않는다. 공통 철회 투영은 `failed` 뒤의 `started`가 과거 `done`을 복원하지 않게 하며 철회 없는 시작과 새 완료는 유지한다. 이 기반은 `tests/report/test_implementation_comparison.py`의 저장 자료·재개방·계획·후보·한도 사례와 `tests/run/test_prepare.py`의 공통 상태 회귀로 검사한다. `task_assembly.py`는 같은 예산을 단계별 원본·보존 내용 검증까지 전달하고 단계별 정체성을 붙인다. 기존 단계 게시 잠금을 추가로 얻지 않는다. 작업 전체 게시 잠금 안에서 선택하며 게시 직전에 새 계획·매니페스트 후보와 실행 시도·검사 선택을 다시 확인한다. 단계 완료 뒤의 자동 갱신과 `--scope task`가 같은 게시기를 사용하며 기존 완료·검증·인계 포인터는 바꾸지 않는다. 통합 증명에는 읽기 전용 Git 조회의 명령별 4 MiB·누적 8 MiB·조립 요청이 공유하는 Git 조회 마감 10초 한도를 적용한다. 이 수치는 초기 한도이며 실행 성능 보장이 아니다. 자료 조립의 공유 읽기 한도와 게시 전 입력·선택 재검사의 한도는 각각 별도 검증 구간이다.
41
+
42
+ 기존 최종 보고서 HTML은 `report_html/render.py`가 같은 디렉터리의 임시 파일에 완성·검사하고 원본 지문을 재확인한 뒤 교체한다. `report_html/validation.py`의 자원·앵커 검사는 기존 검증기와 공유한다. `tests/report/test_finalize.py`가 실제 생성기의 쓰기·검사·원본 변경·교체 실패에서 기존 파일 보존과 오류 전파를 검사한다.
43
+
22
44
  Verification inputs version `3.0` requires `reviewPolicy`: a versioned frozen
23
45
  architecture declaration and source bodies with SHA-256 digests. Preparation
24
46
  captures the coding-preflight pack, project-root `AGENTS.md` and `CLAUDE.md`,
@@ -407,6 +429,34 @@ observation and no applicability or skip disposition per frozen check, so the
407
429
  report neither distinguishes an unconfirmed server target nor checks that every
408
430
  applicable check ran. No automated test covers these rules.
409
431
 
432
+ 비교 보고서의 후속 소비자를 위해 `collect_report_evidence_snapshot`은 기존 근거 행과 함께
433
+ 실제로 읽은 입력의 지문 및 검증자별 호출·시도·세대·최신 검사 실행 선택을 반환한다.
434
+ 기록의 필드와 `recordDigest`는 한 번 읽어 검증한 같은 바이트에서 나온다. 선택적 바이트
435
+ 읽기 함수와 디렉터리 열거 함수를 주입하는 소비자는 읽기·열거 전에 한도를 적용할 수 있다.
436
+ 기존 `collect_report_evidence`의 반환 필드와 기본 선택은 유지한다. 새 검사 디렉터리의
437
+ 생성은 기존 파일 지문에 드러나지 않으므로, 후속 게시자는 지문과 선택 결과를 함께
438
+ 대조해야 한다.
439
+
440
+ `implementation_generation_evidence.read_settled_implementation_generation`은 기존 실행 정체성·예약·
441
+ 완료 반환 봉인·검증 세대 결합을 재사용해 현재 구현 세대를 읽는다. 최신 구현자나 검증자의
442
+ 시도가 미완료이거나 실패했거나 같은 세대를 입증하지 못하면 과거 완료 세대를 선택하지
443
+ 않고 제한을 반환한다. 명령의 종료 코드나 검증자의 FAIL 판정에 PASS를 요구하는 새
444
+ 승인 조건을 추가하지 않는다. 고정 입력 3.0의 실행에도 적용하고, 4.0에서는 기존 설계
445
+ 기준 결합을 재사용한다. 같은 구현자 호출의 재시도와 세대 사이에 명시적 시도 결합이
446
+ 없으면 그 순서를 입증할 수 없다고 표시한다. `implementation_comparison/run_evidence.py`가
447
+ 이 권위와 실제 명령 기록의 같은 바이트를 재사용해 보존 대상 귀속을 판정한다. 작성자가
448
+ 기입한 검증 상태나 출처는 귀속 근거가 아니다. 게시·재사용·상태·링크 확인은 알려진 파일
449
+ 지문과 현재 세대·시도·최신 검사 선택을 함께 다시 대조한다. 새 검사 디렉터리만 생겨도
450
+ 이전 판을 현재로 반환하지 않는다. 관련 연결은 `tests/verification/test_report_execution_evidence.py`가 검사한다.
451
+
452
+ 두 읽기 경로는 `qa_procedures.read_fingerprinted_artifact`의 지문 기록과 재읽기 판정을
453
+ 공유한다. 처음 읽을 수 없는 입력은 지문에 `None`을 남기며, 앞서 읽은 입력의 재읽기가
454
+ 실패하거나 내용이 바뀌면 앞선 지문을 유지하고 거부한다. 실제 읽기 실패는 원인을 연결해
455
+ 전달한다. 전체 기록·출력 객체의 보관은 새 스냅샷 호출이 명시적으로 요청할 때만
456
+ 수행하고, 기존 수집기는 요약과 같은 바이트 지문을 만든 뒤 검사별 원본을 해제한다.
457
+ 이 경계는 기존 `tests/verification/test_report_execution_evidence.py`와
458
+ `tests/verification/test_design_review.py`가 실제 재읽기·객체 수명·별칭·한도를 검사한다.
459
+
410
460
  `okstra model-io run-input --run-manifest <path>` projects the recorded
411
461
  `verificationInputsPath` and `verificationInputsDigest` as fixed scalar lines.
412
462
  Absent or non-scalar values display `-`, including older manifests without a
package/docs/cli.md CHANGED
@@ -66,17 +66,30 @@ time; `createdAt` includes its time-zone offset. The result is
66
66
  `{path, currentStep, steps, ids, nextAction, failStreak, commitPoint}`.
67
67
  `nextAction` is `write`, `review`, `ask-user-decision`, `run-tests` or `done`.
68
68
 
69
- `reviewers` works on the current review step. It returns the operation, duty,
70
- `binding` text and reviewer `slots`. `analysis-review` and `spec-review` use the
71
- `trace-scope-review` operation (`scope-critic`); `interface-review` uses
72
- `trace-interface-review` (`interface-reviewer`). Slots come from the registered
73
- model pool, ordered so models outside the host's own provider come first;
74
- `--count` defaults to 1, must be a positive integer, and is capped by the
75
- operation contract (`INVALID_ARGUMENT` otherwise). `independence` is
76
- `cross-provider` when a slot's provider differs from the host's own provider,
77
- otherwise `same-provider`. The binding names the trace path, step, next round,
78
- the SHA-256 digest of the reviewed writing section's raw text (fenced blocks
79
- included) and the host runtime.
69
+ 상태 응답의 `comparison`에는 기존 기준 필드와 함께 `target`·`report` 조회 결과가 붙는다. 대상의 `targetRef`가 `null`이면 수집된 종료 소스가 없다는 뜻이며, 비교 판이 없으면 `report.status`는 `not-generated`다. 정상 판의 `current`, 소비 입력이나 산출물이 달라진 `stale`, 읽기 실패의 `failed`를 구현 완료 상태와 구분한다. 보고서 조회만 실패해도 정상 기준·대상 참조는 유지한다. 상태 조회는 테스트·상태 전이·소스 재수집·HTML 생성을 수행하지 않는다. 통합 성공을 저장한 `advance`는 이력 동기화 전에 종료 대상을 한 번 보존하고 `comparison.renderCommand`를 반환한다. 이 응답에서 HTML을 즉시 생성하지 않는다. `sync`는 종료 대상을 다시 수집하지 않는다. 내부 JSON 경계와 상태 검사는 `tests/report/test_implementation_comparison.py`, 기존 추적 시도의 기준 보존 검사는 `tests-js/trace.test.mjs`가 확인한다.
70
+
71
+ 비교 HTML은 저장된 원본과 종료 대상으로 별도 생성한다. 현재 세션은 완료 응답의 실제 `notesPath`에 공통 안내(`templates/reports/implementation-comparison-notes.md`)의 설명을 작성한 뒤 반환된 명령을 실행한다. `notesPath`가 `null`이면 경로를 계산하지 않고 `trace status --path`로 재조회한다. 재조회 후에도 경로가 없으면 구현 완료·이력 동기화 결과와 비교 생성 불가를 따로 안내한다. 경로는 있지만 기준·종료 참조가 없는 경우에는 해당 제한을 남긴 부분 보고서를 만들 수 있다.
72
+
73
+ ```bash
74
+ okstra implementation-report render --trace <file>
75
+ okstra implementation-report render --run-manifest <file> [--scope task] [--project-root <dir>]
76
+ ```
77
+
78
+ 추적 원본과 실행 매니페스트 중 하나를 선택한다. 명령은 `published`·`reused`에서 종료 코드 0, `stale`·`failed`와 입력 오류에서 1을 반환한다. 정상 응답의 `dataPath`·`htmlPath`는 프로젝트 기준 경로이며, `reportStatus`의 `ready`는 읽을 수 있다는 뜻으로 모든 동작의 실행 검증을 뜻하지 않는다. 저장 원본으로 재생성하므로 구현·검사·이력 동기화를 반복하지 않는다. 비교 선언이 있는 구현 실행은 작성자 전달 전에 종료 대상을 보존하고, 정상 검증을 마친 `report-finalize`에서 비교 게시와 기존 HTML 링크 갱신을 각각 반환한다. 작성자는 합성 자료의 실제 실행 근거와 공통 안내를 사용해 선택적 설명을 작성한다. 보존 뒤 소스 변경을 발견하면 자동 게시를 보류한다. 비교·링크 오류는 기존 완료 결과와 분리한다.
79
+
80
+ `--scope task`는 선택한 구현 실행이 속한 작업을 해소해 최신 계획과 유효한 완료·이월 기록으로 전체 보고서를 만든다. 단계별 설명·실행 근거의 정체성을 유지하며, 같은 파일의 변경이나 효과를 합산하지 않는다. 단일 누적 종료 대상은 선택된 모든 단계의 커밋을 포함하는 Git 관계와 보존 소스·인덱스의 일치가 입증될 때만 제공한다. 병렬 분기나 미커밋 상태의 포함 여부를 입증하지 못하면 단계별 전후 상태와 관찰 경로의 합집합을 표시한다. 보고서 생성은 읽기 전용 Git 조회만 허용하고 병합·재배치·검사·모델 호출을 수행하지 않는다. 실제 `stage-done`은 완료 기록을 쓴 뒤 같은 전체 게시기를 호출하고 선택적 `comparison` 결과를 반환한다. 비교 실패는 완료·이월을 취소하지 않으며 같은 `--scope task` 명령으로 보고서만 다시 생성한다.
81
+
82
+ 기준 없는 옛 기록은 추적 문서의 기록된 `baseCommit` 또는 동결 입력 4.0의 `reviewBase`를 읽을 수 있을 때 커밋 내용을 사후 복원한다. 당시 작업 파일·인덱스·미추적 상태는 알 수 없으므로 기존 기준으로 승격하지 않는다. 기존 업무 설명은 선택 보고서 해시와 프로젝트·HEAD·전체 파일 집합·내용·인덱스가 같은 저장 자료만 재사용하고 기존 문서 출처로 표시한다. 다른 프로젝트를 검색하거나 설명을 다시 생성하지 않는다.
83
+
84
+ `new`는 프로젝트 루트가 Git 저장소 안에 있고 `.okstra/` 밖에 커밋하지 않은 변경이나 추적하지 않는 파일이 없을 때, 그때의 `HEAD`를 `baseCommit`으로 기록한다. 시작 전에 있던 변경이 이 작업의 줄로 세어지지 않게 하려는 조건이다. `implementation`이 끝난 뒤의 `advance`와 `status` 결과에는 `lineCounts`가 붙는다. 값은 `baseCommit` 이후 프로젝트 루트 아래에서 추가된 줄 수이며, 커밋하지 않은 변경과 추적하지 않는 파일을 포함하고 `.okstra/` 아래 파일은 뺀다. 이름만 바꾼 파일은 바뀐 줄만 센다. `tests-red` 표의 `Path`이거나 일반 테스트 경로 규칙에 맞는 파일은 테스트 줄, 나머지는 소스 줄로 센다. 규칙은 `tests/`·`test/`·`spec/`·`specs/`·`__tests__/`·`testing/`·`testdata/`·`fixtures/`·`e2e/` 디렉터리, `*.test.*`·`*.spec.*`·`*.cy.*`·`*_test.*`·`test_*.py`·`conftest.py`·`tests.py`·`test-utils.*` 파일이다. 결과는 `{available: true, baseCommit, source, test, ratio, threshold: 2, exceeded}`이고, `exceeded`는 테스트 줄이 소스 줄의 2배를 넘을 때 `true`다. 소스 줄이 0이면 `ratio`는 `null`이다. 경고일 뿐 단계 진행을 막지 않는다. 기준 커밋이 없거나 Git이 실패하거나 상한을 넘으면 `{available: false, reason}`이다. 상한은 다음과 같다: Git 출력 4 MiB·30초, 추적하지 않는 파일 2,000개·합계 32 MiB. 4 MiB를 넘거나 NUL 바이트가 있는 파일은 세지 않는다. 진행 중에 병합하거나 리베이스하면 다른 작업의 줄도 함께 세어진다.
85
+
86
+ `reviewers`는 현재 검토 단계에 대해 동작하며, 운영(operation)·직무(duty)·`binding` 문구·검토자 `slots`를 돌려준다. 단계별 운영은 다음과 같다.
87
+
88
+ - `analysis-review`, `spec-review`: `trace-scope-review`(`scope-critic`)
89
+ - `interface-review`: `trace-interface-review`(`interface-reviewer`)
90
+ - `tests-review`: `trace-tests-review`(`test-reviewer`)
91
+
92
+ 슬롯은 등록된 모델 풀에서 고르며, 호스트와 다른 공급자의 모델이 앞에 온다. `--count`는 기본값 1의 양의 정수이고 운영 계약의 상한을 넘으면 `INVALID_ARGUMENT`다. 슬롯 공급자가 호스트 공급자와 다르면 `independence`는 `cross-provider`, 같으면 `same-provider`다. binding에는 trace 경로, 단계, 다음 회차, 검토 대상 절 원문(펜스 블록 포함)의 SHA-256 다이제스트, 호스트 런타임이 들어간다. `tests-review`의 검토 대상 절은 `tests-red`이며, 근거 블록도 다이제스트에 포함된다.
80
93
 
81
94
  `advance` accepts only the current step. A review passes in one of two ways:
82
95
 
@@ -92,9 +105,7 @@ included) and the host runtime.
92
105
  - `--verdict pass --approve "<user quote>"`, the user-approval mode, which records
93
106
  the quote under `approval`.
94
107
 
95
- `--verdict fail` alone always fails the review. Failed reviews return to their
96
- writing step and increment their failure streak. Three consecutive failures ask
97
- the agent to obtain a user decision.
108
+ `--verdict fail`만 주면 검토는 항상 불합격이다. 불합격한 검토는 작성 단계로 돌아가고 연속 실패 횟수를 1 늘린다. 세 번 연속 실패하면 에이전트가 사용자 결정을 받아야 한다. 검토 합격은 검토한 절을 다시 읽는다. `analysis`·`interface-design`은 ID와 `Key`/`Value` 표를 다시 기록하고, `tests-review` 합격은 사용 사례마다 통합 테스트 행이 있는지 다시 검사한다. `tests-review`가 불합격하면 `tests-red`로 돌아가며, 새 RED 근거로 `tests-red`를 다시 진행하면 이전 근거 블록을 새 블록으로 교체한다. 근거를 기록한 적 없는 단계에 근거 표지가 있으면 `TRACE_MALFORMED`로 거부한다.
98
109
 
99
110
  Writing sections use Markdown tables with fixed English headers:
100
111
 
@@ -113,6 +124,8 @@ typecheck GREEN; `tests-red` requires unit and integration RED, each classified
113
124
  remain RED; `integration` requires integration GREEN. Other failure causes are
114
125
  `assertion`, `compile-error`, `import-error` and `other`.
115
126
 
127
+ `tests-review` 단계가 생기기 전에 저장한 시도도 읽는다. 상태에 `tests-review` 기록이 없으면, `tests-red`를 아직 지나지 않은 시도는 `pending`으로, 이미 지난 시도는 검토 없이 `done`(`round: 0`)으로 채운다. 이 기록은 다음 `advance` 때 저장된다.
128
+
116
129
  The command updates JSON frontmatter and appends evidence blocks atomically.
117
130
  The body belongs to the agent. `commitPoint` is set after `interface-code`,
118
131
  `implementation` and `integration`; the command does not commit.
@@ -141,7 +154,8 @@ Without binding options, existing standalone creation is unchanged.
141
154
 
142
155
  A successful linked operation also returns `taskKey`, `task` and `taskSync`.
143
156
  Trace publication precedes task projection. `TASK_SYNC_FAILED` includes
144
- `traceSaved`, `path`, `taskKey` and a retry command. Query `status`, then use
157
+ `traceSaved`, `path`, `taskKey` and a retry command.
158
+ 통합 성공 뒤 동기화 실패 응답에도 `comparison`을 보존한다. 비교 생성 성공이 `TASK_SYNC_FAILED`를 성공으로 바꾸지 않는다. Query `status`, then use
145
159
  `sync` to retry projection without advancing an already saved step. Read-only
146
160
  status returns `taskSync: "pending"` when acknowledgment is unavailable. History
147
161
  retains prior attempts; completion uses direct-work provenance with
@@ -243,6 +257,8 @@ For a stage, pass its identified `--run-manifest <path>` to reuse the author's
243
257
  frozen policy. A missing author-policy reference is unverified policy alignment;
244
258
  do not infer a latest run or claim that independently captured policies match.
245
259
 
260
+ Python이 아닌 코드의 함수 경계를 읽지 못하면 `census`는 `Unresolved function boundaries`에 그 파일을 적고 종료 코드 1을 낸다. `--function-inventory <path>`를 붙여 다시 실행하면, 파일이 없을 때 해당 파일을 `null`로 둔 양식을 쓰고 종료 코드 2를 낸다. 각 항목을 frozen head 기준 `functions: [{start, end, name}]`와 비어 있지 않은 `rationale`로 채운 뒤 다시 실행하면, 변경 줄이 걸친 함수마다 semantic 셀이 생긴다. 양식의 `base`·`head`에는 census에 넘긴 ref를 해석한 커밋이 기록되므로, 새 커밋이 생기면 양식을 다시 만들어야 한다. 범위 검사는 목록이 빠짐없는지 증명하지 않는다.
261
+
246
262
  `okstra code-review assign --census <review-id>.census.md`는 프로젝트 `.okstra/` 아래의
247
263
  전체 census를 축별 배정 census로 나눈다. 셀이 있는 축마다 같은 디렉터리에
248
264
  `<review-id>.<axis>.census.md`를 쓰고, `Axis`·`Cells`·`Census` 줄을 축 순서
@@ -34,6 +34,10 @@ and compact attempt history without a verification run. Regression owners are
34
34
  `tests-js/trace.test.mjs`; run `npm run test:js`
35
35
  separately from `npm run check`.
36
36
 
37
+ 구현 전후 자료의 공통 소유자는 `scripts/okstra_ctl/implementation_comparison/`이다. `source.py`가 읽기 한도를 적용한 소스·Git 수집을, `baseline.py`가 소유 정체성·경로 선택·최초 실패·불변 보존과 상태 조회를 담당한다. `target.py`는 종료 세대의 불변 수집·조회와 저장 완료가 확인된 추적 대상 수집, `assembly.py`는 원본 지문과 주장별 근거 연결, `html.py`는 표시만 소유한다. `model.py`는 공통 입력 타입과 한도, `inputs.py`는 원본 지문 검증과 기존 실행 원본의 선택·정규화, `publication.py`는 소유 범위 잠금·판 게시·현재 포인터와 상태 조회를 담당한다. `__main__.py`는 한도를 적용한 내부 JSON 전달 경계이며 Node의 `runPythonModule`은 선택적 표준 입력을 전달한다. `preparation.py`는 최초 전체 매니페스트의 비교 선언과 작업 기준의 최초 수집 정책을 소유한다. `run.py`는 실제 단계 작업 공간을 확정한 준비 경로에 연결하며, `src/commands/trace/comparison.mts`는 추적 시도 생성·상태 조회·완료 대상 수집의 얇은 전달과 기존 추적 자료의 정규화를 담당한다. `trace/document.mts`는 기존 추적 읽기를 두 명령에서 공유하며 `src/commands/implementation-report/implementation-report.mts`는 저장 자료의 공개 재생성 진입점이다. 공통 설명 안내는 `templates/reports/implementation-comparison-notes.md`, TDD의 완료 안내 순서는 `skills/okstra-tdd/SKILL.md`가 소유한다. `run_evidence.py`는 완료 세대·실제 검사 기록·보존 대상 결합과 최신 선택 재검사를, `run_integration.py`는 작성 전 대상 보존·합성 자료·정확한 설명 권한·선택적 완료 게시를 연결한다. `task_assembly.py`가 작업 전체를 조립하고 `commit_source.py`가 기록된 커밋만 제한 조회하며 `business_reuse.py`가 범위·해시가 같은 기존 설명을 읽는다. 새 입력을 재선택한 같은 게시기는 작업 전체 범위에도 사용하며 기존 보고서와 추적 frontmatter는 각 원본이 계속 소유한다. 기존 HTML의 원본 보존 교체와 공유 검사는 `report_html/render.py`·`validation.py`가 담당한다.
38
+
39
+ `implementation_comparison/task_selection.py`는 전체 작업 비교가 소비할 최신 유효 단계의 읽기 전용 선택 기반이다. 기존 계획 해석·소비 상태·이월 성공·재번호 대조를 호출하고 실제 보고서와 실행 명세의 정체성을 결합한다. `stage_map.parse_stage_map_data`, `plan_run_root.list_implementation_planning_reports`의 선택적 열거, `implementation_outcome.carry_is_pass_grade`, `stage_ledger.renumbering_divergence`가 기존 판정 본문을 공유한다. 원장 복구나 완료 쓰기는 호출하지 않으며 `task_assembly.py`는 단계별 근거 정체성을 유지하고 입증된 통합 대상만 누적 비교한다. `stage_done.py`의 선택적 부가 처리와 공개 `--scope task`가 같은 조립·게시 기능을 소비한다.
40
+
37
41
  `okstra` is a host-aware, multi-provider cross-verification runtime distributed as the npm package `okstra`. It is not a one-shot reviewer; it runs one neutral lifecycle core through Claude Code, Codex, or an explicit external adapter around a stable task key.
38
42
 
39
43
  Current baseline:
@@ -311,7 +315,8 @@ Important modules:
311
315
  | `pr_template.py` | PR body template resolution for release-handoff |
312
316
  | `report_views.py`, `render_final_report.py`, `final_report_schema.py` | Final-report render layer: from the assembled `data.json` (schema v2 or v3) it independently produces the full reading copy Markdown and human HTML; both schema versions render the reading copy from `final-report-v2.template.md` (schema v3 reuses the v2 template for read/render compatibility) |
313
317
  | `report_inputs.py` | Report contract 3.0 role-input path + single-owner registry — resolves each owning role's input artifact from the manifest (`narrative` → report-writer, `approval-decisions` → lead, `agent-activity` → activity ledger, `execution-status` → team-state, `convergence`; for an implementation or final-verification run marked `verificationEvidenceVersion`, `execution-evidence` → verification-execution, the run's verification directory) |
314
- | `report_execution_evidence.py` | Derives each verifier's execution evidence references and final-verification command rows from the verification execution records, and compares a report's references with them for the phase validators |
318
+ | `report_execution_evidence.py` | 검증 실행 기록에서 검증자별 근거와 최종 검증 명령 행을 조립하고 보고서의 근거를 대조한다. 비교 소비자는 같은 해석 바이트의 지문과 호출·시도·세대·최신 검사 선택을 함께 받을 수 있다. |
319
+ | `implementation_generation_evidence.py` | 실행 정체성·예약·반환 봉인과 고정 검증 입력을 재사용해 현재 완료된 구현 세대와 소비 입력 지문을 읽는다. 설계 검토의 승인 판정과 분리하며, 입증하지 못한 현재 시도 대신 과거 완료 세대를 선택하지 않는다. |
315
320
  | `report_assembly.py` | Validates the role-owned report inputs and publishes the contract 3.0 record once (assembled in a temp file, then atomically promoted); a bad input aborts with owner / artifact path / field path / reason and preserves the existing `data.json` |
316
321
  | `report_projections.py` | Pure projections turning role-owned execution inputs (agent activity, execution status, convergence, design, token usage) into canonical final-report fragments |
317
322
  | `report_narrative.py` | 계약 3.0의 작성자 소유 입력을 manifest의 `reportAuthoringFormat`에 따라 읽고 쓴다. 새 `json-v1`은 표준 JSON 객체와 Markdown 설명 문자열을 사용하며, 기존 `markdown-v1` 줄 문법도 유지한다. 중첩된 기계 소유 필드까지 소유권을 검사한다 |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "okstra",
3
- "version": "0.234.0",
3
+ "version": "0.235.0",
4
4
  "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
5
5
  "license": "MIT",
6
6
  "author": "devonshin",
@@ -1,5 +1,5 @@
1
1
  {
2
- "package": "0.234.0",
3
- "builtAt": "2026-11-15T13:56:18.119Z",
2
+ "package": "0.235.0",
3
+ "builtAt": "2026-11-17T05:54:24.676Z",
4
4
  "repoRoot": "/home/runner/work/okstra/okstra"
5
5
  }
@@ -0,0 +1,6 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "id": "trace-tests-review",
4
+ "dutyId": "test-reviewer",
5
+ "count": 3
6
+ }
@@ -0,0 +1,32 @@
1
+ {
2
+ "schemaVersion": "1.0",
3
+ "id": "test-reviewer",
4
+ "roleId": "verifier",
5
+ "responsibilities": [
6
+ "Independently judge whether the RED tests written for an approved interface design verify every use case through the smallest set of non-overlapping assertions, before any implementation is written."
7
+ ],
8
+ "requiredConduct": [
9
+ "Map every use case to its integration test and every unit test to the rule it asserts. Read the test files, the interface code they call and the project's existing test helpers and conventions. For each assertion, check which test layer owns it: unit tests own a rule's variants (boundaries, limits, error kinds), and an integration test checks one representative wired case of its use case."
10
+ ],
11
+ "decisionPrinciples": [
12
+ "Prefer the fewest tests that still distinguish every required outcome. Distinguish an unverified use case or outcome, an assertion repeated across unit and integration layers, test setup copied instead of shared, a test that mocks the unit under test and a RED result caused by something other than missing implementation from a stylistic preference."
13
+ ],
14
+ "authorityAndBoundaries": [
15
+ "Review the assigned tests against the approved use cases, interface design and existing code without rewriting them. Do not add requirements, change the interface or write implementation code."
16
+ ],
17
+ "evidenceStandards": [
18
+ "Each finding names the use case or rule affected, the test at fault as path:line, the overlapping or missing assertion, and its consequence for later maintenance or for catching a defect. A clean verdict states which use cases and rules were mapped to which tests."
19
+ ],
20
+ "collaborationContract": [
21
+ "Return findings and the verdict to the lead with their evidence. Do not negotiate the tests with their author or decide whether the use cases themselves should change."
22
+ ],
23
+ "completionCriteria": [
24
+ "Every use case has been traced to its integration test, every unit test to the rule it asserts, overlapping assertions and copied setup have been checked, and missing coverage, defects and clean checks are all recorded."
25
+ ],
26
+ "prohibitions": [
27
+ "Do not pass tests that leave a use case or required outcome unverified, or that repeat a unit-tested rule variant in an integration test, and do not turn naming or style preferences into defects."
28
+ ],
29
+ "blockedStateReporting": [
30
+ "Identify the missing use-case table, test file or source context, the mapping that cannot be completed, the attempts made and the use cases or rules left unverified."
31
+ ]
32
+ }
@@ -4,7 +4,7 @@
4
4
 
5
5
  Phase 6 gives the report writer all settled analysis, convergence, task, and planning context required for synthesis. Read access supplies context; it does not grant write authority over another owner's file.
6
6
 
7
- The report writer writes only the report authoring input, its pointer record, and its audit sidecar. The run manifest's `reportAuthoringFormat` selects standard JSON for `json-v1`; an absent field selects the existing `markdown-v1` line grammar. `reportNarrativePath` retains its name and identifies that exact input path. Never infer the format from its suffix or change an existing run's format. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
7
+ The report writer writes the report authoring input, its pointer record, and its audit sidecar. When the synthesis packet explicitly supplies `authoringContract.implementationComparison.notesPath`, it may also write comparison notes to that exact path using the supplied notes guide and identities. Missing comparison notes do not prevent completion of the original report. The run manifest's `reportAuthoringFormat` selects standard JSON for `json-v1`; an absent field selects the existing `markdown-v1` line grammar. `reportNarrativePath` retains its name and identifies that exact input path. Never infer the format from its suffix or change an existing run's format. It must not write or patch `final-report-*.data.json`, the approval decision ledger, activity ledger, team state, convergence state, or design-preparation input.
8
8
 
9
9
  The narrative owns judgments, plan body, summaries, user explanation, recommended steps, and follow-up descriptions. It never owns `designPreparation`, `designSurfaceCoverage`, `executionStatus`, `executionRoles`, `tokenUsage`, `crossVerification`, `approvalContext`, `clarificationItems`, `agentActivity`, or `planBodyVerification`. It must not pre-fill a future round, future gate result, activity identifier, usage value, or resolution.
10
10
 
@@ -15,6 +15,7 @@ Report assembly reads the role-owned inputs, validates them, derives links and s
15
15
  | Input | Owner | Write boundary |
16
16
  |---|---|---|
17
17
  | report authoring input in the declared format | report-writer | `reportNarrativePath` |
18
+ | optional implementation comparison notes | report-writer | exact `authoringContract.implementationComparison.notesPath` supplied by the synthesis packet |
18
19
  | approval decision ledger | lead | `approvalDecisionsPath` through `okstra approval-decision` |
19
20
  | activity ledger | activity recorder | `leadEventsPath` through `okstra agent-activity append` |
20
21
  | team state and usage | runtime/accounting adapter | `teamStatePath` |
@@ -58,6 +59,17 @@ This is enforced by
58
59
  `report_synthesis_packet.build_report_synthesis_packet()`, and
59
60
  `report_assembly.assemble_report()`.
60
61
 
62
+ For an implementation run with a comparison declaration, initial materialization
63
+ preserves the current completed verification generation before dispatch. The
64
+ packet supplies the original baseline and target references, optional notes path,
65
+ common notes guide, actual execution records, and capture limitations. Reuse the
66
+ implementation explanation already in the packet to explain the triggering
67
+ condition, previous handling, changed processing, resulting behavior, and impact.
68
+ Reference only supplied record identifiers and known preserved source locations;
69
+ mark missing or unmeasured support as a limitation. Do not copy authored origins,
70
+ target attribution, hashes, or command results into notes. Corrective authoring
71
+ reads the same saved target rather than capturing the working source again.
72
+
61
73
  Materialize the duty prompt with `okstra agent-prompt materialize --audience report-writer ...`. `--assignment-ref` is `initial/report-writer` — the run manifest declares the report writer under the `initial` phase, so `report-writer/report-writer` is refused. `--result` is the narrative path the run manifest's `reportNarrativePath` names (report contract 3.0; the `expectedReportRecordPath` data.json under 2.0) and `--audit-source` is the roster's worker result (`team-state` `workers[].resultPath` for `report-writer`). The materializer refuses any other value: report assembly reads the narrative from the manifest path and nowhere else, and `okstra team await` records the roster row completed only when the roster's file exists. A corrective dispatch (fix, self-fix, verdict, citations, supersession) reuses both paths and changes only the prompt path and the invocation ID. **Enforced:** `_validate_report_writer_paths` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`. The materializer also writes the report synthesis packet next to the narrative and puts `- Report synthesis packet: <path>` as the first line of the prompt's `## Inputs` section — opening the section when the instruction has none, or inserting under the instruction's own `## Inputs` heading when it has one. The instruction therefore does not enumerate raw source paths; a missing or unreadable packet source is refused before dispatch with its owner (`report synthesis packet contract defects`). **Enforced:** `_report_writer_input_lines` in `scripts/okstra_ctl/agent/prompt_cli/materialize.py`. The prompt starts with these anchors in order:
62
74
 
63
75
  1. `**Project Root:**`