okstra 0.229.0 → 0.231.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 (150) hide show
  1. package/README.md +1 -5
  2. package/dist/cli-registry.mjs +0 -18
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/lifecycle/doctor.mjs +0 -15
  5. package/dist/commands/lifecycle/doctor.mjs.map +1 -1
  6. package/dist/lib/skill-catalog.mjs +4 -4
  7. package/dist/lib/skill-catalog.mjs.map +1 -1
  8. package/docs/architecture/storage-model.md +168 -18
  9. package/docs/architecture.md +15 -14
  10. package/docs/coding-rules.md +15 -0
  11. package/docs/contributor-change-matrix.md +5 -5
  12. package/docs/project-structure-overview.md +13 -19
  13. package/package.json +2 -3
  14. package/runtime/BUILD.json +2 -2
  15. package/runtime/bin/lib/okstra/interactive.sh +2 -1
  16. package/runtime/prompts/coding-preflight/clean-code.md +8 -0
  17. package/runtime/prompts/coding-preflight/overview.md +1 -0
  18. package/runtime/prompts/launch.template.md +7 -5
  19. package/runtime/prompts/lead/convergence.md +4 -4
  20. package/runtime/prompts/lead/okstra-lead-contract.md +19 -18
  21. package/runtime/prompts/lead/phase-routing.md +1 -1
  22. package/runtime/prompts/lead/report-writer.md +3 -3
  23. package/runtime/prompts/lead/team-contract.md +3 -3
  24. package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -0
  25. package/runtime/python/okstra_ctl/agent/invocation.py +190 -9
  26. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +31 -1
  27. package/runtime/python/okstra_ctl/blocking_checks.py +10 -0
  28. package/runtime/python/okstra_ctl/cmux.py +4 -2
  29. package/runtime/python/okstra_ctl/code_review_census.py +194 -0
  30. package/runtime/python/okstra_ctl/code_review_coverage.py +3 -1
  31. package/runtime/python/okstra_ctl/code_review_scope.py +9 -6
  32. package/runtime/python/okstra_ctl/code_review_target.py +38 -2
  33. package/runtime/python/okstra_ctl/conformance.py +30 -0
  34. package/runtime/python/okstra_ctl/conformance_evidence.py +316 -0
  35. package/runtime/python/okstra_ctl/correction_round.py +19 -13
  36. package/runtime/python/okstra_ctl/dispatch_core.py +1 -1
  37. package/runtime/python/okstra_ctl/dispatch_state.py +1 -0
  38. package/runtime/python/okstra_ctl/execution_mutation_audit.py +13 -1
  39. package/runtime/python/okstra_ctl/generated_input.py +21 -0
  40. package/runtime/python/okstra_ctl/ids.py +1 -41
  41. package/runtime/python/okstra_ctl/incremental_carry.py +7 -4
  42. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +30 -0
  43. package/runtime/python/okstra_ctl/interactive_cli.py +5 -0
  44. package/runtime/python/okstra_ctl/locks.py +28 -1
  45. package/runtime/python/okstra_ctl/model_io/renderers.py +7 -0
  46. package/runtime/python/okstra_ctl/paths.py +90 -33
  47. package/runtime/python/okstra_ctl/phases/catalog.py +3 -0
  48. package/runtime/python/okstra_ctl/phases/change_impact_analysis/spec.md +2 -2
  49. package/runtime/python/okstra_ctl/phases/discussion/spec.md +63 -63
  50. package/runtime/python/okstra_ctl/phases/discussion/wizard.py +2 -11
  51. package/runtime/python/okstra_ctl/phases/error_analysis/report_assets/error-analysis-input.template.md +1 -1
  52. package/runtime/python/okstra_ctl/phases/error_analysis/spec.md +2 -2
  53. package/runtime/python/okstra_ctl/phases/feature_analysis/spec.md +1 -1
  54. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +5 -4
  55. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification-input.template.md +1 -1
  56. package/runtime/python/okstra_ctl/phases/final_verification/report_assets/final-verification.template.html +8 -0
  57. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +5 -4
  58. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +53 -0
  59. package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +6 -2
  60. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +4 -2
  61. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +1 -1
  62. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +23 -7
  63. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation-input.template.md +1 -1
  64. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +1 -1
  65. package/runtime/python/okstra_ctl/phases/implementation/spec.md +6 -4
  66. package/runtime/python/okstra_ctl/phases/implementation/validation.py +152 -30
  67. package/runtime/python/okstra_ctl/phases/implementation_option_selection/spec.md +2 -2
  68. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -22
  69. package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -12
  70. package/runtime/python/okstra_ctl/phases/implementation_planning/plan_body.py +14 -0
  71. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +4 -4
  72. package/runtime/python/okstra_ctl/phases/implementation_planning/report_assets/implementation-planning-input.template.md +1 -1
  73. package/runtime/python/okstra_ctl/phases/implementation_planning/spec.md +1 -1
  74. package/runtime/python/okstra_ctl/phases/implementation_planning/wizard.py +11 -4
  75. package/runtime/python/okstra_ctl/phases/project_analysis/spec.md +2 -2
  76. package/runtime/python/okstra_ctl/phases/release_handoff/entry.py +7 -3
  77. package/runtime/python/okstra_ctl/phases/release_handoff/operations.py +4 -5
  78. package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +1 -1
  79. package/runtime/python/okstra_ctl/phases/release_handoff/report_assets/release-handoff-input.template.md +1 -1
  80. package/runtime/python/okstra_ctl/phases/release_handoff/spec.md +4 -4
  81. package/runtime/python/okstra_ctl/phases/technical_verification/spec.md +1 -1
  82. package/runtime/python/okstra_ctl/plan_items.py +28 -0
  83. package/runtime/python/okstra_ctl/process_group.py +26 -3
  84. package/runtime/python/okstra_ctl/qa_commands.py +5 -1
  85. package/runtime/python/okstra_ctl/recap.py +1 -2
  86. package/runtime/python/okstra_ctl/render.py +25 -2
  87. package/runtime/python/okstra_ctl/report_assembly.py +102 -1
  88. package/runtime/python/okstra_ctl/report_execution_evidence.py +220 -0
  89. package/runtime/python/okstra_ctl/report_finalize.py +3 -3
  90. package/runtime/python/okstra_ctl/report_inputs.py +28 -0
  91. package/runtime/python/okstra_ctl/report_narrative.py +12 -3
  92. package/runtime/python/okstra_ctl/report_synthesis_packet.py +5 -0
  93. package/runtime/python/okstra_ctl/run.py +40 -20
  94. package/runtime/python/okstra_ctl/stage_close.py +52 -6
  95. package/runtime/python/okstra_ctl/stage_command_commits.py +143 -0
  96. package/runtime/python/okstra_ctl/stage_fix_carry.py +21 -1
  97. package/runtime/python/okstra_ctl/stage_integrate.py +90 -25
  98. package/runtime/python/okstra_ctl/verification_capture.py +291 -0
  99. package/runtime/python/okstra_ctl/verification_conformance.py +28 -9
  100. package/runtime/python/okstra_ctl/verification_dispatch.py +136 -0
  101. package/runtime/python/okstra_ctl/verification_evidence.py +671 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +34 -16
  103. package/runtime/python/okstra_ctl/verification_input_ref.py +9 -0
  104. package/runtime/python/okstra_ctl/verification_input_types.py +2 -0
  105. package/runtime/python/okstra_ctl/verification_inputs.py +83 -2
  106. package/runtime/python/okstra_ctl/verification_invocation.py +140 -0
  107. package/runtime/python/okstra_ctl/verification_target.py +10 -3
  108. package/runtime/python/okstra_ctl/wizard/engine.py +23 -0
  109. package/runtime/python/okstra_ctl/wizard/registry.py +2 -1
  110. package/runtime/python/okstra_ctl/wizard/render.py +2 -1
  111. package/runtime/python/okstra_ctl/wizard/sources.py +14 -3
  112. package/runtime/python/okstra_ctl/wizard/steps_identity.py +2 -1
  113. package/runtime/python/okstra_ctl/wizard/steps_plan.py +6 -2
  114. package/runtime/python/okstra_ctl/worker_runner.py +1 -1
  115. package/runtime/python/okstra_ctl/worktree/git_ops.py +8 -1
  116. package/runtime/python/okstra_ctl/worktree/rebase.py +5 -2
  117. package/runtime/python/okstra_ctl/worktree_lock_cli.py +70 -17
  118. package/runtime/python/okstra_ctl/worktree_registry.py +4 -0
  119. package/runtime/schemas/final-report-v3.0.schema.json +184 -1
  120. package/runtime/skills/okstra-code-review/SKILL.md +7 -5
  121. package/runtime/skills/okstra-code-review/references/census-rules.md +2 -2
  122. package/runtime/skills/okstra-explain-flow/SKILL.md +1 -1
  123. package/runtime/skills/okstra-run/SKILL.md +11 -7
  124. package/runtime/skills/okstra-schedule-gen/SKILL.md +3 -3
  125. package/runtime/skills/okstra-setup/SKILL.md +2 -3
  126. package/runtime/templates/reports/html/i18n/en.json +7 -0
  127. package/runtime/templates/reports/html/i18n/ko.json +7 -0
  128. package/runtime/validators/validate-run.py +130 -20
  129. package/runtime/validators/validate-workflow.sh +1 -1
  130. package/docs/cli.md +0 -1060
  131. package/docs/container.md +0 -100
  132. package/docs/follow-ups/2026-07-10-final-report-option-3.md +0 -51
  133. package/docs/performance-improvement-plan-v2.md +0 -369
  134. package/runtime/python/okstra_ctl/container.py +0 -702
  135. package/runtime/python/okstra_ctl/rollup.py +0 -241
  136. package/runtime/python/okstra_ctl/usage_report.py +0 -362
  137. package/runtime/skills/okstra-container-build/SKILL.md +0 -139
  138. package/runtime/skills/okstra-inspect/SKILL.md +0 -100
  139. package/runtime/skills/okstra-inspect/facets/cost.md +0 -84
  140. package/runtime/skills/okstra-inspect/facets/error-zip.md +0 -41
  141. package/runtime/skills/okstra-inspect/facets/errors.md +0 -69
  142. package/runtime/skills/okstra-inspect/facets/history.md +0 -86
  143. package/runtime/skills/okstra-inspect/facets/logs.md +0 -89
  144. package/runtime/skills/okstra-inspect/facets/recap.md +0 -167
  145. package/runtime/skills/okstra-inspect/facets/report.md +0 -57
  146. package/runtime/skills/okstra-inspect/facets/run-audit.md +0 -34
  147. package/runtime/skills/okstra-inspect/facets/status.md +0 -163
  148. package/runtime/skills/okstra-inspect/facets/time.md +0 -57
  149. package/runtime/skills/okstra-rollup/SKILL.md +0 -75
  150. package/runtime/skills/okstra-usage/SKILL.md +0 -71
