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
@@ -25,6 +25,8 @@ from .agent.invocation import (
25
25
  verify_agent_invocation,
26
26
  )
27
27
  from .path_hints import hydrate_active_run_context
28
+ from .verification_dispatch import VerificationDispatchError, seal_dispatch_generation
29
+ from .verification_invocation import VerificationGenerationReference
28
30
  from .report_inputs import report_narrative_path, uses_report_contract_v3
29
31
  from .report_synthesis_packet import (
30
32
  ReportSynthesisPacketError,
@@ -190,6 +192,7 @@ class _PromptItem:
190
192
  resources: tuple["_PromptResource", ...] = ()
191
193
  temp_path: Path | None = None
192
194
  stage_extract: str = ""
195
+ verification_generation: VerificationGenerationReference | None = None
193
196
 
194
197
 
195
198
  @dataclass(frozen=True)
@@ -496,6 +499,12 @@ def _prepare_prompt_item(
496
499
  if item.existed:
497
500
  _validate_existing_prompt(context, prepared_item)
498
501
  return prepared_item
502
+ # A published prompt's metadata already names its generation and
503
+ # `verify_agent_invocation` checks that binding; sealing again on reuse would
504
+ # recapture a tree the verifier's own run may have changed.
505
+ prepared_item = replace(
506
+ prepared_item, verification_generation=_seal_generation(context, item),
507
+ )
499
508
  temp_path: Path | None = None
500
509
  try:
501
510
  item.final_path.parent.mkdir(parents=True, exist_ok=True)
@@ -540,9 +549,28 @@ def _prepare_prompt_item(
540
549
  resources=resources,
541
550
  temp_path=temp_path,
542
551
  stage_extract=item.stage_extract,
552
+ verification_generation=prepared_item.verification_generation,
543
553
  )
544
554
 
545
555
 
556
+ def _seal_generation(
557
+ context: _MaterializationContext,
558
+ item: _PromptItem,
559
+ ) -> VerificationGenerationReference | None:
560
+ try:
561
+ return seal_dispatch_generation(
562
+ context.project_root, context.request.run_manifest_path, context.manifest,
563
+ context.active_context, audience=item.plan.duty_audience,
564
+ dispatch_kind="initial",
565
+ )
566
+ except VerificationDispatchError as exc:
567
+ raise InitialPromptMaterializationError(
568
+ "required_input_missing" if exc.missing_executor_result
569
+ else "validation_failed",
570
+ f"verification generation: {exc}",
571
+ ) from exc
572
+
573
+
546
574
  def _with_prompt_resources(
547
575
  item: _PromptItem,
548
576
  resources: tuple[_PromptResource, ...],
@@ -556,6 +584,7 @@ def _with_prompt_resources(
556
584
  resources=resources,
557
585
  temp_path=item.temp_path,
558
586
  stage_extract=item.stage_extract,
587
+ verification_generation=item.verification_generation,
559
588
  )
560
589
 
561
590
 
@@ -710,6 +739,7 @@ def _agent_invocation_request(
710
739
  duty_id=identity.duty_id if identity is not None else None,
711
740
  invocation_ref=invocation_id if identity is not None else None,
712
741
  attempt=1,
742
+ verification_generation=item.verification_generation,
713
743
  )
714
744
 
715
745
 
@@ -15,6 +15,7 @@ from pathlib import Path
15
15
 
16
16
  from . import next_phase
17
17
  from .ids import slugify_task_segment
18
+ from .generated_input import names_generated_input_document
18
19
  from .implementation_outcome import reconcile_implementation_outcome
19
20
  from .json_boundary import JsonBoundaryError, load_owned_object
20
21
  from .paths import RunRef, task_dir
@@ -109,6 +110,8 @@ def _autofill(args: argparse.Namespace) -> int:
109
110
  task_type = ""
110
111
  if args.need_brief:
111
112
  brief = (data.get("taskBriefPath") or "").strip()
113
+ if names_generated_input_document(Path(args.project_root), args.task_key, brief):
114
+ brief = ""
112
115
  if args.need_type:
113
116
  # 포인터 판정은 파이썬이 갖는다 — `ready` 가 아니면 빈 문자열이라
114
117
  # 셸이 센티널 목록을 따로 들고 있을 이유가 없다.
@@ -195,6 +198,8 @@ def main(argv: list[str] | None = None) -> int:
195
198
 
196
199
  autofill = sub.add_parser("autofill")
197
200
  autofill.add_argument("--manifest", required=True)
201
+ autofill.add_argument("--project-root", required=True)
202
+ autofill.add_argument("--task-key", required=True)
198
203
  autofill.add_argument("--need-brief", action="store_true")
199
204
  autofill.add_argument("--need-type", action="store_true")
200
205
  autofill.set_defaults(handler=_autofill)
@@ -4,6 +4,7 @@ from __future__ import annotations
4
4
  import contextlib
5
5
  import fcntl
6
6
  import hashlib
7
+ from collections.abc import Callable, Iterator
7
8
  from pathlib import Path
8
9
 
9
10
  from .ids import _escape_segment_for_join, _safe_fs_segment
@@ -85,6 +86,32 @@ def worktree_exec_lock(home, worktree, *, on_wait=None):
85
86
  잠그지 못할 때 어떻게 할지는 호출자가 정한다.
86
87
  """
87
88
  lockfile = worktree_exec_lock_path(home, worktree)
89
+ with _exclusive_lock(lockfile, on_wait):
90
+ yield lockfile
91
+
92
+
93
+ def resource_exec_lock_path(home: str | Path, resource_key: str) -> Path:
94
+ """`<home>/.locks/resource-exec/<key hash>.lock`, shared by every worktree."""
95
+ key = hashlib.sha256(resource_key.encode("utf-8")).hexdigest()
96
+ return Path(home) / ".locks" / "resource-exec" / f"{key[:32]}.lock"
97
+
98
+
99
+ @contextlib.contextmanager
100
+ def resource_exec_lock(
101
+ home: str | Path, resource_key: str, *,
102
+ on_wait: Callable[[Path], None] | None = None,
103
+ ) -> Iterator[Path]:
104
+ """Serialize checks that use one fixed resource (a port, a test database)
105
+ that worktree isolation cannot separate."""
106
+ lockfile = resource_exec_lock_path(home, resource_key)
107
+ with _exclusive_lock(lockfile, on_wait):
108
+ yield lockfile
109
+
110
+
111
+ @contextlib.contextmanager
112
+ def _exclusive_lock(
113
+ lockfile: Path, on_wait: Callable[[Path], None] | None,
114
+ ) -> Iterator[None]:
88
115
  lockfile.parent.mkdir(parents=True, exist_ok=True)
89
116
  with lockfile.open("a") as f:
90
117
  try:
@@ -94,6 +121,6 @@ def worktree_exec_lock(home, worktree, *, on_wait=None):
94
121
  on_wait(lockfile)
95
122
  fcntl.flock(f.fileno(), fcntl.LOCK_EX)
96
123
  try:
97
- yield lockfile
124
+ yield
98
125
  finally:
99
126
  fcntl.flock(f.fileno(), fcntl.LOCK_UN)
@@ -178,6 +178,13 @@ def render_verification_input(
178
178
  "\n## Approved Plan\n\n",
179
179
  *quoted_value_lines("Approved plan", inputs["approvedPlan"]),
180
180
  ])
181
+ if "conformanceBaseline" in inputs:
182
+ rows.extend([
183
+ "\n## Conformance Baseline\n\n",
184
+ *quoted_value_lines(
185
+ "Conformance baseline", inputs["conformanceBaseline"],
186
+ ),
187
+ ])
181
188
  return "".join(rows)
182
189
 
183
190
 
@@ -15,10 +15,10 @@ from __future__ import annotations
15
15
 
16
16
  import os
17
17
  import re
18
- from collections.abc import Callable, Sequence
18
+ from collections.abc import Callable, Mapping, Sequence
19
19
  from dataclasses import dataclass, replace
20
20
  from pathlib import Path
21
- from typing import Optional
21
+ from typing import Any, Optional
22
22
 
23
23
  from okstra_project.dirs import (
24
24
  DISCOVERY_RELATIVE,
@@ -42,7 +42,6 @@ __all__ = [
42
42
  "resolve_under_root",
43
43
  "task_dir",
44
44
  "task_runs_dir",
45
- "container_paths",
46
45
  "okstra_home",
47
46
  "find_asset_root",
48
47
  "RUN_VALIDATOR_RELATIVE",
@@ -118,6 +117,14 @@ _REPORT_SEQ_RE = re.compile(
118
117
  r"^final-report-.+-(?P<seq>\d{3,})\.(?:md|data\.json)$"
119
118
  )
120
119
  _TASKS_SEGMENTS = Path(TASKS_RELATIVE).parts
120
+ _EXECUTION_SEGMENT_RE = re.compile(r"[A-Za-z0-9][A-Za-z0-9._-]*")
121
+ _CHECK_RUN_RE = re.compile(r"run-([1-9][0-9]*)")
122
+
123
+
124
+ def _positive_int(value: object, label: str) -> int:
125
+ if isinstance(value, bool) or not isinstance(value, int) or value < 1:
126
+ raise ValueError(f"{label} must be a positive integer")
127
+ return value
121
128
 
122
129
 
123
130
  def _newest_report(reports_dir: Path) -> Optional[Path]:
@@ -228,12 +235,55 @@ class RunRef:
228
235
  return self.verification_dir / f"inputs{self._suffix}.json"
229
236
 
230
237
  def verification_generation(self, generation: int) -> Path:
231
- if (isinstance(generation, bool) or not isinstance(generation, int)
232
- or generation < 1):
233
- raise ValueError("verification generation must be a positive integer")
238
+ _positive_int(generation, "verification generation")
234
239
  return (self.verification_dir / f"generations{self._suffix}"
235
240
  / f"generation-{generation}.json")
236
241
 
242
+ def verification_check_dir(
243
+ self, invocation_ref: str, attempt: int, check_ref: str,
244
+ ) -> Path:
245
+ """The directory holding every run of `check_ref` (`kind:id`) in one attempt."""
246
+ segment = check_ref.replace(":", "-", 1)
247
+ if not _EXECUTION_SEGMENT_RE.fullmatch(segment):
248
+ raise ValueError(f"verification execution segment is unsafe: {segment}")
249
+ return self._verification_attempt_dir(invocation_ref, attempt) / segment
250
+
251
+ def _verification_attempt_dir(self, invocation_ref: str, attempt: int) -> Path:
252
+ if not _EXECUTION_SEGMENT_RE.fullmatch(invocation_ref):
253
+ raise ValueError(
254
+ f"verification execution segment is unsafe: {invocation_ref}")
255
+ _positive_int(attempt, "verification execution attempt")
256
+ return (self.verification_dir / f"executions{self._suffix}" / invocation_ref
257
+ / f"attempt-{attempt}")
258
+
259
+ def verification_execution_dir(
260
+ self, invocation_ref: str, attempt: int, check_ref: str, check_run: int,
261
+ ) -> Path:
262
+ """One check run's directory; a check run is not a worker attempt."""
263
+ _positive_int(check_run, "verification execution check run")
264
+ return (self.verification_check_dir(invocation_ref, attempt, check_ref)
265
+ / f"run-{check_run}")
266
+
267
+ def latest_verification_check_run(
268
+ self, invocation_ref: str, attempt: int, check_ref: str,
269
+ ) -> int | None:
270
+ runs = self.verification_check_dir(invocation_ref, attempt, check_ref)
271
+ numbers = [int(match.group(1)) for match in (
272
+ _CHECK_RUN_RE.fullmatch(path.name)
273
+ for path in (runs.iterdir() if runs.is_dir() else ())
274
+ ) if match]
275
+ return max(numbers, default=None)
276
+
277
+ def verification_check_refs(self, invocation_ref: str, attempt: int) -> list[str]:
278
+ """The checks (`kind:id`) one attempt ran, sorted."""
279
+ attempt_dir = self._verification_attempt_dir(invocation_ref, attempt)
280
+ return sorted(
281
+ path.name.replace("-", ":", 1)
282
+ for path in (attempt_dir.iterdir() if attempt_dir.is_dir() else ())
283
+ if path.is_dir() and "-" in path.name
284
+ and _EXECUTION_SEGMENT_RE.fullmatch(path.name)
285
+ )
286
+
237
287
  @property
238
288
  def convergence_state(self) -> Path:
239
289
  """이 run 의 finding convergence 상태 파일.
@@ -242,7 +292,9 @@ class RunRef:
242
292
  디렉터리마다 seq 를 따로 세므로(`reports: 004` 와 `state: 005` 가 실제로
243
293
  갈린 적이 있다), 리포트 경로에서 만든 ref 로 이 값을 계산하면 그 갈린
244
294
  run 에서는 존재하지 않는 파일을 가리킨다. 호출자는 파일이 없는 경우를
245
- 정상 분기로 다뤄야 한다.
295
+ 정상 분기로 다뤄야 한다. The per-directory count above describes runs
296
+ prepared before `compute_run_paths` gave every category one seq; those
297
+ runs stay on disk.
246
298
  """
247
299
  return self.run_dir / "state" / f"convergence{self._suffix}.json"
248
300
 
@@ -303,6 +355,18 @@ class RunRef:
303
355
  run_dir.parent.parent, run_dir.name, seq=seq, stage=stage
304
356
  )
305
357
 
358
+ @classmethod
359
+ def from_manifest(
360
+ cls, manifest_path: Path, manifest: Mapping[str, Any],
361
+ ) -> "RunRef":
362
+ ref = cls.from_run_dir(
363
+ manifest_path.parent.parent,
364
+ seq=int(manifest["runSequencesByCategory"]["manifests"]),
365
+ )
366
+ if ref.manifest.resolve() != manifest_path.resolve():
367
+ raise ValueError("run manifest is not at its canonical run path")
368
+ return ref
369
+
306
370
  @classmethod
307
371
  def from_report_path(cls, report_path: Path) -> "RunRef":
308
372
  """final-report 경로에서 정체를 복원한다.
@@ -428,20 +492,6 @@ def task_timeline_file(task_root: Path) -> Path:
428
492
  return Path(task_root) / "history" / "timeline.json"
429
493
 
430
494
 
431
- def container_paths(project_root: Path, task_group: str, task_id: str) -> dict:
432
- """container 산출물 경로 묶음(순수 계산, mkdir 금지).
433
-
434
- task root 하위 ``container/`` 디렉터리에 deploy 산출물을 모은다. base 가
435
- ``task_dir`` 에서 파생되므로 라벨(compose project name)↔디스크 경로의 slug
436
- 규칙이 자동으로 일치한다."""
437
- base = task_dir(project_root, task_group, task_id) / "container"
438
- return {
439
- "container_dir": base,
440
- "env_override": base / "env.override",
441
- "deploy_state": base / "deploy-state.json",
442
- }
443
-
444
-
445
495
  def next_run_seq(run_seq_dir: Path, task_type_segment: str) -> int:
446
496
  """run_seq_dir 안에서 `*-<task-type>-NNN[.<ext>]` 항목을 스캔해 다음 seq 번호를
447
497
  돌려준다. 디렉터리 부재 시 1.
@@ -514,6 +564,11 @@ def compute_run_paths(
514
564
  run_seq_override: 정수가 주어지면 7개 seq 모두 그 값으로 강제. 외부에서
515
565
  seq 를 미리 reserve 한 경로용(현재는 테스트 hook). 미지정 시 디스크 스캔
516
566
  결과로 결정.
567
+
568
+ Every artifact of one run takes one seq, the next one free in all seven
569
+ directories. A run that fails before writing a report or worker result
570
+ leaves those directories behind the others; counting each on its own would
571
+ hand the next run the failed run's report and result paths.
517
572
  """
518
573
  project_root = Path(project_root)
519
574
  workspace_root = Path(workspace_root)
@@ -578,21 +633,23 @@ def compute_run_paths(
578
633
  else run_dir / "carry"
579
634
  )
580
635
 
636
+ seq_dirs = {
637
+ "manifests": run_manifests,
638
+ "prompts": run_prompts,
639
+ "reports": run_reports,
640
+ "status": run_status,
641
+ "state": run_state,
642
+ "sessions": run_sessions,
643
+ "worker_results": worker_results,
644
+ }
581
645
  if run_seq_override is not None:
582
646
  seq_int = int(run_seq_override)
583
- seqs = {k: f"{seq_int:03d}" for k in (
584
- "manifests", "prompts", "reports", "status", "state",
585
- "sessions", "worker_results")}
586
647
  else:
587
- seqs = {
588
- "manifests": f"{next_run_seq(run_manifests, task_type_segment):03d}",
589
- "prompts": f"{next_run_seq(run_prompts, task_type_segment):03d}",
590
- "reports": f"{next_run_seq(run_reports, task_type_segment):03d}",
591
- "status": f"{next_run_seq(run_status, task_type_segment):03d}",
592
- "state": f"{next_run_seq(run_state, task_type_segment):03d}",
593
- "sessions": f"{next_run_seq(run_sessions, task_type_segment):03d}",
594
- "worker_results": f"{next_run_seq(worker_results, task_type_segment):03d}",
595
- }
648
+ seq_int = max(
649
+ next_run_seq(directory, task_type_segment)
650
+ for directory in seq_dirs.values()
651
+ )
652
+ seqs = {k: f"{seq_int:03d}" for k in seq_dirs}
596
653
 
597
654
  suffixes = {k: f"-{task_type_segment}-{v}" for k, v in seqs.items()}
598
655
  run_file_suffix = suffixes["reports"]
@@ -10,6 +10,9 @@ from pathlib import Path
10
10
 
11
11
  from ..asset_roots import walk_to_asset_root
12
12
 
13
+ # Prepare writes its own input document into the brief slot for these task types.
14
+ INPUT_DOCUMENT_TASK_TYPES = ("release-handoff", "discussion")
15
+
13
16
 
14
17
  class PhaseAssetError(ValueError):
15
18
  """단계 자산을 요청한 실행 루트에서 해석할 수 없다."""
@@ -17,8 +17,8 @@ This phase maps a proposed change's preserved behavior, affected and unaffected
17
17
  | ID | Guarantee | Enforcement |
18
18
  |---|---|---|
19
19
  | CI-1 | Planning inputs contain constraints and unknowns only. | `scripts/okstra_ctl/phases/change_impact_analysis/validation.py::validate_change_impact_semantics` |
20
- | CI-2 | Impact items require current-code evidence within the included scope. | `validators/validate_analysis_report.py::_validate_all_current_code_evidence`, `scripts/okstra_ctl/phases/change_impact_analysis/tests/test_change_impact_analysis_validation.py::test_change_impact_item_requires_current_code_evidence` |
21
- | CI-3 | The wizard collects feature evidence before project evidence. | `tests/domain/wizard/test_analysis_inputs.py::test_change_impact_collects_feature_then_project_evidence` |
20
+ | CI-2 | Impact items require current-code evidence within the included scope. | `validators/validate_analysis_report.py::_validate_all_current_code_evidence` |
21
+ | CI-3 | The wizard collects feature evidence before project evidence. | unenforced |
22
22
  | CI-4 | Common validation checks the frozen analysis source, target and evidence snapshot. | `validators/validate_analysis_report.py::validate_analysis_snapshot` |
23
23
 
24
24
  ## Tests
@@ -4,64 +4,64 @@
4
4
 
5
5
  | ID | Guarantee | Enforcement |
6
6
  |---|---|---|
7
- | DS-1 | `discussion` is a registered task type whose profile, role contract and report assets live in this package | `tests/contract/test_phase_catalog.py::test_migrated_profile_is_absent_from_the_legacy_directory` |
8
- | DS-2 | Roles are analyser 1..5 (recommended 3), report-writer 1 and a dynamic verifier per selected analyser; the lead is the facilitator | `tests/domain/test_role_requirements.py::test_every_public_task_type_declares_complete_role_requirements` |
7
+ | DS-1 | `discussion` is a registered task type whose profile, role contract and report assets live in this package | unenforced |
8
+ | DS-2 | Roles are analyser 1..5 (recommended 3), report-writer 1 and a dynamic verifier per selected analyser; the lead is the facilitator | unenforced |
9
9
  | DS-3 | Analysers receive the `discussion-worker` duty through the common prompt policy | `scripts/okstra_ctl/worker_prompt_policy.py::ANALYSIS_DUTY_BY_TASK_TYPE` |
10
- | DS-4 | A supported lead reaches the common worker dispatch plan without a separate executor | `tests/run/test_discussion_prepare.py::test_a_claude_code_lead_reaches_the_analyser_dispatch_plan` |
11
- | DS-5 | A non-`claude-code` lead outside cmux is rejected before any task artifact is written | `tests/adapters/dispatch/test_cmux.py::test_a_non_claude_lead_still_needs_render_only_outside_cmux` |
10
+ | DS-4 | A supported lead reaches the common worker dispatch plan without a separate executor | unenforced |
11
+ | DS-5 | A non-`claude-code` lead outside cmux is rejected before any task artifact is written | unenforced |
12
12
  | DS-6 | The run carries no lifecycle routing; the next-phase pointer stays pending | `scripts/okstra_ctl/next_phase.py::_SIDETRACK_TASK_TYPES` |
13
- | DS-7 | Completion requires the user's confirmation, not agent consensus or a convergence stop: the derived phase reaches `completed` only from a revision published by `confirm-completion`, and `cycle-close` only ends a verification cycle (DS-19) | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_publication_is_refused_until_the_user_confirms_a_complete_draft` |
14
- | DS-8 | A discussion starts without a brief: prepare takes `--discussion-start`, refuses `--task-brief`, and writes the input document that takes the brief's place | `tests/run/test_discussion_prepare.py::test_direct_entry_starts_without_a_brief_and_records_the_start_input` |
15
- | DS-9 | A start-input error is refused before prepare writes any run artifact or discussion record | `tests/run/test_discussion_prepare.py::test_an_input_error_writes_no_partial_run` |
16
- | DS-10 | The wizard asks for the start input instead of a brief, from a new task (`okstra wizard init --task-type discussion`) and from an existing task; every other task type keeps its question order | `tests/domain/wizard/test_discussion_start.py::test_a_requested_discussion_starts_a_new_task_without_a_brief`, `tests/domain/wizard/test_discussion_start.py::test_an_existing_task_continues_its_discussion_without_a_brief_step`; `tests/domain/wizard/test_task_selection.py::test_brand_new_task_branches_into_group_then_brief_then_type_then_id` |
17
- | DS-11 | A resent question, answer or decision returns the stored record instead of adding a second one; a different answer to an answered question is refused | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_store.py::test_a_resent_answer_is_stored_once_and_a_different_one_is_refused` |
18
- | DS-12 | An append cut off mid-line and a draft that lags the records both recover on the next read or write | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_store.py::test_an_interrupted_append_and_a_stale_draft_recover` |
19
- | DS-13 | Concurrent writers keep every record and get distinct ids | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_store.py::test_concurrent_writes_keep_every_record_with_distinct_ids` |
20
- | DS-14 | A record names its author and the discussion run it came from; a run manifest of another task, or a start input naming another task's discussion, is refused | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_store.py::test_a_run_of_another_task_is_refused`, `scripts/okstra_ctl/phases/discussion/tests/test_discussion_store.py::test_only_the_addressee_answers_and_records_keep_author_and_run`; `tests/domain/wizard/test_discussion_start.py::test_the_wizard_refuses_another_tasks_discussion` |
21
- | DS-15 | Continuing a discussion hands the next run the confirmed subject, the user decisions and the questions still waiting for an answer | `tests/run/test_discussion_prepare.py::test_a_resumed_run_restores_decisions_and_pending_questions` |
22
- | DS-16 | A direct question is dispatched alone to its addressee as a new `discussion-question` invocation built from the discussion read model, through the common `agent-prompt materialize --batch` path; its whole result is recorded once as the addressee's answer and reaches every participant's next instruction | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_direct_question_is_dispatched_alone_and_its_answer_reaches_every_participant` |
23
- | DS-17 | Questions go to the user one at a time in record order, and no research cycle opens while a question waits for the user or a participant | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_questions_go_to_the_user_one_at_a_time_and_research_waits_for_the_answers` |
24
- | DS-18 | A research cycle whose input references (start inputs, subject, answers, materials) equal the last closed cycle's is not dispatched; the remaining disagreements and options go to the user. New evidence or a new alternative opens the next cycle in a continuation run | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_repeated_input_is_not_researched_again_and_goes_to_the_user` |
25
- | DS-19 | Closing a cycle imports the convergence findings as claims with their origin author and the verifiers' verdicts, ends that verification cycle only, and leaves user decisions and user questions untouched | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_fact_check_never_settles_the_users_intent` |
26
- | DS-20 | An author's vote on its own claim is refused, not counted as a refutation — the convergence engine's final-state validation is reused | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_an_authors_check_of_its_own_claim_is_refused_as_a_refutation` |
27
- | DS-21 | A batch-start failure and a failure left after the dispatcher's retry loop are recorded per participant without deleting completed results; the cycle neither reopens research nor closes until the user chooses retry, replace or reduce, and a second, different choice for the same failure is refused | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_start_failure_keeps_completed_results_and_a_reduced_cycle_closes`, `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_failure_after_the_retry_loop_is_retried_in_the_same_run` |
28
- | DS-22 | A retry stays in the same run as a new invocation; a replacement continues in a run prepared with `--discussion-start <task-key>`, whose research input carries the earlier results under their original author and run, and every cycle records its roster | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_failure_after_the_retry_loop_is_retried_in_the_same_run`, `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_replacement_continues_in_a_new_run_and_keeps_the_original_authors` |
29
- | DS-23 | A failed direct question waits for the user's choice; `reduce` drops it from the participants' pending questions and `replace` is refused for it | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_failed_direct_question_can_be_dropped_without_blocking_research` |
30
- | DS-24 | Concurrent `cycle-open` calls for one run record one cycle | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_concurrent_cycle_opens_record_one_cycle` |
31
- | DS-25 | On a `claude-code` lead, whose analysers run as native sessions, `settle` reads the common `record-dispatch` / `link-result` / `abandon-attempt` records: a linked result is a result, an attempt closed without one is a failure, and an open attempt refuses settlement | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_workflow.py::test_a_claude_code_lead_settles_its_native_session_research` |
32
- | DS-26 | A `discussion-question` prompt keeps the analysis contract but stays outside the analysis-core prompt equality group | `tests/contract/test_critic_prompt_equality_exemption.py::test_a_discussion_question_keeps_the_analysis_contract_outside_the_equality_group` |
33
- | DS-27 | A confirmation names the draft version the user saw; a version older than the current records, or a stored confirmation followed by any later record, publishes nothing | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_a_stale_confirmation_is_refused` |
34
- | DS-28 | Completion is refused while the subject, a requirement, an in-scope or an excluded entry, a closed research cycle, a user or participant answer, or a failure choice is missing; remaining disagreements do not block and are carried into the revision with their standing | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_publication_is_refused_until_the_user_confirms_a_complete_draft`, `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_the_user_completes_with_disagreements_and_the_revision_keeps_them` |
35
- | DS-29 | A revision carries the subject, start inputs, requirements with the follow-up they apply to, scope and exclusions, direction, the user's confirmation, decisions, disagreements, evidence claims, unverified scope, every cycle's roster and every failure with the user's choice; a reduced roster is marked and its failure listed as unverified | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_the_user_completes_with_disagreements_and_the_revision_keeps_them`, `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_a_reduced_roster_is_recorded_as_unverified_scope` |
36
- | DS-30 | One confirmation publishes one revision, `<task-key>/revision-NNN` by completion sequence, written once read-only; a resent or concurrent confirmation returns that revision | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_a_resent_or_concurrent_confirmation_publishes_one_revision` |
37
- | DS-31 | A publication interrupted before the revision file is written leaves no revision; resending the same confirmation publishes it | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_an_interrupted_publication_is_completed_by_the_same_confirmation`, `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_a_stale_confirmation_is_refused` |
38
- | DS-32 | A completed discussion takes no record but `reopen` naming its latest revision, and prepare refuses a new start input for it; after `reopen`, the new draft and the earlier revision read side by side, the earlier revision's bytes never change, and the next revision carries its id, content digest and the reason for change | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_reopening_keeps_the_previous_revision_byte_for_byte_beside_the_new_draft` |
39
- | DS-33 | The final report's `discussion` block is written by report assembly, never by the report writer, and carries only the revision id and content digest (or the draft version); assembly refuses a block whose digest no longer matches the revision file, `validate-run` reports the mismatch, and the run passes the reachable `report-finalize` steps without real providers | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_a_discussion_report_references_only_the_revision_and_passes_finalize` |
40
- | DS-34 | Finalizing a run whose discussion is still a draft publishes no revision; its report carries the draft version | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_finalizing_a_draft_run_never_publishes_a_revision` |
41
- | DS-35 | A follow-up brief carries the revision's common requirements and those of its follow-up label, each with its record id; the other follow-ups' requirements and the excluded scope are listed as out of scope; it passes `validators/validate-brief.py` and recommends `requirements-discovery`. A discussion with no follow-up lists its labels as unlinked | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_a_follow_up_brief_carries_its_requirements_and_starts_at_requirements_discovery` |
42
- | DS-36 | Fields reused from the user's confirmations name their record in the revision; an observation method the revision does not carry is new meaning, so the brief stays `reporter-confirmations: pending` with an `intent-check:` row and prepare refuses it until the user confirms | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_a_follow_up_brief_carries_its_requirements_and_starts_at_requirements_discovery` |
43
- | DS-37 | The follow-up's brief pins the discussion, revision id, content digest and requirement ids; prepare records them in the run inputs as `discussionRevisionRef`, and the manager launch packet carries the same reference and starts a new child at `requirements-discovery` | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_a_follow_up_brief_carries_its_requirements_and_starts_at_requirements_discovery`, `tests/test_okstra_manager_launch.py::test_build_launch_packet_carries_a_discussion_follow_up_revision_and_its_first_phase` |
44
- | DS-38 | A newer revision flags every linked follow-up `needs-impact-review` with the changes from its pinned revision; a follow-up never moves by itself (`follow-up-brief` for another revision is refused), only the follow-up the user adopts with `apply` moves, a resent `apply` returns the stored record, and a different choice for the same follow-up and revision is refused | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_only_the_follow_up_the_user_selects_adopts_the_new_revision` |
45
- | DS-39 | Adopting a revision for a follow-up that has an implementation-planning plan routes it to the plan amendment path and leaves its plan and brief byte-identical | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_a_follow_up_with_a_plan_is_routed_to_plan_amendment` |
46
- | DS-40 | The target brief is written before the link record; a link write interrupted after the brief, or a torn link line, is completed by resending the same command, and the link is recorded once | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_an_interrupted_link_write_is_retried_once` |
47
- | DS-41 | `links` re-reads each target's brief, also in another project; a target that cannot be read is `unknown`, never `current`; a brief this command did not write last is not replaced without `--replace` | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_a_target_in_another_project_is_read_back_and_unknown_when_unreadable` |
48
- | DS-42 | `confirm-completion` registers the published revision in the Memory Book without a prompt, through `okstra memory add --source-key discussion:<revision-id>`; the entry holds a summary of decisions, disagreements, risks and unverified scope with the revision id, content digest, project and task — not the start inputs or the agreed evidence — and searching the revision id finds it | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_memory.py::test_completion_registers_a_summary_that_traces_back_to_the_revision` |
49
- | DS-43 | A re-discussion's revision is a new source key and a separate Memory Book entry | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_memory.py::test_a_re_discussion_registers_a_separate_entry` |
50
- | DS-44 | A resent confirmation does not call the Memory Book again, and concurrent registrations of one revision leave one entry; with the discussion's registration state lost, the Memory Book's own source-key check returns the stored entry | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_memory.py::test_a_resent_or_concurrent_registration_leaves_one_entry`, `tests-js/memory.test.mjs::concurrent memory add --source-key of one key leaves one entry` |
51
- | DS-45 | A failed registration leaves the revision published and `pending`; `status` lists it under `memoryRegistration` and `memory-sync` retries it with the same source key | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_memory.py::test_a_failed_registration_keeps_the_revision_and_memory_sync_recovers` |
52
- | DS-46 | A summary the Memory Book refuses as a likely secret is `refused` with the secret kinds shown; `memory-sync` does not retry it, and an unchanged `--summary-file` is refused; only a changed summary registers | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_memory.py::test_a_secret_refusal_is_shown_and_retried_only_after_the_summary_changes`, `tests-js/memory.test.mjs::memory add --source-key --json reports a secret refusal as JSON on stdout` |
13
+ | DS-7 | Completion requires the user's confirmation, not agent consensus or a convergence stop: the derived phase reaches `completed` only from a revision published by `confirm-completion`, and `cycle-close` only ends a verification cycle (DS-19) | unenforced |
14
+ | DS-8 | A discussion starts without a brief: prepare takes `--discussion-start`, refuses `--task-brief`, and writes the input document that takes the brief's place | unenforced |
15
+ | DS-9 | A start-input error is refused before prepare writes any run artifact or discussion record | unenforced |
16
+ | DS-10 | The wizard asks for the start input instead of a brief, from a new task (`okstra wizard init --task-type discussion`) and from an existing task; every other task type keeps its question order | unenforced |
17
+ | DS-11 | A resent question, answer or decision returns the stored record instead of adding a second one; a different answer to an answered question is refused | unenforced |
18
+ | DS-12 | An append cut off mid-line and a draft that lags the records both recover on the next read or write | unenforced |
19
+ | DS-13 | Concurrent writers keep every record and get distinct ids | unenforced |
20
+ | DS-14 | A record names its author and the discussion run it came from; a run manifest of another task, or a start input naming another task's discussion, is refused | unenforced |
21
+ | DS-15 | Continuing a discussion hands the next run the confirmed subject, the user decisions and the questions still waiting for an answer | unenforced |
22
+ | DS-16 | A direct question is dispatched alone to its addressee as a new `discussion-question` invocation built from the discussion read model, through the common `agent-prompt materialize --batch` path; its whole result is recorded once as the addressee's answer and reaches every participant's next instruction | unenforced |
23
+ | DS-17 | Questions go to the user one at a time in record order, and no research cycle opens while a question waits for the user or a participant | unenforced |
24
+ | DS-18 | A research cycle whose input references (start inputs, subject, answers, materials) equal the last closed cycle's is not dispatched; the remaining disagreements and options go to the user. New evidence or a new alternative opens the next cycle in a continuation run | unenforced |
25
+ | DS-19 | Closing a cycle imports the convergence findings as claims with their origin author and the verifiers' verdicts, ends that verification cycle only, and leaves user decisions and user questions untouched | unenforced |
26
+ | DS-20 | An author's vote on its own claim is refused, not counted as a refutation — the convergence engine's final-state validation is reused | unenforced |
27
+ | DS-21 | A batch-start failure and a failure left after the dispatcher's retry loop are recorded per participant without deleting completed results; the cycle neither reopens research nor closes until the user chooses retry, replace or reduce, and a second, different choice for the same failure is refused | unenforced |
28
+ | DS-22 | A retry stays in the same run as a new invocation; a replacement continues in a run prepared with `--discussion-start <task-key>`, whose research input carries the earlier results under their original author and run, and every cycle records its roster | unenforced |
29
+ | DS-23 | A failed direct question waits for the user's choice; `reduce` drops it from the participants' pending questions and `replace` is refused for it | unenforced |
30
+ | DS-24 | Concurrent `cycle-open` calls for one run record one cycle | unenforced |
31
+ | DS-25 | On a `claude-code` lead, whose analysers run as native sessions, `settle` reads the common `record-dispatch` / `link-result` / `abandon-attempt` records: a linked result is a result, an attempt closed without one is a failure, and an open attempt refuses settlement | unenforced |
32
+ | DS-26 | A `discussion-question` prompt keeps the analysis contract but stays outside the analysis-core prompt equality group | unenforced |
33
+ | DS-27 | A confirmation names the draft version the user saw; a version older than the current records, or a stored confirmation followed by any later record, publishes nothing | unenforced |
34
+ | DS-28 | Completion is refused while the subject, a requirement, an in-scope or an excluded entry, a closed research cycle, a user or participant answer, or a failure choice is missing; remaining disagreements do not block and are carried into the revision with their standing | unenforced |
35
+ | DS-29 | A revision carries the subject, start inputs, requirements with the follow-up they apply to, scope and exclusions, direction, the user's confirmation, decisions, disagreements, evidence claims, unverified scope, every cycle's roster and every failure with the user's choice; a reduced roster is marked and its failure listed as unverified | unenforced |
36
+ | DS-30 | One confirmation publishes one revision, `<task-key>/revision-NNN` by completion sequence, written once read-only; a resent or concurrent confirmation returns that revision | unenforced |
37
+ | DS-31 | A publication interrupted before the revision file is written leaves no revision; resending the same confirmation publishes it | unenforced |
38
+ | DS-32 | A completed discussion takes no record but `reopen` naming its latest revision, and prepare refuses a new start input for it; after `reopen`, the new draft and the earlier revision read side by side, the earlier revision's bytes never change, and the next revision carries its id, content digest and the reason for change | unenforced |
39
+ | DS-33 | The final report's `discussion` block is written by report assembly, never by the report writer, and carries only the revision id and content digest (or the draft version); assembly refuses a block whose digest no longer matches the revision file, `validate-run` reports the mismatch, and the run passes the reachable `report-finalize` steps without real providers | unenforced |
40
+ | DS-34 | Finalizing a run whose discussion is still a draft publishes no revision; its report carries the draft version | unenforced |
41
+ | DS-35 | A follow-up brief carries the revision's common requirements and those of its follow-up label, each with its record id; the other follow-ups' requirements and the excluded scope are listed as out of scope; it passes `validators/validate-brief.py` and recommends `requirements-discovery`. A discussion with no follow-up lists its labels as unlinked | unenforced |
42
+ | DS-36 | Fields reused from the user's confirmations name their record in the revision; an observation method the revision does not carry is new meaning, so the brief stays `reporter-confirmations: pending` with an `intent-check:` row and prepare refuses it until the user confirms | unenforced |
43
+ | DS-37 | The follow-up's brief pins the discussion, revision id, content digest and requirement ids; prepare records them in the run inputs as `discussionRevisionRef`, and the manager launch packet carries the same reference and starts a new child at `requirements-discovery` | unenforced |
44
+ | DS-38 | A newer revision flags every linked follow-up `needs-impact-review` with the changes from its pinned revision; a follow-up never moves by itself (`follow-up-brief` for another revision is refused), only the follow-up the user adopts with `apply` moves, a resent `apply` returns the stored record, and a different choice for the same follow-up and revision is refused | unenforced |
45
+ | DS-39 | Adopting a revision for a follow-up that has an implementation-planning plan routes it to the plan amendment path and leaves its plan and brief byte-identical | unenforced |
46
+ | DS-40 | The target brief is written before the link record; a link write interrupted after the brief, or a torn link line, is completed by resending the same command, and the link is recorded once | unenforced |
47
+ | DS-41 | `links` re-reads each target's brief, also in another project; a target that cannot be read is `unknown`, never `current`; a brief this command did not write last is not replaced without `--replace` | unenforced |
48
+ | DS-42 | `confirm-completion` registers the published revision in the Memory Book without a prompt, through `okstra memory add --source-key discussion:<revision-id>`; the entry holds a summary of decisions, disagreements, risks and unverified scope with the revision id, content digest, project and task — not the start inputs or the agreed evidence — and searching the revision id finds it | unenforced |
49
+ | DS-43 | A re-discussion's revision is a new source key and a separate Memory Book entry | unenforced |
50
+ | DS-44 | A resent confirmation does not call the Memory Book again, and concurrent registrations of one revision leave one entry; with the discussion's registration state lost, the Memory Book's own source-key check returns the stored entry | `tests-js/memory.test.mjs::concurrent memory add --source-key of one key leaves one entry` |
51
+ | DS-45 | A failed registration leaves the revision published and `pending`; `status` lists it under `memoryRegistration` and `memory-sync` retries it with the same source key | unenforced |
52
+ | DS-46 | A summary the Memory Book refuses as a likely secret is `refused` with the secret kinds shown; `memory-sync` does not retry it, and an unchanged `--summary-file` is refused; only a changed summary registers | `tests-js/memory.test.mjs::memory add --source-key --json reports a secret refusal as JSON on stdout` |
53
53
  | DS-47 | `memory add` without `--source-key` writes the same index row and frontmatter as before and takes no source-key lock | `tests-js/memory.test.mjs::a plain memory add keeps its index row and frontmatter free of a source key` |
54
- | DS-48 | `okstra manager task sync` records a discussion child's state, phase, pending questions, revisions with their change reasons and each follow-up's pinned revision and review state by reference — no requirement or revision content — without writing to the discussion's project; `task status` counts the child under `discussion`, never `done`, and a discussion completes with no manager | `tests/test_okstra_manager_sync.py::test_sync_references_a_discussion_and_counts_it_apart_from_follow_up_completion` |
55
- | DS-49 | A discussion record or follow-up brief the manager cannot read is `unknown` on the next sync, not its last synced value | `tests/test_okstra_manager_sync.py::test_an_unreadable_discussion_source_is_unknown_not_its_last_sync` |
56
- | DS-50 | A manager child without a registered brief launches with the follow-up brief `follow-up-brief` wrote for it, found in the last-synced links of a discussion child of the same manager task, and carries its pinned revision | `tests/test_okstra_manager_sync.py::test_sync_references_a_discussion_and_counts_it_apart_from_follow_up_completion` |
57
- | DS-51 | `okstra-discussion` (`okstra wizard init --task-type discussion`) and `okstra-run`'s task-type pick produce the same `render-bundle` argv and the same prepared run inputs | `tests/run/test_discussion_prepare.py::test_both_entrypoints_prepare_the_same_discussion_run` |
58
- | DS-52 | `okstra.sh` forwards `--discussion-start`, asks for it instead of a brief, and passes no `--task-brief` for a discussion | `tests/run/test_okstra_sh_discussion_passthrough.py::test_okstra_sh_forwards_the_discussion_start_and_a_continuation_without_a_brief` |
59
- | DS-53 | A same-provider and a mixed-provider roster go through the same prepare, assignment and research-batch `materialize` path; on a `claude-code` lead only the analysers outside the host's provider are planned by `worker-dispatch` as `cli-wrapper` | `tests/run/test_discussion_prepare.py::test_same_and_mixed_provider_rosters_take_the_same_research_path` |
60
- | DS-54 | The lead instructions carry the boundary's source-edit and implementation-plan prohibitions; every discussion worker runs under a `source-readonly` write policy, and a worker that edits source is refused by the common mutation audit and recorded as a failure, never a result | `tests/run/test_discussion_prepare.py::test_a_discussion_worker_that_edits_source_is_refused_and_records_no_result` |
61
- | DS-55 | Concurrent `apply` choices for one follow-up and revision record one `apply`; the other choices are refused and the brief follows only the recorded choice | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_concurrent_choices_for_one_follow_up_record_one_apply` |
62
- | DS-56 | One isolated project runs the whole flow through prepare and `okstra discussion`: a description start (no research before the subject is confirmed), a refutation cycle, an interrupted run resumed with the same pending question and a resent answer stored once, a second cycle opened only by new input, completion with a remaining disagreement and Memory Book registration, two follow-ups at `requirements-discovery` with the revision in the run inputs, a re-discussion, and adoption of the new revision by one follow-up only; the project source stays unchanged | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up` |
63
- | DS-57 | After `reopen` the draft starts with the reopened revision's requirements and scope under their original record ids, each marked with that revision; completion needs no re-entry of them; adding an item the draft holds returns it; `withdraw` removes one item with the user's reason, a resend returns it and a second withdrawal of the same item is refused; the next revision's `itemChanges` lists what it carried, added and withdrawn, `impact` shows each withdrawal's reason, and the earlier revision's bytes do not change | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_completion.py::test_a_reopened_draft_carries_the_previous_items_until_the_user_withdraws_them`, `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_only_the_follow_up_the_user_selects_adopts_the_new_revision` |
64
- | DS-58 | A follow-up routed to plan amendment moves only through `complete-amendment`, and only after the target has an implementation-planning report newer than the one at routing with `frontmatter.approved: true`; without it the command is refused naming what is missing and `links` stays `amendment-pending` with that reason (`unknown` when the plan cannot be read). Completion rewrites the brief under the `--replace` rule, records the previous and new revision, the routed `apply` and the plan report, leaves every plan byte unchanged, turns the target `current`, and a resend returns the record | `scripts/okstra_ctl/phases/discussion/tests/test_discussion_followup.py::test_a_routed_adoption_moves_the_pin_only_after_the_user_approves_the_amended_plan` |
54
+ | DS-48 | `okstra manager task sync` records a discussion child's state, phase, pending questions, revisions with their change reasons and each follow-up's pinned revision and review state by reference — no requirement or revision content — without writing to the discussion's project; `task status` counts the child under `discussion`, never `done`, and a discussion completes with no manager | unenforced |
55
+ | DS-49 | A discussion record or follow-up brief the manager cannot read is `unknown` on the next sync, not its last synced value | unenforced |
56
+ | DS-50 | A manager child without a registered brief launches with the follow-up brief `follow-up-brief` wrote for it, found in the last-synced links of a discussion child of the same manager task, and carries its pinned revision | unenforced |
57
+ | DS-51 | `okstra-discussion` (`okstra wizard init --task-type discussion`) and `okstra-run`'s task-type pick produce the same `render-bundle` argv and the same prepared run inputs | unenforced |
58
+ | DS-52 | `okstra.sh` forwards `--discussion-start`, asks for it instead of a brief, and passes no `--task-brief` for a discussion | unenforced |
59
+ | DS-53 | A same-provider and a mixed-provider roster go through the same prepare, assignment and research-batch `materialize` path; on a `claude-code` lead only the analysers outside the host's provider are planned by `worker-dispatch` as `cli-wrapper` | unenforced |
60
+ | DS-54 | The lead instructions carry the boundary's source-edit and implementation-plan prohibitions; every discussion worker runs under a `source-readonly` write policy, and a worker that edits source is refused by the common mutation audit and recorded as a failure, never a result | unenforced |
61
+ | DS-55 | Concurrent `apply` choices for one follow-up and revision record one `apply`; the other choices are refused and the brief follows only the recorded choice | unenforced |
62
+ | DS-56 | One isolated project runs the whole flow through prepare and `okstra discussion`: a description start (no research before the subject is confirmed), a refutation cycle, an interrupted run resumed with the same pending question and a resent answer stored once, a second cycle opened only by new input, completion with a remaining disagreement and Memory Book registration, two follow-ups at `requirements-discovery` with the revision in the run inputs, a re-discussion, and adoption of the new revision by one follow-up only; the project source stays unchanged | unenforced |
63
+ | DS-57 | After `reopen` the draft starts with the reopened revision's requirements and scope under their original record ids, each marked with that revision; completion needs no re-entry of them; adding an item the draft holds returns it; `withdraw` removes one item with the user's reason, a resend returns it and a second withdrawal of the same item is refused; the next revision's `itemChanges` lists what it carried, added and withdrawn, `impact` shows each withdrawal's reason, and the earlier revision's bytes do not change | unenforced |
64
+ | DS-58 | A follow-up routed to plan amendment moves only through `complete-amendment`, and only after the target has an implementation-planning report newer than the one at routing with `frontmatter.approved: true`; without it the command is refused naming what is missing and `links` stays `amendment-pending` with that reason (`unknown` when the plan cannot be read). Completion rewrites the brief under the `--replace` rule, records the previous and new revision, the routed `apply` and the plan report, leaves every plan byte unchanged, turns the target `current`, and a resend returns the record | unenforced |
65
65
 
66
66
  ## 1. Purpose
67
67
 
@@ -165,20 +165,20 @@ The design's acceptance scenarios and the tests that prove them. Each test drive
165
165
 
166
166
  | # | Scenario | Tests |
167
167
  |---|---|---|
168
- | 1 | A short description starts the discussion; research runs in parallel only after the user confirms the subject | `test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up`, `tests/run/test_discussion_prepare.py::test_direct_entry_starts_without_a_brief_and_records_the_start_input`, `tests/run/test_discussion_prepare.py::test_a_claude_code_lead_reaches_the_analyser_dispatch_plan` |
169
- | 2 | Same-provider and mixed-provider rosters use the same prepare and assignment path | `tests/run/test_discussion_prepare.py::test_same_and_mixed_provider_rosters_take_the_same_research_path` |
168
+ | 1 | A short description starts the discussion; research runs in parallel only after the user confirms the subject | `test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up` |
169
+ | 2 | Same-provider and mixed-provider rosters use the same prepare and assignment path | unenforced |
170
170
  | 3 | A question to one participant and its answer reach every participant's next input | `test_discussion_workflow.py::test_a_direct_question_is_dispatched_alone_and_its_answer_reaches_every_participant` |
171
- | 4 | Resuming while a question waits restores it, and a stored answer is not processed twice | `tests/run/test_discussion_prepare.py::test_a_resumed_run_restores_decisions_and_pending_questions`, `test_discussion_store.py::test_a_resent_answer_is_stored_once_and_a_different_one_is_refused`, `test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up` |
171
+ | 4 | Resuming while a question waits restores it, and a stored answer is not processed twice | `test_discussion_store.py::test_a_resent_answer_is_stored_once_and_a_different_one_is_refused`, `test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up` |
172
172
  | 5 | A repeated claim set stops further calls and presents disagreements and options | `test_discussion_workflow.py::test_a_repeated_input_is_not_researched_again_and_goes_to_the_user` |
173
173
  | 6 | With a grounded disagreement left, the user's risk confirmation publishes a revision that carries it | `test_discussion_completion.py::test_the_user_completes_with_disagreements_and_the_revision_keeps_them` |
174
174
  | 7 | Replacing a failed participant opens a new run of the same discussion and keeps earlier authors and results | `test_discussion_workflow.py::test_a_replacement_continues_in_a_new_run_and_keeps_the_original_authors` |
175
175
  | 8 | After a re-discussion both follow-ups of the first revision need impact review; only the one the user picks adopts the new revision | `test_discussion_followup.py::test_only_the_follow_up_the_user_selects_adopts_the_new_revision`, `test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up` |
176
176
  | 9 | A failed Memory Book registration keeps the revision; retries leave one entry per revision | `test_discussion_memory.py::test_a_failed_registration_keeps_the_revision_and_memory_sync_recovers`, `test_discussion_memory.py::test_a_resent_or_concurrent_registration_leaves_one_entry` |
177
- | 10 | A discussion completes without a manager; a linked manager keeps discussion completion apart from implementation completion | `tests/test_okstra_manager_sync.py::test_sync_references_a_discussion_and_counts_it_apart_from_follow_up_completion` |
178
- | 11 | A discussion run neither edits project source nor writes a detailed implementation plan | `tests/run/test_discussion_prepare.py::test_a_discussion_worker_that_edits_source_is_refused_and_records_no_result`, `test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up` |
179
- | 12 | The `okstra-run` wizard starts a discussion without a brief; other task types keep their question order | `tests/domain/wizard/test_discussion_start.py::test_a_requested_discussion_starts_a_new_task_without_a_brief`, `tests/domain/wizard/test_discussion_start.py::test_an_existing_task_continues_its_discussion_without_a_brief_step`, `tests/domain/wizard/test_task_selection.py::test_brand_new_task_branches_into_group_then_brief_then_type_then_id`, `tests/run/test_discussion_prepare.py::test_both_entrypoints_prepare_the_same_discussion_run` |
180
- | 13 | A lead host outside the supported combinations is refused before the run | `tests/adapters/dispatch/test_cmux.py::test_a_non_claude_lead_still_needs_render_only_outside_cmux` |
181
- | 14 | A follow-up starts at `requirements-discovery` and its run inputs keep the revision reference | `test_discussion_followup.py::test_a_follow_up_brief_carries_its_requirements_and_starts_at_requirements_discovery`, `tests/test_okstra_manager_launch.py::test_build_launch_packet_carries_a_discussion_follow_up_revision_and_its_first_phase` |
177
+ | 10 | A discussion completes without a manager; a linked manager keeps discussion completion apart from implementation completion | unenforced |
178
+ | 11 | A discussion run neither edits project source nor writes a detailed implementation plan | `test_discussion_end_to_end.py::test_a_discussion_runs_from_a_description_to_one_adopted_follow_up` |
179
+ | 12 | The `okstra-run` wizard starts a discussion without a brief; other task types keep their question order | unenforced |
180
+ | 13 | A lead host outside the supported combinations is refused before the run | unenforced |
181
+ | 14 | A follow-up starts at `requirements-discovery` and its run inputs keep the revision reference | `test_discussion_followup.py::test_a_follow_up_brief_carries_its_requirements_and_starts_at_requirements_discovery` |
182
182
  | 15 | A secret refusal is shown and not retried; the revision stays | `test_discussion_memory.py::test_a_secret_refusal_is_shown_and_retried_only_after_the_summary_changes` |
183
183
 
184
184
  Scenario 11 rests on the write-policy audit for source edits. For plans it rests on the boundary text only: the `validate-run` forbidden-action scan (`validators/forbidden_actions.py::forbidden_patterns_for`) matches shell commands, so a plan written into a worker result or the report narrative is not detected.
@@ -31,17 +31,8 @@ def _has_discussion(state: WizardState) -> bool:
31
31
 
32
32
 
33
33
  def _brief(state: WizardState) -> str:
34
- """새 task 는 방금 고른 brief, 기존 task 는 매니페스트에 등록된 brief.
35
-
36
- 토론 run 이 등록한 brief 는 prepare 가 만든 입력 문서라 후보가 아니다."""
37
- if state.brief_path:
38
- return state.brief_path
39
- existing = state.existing_brief_path
40
- if not existing:
41
- return ""
42
- generated = DiscussionStore(Path(state.project_root), _task_key(state)).input_path
43
- resolved = Path(existing) if Path(existing).is_absolute() else Path(state.project_root) / existing
44
- return "" if resolved.resolve() == generated.resolve() else existing
34
+ """새 task 는 방금 고른 brief, 기존 task 는 매니페스트에 등록된 brief."""
35
+ return state.brief_path or state.existing_brief_path
45
36
 
46
37
 
47
38
  def _accept(state: WizardState, value: str) -> str:
@@ -80,7 +80,7 @@ taskType: "{{FM_TASK_TYPE}}"
80
80
 
81
81
  > Analysers MUST NOT expand the hypothesis space or evidence collection into items listed here. If an analyser believes an excluded item is causally linked to the symptom, it is reported as a recommended follow-up analysis task in the final report — never silently merged into the current root-cause narrative. If this section is left empty, analysers treat any cause beyond what `Symptom Summary` and `Reproduction Context` describe as out of scope by default.
82
82
 
83
- **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.
83
+ **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.
84
84
 
85
85
  ## Questions for Analysers
86
86