@@ -4,7 +4,7 @@
4
4
 
5
5
  | ID | Guarantee | Enforcement |
6
6
  |---|---|---|
7
- | PA-1 | Project analysis rejects analysis-target and evidence-input arguments before run artifacts are written | `scripts/okstra_ctl/phases/project_analysis/entry.py::validate_project_analysis_inputs`; `tests/run/test_analysis_prepare_inputs.py::test_project_analysis_rejects_target_and_evidence_before_context` |
7
+ | PA-1 | Project analysis rejects analysis-target and evidence-input arguments before run artifacts are written | `scripts/okstra_ctl/phases/project_analysis/entry.py::validate_project_analysis_inputs` |
8
8
  | PA-2 | Feature-index entry points stay inside the declared analysis scope | `scripts/okstra_ctl/phases/project_analysis/validation.py::validate_project_semantics` |
9
9
  | PA-3 | Interface and workflow component references name declared components when components are present | `scripts/okstra_ctl/phases/project_analysis/validation.py::_validate_component_references` |
10
10
  | PA-4 | Source-commit and evidence-input snapshots remain common analysis contracts | `validators/validate_analysis_report.py::validate_analysis_snapshot` |
@@ -30,4 +30,4 @@ The profile supplies no lifecycle destination selection rule. Common `next_phase
30
30
 
31
31
  ## Tests
32
32
 
33
- `tests/test_project_analysis_validation.py` checks declared and unknown interface/workflow component references, empty-component behavior and scoped feature entry points. Existing `tests/contract/test_validate_run_analysis.py` exercises the full common analysis validator, and `tests/run/test_analysis_prepare_inputs.py` checks rejection before preparation writes a run context. Common report rendering tests cover the phase body through the public router.
33
+ `tests/test_project_analysis_validation.py` checks declared and unknown interface/workflow component references, empty-component behavior and scoped feature entry points. Existing the retired Python suite exercises the full common analysis validator, and the retired Python suite previously checked rejection before preparation writes a run context. Common report rendering tests cover the phase body through the public router.
@@ -18,6 +18,12 @@ from .operations import (
18
18
  )
19
19
 
20
20
 
21
+ def handoff_input_path(project_root: Path, task_group: str, task_id: str) -> Path:
22
+ from okstra_ctl.paths import task_dir
23
+
24
+ return task_dir(project_root, task_group, task_id) / "release-handoff-input.md"
25
+
26
+
21
27
  def _collect_handoff_source_report_rows(
22
28
  rows: list, nums: list,
23
29
  ) -> list:
@@ -124,7 +130,6 @@ def materialize_handoff_input(
124
130
  okstra_ctl.handoff 의 SSOT 판정을 prepare 에서도 그대로 강제한다.
125
131
  반환: ctx 에 올릴 {"HANDOFF_STAGES": ...}."""
126
132
  from okstra_ctl.consumers import read_consumers
127
- from okstra_ctl.paths import task_dir
128
133
  from okstra_ctl.render import render_template_with_ctx
129
134
  from okstra_ctl.run_context import _now_task_date
130
135
 
@@ -160,8 +165,7 @@ def materialize_handoff_input(
160
165
  raise PrepareError(
161
166
  f"release-handoff input template missing: {template}.{install_hint}"
162
167
  )
163
- out = (task_dir(project_root, inp.task_group, inp.task_id)
164
- / "release-handoff-input.md")
168
+ out = handoff_input_path(project_root, inp.task_group, inp.task_id)
165
169
  out.parent.mkdir(parents=True, exist_ok=True)
166
170
  render_template_with_ctx(str(template), str(out), {
167
171
  "TASK_KEY": f"{inp.project_id}:{inp.task_group}:{inp.task_id}",
@@ -25,13 +25,12 @@ from okstra_ctl.worktree import (
25
25
  class HandoffConflict(Exception):
26
26
  """선행 stage 들 사이의 merge 충돌 — exit 2, 충돌 경로 동봉."""
27
27
 
28
- def __init__(self, stage: int, branch: str, paths: List[str]):
28
+ def __init__(self, stage: int, branch: str, paths: List[str],
29
+ message: str):
29
30
  self.stage = stage
30
31
  self.branch = branch
31
32
  self.paths = paths
32
- super().__init__(
33
- f"merge conflict while merging stage {stage} ({branch}): "
34
- f"{', '.join(paths)}")
33
+ super().__init__(message)
35
34
 
36
35
 
37
36
  def compute_eligibility(stage_map: List[Dict[str, Any]],
@@ -118,7 +117,7 @@ def _merge_base_for(*, project_root, project_id, task_group, task_id,
118
117
  anchor_base=anchor_base)
119
118
  except MergeBranchConflict as exc:
120
119
  raise HandoffConflict(stage=exc.stage, branch=exc.branch,
121
- paths=exc.paths) from exc
120
+ paths=exc.paths, message=str(exc)) from exc
122
121
  except IntegrateError as exc:
123
122
  raise HandoffError(str(exc)) from exc
124
123
 
@@ -38,7 +38,7 @@
38
38
  This is the release base for the run, not necessarily each PR's base: a stage that sits on another stage of this task targets that stage's branch. The release base MUST contain the task's implementation anchor base. `pr-plan` derives stacking inside this task only; when the task was built on another task's unmerged stage branch, the release base is that predecessor task's stage branch, which prepare names as the recommended base. The chosen base MUST NOT be one of this task's stage branches. If it is, re-ask.
39
39
  2p. **PR plan** (only when the user picked `push + PR`) — run
40
40
  `okstra handoff pr-plan --plan-run-root <...> --approved-plan <...> --project-root <project root> --project-id <id> --task-group <g> --task-id <t> --work-category <c> --stages <HANDOFF_STAGES> --base <chosen-base>`.
41
- It returns one row per stage with `head_branch`, `head_commit`, `base_kind` (`release-base` | `stage` | `merge-base`), `base_branch` and `base_commit`. Exit 2 means the predecessors of a multi-dependency stage conflict with each other: show the `conflicts` paths and stop (route: resolve manually, then retry). Exit 1 means an eligibility or dependency violation — most often a stage whose predecessor is neither in this run nor already PR'd nor merged into the release base: show the error verbatim and re-ask the action selection. When the error says the release base does not contain the implementation anchor, the error names the `--base` that does: show it verbatim and re-ask Q2 with that branch first. **Enforced:** `okstra_ctl.phases.release_handoff.operations._resolve_stage_base` refuses the plan. On success these rows are authoritative for every subsequent step; the lead does not recompute a base by hand.
41
+ It returns one row per stage with `head_branch`, `head_commit`, `base_kind` (`release-base` | `stage` | `merge-base`), `base_branch` and `base_commit`. Exit 2 means the predecessors of a multi-dependency stage conflict with each other: show the `conflicts` paths and the `error` text verbatim and stop. The `error` names the merge-base branch, the anchor it starts from and the predecessor commits to merge in order; route: the user rebuilds that branch by hand as described, then retries, and `pr-plan` reuses it only when it contains the anchor and every listed commit. Exit 1 means an eligibility or dependency violation — most often a stage whose predecessor is neither in this run nor already PR'd nor merged into the release base: show the error verbatim and re-ask the action selection. When the error says the release base does not contain the implementation anchor, the error names the `--base` that does: show it verbatim and re-ask Q2 with that branch first. **Enforced:** `okstra_ctl.phases.release_handoff.operations._resolve_stage_base` refuses the plan. On success these rows are authoritative for every subsequent step; the lead does not recompute a base by hand.
42
42
  A `merge-base` row means `pr-plan` created a branch merging that stage's predecessors. That branch is a PR base only — it is never a PR head — and it MUST be pushed before the PR that targets it.
43
43
  The output also carries `push_plan` and `warnings`. `push_plan` is every branch the PRs sit on, already in push order (each `merge-base` first, then the stage heads in dependency order), with the `commit` it must reach and an `action` of `create` (origin does not have it), `fast-forward` (origin is behind) or `up-to-date` (origin already has that commit — do not push it). GitHub resolves a PR's head and base by name on origin, so this list, not the local branch set, is what makes the stack real. A `warnings` row means `pr-plan` fast-forwarded a local branch to origin because origin was ahead: the commits origin adds are outside what this run verified. Quote every `warnings` row verbatim in Executed Commands and say so in the branch/PR explanation — the user is deciding whether to release commits this run did not verify. `pr-plan` refuses outright when a branch moved outside okstra or diverged from origin, since only a force push could deliver it.
44
44
  2b. **Pre-merge conflict probe** (only when the user picked `push + PR`) — before pushing, for each planned stage in dependency order:
@@ -86,7 +86,7 @@ The user picks ONE release base for the whole run. Each stage's own PR base is t
86
86
 
87
87
  > The lead MUST NOT extend handoff actions into items listed here. If an excluded item should ship in this PR, edit this section before the run starts — do not silently fold it in.
88
88
 
89
- **Enforced (delivery only):** `tests/contract/test_scope_boundary_delivery.py` pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
89
+ **Enforced (delivery only):** the retired Python suite pins that a filled section reaches every analysis worker through `okstra_ctl.analysis_packet` — drop it from `CANONICAL_BRIEF_SECTIONS` and every run's exclusions vanish silently. The exclusions themselves are prose and are **not** machine-checked: only the codebase-scan `out-of-scope` frontmatter is a path list, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` checks that one.
90
90
 
91
91
  ## Questions for Lead Drafting
92
92
 
@@ -9,9 +9,9 @@ Report shapes remain in `schemas/final-report-v2.0.schema.json` and `schemas/fin
9
9
  | ID | Guarantee | Enforcement |
10
10
  |---|---|---|
11
11
  | RH-1 | A PR carries a release-ready stage's recorded commit and dependency base | `scripts/okstra_ctl/phases/release_handoff/operations.py::pr_plan` |
12
- | RH-2 | Diverged origin branches are rejected without force-pushing | `scripts/okstra_ctl/phases/release_handoff/tests/test_handoff_pr_plan.py::test_pr_plan_refuses_a_branch_it_cannot_deliver` |
13
- | RH-3 | An actively reserved stage is not handed to the main worktree | `scripts/okstra_ctl/phases/release_handoff/tests/test_local_checkout_occupancy.py::test_an_active_stage_row_is_refused` |
14
- | RH-4 | Missing optional report fields do not prevent rendering | `scripts/okstra_ctl/phases/release_handoff/tests/test_release_handoff_optional_keys.py::test_the_shape_a_skipped_run_writes_renders_end_to_end` |
12
+ | RH-2 | Diverged origin branches are rejected without force-pushing | unenforced |
13
+ | RH-3 | An actively reserved stage is not handed to the main worktree | unenforced |
14
+ | RH-4 | Missing optional report fields do not prevent rendering | unenforced |
15
15
 
16
16
  ## Index
17
17
 
@@ -29,7 +29,7 @@ Report shapes remain in `schemas/final-report-v2.0.schema.json` and `schemas/fin
29
29
 
30
30
  `release-handoff` is the terminal phase that pushes already-committed implementation stages with a release-ready verdict, or hands them off as pull requests. **One stage is one PR.** The PR head is that stage's stack branch; the base comes from its `depends-on` — the release base for a stage with no live dependency, the predecessor's branch for a stage with one (a stacked PR), and a branch merging the predecessors for a stage with several.
31
31
 
32
- When a predecessor advances, `okstra_ctl.stage_rebase.synchronize_stage_stack` rebases downstream stages in dependency order rather than merging the predecessor into them. It records the new bases and completion commits, preserving prior heads under `refs/okstra/rebase-backups/`. Implementation entry and verification target acquisition use the same operation. PR planning stops after a stack change and requires fresh final-verification; the new completion rows invalidate earlier verification through `consumers.verified_accepted_stages`. Dirty or active stages, rewritten unproven predecessors, and rebase conflicts stop synchronization. A completed stage whose predecessor was reopened, and so has no done row, is left unchanged; the first synchronization after that predecessor is done again rebases it. The tests in `tests/worktree/test_stage_rebase.py` cover ordering, preservation, and verification invalidation. Origin divergence remains a delivery error, never a reason to merge old origin history into the rebased branch.
32
+ When a predecessor advances, `okstra_ctl.stage_rebase.synchronize_stage_stack` rebases downstream stages in dependency order rather than merging the predecessor into them. It records the new bases and completion commits, preserving prior heads under `refs/okstra/rebase-backups/`. Implementation entry and verification target acquisition use the same operation. PR planning stops after a stack change and requires fresh final-verification; the new completion rows invalidate earlier verification through `consumers.verified_accepted_stages`. Dirty or active stages, rewritten unproven predecessors, and rebase conflicts stop synchronization. A completed stage whose predecessor was reopened, and so has no done row, is left unchanged; the first synchronization after that predecessor is done again rebases it. The tests in the retired Python suite cover ordering, preservation, and verification invalidation. Origin divergence remains a delivery error, never a reason to merge old origin history into the rebased branch.
33
33
 
34
34
  Because the PRs are a stack, they must be merged in dependency order with a merge commit or a rebase-merge. A squash replaces the commits the next PR's base points at, so the stack breaks — every PR body states this, and the lead never merges.
35
35
 
@@ -26,7 +26,7 @@ Both `report_assembly.py` and `validators/validate-run.py` call this validation
26
26
 
27
27
  ## Tests
28
28
 
29
- `tests/test_technical_verification.py` covers input ownership, unsafe/unclassified sources, source preservation, exclusive snapshot creation, fact completeness, failed or missing commands, logs, sequence and symlink boundaries, full preparation and schema-v2/v3 report rendering. `tests/report/test_report_assembly.py::test_technical_assembly_requires_evidence_before_replacing_record` checks publication preserves an existing record when evidence fails.
29
+ `tests/test_technical_verification.py` covers input ownership, unsafe/unclassified sources, source preservation, exclusive snapshot creation, fact completeness, failed or missing commands, logs, sequence and symlink boundaries, full preparation and schema-v2/v3 report rendering. the retired Python suite previously checked publication preserves an existing record when evidence fails.
30
30
 
31
31
  ## Guarantees
32
32
 
@@ -626,6 +626,34 @@ def reverify_item_ids(
626
626
  return queue
627
627
 
628
628
 
629
+ def verified_content_hashes(rows: Sequence[Mapping[str, Any]]) -> dict[str, str]:
630
+ """`{item id: verifiedContentHash}` for the rows a recorded verdict covers."""
631
+ return {
632
+ str(row["id"]): str(row["verifiedContentHash"])
633
+ for row in rows
634
+ if isinstance(row, Mapping)
635
+ and isinstance(row.get("id"), str)
636
+ and isinstance(row.get("verifiedContentHash"), str)
637
+ }
638
+
639
+
640
+ def queue_candidate_ids(
641
+ items: Sequence[Mapping[str, Any]],
642
+ ledger: Mapping[str, str] | None,
643
+ previous_hashes: Mapping[str, str],
644
+ ) -> set[str]:
645
+ """Items a round may dispatch before verdict reuse narrows them.
646
+
647
+ `plan-items prepare` and `incremental-carry` both persist a queue, and
648
+ `team await` refuses a round whose prepared items fall outside the state's,
649
+ so both writers take their candidates from this one rule.
650
+ """
651
+ candidates = set(dispatch_item_ids(items, ledger))
652
+ if previous_hashes:
653
+ candidates.update(reverify_item_ids(items, previous_hashes, ledger))
654
+ return candidates
655
+
656
+
629
657
  def requires_plan_repair(verification: Mapping[str, Any]) -> bool:
630
658
  """검사·구현 가능성의 사실 결함은 단계 수에 따른 자문 면제에서 제외한다."""
631
659
  return any(
@@ -78,10 +78,33 @@ def group_rss_bytes(pgid: int) -> int:
78
78
  return total_kb * 1024
79
79
 
80
80
 
81
- def kill_group(pgid: int) -> bool:
82
- """그룹에 남은 프로세스를 SIGKILL 한다. 보낼 대상이 있었으면 True."""
81
+ def live_group_members(pgid: int) -> int | None:
82
+ """Members of group `pgid` that are not zombies; None when ps fails.
83
+
84
+ Signal 0 cannot answer this: it fails with EPERM both for a zombie-only
85
+ group on macOS and for a live member running under other credentials.
86
+ """
87
+ try:
88
+ output = subprocess.run(
89
+ ["ps", "-A", "-o", "pgid=,stat="],
90
+ capture_output=True, text=True, check=True,
91
+ ).stdout
92
+ except (OSError, subprocess.CalledProcessError):
93
+ return None
94
+ return sum(
95
+ 1 for row in output.splitlines()
96
+ if (fields := row.split()) and len(fields) == 2
97
+ and fields[0] == str(pgid) and not fields[1].startswith("Z")
98
+ )
99
+
100
+
101
+ def kill_group(pgid: int, signum: int = signal.SIGKILL) -> bool:
102
+ """그룹에 남은 프로세스를 SIGKILL 한다. 보낼 대상이 있었으면 True.
103
+
104
+ `signum` sends another signal, such as the SIGTERM of an interruption.
105
+ """
83
106
  try:
84
- os.killpg(pgid, signal.SIGKILL)
107
+ os.killpg(pgid, signum)
85
108
  except ProcessLookupError:
86
109
  return False
87
110
  except PermissionError:
@@ -27,7 +27,11 @@ from typing import Iterable, Mapping
27
27
  # `test` 와 분리한다. implementation verifier / final-verification 의 DB 실제실행 게이트가
28
28
  # diff 가 DB 를 건드릴 때 이 카테고리(또는 plan validation 의 db 스텝)를 요구한다.
29
29
  ALLOWED_CATEGORIES: tuple[str, ...] = ("lint", "format", "typecheck", "test", "db-test")
30
- QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
30
+ QA_VERIFIER_AUDIENCE_BY_TASK_TYPE = {
31
+ "implementation": "implementation-verifier",
32
+ "final-verification": "acceptance-verifier",
33
+ }
34
+ QA_COMMAND_EXECUTING_TASK_TYPES = tuple(QA_VERIFIER_AUDIENCE_BY_TASK_TYPE)
31
35
  QA_SOURCE_DIGEST_PATTERN = re.compile(r"sha256:[0-9a-f]{64}")
32
36
  QA_RELATIVE_PATH_DESCRIPTION = (
33
37
  "non-blank relative POSIX path with at least one component after normalization, "
@@ -212,8 +212,7 @@ def assemble_group_recap(project_root: Path, task_group: str) -> dict:
212
212
  브리프 디렉터리가 목록과 순서를, 카탈로그(task-manifest)가 실제 phase·상태를,
213
213
  그룹 문서의 Task Memory 영역이 결론(headline·decisions·watch out·follow-ups)을
214
214
  준다. 어느 하나만으로는 틀린다 — 카탈로그는 미시작 브리프를 모르고, 메모리는
215
- 2026-09-07 이전에 끝난 task 를 모른다. 숫자 집계(CPU·에러)는 rollup 의 것이라
216
- 여기서 세지 않는다.
215
+ 2026-09-07 이전에 끝난 task 를 모른다.
217
216
  """
218
217
  context_file = group_context.group_context_file(project_root, task_group)
219
218
  text = context_file.read_text(encoding="utf-8") if context_file.is_file() else ""
@@ -17,7 +17,7 @@ session id 등) 를 덧붙여 전달한다.
17
17
 
18
18
  from __future__ import annotations
19
19
 
20
- from .phases.catalog import profile_sidecar
20
+ from .phases.catalog import INPUT_DOCUMENT_TASK_TYPES, profile_sidecar
21
21
 
22
22
  import hashlib
23
23
  import json
@@ -1405,6 +1405,14 @@ def _derive_latest_pointers(existing: dict, ctx: dict, current_report_relative:
1405
1405
  }
1406
1406
 
1407
1407
 
1408
+ def _registered_task_brief(existing: dict, ctx: dict) -> str:
1409
+ # Downstream runs carry the manifest value in as their brief, so an input
1410
+ # document prepare generated must not replace the task's requirement brief.
1411
+ if ctx.get("TASK_TYPE") in INPUT_DOCUMENT_TASK_TYPES:
1412
+ return existing.get("taskBriefPath", "")
1413
+ return ctx.get("BRIEF_RELATIVE_PATH", "")
1414
+
1415
+
1408
1416
  def render_task_manifest(manifest_path: str, ctx: dict) -> None:
1409
1417
  path = Path(manifest_path)
1410
1418
  existing = {}
@@ -1484,7 +1492,7 @@ def render_task_manifest(manifest_path: str, ctx: dict) -> None:
1484
1492
  "workStatusNote": existing.get("workStatusNote", ""),
1485
1493
  "latestWorkRecordPath": existing.get("latestWorkRecordPath", ""),
1486
1494
  "registrationSource": existing.get("registrationSource", ""),
1487
- "taskBriefPath": ctx.get("BRIEF_RELATIVE_PATH", ""),
1495
+ "taskBriefPath": _registered_task_brief(existing, ctx),
1488
1496
  "recommendedWorkers": reviewers,
1489
1497
  "relatedTasks": related_tasks,
1490
1498
  "currentStatus": ctx.get("CURRENT_TASK_STATUS", ""),
@@ -1697,6 +1705,18 @@ def _build_convergence_block(ctx: dict) -> dict:
1697
1705
  }
1698
1706
 
1699
1707
 
1708
+ def _evidence_contract_fields(
1709
+ recorded_manifest: dict | None, ctx: dict,
1710
+ ) -> dict[str, str]:
1711
+ """A recorded run keeps the contract it started with, so a run prepared
1712
+ before the contract existed resumes unmarked."""
1713
+ if recorded_manifest is not None:
1714
+ version = recorded_manifest.get("verificationEvidenceVersion")
1715
+ else:
1716
+ version = ctx.get("VERIFICATION_EVIDENCE_VERSION")
1717
+ return {} if version is None else {"verificationEvidenceVersion": version}
1718
+
1719
+
1700
1720
  def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
1701
1721
  run_manifest_file = Path(run_manifest_path)
1702
1722
  run_manifest_exists = run_manifest_file.is_file()
@@ -1865,6 +1885,9 @@ def render_run_manifest(run_manifest_path: str, ctx: dict) -> None:
1865
1885
  "verificationTargetDigest": ctx.get("VERIFICATION_TARGET_DIGEST", ""),
1866
1886
  "workerResultsDirectoryPath": ctx.get("WORKER_RESULTS_RELATIVE_PATH", ""),
1867
1887
  **artifact_fields(manifest_input_ref),
1888
+ **_evidence_contract_fields(
1889
+ existing_run_manifest if run_manifest_exists else None, ctx,
1890
+ ),
1868
1891
  "reportTemplatePath": ctx.get("FINAL_REPORT_TEMPLATE_RELATIVE_PATH", ""),
1869
1892
  "validatorScriptPath": ctx.get("RUN_VALIDATOR_RELATIVE_PATH", ""),
1870
1893
  "leadSessionId": ctx.get("CLAUDE_SESSION_ID", ""),
@@ -17,10 +17,20 @@ from .clarification_items import (
17
17
  row_blocks_progress,
18
18
  )
19
19
  from .final_report_schema import load_schema_version, validate
20
- from .report_inputs import ReportInputPath, report_input_paths, uses_report_contract_v3
20
+ from .report_inputs import (
21
+ EXECUTION_EVIDENCE_INPUT,
22
+ EXECUTION_EVIDENCE_OWNER,
23
+ ReportInputPath,
24
+ report_input_paths,
25
+ uses_report_contract_v3,
26
+ )
21
27
  from .correction_round import correction_convergence_states, correction_round
22
28
  from .json_boundary import JsonBoundaryError, load_owned_object, serialize_owned_object
23
29
  from .report_narrative import parse_narrative, task_narrative_errors
30
+ from .report_execution_evidence import (
31
+ RECORD_DERIVED_TIERS, collect_report_evidence, command_row,
32
+ )
33
+ from .verification_evidence import roster_verifier_role_execution_ref
24
34
  from .report_synthesis_packet import (
25
35
  report_synthesis_packet_paths,
26
36
  verify_report_synthesis_packet_sources,
@@ -146,6 +156,12 @@ def _input_preflight_issues(
146
156
  ) -> tuple[AssemblyIssue, ...]:
147
157
  issues: list[AssemblyIssue] = []
148
158
  for row in inputs.values():
159
+ if row.key == EXECUTION_EVIDENCE_INPUT:
160
+ if not row.path.is_dir():
161
+ issues.append(AssemblyIssue(
162
+ row.owner, str(row.path), "$", "required input is missing",
163
+ ))
164
+ continue
149
165
  if not row.path.is_file():
150
166
  issues.append(
151
167
  AssemblyIssue(
@@ -543,6 +559,7 @@ def _compose(
543
559
  if scope:
544
560
  data["verificationScope"] = scope
545
561
  data["agentActivity"] = activities
562
+ _attach_execution_evidence(data, project_root, manifest_path, manifest, inputs)
546
563
  data["evidence"] = {"primary": _promoted_evidence([
547
564
  *(("convergence", item) for item in convergence_data["promotedEvidence"]),
548
565
  *round_evidence,
@@ -561,6 +578,88 @@ def _compose(
561
578
  return data
562
579
 
563
580
 
581
+ def _attach_execution_evidence(
582
+ data: dict[str, Any], project_root: Path, manifest_path: Path,
583
+ manifest: Mapping[str, Any], inputs: Mapping[str, ReportInputPath],
584
+ ) -> None:
585
+ """Copy what the verification execution records observed into the report.
586
+
587
+ The narrative keeps each verifier's judgment and observations; the records
588
+ are the only source of a check's command, outcome and output.
589
+ """
590
+ row = inputs.get(EXECUTION_EVIDENCE_INPUT)
591
+ if row is None:
592
+ return
593
+ try:
594
+ evidence = collect_report_evidence(project_root, manifest_path)
595
+ except ValueError as exc:
596
+ _fail(row.owner, row.path, "$", exc)
597
+ narrative = inputs["narrative"]
598
+ if manifest.get("taskType") == "implementation":
599
+ issues = _attach_verifier_evidence(data, manifest, evidence, narrative)
600
+ else:
601
+ issues = _attach_command_log_evidence(data, evidence, narrative)
602
+ if issues:
603
+ raise ReportAssemblyError(tuple(issues))
604
+
605
+
606
+ def _attach_verifier_evidence(
607
+ data: dict[str, Any], manifest: Mapping[str, Any],
608
+ evidence: Mapping[str, Any], narrative: ReportInputPath,
609
+ ) -> list[AssemblyIssue]:
610
+ implementation = data.get("implementation")
611
+ rows = implementation.get("verifierResults") if isinstance(implementation, dict) else None
612
+ issues = []
613
+ for index, row in enumerate(rows if isinstance(rows, list) else []):
614
+ if not isinstance(row, dict) or row.get("verdict") == "not-run":
615
+ continue
616
+ role_execution_ref = roster_verifier_role_execution_ref(manifest, row.get("verifier"))
617
+ if role_execution_ref is None:
618
+ issues.append(AssemblyIssue(
619
+ narrative.owner, str(narrative.path),
620
+ f"implementation.verifierResults[{index}].verifier",
621
+ "an evidence-contract run attaches execution records by roster "
622
+ f"verifier worker id; `{row.get('verifier')}` names none",
623
+ ))
624
+ continue
625
+ verifier = evidence.get(role_execution_ref)
626
+ if verifier is not None and verifier.references:
627
+ row["executionEvidence"] = [dict(item) for item in verifier.references]
628
+ return issues
629
+
630
+
631
+ def _attach_command_log_evidence(
632
+ data: dict[str, Any], evidence: Mapping[str, Any], narrative: ReportInputPath,
633
+ ) -> list[AssemblyIssue]:
634
+ final = data.get("finalVerification")
635
+ if not isinstance(final, dict):
636
+ return []
637
+ log = final.get("readonlyCommandLog")
638
+ rows = log if isinstance(log, list) else []
639
+ issues = [
640
+ AssemblyIssue(
641
+ narrative.owner, str(narrative.path),
642
+ f"finalVerification.readonlyCommandLog[{index}]",
643
+ f"an evidence-contract run takes executed Tier {row.get('tier')} rows "
644
+ "from its verification execution records",
645
+ )
646
+ for index, row in enumerate(rows)
647
+ if isinstance(row, dict) and row.get("status") == "executed"
648
+ and row.get("tier") in RECORD_DERIVED_TIERS
649
+ ]
650
+ number = max((row["number"] for row in rows if isinstance(row, dict)
651
+ and isinstance(row.get("number"), int)), default=0)
652
+ derived = [
653
+ command_row(number + offset, reference)
654
+ for offset, reference in enumerate(
655
+ (reference for verifier in evidence.values()
656
+ for reference in verifier.references), start=1)
657
+ ]
658
+ if derived:
659
+ final["readonlyCommandLog"] = [*rows, *derived]
660
+ return issues
661
+
662
+
564
663
  def _attach_discussion(data: dict[str, Any], project_root: Path, manifest: Mapping[str, Any]) -> None:
565
664
  """확정본은 토론 기록이 정본이다 — 보고서에는 조립이 그 id 와 digest 만 옮긴다."""
566
665
  if manifest.get("taskType") != "discussion":
@@ -838,6 +937,8 @@ def _schema_owner(error: str, narrative_owner: str) -> str:
838
937
  return "design-surface-detector"
839
938
  if "planBodyVerification" in error:
840
939
  return "convergence"
940
+ if "executionEvidence" in error:
941
+ return EXECUTION_EVIDENCE_OWNER
841
942
  if "selectedDirectionRef" in error:
842
943
  return narrative_owner
843
944
  return owners.get(field.split(".", 1)[0], narrative_owner)