okstra 0.232.0 → 0.233.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.
- package/README.md +19 -283
- package/dist/cli-registry.mjs +8 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.mjs +2 -17
- package/dist/lib/memory-auto-register.mjs.map +1 -1
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +36 -5
- package/docs/architecture.md +10 -4
- package/docs/cli.md +279 -2
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +31 -41
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
- package/runtime/prompts/coding-preflight/clean-code.md +18 -20
- package/runtime/prompts/coding-preflight/overview.md +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -1
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
- package/runtime/python/okstra_ctl/code_review_census.py +93 -2
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +140 -15
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +33 -6
- package/runtime/python/okstra_ctl/manager_cli.py +122 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +42 -3
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +38 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +179 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
- package/runtime/python/okstra_ctl/run.py +43 -35
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_project/state.py +20 -0
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +58 -50
- package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
- package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +24 -0
- package/runtime/skills/okstra-memory/SKILL.md +1 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +93 -36
|
@@ -19,6 +19,7 @@ from .paths import (
|
|
|
19
19
|
task_timeline_file,
|
|
20
20
|
)
|
|
21
21
|
from .worker_artifacts import worker_artifact_paths
|
|
22
|
+
from .report_contract import report_authoring_format, report_authoring_suffix
|
|
22
23
|
from .verification_input_ref import (
|
|
23
24
|
VerificationInputReference, artifact_fields, artifact_fields_from_context,
|
|
24
25
|
)
|
|
@@ -322,6 +323,8 @@ def _hydrate_active_source_artifacts(ctx: Mapping[str, str]) -> dict[str, str]:
|
|
|
322
323
|
|
|
323
324
|
def _compact_run_hints(ctx: Mapping[str, Any]) -> dict[str, Any]:
|
|
324
325
|
return {
|
|
326
|
+
"reportAuthoringFormat": ctx.get("REPORT_AUTHORING_FORMAT", "markdown-v1"),
|
|
327
|
+
"usageAccountingPolicy": ctx.get("USAGE_ACCOUNTING_POLICY", "strict"),
|
|
325
328
|
"runRoot": ctx.get("RUN_DIR_RELATIVE_PATH", ""),
|
|
326
329
|
"stage": ctx.get("RUN_STAGE", ""),
|
|
327
330
|
"fileSuffix": ctx.get("RUN_FILE_SUFFIX", ""),
|
|
@@ -342,10 +345,14 @@ def _hydrate_from_hints(
|
|
|
342
345
|
hints: Mapping[str, Any],
|
|
343
346
|
timestamps: Any,
|
|
344
347
|
) -> dict[str, Any]:
|
|
348
|
+
from okstra_token_usage.policy import usage_accounting_policy
|
|
349
|
+
|
|
345
350
|
paths = _build_path_set(identity, hints)
|
|
346
351
|
filenames = _filename_fields(paths)
|
|
347
352
|
relative = _relative_fields(paths["project_root"], paths)
|
|
348
353
|
return {
|
|
354
|
+
"REPORT_AUTHORING_FORMAT": paths["report_authoring_format"],
|
|
355
|
+
"USAGE_ACCOUNTING_POLICY": usage_accounting_policy(_mapping(hints.get("run"))),
|
|
349
356
|
**_identity_fields(identity),
|
|
350
357
|
**_runtime_fields(paths),
|
|
351
358
|
**_absolute_fields(paths),
|
|
@@ -361,12 +368,14 @@ def _build_path_set(identity: Mapping[str, Any], hints: Mapping[str, Any]) -> di
|
|
|
361
368
|
workspace_root = Path(str(identity.get("workspaceRoot", "")))
|
|
362
369
|
project_hints = _mapping(hints.get("project"))
|
|
363
370
|
run_hints = _mapping(hints.get("run"))
|
|
371
|
+
authoring_format = report_authoring_format(run_hints)
|
|
364
372
|
task_root = _project_path(project_root, _task_root_hint(hints))
|
|
365
373
|
run_root = _project_path(project_root, str(run_hints.get("runRoot", "")))
|
|
366
374
|
task_type_segment = _segment(identity, "taskType")
|
|
367
375
|
sequences = _sequences(run_hints)
|
|
368
376
|
suffixes = _suffixes(task_type_segment, sequences)
|
|
369
377
|
paths = {
|
|
378
|
+
"report_authoring_format": authoring_format,
|
|
370
379
|
"project_root": project_root,
|
|
371
380
|
"workspace_root": workspace_root,
|
|
372
381
|
"okstra_root": _project_path(project_root, str(project_hints.get("okstraRoot", OKSTRA_RELATIVE))),
|
|
@@ -382,7 +391,7 @@ def _build_path_set(identity: Mapping[str, Any], hints: Mapping[str, Any]) -> di
|
|
|
382
391
|
"suffixes": suffixes,
|
|
383
392
|
}
|
|
384
393
|
paths.update(_task_path_set(task_root))
|
|
385
|
-
paths.update(_run_path_set(run_root, task_type_segment, sequences, suffixes))
|
|
394
|
+
paths.update(_run_path_set(run_root, task_type_segment, sequences, suffixes, authoring_format))
|
|
386
395
|
paths.update(_discovery_path_set(paths["discovery_dir"]))
|
|
387
396
|
return paths
|
|
388
397
|
|
|
@@ -413,6 +422,7 @@ def _run_path_set(
|
|
|
413
422
|
task_type_segment: str,
|
|
414
423
|
sequences: Mapping[str, str],
|
|
415
424
|
suffixes: Mapping[str, str],
|
|
425
|
+
authoring_format: str,
|
|
416
426
|
) -> dict[str, Path]:
|
|
417
427
|
run_prompts = run_dir / "prompts"
|
|
418
428
|
worker_results = run_dir / "worker-results"
|
|
@@ -434,7 +444,7 @@ def _run_path_set(
|
|
|
434
444
|
if task_type_segment == "implementation"
|
|
435
445
|
else run_dir / "carry"
|
|
436
446
|
),
|
|
437
|
-
**_run_files(run_dir, run_prompts, worker_results, task_type_segment, sequences, suffixes),
|
|
447
|
+
**_run_files(run_dir, run_prompts, worker_results, task_type_segment, sequences, suffixes, authoring_format),
|
|
438
448
|
}
|
|
439
449
|
|
|
440
450
|
|
|
@@ -445,6 +455,7 @@ def _run_files(
|
|
|
445
455
|
task_type_segment: str,
|
|
446
456
|
sequences: Mapping[str, str],
|
|
447
457
|
suffixes: Mapping[str, str],
|
|
458
|
+
authoring_format: str,
|
|
448
459
|
) -> dict[str, Path]:
|
|
449
460
|
run_manifests = run_dir / "manifests"
|
|
450
461
|
run_state = run_dir / "state"
|
|
@@ -478,7 +489,7 @@ def _run_files(
|
|
|
478
489
|
"codex_worker_result": worker_results / f"codex-worker{suffixes['worker_results']}.md",
|
|
479
490
|
"antigravity_worker_result": worker_results / f"antigravity-worker{suffixes['worker_results']}.md",
|
|
480
491
|
"report_writer_worker_result": worker_results / f"report-writer-worker{suffixes['worker_results']}.md",
|
|
481
|
-
"report_writer_narrative": worker_results / f"report-writer-narrative{suffixes['worker_results']}
|
|
492
|
+
"report_writer_narrative": worker_results / f"report-writer-narrative{suffixes['worker_results']}{report_authoring_suffix(authoring_format)}",
|
|
482
493
|
"approval_decisions": run_state / f"approval-decisions-{task_type_segment}-{sequences['state']}.json",
|
|
483
494
|
"design_preparation": run_state / f"design-preparation-{task_type_segment}-{sequences['state']}.json",
|
|
484
495
|
"plan_body_verification": run_state / f"plan-body-verification-{task_type_segment}-{sequences['state']}.json",
|
|
@@ -557,6 +557,7 @@ def compute_run_paths(
|
|
|
557
557
|
task_type: str,
|
|
558
558
|
run_seq_override: Optional[int] = None,
|
|
559
559
|
stage: Optional[int] = None,
|
|
560
|
+
report_authoring_format: str = "markdown-v1",
|
|
560
561
|
) -> dict:
|
|
561
562
|
"""주어진 identity 와 task-type 에 대해 모든 path/segment 값을 계산해
|
|
562
563
|
dict 로 돌려준다. 부수효과 없음.
|
|
@@ -688,7 +689,10 @@ def compute_run_paths(
|
|
|
688
689
|
codex_worker_result = worker_results / f"codex-worker{suffixes['worker_results']}.md"
|
|
689
690
|
antigravity_worker_result = worker_results / f"antigravity-worker{suffixes['worker_results']}.md"
|
|
690
691
|
report_writer_worker_result = worker_results / f"report-writer-worker{suffixes['worker_results']}.md"
|
|
691
|
-
|
|
692
|
+
from .report_contract import report_authoring_suffix
|
|
693
|
+
|
|
694
|
+
authoring_suffix = report_authoring_suffix(report_authoring_format)
|
|
695
|
+
report_writer_narrative = worker_results / f"report-writer-narrative{suffixes['worker_results']}{authoring_suffix}"
|
|
692
696
|
approval_decisions = run_state / f"approval-decisions-{task_type_segment}-{seqs['state']}.json"
|
|
693
697
|
design_preparation = run_state / f"design-preparation-{task_type_segment}-{seqs['state']}.json"
|
|
694
698
|
plan_body_verification = run_state / f"plan-body-verification-{task_type_segment}-{seqs['state']}.json"
|
|
@@ -714,6 +718,7 @@ def compute_run_paths(
|
|
|
714
718
|
).joinpath(*RUN_VALIDATOR_RELATIVE)
|
|
715
719
|
|
|
716
720
|
abs_paths = {
|
|
721
|
+
"REPORT_AUTHORING_FORMAT": report_authoring_format,
|
|
717
722
|
"PROJECT_ID": project_id,
|
|
718
723
|
"PROJECT_ROOT": str(project_root),
|
|
719
724
|
"WORKSPACE_ROOT": str(workspace_root),
|
|
@@ -31,6 +31,7 @@ class PhaseRecord:
|
|
|
31
31
|
migrated: bool
|
|
32
32
|
view_module: str
|
|
33
33
|
view_function: str
|
|
34
|
+
requires_host_rules: bool
|
|
34
35
|
|
|
35
36
|
|
|
36
37
|
def _view(package_name: str, function: str, *, phase_package: bool) -> tuple[str, str]:
|
|
@@ -44,9 +45,11 @@ def _record(
|
|
|
44
45
|
package_name: str,
|
|
45
46
|
migrated: bool,
|
|
46
47
|
view_function: str,
|
|
48
|
+
*,
|
|
49
|
+
requires_host_rules: bool = False,
|
|
47
50
|
) -> PhaseRecord:
|
|
48
51
|
module, function = _view(package_name, view_function, phase_package=migrated)
|
|
49
|
-
return PhaseRecord(task_type, package_name, migrated, module, function)
|
|
52
|
+
return PhaseRecord(task_type, package_name, migrated, module, function, requires_host_rules)
|
|
50
53
|
|
|
51
54
|
|
|
52
55
|
# 이전되지 않은 단계는 기존 ``prompts/profiles`` 위치를 명시적으로 쓴다.
|
|
@@ -67,8 +70,14 @@ PHASES: tuple[PhaseRecord, ...] = (
|
|
|
67
70
|
True,
|
|
68
71
|
"build_implementation_option_selection_view",
|
|
69
72
|
),
|
|
70
|
-
_record(
|
|
71
|
-
|
|
73
|
+
_record(
|
|
74
|
+
"implementation-planning", "implementation_planning", True,
|
|
75
|
+
"build_implementation_planning_view", requires_host_rules=True,
|
|
76
|
+
),
|
|
77
|
+
_record(
|
|
78
|
+
"implementation", "implementation", True,
|
|
79
|
+
"build_implementation_view", requires_host_rules=True,
|
|
80
|
+
),
|
|
72
81
|
_record("final-verification", "final_verification", True, "build_final_verification_view"),
|
|
73
82
|
_record("release-handoff", "release_handoff", True, "build_release_handoff_view"),
|
|
74
83
|
_record("discussion", "discussion", True, "build_discussion_view"),
|
|
@@ -224,13 +233,21 @@ def _report_template_filename(task_type: str, logical_name: str) -> str | None:
|
|
|
224
233
|
|
|
225
234
|
|
|
226
235
|
|
|
227
|
-
def host_rules(asset_root: Path, task_type: str) -> Path:
|
|
228
|
-
"""
|
|
236
|
+
def host_rules(asset_root: Path, task_type: str) -> Path | None:
|
|
237
|
+
"""선언된 단계의 호스트 지침을 같은 자산 루트에서 찾고 누락을 거부한다."""
|
|
229
238
|
record = phase_record(task_type)
|
|
239
|
+
if not record.requires_host_rules:
|
|
240
|
+
return None
|
|
230
241
|
root = package_root(asset_root) if record.migrated else None
|
|
231
242
|
if root is not None:
|
|
232
|
-
|
|
233
|
-
|
|
243
|
+
path = root / "phases" / record.package_name / "host-rules.md"
|
|
244
|
+
else:
|
|
245
|
+
path = asset_root / "prompts" / "host-orchestration" / f"{task_type}.md"
|
|
246
|
+
if not path.is_file():
|
|
247
|
+
raise PhaseAssetError(
|
|
248
|
+
f"host orchestration rules file not found for task-type {task_type}: {path}"
|
|
249
|
+
)
|
|
250
|
+
return path
|
|
234
251
|
|
|
235
252
|
|
|
236
253
|
def profile_sidecar(asset_root: Path, logical_name: str) -> Path:
|
|
@@ -6,9 +6,9 @@ to recover a stale stage SHA, and what the chaining queue does when the next
|
|
|
6
6
|
stage is not ready. They are not lead phase rules — the lead's rules live in
|
|
7
7
|
`prompts/profiles/`.
|
|
8
8
|
|
|
9
|
-
This file is the single source.
|
|
10
|
-
|
|
11
|
-
|
|
9
|
+
This file is the single source. The wizard returns its path for the host to read
|
|
10
|
+
before preparation. Each run's `instruction-set/host-orchestration-rules.md` is
|
|
11
|
+
generated from it at prepare time. Edit here.
|
|
12
12
|
|
|
13
13
|
### Step 5.1 (implementation only): blocking local conformance waiver offer
|
|
14
14
|
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md
CHANGED
|
@@ -29,8 +29,10 @@ Do not scan holistically and stop when it "looks fine". Work the matrix exhausti
|
|
|
29
29
|
|
|
30
30
|
Use the captured `review-rules.json` IDs and `clean-code.md` "Finding evidence
|
|
31
31
|
and grading" for every finding. Apply M1 and M2 to each changed function, including
|
|
32
|
-
named test helpers.
|
|
33
|
-
|
|
32
|
+
named test helpers. Establish an observable defect, an explicit applicable project
|
|
33
|
+
rule breach or a concrete design or maintenance impact; a preferred name or flow
|
|
34
|
+
alone is insufficient. Correct execution does not waive an established violation.
|
|
35
|
+
Return a plan conflict when the authorized placement cannot
|
|
34
36
|
satisfy the rules; do not retain a violation solely to obey a file restriction.
|
|
35
37
|
Resolve conflicts by `overview.md` policy precedence: explicit repository
|
|
36
38
|
instructions and declared architecture, the common pack, then surrounding code
|
|
@@ -38,19 +40,19 @@ conventions. Existing violations alone do not waive an explicit rule.
|
|
|
38
40
|
|
|
39
41
|
1. **List every changed file:** `git diff --name-only <stage-base>..HEAD`. Apply the shared census exclusion policy and record each exclusion with its reason; executable configuration is not excluded by extension alone. Cover the retained worklist to the end; no sampling.
|
|
40
42
|
2. **Classify each file and select its rule set** from the conventions the preflight already loaded (do NOT re-derive the rules here — read them from the routed pack):
|
|
41
|
-
- any file retained by the shared census exclusion policy → applicable `clean-code.md` checks: truthful + standalone names, one identifier one meaning per file (a key parameter must not take the name a sibling signature gives the entity),
|
|
43
|
+
- any file retained by the shared census exclusion policy → applicable `clean-code.md` checks: truthful + standalone names, one identifier one meaning per file (a key parameter must not take the name a sibling signature gives the entity), cohesive responsibility, manageable complexity and consistent abstraction levels, DRY (incl. scattered domain literals + documented forks), YAGNI, meaningful names for policy values and units, control flow whose decisions and exit paths can be followed, comments explain why. Function size, deep nesting and inline phases prompt closer review; counts alone are not findings or reasons to extract code.
|
|
42
44
|
- The YAGNI cell also counts callers, not just their existence: an abstraction layer this diff *introduces* — helper module, strategy / factory / builder, indirection or wrapper layer, interface or abstract base — with exactly **one** caller after the change is an inline candidate under `overview.md` core principle 2 ("name the second caller now, or inline"). Collapse it into that call site unless one of four exits applies and you record which: the approved plan declares it as a test seam or variation-point extraction, the project-context preflight projection declares hexagonal architecture and it is a port at the domain boundary, it breaks a real import cycle, or its single caller is a published package's public API. This targets reusable layers, not a local helper that names a cohesive step or separates mixed abstraction levels; line count alone does not justify extraction.
|
|
43
45
|
- The YAGNI cell is a grep, not an impression: for every identifier this diff adds — and every one whose last caller it removes — search the whole repository and name the caller you found. A declaration-only, test-only, or commented-out hit is not a caller. Zero callers means delete it here (or fold an added parameter back into its single call site), unless the approved plan reserves it for a named later stage or something outside project code calls it (framework entrypoint, implemented interface method, migration hook, published-package API) — in which case record that justification in the audit note. Fixing it now is cheaper than the verifier's Static design gate, where the same finding is blocking and fails the stage (`_implementation-verifier.md` "Caller-less identifier").
|
|
44
46
|
- a file that wraps a third-party / library call → `clean-code.md` "Wrapping a third-party call": the wrapper adds behaviour the library does not already provide (read the installed library source before keeping a recovery branch — a `catch` repeating the library's own retry recovers nothing), no comment names a condition the call site does not establish, and a rethrow keeps the original error as `cause`.
|
|
45
47
|
- a file that decides, mutates, or persists state → `clean-code.md` "Mutation and state boundaries": decide on the direct identifier rather than a status/flag proxy, capture before-state in one snapshot ahead of the mutating boundary, update only this work's owned fields on an existing row, re-read state before calling a zero-affected-rows write success or failure, put priority-between-inputs in a named domain function, and keep error messages to what was actually observed. Also check that no state union/enum was re-declared beside an authoritative one the domain or a dependency exports.
|
|
46
|
-
- test file (`*.spec.*` / `*.test.*` / `test_*.py` / `*_test.go` …) → `clean-code.md` "Testing discipline": no self-mocking of the SUT, behavioral (outcome) assertions not interaction-only, no tautological delegation assertion, no effect claimed under its own mock, shared-fixture defaults left on the ordinary path, setup values that actually separate the scenarios, every new test helper/mock used by a test in this same diff, no positional mock-argument access (`rg 'mock\.calls'`),
|
|
48
|
+
- test file (`*.spec.*` / `*.test.*` / `test_*.py` / `*_test.go` …) → `clean-code.md` "Testing discipline": no self-mocking of the SUT, behavioral (outcome) assertions not interaction-only, no tautological delegation assertion, no effect claimed under its own mock, shared-fixture defaults left on the ordinary path, setup values that actually separate the scenarios, every new test helper/mock used by a test in this same diff, no positional mock-argument access (`rg 'mock\.calls'`), retained or strengthened tests distinguishing changed core behavior and meaningful failures, selective mutation checks where regression detection is uncertain or project rules require them, assertions on the last write to a record rather than an intermediate one, and test titles naming their unit plus the single condition each case isolates.
|
|
47
49
|
- port / adapter / domain file, when the hexagonal overlay is loaded → `architectures/hexagonal.md`: ports declare contracts rather than implement business decisions; the domain owns policy, and adapters may execute its query specifications efficiently. Do not infer a violation from complex SQL, domain-oriented query names or post-fetch processing alone, or require `findAll` plus in-memory filtering. Check domain placement, inward dependencies and touched concrete-adapter dependencies under the policy precedence above. Apply H1–H6 when the overlay is selected by declaration or layout; H5 alone retains its undeclared-style advisory exception.
|
|
48
50
|
- a service file, when the hexagonal overlay is loaded → `architectures/hexagonal.md` Rule H6: inspect whether changed service code implements a business decision rather than orchestrating a domain-owned one. A private method's domain-oriented name alone is not evidence. Orchestration control flow, DTO mapping and calling a domain predicate are not violations.
|
|
49
51
|
- a file that reads input from outside the process (request body, query, header, upload, message, webhook) or acts on its behalf → `clean-code.md` "Untrusted input and security": a size/count bound rejects oversized input before any check that grows faster than the input (a validator that runs every rule, such as class-validator without `stopAtFirstError`, does not stop at a failed `@ArrayMaxSize`), input reaches SQL / shell / paths / server-side fetches / templates / regexes only through parameters, allowlists or escaping, a new entry point carries the auth guard and compares the caller with the owner of an input-chosen id, no secret or personal data reaches code, logs or responses, and nothing evaluates or unsafely deserializes input.
|
|
50
52
|
- every changed source file → `clean-code.md` "Trace what this change can do wrong": walk the error, partial, concurrent and selection paths this diff creates to their end — past the failures the plan lists, and including where a cleaning `try` registers its cleanup target relative to each call that can throw — and fix wherever a wrong result comes out. Name the input that produces it — if you cannot name one, there is nothing to fix here and you move on rather than restructuring code that works.
|
|
51
53
|
A file can hold several roles — apply every rule set that fits it.
|
|
52
54
|
3. **Decide clean-or-finding for each cell.** Read the full file when a rule needs context (never judge a port/adapter/domain or a naming rule from the hunk alone).
|
|
53
|
-
4. **Fix each finding in place** before the commit.
|
|
55
|
+
4. **Fix each finding in place** before the commit. For an evidenced readability problem, sketch how the fix resolves its concrete consequence in your audit note, then apply it. Choose the smallest suitable change, such as a clearer condition, a named value or a cohesive helper. When the fix is genuinely out of this stage's scope, record it as an `Out-of-plan` note instead of silently leaving it.
|
|
54
56
|
|
|
55
57
|
## Coverage footer (BLOCKING deliverable)
|
|
56
58
|
|
|
@@ -60,7 +62,7 @@ Account for excluded files with their shared-census exclusion reasons in the sam
|
|
|
60
62
|
footer. Examined files plus excluded files cover the complete changed-file list;
|
|
61
63
|
an exclusion does not claim a clean inspection.
|
|
62
64
|
|
|
63
|
-
`Coverage: users.service.ts [names: clean,
|
|
65
|
+
`Coverage: users.service.ts [names: clean, cohesion: fixed 1], users.repository.adapter.ts [hexagonal: fixed 1, names: clean], users.service.spec.ts [testing-discipline: clean]; excluded: README.md [prose documentation]`
|
|
64
66
|
|
|
65
67
|
`clean` is a result you assert, not a blank you leave. Naming the rule set without its outcome reads identically whether you checked it or skipped it, which is exactly what this footer exists to distinguish — the completion self-check and any reviewer read it to confirm nothing in the diff was skipped. A sweep with no footer, or a footer whose entries carry no outcome, is an unfinished sweep.
|
|
66
68
|
|
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md
CHANGED
|
@@ -24,7 +24,7 @@ fails, fix it or surface the violation — do not claim done on a failing item.
|
|
|
24
24
|
- verification: ran the actual build/test — paste the exact command line and its real exit code / output tail, never a paraphrased "tests pass"
|
|
25
25
|
- acceptance: each implemented plan step's `Acceptance:` condition is observably met — cite the RED→GREEN test (or the command output) proving it per step, not one global "acceptance met"; and each `Test case (success|boundary|failure)` the plan declared for this stage has a matching test in the diff (name the test), so declared edge/failure cases are not silently uncovered
|
|
26
26
|
- quality outcomes: apply the captured `clean-code.md` "Five simultaneous quality outcomes" to the actual diff. Preserve each applicable expectation, performance/resource bound, safety/security check and its evidence in the acceptance and verification results above. Name missing or waived evidence; do not infer all five outcomes from a green command or complete coverage table
|
|
27
|
-
-
|
|
27
|
+
- regression evidence: map changed core behavior and meaningful failure outcomes to retained or strengthened tests and their actual command results. Use targeted mutation checks where regression detection remains uncertain, especially for security, concurrency or recovery, or where explicit project rules require them. For each selected mutation, cite the changed behavior and focused test failure, restore the source and rerun the test; preserve selected or required checks not performed as unverified. Follow `clean-code.md` "Testing discipline" rather than enumerating every syntactic branch for manual mutation
|
|
28
28
|
- cleanup: no dead or commented-out code left behind, and no caller-less identifier — list every identifier this diff added or whose last caller it removed, and cite the caller you grepped for each one (or the plan step / non-project-code contract point that justifies keeping it with none). "No new identifiers" is a valid answer; a global "cleaned up" is not
|
|
29
29
|
|
|
30
30
|
Close with a `Self-check coverage:` line naming the files you verified the
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
- In `candidate-comparison` mode, the lead merges overlapping candidates, then re-evaluates every merged candidate against the same criteria before ranking it.
|
|
26
26
|
- In `candidate-comparison` mode, display at most three merged candidates and record every rejected candidate with its rejection reason and cited evidence for audit.
|
|
27
27
|
- Map every displayed candidate or preselected direction to the stable brief end-state IDs it satisfies, preserves, or leaves unresolved.
|
|
28
|
-
- **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --task-manifest <taskManifestPath> --narrative <
|
|
28
|
+
- **Close the vote gaps before you conclude `blocked`.** Round 1 runs the designers in parallel, so each one votes only on the candidates it proposed and the merged set ends up with a different hole per analyser. A candidate that is otherwise sound then fails the every-analyser clause and drops out of the ranking — three such candidates blocked a run whose comparison had in fact converged (2026-09-10, dev-10629-4: IO-001, IO-002 and IO-003 each held two `feasible` votes and each was missing a different designer). Run `okstra option-votes gaps --run-manifest <current-run-manifest> --task-manifest <taskManifestPath> --narrative <reportNarrativePath>` before assembly. For each analyser it names, dispatch one vote-completion assignment asking for that analyser's own feasibility verdict, rationale, and counterevidence on the named candidate — no new candidate, so the run stays in `candidate-comparison` mode. The command reports no gap when a vote cannot settle the block (safety blockers, unresolved feasibility facts, too few feasible verdicts); that is the honest `blocked`.
|
|
29
29
|
- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
|
|
30
30
|
- Classify every `unresolvedFeasibilityFacts` entry with `resolutionKind`: `user-decision` requires nonempty `clarificationRefs` naming the actual C-NNN records for that fact; `technical-verification` requires source review, design evidence, or experiments and does not require a user question. `deferred-gate` marks a fact that no technical-verification run can close because closing it needs something that phase forbids, such as a deployed environment (for example, a cold-start measurement of a deployed Lambda); it requires `gate`, naming where the fact closes (a brief `External Gates` entry, or final-verification user-owned external QA), and it does not make the candidate invalid. A fact that a probe, a source read, or a disposable local service can close is `technical-verification`, not `deferred-gate`. The selected direction snapshot carries every remaining fact of the chosen option as `deferredFeasibilityFacts`, so planning schedules its gate. Enforced by `blocking_feasibility_facts` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`. Preserve `fact`, `whyItMatters`, and `evidence`. Reuse answered questions and their recorded dispositions; never reopen one merely to save the report. An unrelated open question does not satisfy a missing reference. Historical unclassified entries remain readable, but blocked report reassembly requires the writer to classify them explicitly. Enforced by `validate_blocked_answer_channel` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`. Saving preserves `routing: blocked` and does not make a candidate valid. In `humanSummary.actions`, `verdictCard.nextStep`, and selection guidance, distinguish pending user decisions from remaining technical verification; after the pilot route is answered, carry the selected route and remove the old answer-waiting instruction.
|
|
31
31
|
- **A split vote ends in a user decision, not another run.** When no candidate is valid only because its votes split (at least one `feasible`, the others `uncertain` or `not-feasible`, no `safetyBlockers`), another option-selection or technical-verification run asks the same designers the same question and returns the same split (fontradar dev-11562: three runs, `feasible` against `uncertain` each time). Before you route `blocked` or `technical-verification` on such a candidate, open one approval decision for it with `okstra approval-decision open --ledger <approvalDecisionsPath> --candidate-ref <IO-NNN>` naming that candidate (classification `noncritical-dissent`): the recommended option is `accept-risk` (proceed with this direction and carry the dissent and the remaining facts into planning), the alternative is `request-revision` (keep the run blocked). Ask the user in-session; record the answer with `okstra approval-decision resolve`. On `accept-risk`, the writer sets `splitAcceptance.clarificationRef` on that candidate, which makes it valid with one `feasible` vote; it then follows the ordinary routing (`implementation-planning` for a validated preselected direction, `pending-direction-selection` in `candidate-comparison`). Leave the votes and facts on the row. The answer accepts that candidate only; no other candidate cites it. When the user is not present, publish the report `blocked` with that approval row open; the next run carries the answer. Enforced by `validate_split_acceptance` in `scripts/okstra_ctl/phases/implementation_option_selection/validation.py`, called by report assembly and `validate-run.py`.
|
|
@@ -27,11 +27,9 @@ from collections.abc import Mapping
|
|
|
27
27
|
from pathlib import Path
|
|
28
28
|
from typing import Any
|
|
29
29
|
|
|
30
|
-
from okstra_ctl.final_report_schema import load_schema_version
|
|
31
30
|
from okstra_ctl.phases.implementation_option_selection.validation import VoteGap, vote_gaps
|
|
32
31
|
from okstra_ctl.json_boundary import JsonBoundaryError, load_owned_object
|
|
33
|
-
from okstra_ctl.
|
|
34
|
-
from okstra_ctl.report_narrative import parse_narrative_structure
|
|
32
|
+
from okstra_ctl.report_narrative import load_writer_input
|
|
35
33
|
|
|
36
34
|
|
|
37
35
|
class OptionVotesError(ValueError):
|
|
@@ -45,7 +43,9 @@ def _record_from_report(path: Path) -> dict[str, Any]:
|
|
|
45
43
|
raise OptionVotesError(f"report record is unreadable: {exc}") from exc
|
|
46
44
|
|
|
47
45
|
|
|
48
|
-
def _record_from_narrative(
|
|
46
|
+
def _record_from_narrative(
|
|
47
|
+
path: Path, *, run_manifest: Path | None = None,
|
|
48
|
+
) -> dict[str, Any]:
|
|
49
49
|
"""작성자 서사를 레코드 모양으로 읽는다.
|
|
50
50
|
|
|
51
51
|
값 결함은 무시한다 — 교정 원장이 고칠 자리이고, 표 구멍을 세는 데에는
|
|
@@ -53,12 +53,11 @@ def _record_from_narrative(path: Path) -> dict[str, Any]:
|
|
|
53
53
|
아직 교정 중인 run 은 이 명령을 쓸 수 없다.
|
|
54
54
|
"""
|
|
55
55
|
try:
|
|
56
|
-
|
|
57
|
-
|
|
56
|
+
return load_writer_input(
|
|
57
|
+
path, run_manifest=run_manifest, structure_only=True,
|
|
58
|
+
)
|
|
59
|
+
except (OSError, UnicodeError, ValueError) as exc:
|
|
58
60
|
raise OptionVotesError(f"narrative is unreadable: {exc}") from exc
|
|
59
|
-
schema = load_schema_version(CURRENT_REPORT_SCHEMA_VERSION)
|
|
60
|
-
record, _defects = parse_narrative_structure(markdown, schema)
|
|
61
|
-
return record
|
|
62
61
|
|
|
63
62
|
|
|
64
63
|
def participating_analysers(manifest_path: Path) -> tuple[str, ...]:
|
|
@@ -131,7 +130,7 @@ def _gaps(args: argparse.Namespace) -> int:
|
|
|
131
130
|
record = (
|
|
132
131
|
_record_from_report(args.report)
|
|
133
132
|
if args.report
|
|
134
|
-
else _record_from_narrative(args.narrative)
|
|
133
|
+
else _record_from_narrative(args.narrative, run_manifest=args.run_manifest)
|
|
135
134
|
)
|
|
136
135
|
gaps = vote_gaps(
|
|
137
136
|
_selection(record), participating_analysers(args.task_manifest)
|
|
@@ -176,7 +175,8 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
176
175
|
help="a published final-report `.data.json`")
|
|
177
176
|
gaps_parser.add_argument(
|
|
178
177
|
"--narrative", type=Path,
|
|
179
|
-
help="the report writer's
|
|
178
|
+
help="the report writer's declared input, before assembly")
|
|
179
|
+
gaps_parser.add_argument("--run-manifest", type=Path)
|
|
180
180
|
gaps_parser.add_argument("--json", action="store_true")
|
|
181
181
|
return parser
|
|
182
182
|
|
|
@@ -69,8 +69,7 @@ from okstra_ctl.plan_review_context import render_review_context
|
|
|
69
69
|
from okstra_ctl.stage_ledger import build_stage_ledger
|
|
70
70
|
from okstra_ctl.claim_reproduction import NOT_RUNNABLE, reproduce
|
|
71
71
|
from okstra_ctl.file_size_cap import headroom_text, planned_file_headroom
|
|
72
|
-
from okstra_ctl.
|
|
73
|
-
from okstra_ctl.report_narrative import parse_narrative
|
|
72
|
+
from okstra_ctl.report_narrative import load_writer_input
|
|
74
73
|
from okstra_ctl.report_assembly import validate_plan_draft
|
|
75
74
|
from okstra_ctl.error_log_write import record_runtime_failure
|
|
76
75
|
from okstra_ctl.user_response import parse_user_response_entries
|
|
@@ -194,9 +193,11 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
194
193
|
commands = parser.add_subparsers(dest="command", required=True)
|
|
195
194
|
extract = commands.add_parser("extract")
|
|
196
195
|
_add_plan_source(extract)
|
|
196
|
+
extract.add_argument("--run-manifest", type=Path)
|
|
197
197
|
extract.add_argument("--output", type=Path, required=True)
|
|
198
198
|
validate = commands.add_parser("validate")
|
|
199
199
|
_add_plan_source(validate)
|
|
200
|
+
validate.add_argument("--run-manifest", type=Path)
|
|
200
201
|
validate.add_argument("--items", type=Path, required=True)
|
|
201
202
|
prepare = commands.add_parser("prepare")
|
|
202
203
|
_add_plan_source(prepare)
|
|
@@ -425,13 +426,13 @@ def _plan_source(args: argparse.Namespace) -> dict[str, Any]:
|
|
|
425
426
|
if args.data is not None:
|
|
426
427
|
return _load_json_object(args.data)
|
|
427
428
|
try:
|
|
428
|
-
|
|
429
|
+
return load_writer_input(
|
|
430
|
+
args.narrative, run_manifest=getattr(args, "run_manifest", None),
|
|
431
|
+
)
|
|
429
432
|
except (OSError, UnicodeError) as exc:
|
|
430
433
|
raise PlanItemContractError(
|
|
431
434
|
f"cannot read report narrative {args.narrative}: {exc}"
|
|
432
435
|
) from exc
|
|
433
|
-
try:
|
|
434
|
-
return parse_narrative(markdown, load_schema_version("3.0"))
|
|
435
436
|
except ValueError as exc:
|
|
436
437
|
raise PlanItemContractError(f"invalid report narrative: {exc}") from exc
|
|
437
438
|
|
|
@@ -1191,12 +1192,14 @@ def validate_current_review(run_manifest: Path) -> PreparedPlanReview:
|
|
|
1191
1192
|
name = authority.payload.get("reportNarrativePath")
|
|
1192
1193
|
if not isinstance(name, str) or not name:
|
|
1193
1194
|
raise PlanItemContractError("reportNarrativePath is missing")
|
|
1194
|
-
narrative =
|
|
1195
|
-
if not narrative.is_relative_to(authority.run_dir):
|
|
1195
|
+
narrative = authority.project_root / name
|
|
1196
|
+
if not narrative.resolve(strict=True).is_relative_to(authority.run_dir):
|
|
1196
1197
|
raise PlanItemContractError("plan narrative must stay inside the current run")
|
|
1197
1198
|
items_path = _prepared_items_path(run_manifest, require_regular=True)
|
|
1198
1199
|
prepared = _load_json_object(items_path)
|
|
1199
|
-
source = _plan_source(argparse.Namespace(
|
|
1200
|
+
source = _plan_source(argparse.Namespace(
|
|
1201
|
+
data=None, narrative=narrative, run_manifest=run_manifest,
|
|
1202
|
+
))
|
|
1200
1203
|
items = _envelope(source)["items"]
|
|
1201
1204
|
if prepared.get("items") != items:
|
|
1202
1205
|
raise PlanItemContractError("prepared plan items do not match the current narrative")
|
|
@@ -1224,7 +1227,7 @@ def finish_verification_round(
|
|
|
1224
1227
|
verified = subprocess.run(
|
|
1225
1228
|
[sys.executable, str(assets.joinpath(*RUN_VALIDATOR_RELATIVE)),
|
|
1226
1229
|
"--section", "plan-body", "--narrative", str(review.narrative),
|
|
1227
|
-
"--state", str(review.state)],
|
|
1230
|
+
"--state", str(review.state), "--run-manifest", str(review.manifest)],
|
|
1228
1231
|
capture_output=True, text=True, check=False, timeout=60,
|
|
1229
1232
|
)
|
|
1230
1233
|
if verified.returncode:
|
|
@@ -8,12 +8,9 @@ rules live in `prompts/profiles/`.
|
|
|
8
8
|
### Step 5.1 (implementation-planning only): user-confirmed TDD bypass offer
|
|
9
9
|
|
|
10
10
|
Every plan stage must open with a `RED:` step whose outcome is FAIL and reach a
|
|
11
|
-
later `GREEN:` step (validator S10c). `tddExemption` waives that
|
|
12
|
-
|
|
13
|
-
stage that
|
|
14
|
-
got through by filing the nearest category. That is the failure this flag
|
|
15
|
-
exists to remove: **a closed reason list with no escape makes the plan
|
|
16
|
-
misdescribe itself.**
|
|
11
|
+
later `GREEN:` step (validator S10c). `tddExemption` waives that for
|
|
12
|
+
`doc-only`, `config-only`, `pure-rename`, or a user-granted `user-bypass`. A
|
|
13
|
+
stage that fits none of these is not filed under the nearest category.
|
|
17
14
|
|
|
18
15
|
`render-bundle` accepts an optional `--tdd-bypass "<stage>:<reason>"` flag
|
|
19
16
|
(implementation-planning only). It records a **user-acknowledged** bypass into
|
|
@@ -10,6 +10,8 @@ Use the absolute common-contract paths in the lead prompt's `Okstra Runtime Reso
|
|
|
10
10
|
|
|
11
11
|
This contract defines a **second, independent** verification round that fires only for `task-type = implementation-planning`. The round verifies the *consolidated plan* that the report-writer worker has authored, not the worker findings that were already reconciled earlier.
|
|
12
12
|
|
|
13
|
+
Take every authoring input path below from the current run manifest's `reportNarrativePath`. Its declared `reportAuthoringFormat=json-v1` selects standard JSON with ordinary Markdown inside description strings; an absent field retains `markdown-v1` and its line grammar. Pass that same run manifest to `plan-items prepare`, `seed`, `extract`, `validate`, `validate-prepared`, `plan-verify`, and `incremental-carry` so each consumer selects the declared format. Keep the actual `.json` or `.md` extension when preserving a correction attempt. The final reader's Markdown and HTML remain derived outputs.
|
|
14
|
+
|
|
13
15
|
## Lifecycle position (BLOCKING)
|
|
14
16
|
|
|
15
17
|
Plan-body verification runs **after** finding convergence and **after** the report-writer draft is written. Sequence inside a single implementation-planning run:
|
|
@@ -17,7 +19,7 @@ Plan-body verification runs **after** finding convergence and **after** the repo
|
|
|
17
19
|
```
|
|
18
20
|
Phase 4 workers produce independent analyses (Findings F-001…)
|
|
19
21
|
→ Phase 5.5 FINDING convergence (`prompts/lead/convergence.md`, sections "Convergence Algorithm" through "Convergence State Artifact")
|
|
20
|
-
→ Phase 6 report-writer authors
|
|
22
|
+
→ Phase 6 report-writer authors the manifest-declared input (consolidated Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)
|
|
21
23
|
→ okstra plan-items prepare + prompt + validate-prepared creates and projects the deterministic P-* queue
|
|
22
24
|
→ PLAN-BODY VERIFICATION ROUND ← this contract
|
|
23
25
|
→ final render/validation
|
|
@@ -64,9 +66,9 @@ Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (
|
|
|
64
66
|
From the report-writer's draft of `## 5.4 Implementation Plan Deliverables`, the lead creates the verification queue only through this sequence (see also `templates/reports/final-report-v2.template.md` §5.5.9):
|
|
65
67
|
|
|
66
68
|
```text
|
|
67
|
-
okstra plan-items prepare --narrative <
|
|
69
|
+
okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>
|
|
68
70
|
→ place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in every verifier prompt
|
|
69
|
-
→ okstra plan-items validate-prepared --narrative <
|
|
71
|
+
→ okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>
|
|
70
72
|
```
|
|
71
73
|
|
|
72
74
|
The persisted `items[]` are the sole queue. The lead MUST NOT freely summarise,
|
|
@@ -413,11 +415,11 @@ round before any host or provider process starts.
|
|
|
413
415
|
|
|
414
416
|
For contract 3.0, `prepare` checks the selected-direction draft with the same semantic validator as publication before writing the queue. Correct all reported references, coverage rows and planned commands through the writer correction procedure, then retry in this run. **Enforced:** `report_assembly.validate_plan_draft` and `plan_items_cli._prepare`; the retired Python suite previously checked that invalid coverage creates no prepared queue.
|
|
415
417
|
|
|
416
|
-
1. Lead runs `okstra plan-items prepare --narrative <
|
|
418
|
+
1. Lead runs `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. A `File-size headroom` line that prepare prints, and that `okstra plan-items prompt` carries under `## File-size headroom`, is a report only: it names an existing file the plan writes, its lines left before the 500-line implementation limit and the stages that write it. It does not block, open a correction or count as a verdict. After a self-fix rewrite, and after `okstra incremental-carry` on a re-run, pass `--state <plan-body-verification.json>` on prepare and validate-prepared; validate-prepared needs the same `--state` the last prepare used, or it refuses with `prepared dispatch queue does not match` or `prepared review evidence changed`. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and the retired Python suite. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
|
|
417
419
|
|
|
418
|
-
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <
|
|
420
|
+
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <reportNarrativePath> --state <plan-body-verification.json> --run-manifest <run-manifest.json>`. `apply-verdicts` in step 8 refuses a verdict whose item has no `planBodyVerification.planItems[]` row. The report writer never owns that state, so the deterministic seed is the only creator of its rows. The seed is idempotent by id and never touches existing verdicts, so it is safe to re-run between rounds and after a self-fix re-extraction. It does refresh `contentHash` from the current extract. Skipping it makes step 8 fail with `plan-body state has no row for [...]`.
|
|
419
421
|
|
|
420
|
-
**On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry
|
|
422
|
+
**On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> ...` and repeats prepare, prompt and validate-prepared with `--state` before dispatch (launch prompt "Incremental re-verification" step 7). A newly seeded item inherits verdicts only when its body and verified evidence fingerprint match the prepared snapshot for the same task. Reused rows carry `carriedForwardFromSeq`; their full verdicts are preserved. Legacy body-only records re-enter verification. A matching id alone never carries: `P-*` ids are positional. The flag requires `--state` and refuses another task's state. **Enforced:** `implementation_planning.authoring._carry_prior_run_verdicts` and `plan_item_evidence.reusable_item_ids`.
|
|
421
423
|
|
|
422
424
|
**`--run-manifest` is what scopes the gate to the stage you are starting.** Seed uses it to overlay disk `done` / `active` onto `planBodyVerification.stageLedger`. The current plan's depends-on fills `ready` / `blocked` when no prior plan exists, so a first run does not treat every stage as in-scope. **Enforced:** `okstra_ctl.plan_items.planning_stage_ledger`.
|
|
423
425
|
2. For each analyser worker in the roster, use `okstra plan-items prompt` output verbatim as the instruction body in the materialization sequence above. Read §"Re-verification rounds (round 2+)" before preparing a later round; read §"Plan-body reverify prompt" only when diagnosing a prompt-contract failure.
|
|
@@ -446,10 +448,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
|
|
|
446
448
|
- any advisory `dissent-isolated` / `needs-reverify` present, no `majority-disagree` → `passed-with-dissent`
|
|
447
449
|
- all items `full-consensus` → `passed`
|
|
448
450
|
|
|
449
|
-
**Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are in the
|
|
451
|
+
**Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are recorded in the convergence-owned plan-body state, lead runs
|
|
450
452
|
|
|
451
453
|
```
|
|
452
|
-
okstra plan-verify --
|
|
454
|
+
okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>
|
|
453
455
|
```
|
|
454
456
|
|
|
455
457
|
and records what it returns: `gate.recomputed` is the round's gate value, `gate.blockedBy` its `gateBlockedBy` causes, `gate.blockingItems` the items that block. The same call runs every plan-body check a round can be judged on alone — provenance, fixability, subject substance, self-fix grouping, round recording, clarification matching, state-file rounds — and exits 2 with `failures[]` when the round is not contract-clean. **A round is not complete while that exit code is non-zero.**
|
|
@@ -485,10 +487,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
|
|
|
485
487
|
- **Group the targets by cause before instructing (BLOCKING).** Blocked items are usually several derivatives of one defect. Lead partitions this round's targets into cause groups and instructs each group as **"remove this cause"**, naming the derivatives it accounts for. The convergence command owns the persisted group and correction fields; the lead does not edit JSON state.
|
|
486
488
|
- lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration): one `rewrite` entry per item in a corrections ledger, whose `rule` states the cause group's required outcome; procedure in `prompts/lead/report-writer.md` §"Corrective report-writer dispatch (ledger required)".
|
|
487
489
|
- missing or weak `P-Prep-*` contracts are repaired by adding kind-specific inline detail or an AI-prepared PREP item with a concrete proposal. Facts that require user or external authority remain `blocked` and keep their request material; never invent those facts during self-fix.
|
|
488
|
-
- **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract
|
|
490
|
+
- **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --output <extract-path>` and re-verify any item whose `subject` no longer matches; never carry the old vote forward across a shift. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdicts_match_current_subjects` (re-pointing) and `_validate_plan_item_extraction_completeness` (dangling ids).
|
|
489
491
|
- **Classify each cause group before instructing it (BLOCKING).** A group is either an *authoring* defect — the plan says something wrong, incomplete, or self-contradictory, which self-fix owns — or a *citation* defect, where the plan points at an analysis artifact incorrectly. Only the first is self-fix work. For the second the finding already exists and already went through convergence, so the fix is to re-cite the converged artifact; instructing report-writer to re-derive the fact means the author reads the source material and produces a **finding that never went through convergence**, which the plan then carries as if it had. That is the role boundary the lead contract draws ("keep analysis, execution, verification, and report authoring responsibilities distinct; return defects to the role that owns them"), and report-writer is authoring-only by its own contract. `P-Req-*` items with breakage kind `f` are where this goes wrong most often: the question is usually whether a coverage row points correctly at something already measured, not whether the measurement is right. State the classification in the group's instruction so the author knows which of the two it is being asked to do.
|
|
490
492
|
- **A verdict older than the last self-fix is not a verdict unless the item's content is unchanged (BLOCKING).** A verdict cast in round 1 judged the text before the only automatic rewrite. Once that rewrite runs, a changed item's judgement is about a plan that no longer exists. `--round <N>` on `apply-verdicts` stamps each row and copies `contentHash` onto `verifiedContentHash`. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdict_rounds_outlive_self_fix` fails an in-scope item whose verdict round is at or before `selfFixRoundsApplied` **and** whose `contentHash` does not match `verifiedContentHash`. Matching hashes keep the prior verdict — that is what avoids a sweep round over unchanged stages. Deferred and observed items are out of the gate and do not need a post-self-fix verdict. **Enforced:** `_validate_verdict_rounds_outlive_self_fix`.
|
|
491
|
-
- Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --
|
|
493
|
+
- Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>`, then call `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. These commands fail on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a duplicate worker result. `apply-verdicts` without `--append` replaces every recorded row of the queued items, so it also refuses — before writing — when a row belongs to a round that `complete-round` never closed, naming the round to close first; the votes of a closed round live in `planItems[].rounds`. Skipping `complete-round` between rounds and applying the next one lost 19 items' round-1 votes (2026-09-09). `--discard-open-rounds` is only for re-applying the lost rounds from their result files in order: it also restores `dispatchQueue` to the items those result files answer, because the persisted queue is the latest round's and a verdict for an earlier, wider queue is otherwise refused as outside it (round 1 = 26 items, critic tie = 8, round 3 = 19 on that same run — only the 19 survived). Re-apply each lost round with the flag, `complete-round` it, then the next. **Enforced:** `okstra_ctl.plan_items_cli._reject_uncompleted_round_loss` and `_restore_queue_from_results`.
|
|
492
494
|
- For a self-fix, record the correction through the typed convergence command rather than writing `selfFixNote` or `selfFixGroups` JSON. A resolved item does not create a clarification.
|
|
493
495
|
- **Each round is a worker batch.** Before dispatching round N ≥ 2, reclaim the previous round's completed verifiers exactly as at any other batch boundary (`prompts/lead/okstra-lead-contract.md` "Run-scoped worker-resource lifecycle") and emit `PROGRESS: phase-batch-cleanup panes=<n>`, then announce the round with `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>`. Saying a round will "reuse" the previous verifiers and then dispatching under fresh names leaves every prior round holding its panes — five rounds of that is what exhausts the pane budget and blocks the next dispatch. **Enforced:** `validators/validate_session_conformance.py` `_check_plan_verify_cleanup_checkpoints` requires both lines once the state file records two or more rounds.
|
|
494
496
|
- **Round completion.** A round is complete only after `okstra plan-verify` exits 0 and `okstra plan-items complete-round` succeeds. A round left with a non-zero exit carries its defect into the next round's inputs. Exit 0 with a non-empty `advisories[]` is a complete round: those findings are recorded, not round-blocking (step 5, §"`failures[]` carries only the blocking findings"). Report assembly and rendering occur only after the convergence state is terminal. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_plan_body_state_rounds` requires one stored round per round number and a corresponding item vote.
|
|
@@ -86,7 +86,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
86
86
|
- §5.5.9 plan-body verification runs with an **adversarial posture** (`scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is majority-based for kinds `b`/`c`/`e`, but a single `DISAGREE` blocks on its own for the concrete, safety-critical kind `a` (path/symbol mismatch) — and `f` on `P-Req-*` items. `P-Var-*` items are excepted from the kind-`a` exception: a variation-point defect takes a majority. Rollback ordering (`d`) is advisory and never blocks the gate — a rollback is executed by a human, not by okstra's workers or verifiers. A majority also needs ≥2 participating votes, so a lone dissent whose peer returned a non-result does not block on a majority-gated kind (see that contract's §"Adversarial plan-body posture").
|
|
87
87
|
- **Incremental re-verification scope (clarification re-runs):** when the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), workers re-analyze ONLY the stages listed in `reverify_stages` (the downstream closure of the impacted stages). Workers MUST NOT re-open, re-score, or re-judge any stage in `carry_stages` — those stages' prior plan-item verdicts are carried forward verbatim, and a worker never overwrites a carried verdict with its own judgement. When the decision is `mode == "full"` (the default), every stage is re-analyzed as usual.
|
|
88
88
|
- **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. **When this run only ADDS stages** — every prior stage is `done` and none of them is being re-opened — there are no stage numbers to give: pass `--carry-all-reason` instead. Pinning any prior stage as impacted makes `incremental-carry` demand plan-item verdicts from the current snapshot, which no longer holds them (a `done` stage's plan items are `observed`, so they are never dispatched or scored in this run), so that path has no answer that works. The stage's own row is still declared in the narrative — that is the numbering rule above, not a re-verification. `--carry-all-reason` still applies the base-ref check: if the branch moved, the decision degrades to `full` because the prior stages are no longer "as written". Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, `carry-all` supplies the `--carry-all-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
|
|
89
|
-
- **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --cur-narrative
|
|
89
|
+
- **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> --state ... --out-state ...` against that record. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
|
|
90
90
|
{{INCLUDE:_coverage-critic.md}}
|
|
91
91
|
- Non-goals:
|
|
92
92
|
- code-level micro-optimization unless it changes the implementation approach
|
|
@@ -115,8 +115,8 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
115
115
|
- **`user-bypass` — the stage that is honestly none of the three.** Some stages have no failing-before state to write and no category that describes them (measured 2026-09-10: a stage whose product change was already committed and conformance-proved under a previous run of the same stage, so the only truthful reason was "this stage reconciles that stage's QA declaration"). Do **not** file the closest of the three; that makes the plan misdescribe itself and S10e passes on a reason that is not true. Declare `tddExemption: user-bypass — <the user's own words>` and stop: the value holds only while `<task-root>/qa/tdd-bypass.json` records the user's grant for that stage number. **You cannot write that record.** Ask the user, in your report's clarification row or directly, to re-run prepare with `--tdd-bypass "<stage>:<reason>"`; their reason is stored verbatim and the record shows the stage as bypassed by the user rather than as one of the three canned categories. **Enforced (S10e):** `collect_data_validation_errors` takes the granted stage numbers from `okstra_ctl.tdd_bypass.granted_stages`; a stage naming the token with no grant fails exactly as an arbitrary reason does, and the failure message carries the flag that produces a passing value.
|
|
116
116
|
- `stageMap[].dependsOn` must form a DAG (no self-dependency, no unknown stage, no cycle), each row's `stepCount` must equal its stage's actual `stepwiseExecution` row count, and two `(none)`-dependency stages must not name the same file in their `exitContract` — they run as concurrent implementation runs in separate worktrees. **Enforced (S8/S4/S9):** same function.
|
|
117
117
|
- Legacy candidate-comparison-only deliverable:
|
|
118
|
-
- The report writer records the plan body in
|
|
119
|
-
- **
|
|
118
|
+
- The report writer records the plan body under `implementationPlanning` in the input at the run manifest's `reportNarrativePath`, using its declared `reportAuthoringFormat`. `json-v1` uses exact JSON schema keys and native values, with ordinary Markdown allowed inside description strings. An absent field retains the `markdown-v1` line grammar. Report assembly adds machine-owned `designPreparation`, `designSurfaceCoverage`, and `planBodyVerification`, then validates the completed `data.json` against the frozen final-report schema.
|
|
119
|
+
- **Legacy Markdown field labels under `Implementation Planning`:** `Coverage Summary`, `Cross Project Dependencies`, `Decision Drafts`, `Dependency Migration Risk`, `Direction Invalidation`, `Direction Realization`, `Incremental Decision`, `Option Candidates`, `Outcome`, `Planning Contract`, `Recommended Option`, `Requirement Coverage`, `Rollback Strategy`, `Routing`, `Selected Direction Ref`, `Skipped ADR Candidates`, `Stage Map`, `Stages`, `Stepwise Execution`, `Supersession Ledger`, `Tradeoff Matrix`, `User Narrative`, `Validation Checklist`, `Variation Point Analysis`. For `json-v1`, use the exact keys in the synthesis packet's writer-owned schema instead, such as `implementationPlanning.requirementCoverage`. The `## 5.5.<i>` headings, the `step | action | ...` tables, and the `Slice value:` / `Test case (...):` lines described below are the shape of the **rendered report a reader sees**. JSON carries that content as structured values; only `markdown-v1` uses `- **Field**` / `- Item <N>` / `> value` rows. `designPreparation` and `planBodyVerification` belong to report assembly and are rejected in either format.
|
|
120
120
|
- Legacy candidate-comparison requires at least two implementation options. **Each option must include**:
|
|
121
121
|
- **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.
|
|
122
122
|
- **Two-tier change description.** Each `fileStructure` row carries `summary` **and** optional `details`, and they are not interchangeable:
|
|
@@ -208,7 +208,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
208
208
|
- Selected-direction plans omit `implementation-option:` because `selectedDirectionRef` already fixes the direction; the legacy-only selector rule is owned by the legacy deliverable section above.
|
|
209
209
|
- **the frontmatter `approved: false` line is rendered unconditionally; if the plan-body verification gate (§5.5.9) returns `blocked-by-disagreement` or `aborted-non-result`, the writer MUST keep `approved: false` and the validator refuses any report that ships with `approved: true` under such a gate result.**
|
|
210
210
|
- every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (the unified table is the single home for these — the "no separate `Open Questions` block" rule is in the shared `_common-contract.md` clarification policy)
|
|
211
|
-
- **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <
|
|
211
|
+
- **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in the verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. Do not freely summarise, select, omit, reorder, or renumber the queue. Prompt headings use the compact subject and include the lossless payload. For every item, ask:
|
|
212
212
|
|
|
213
213
|
```text
|
|
214
214
|
What concrete false-positive input, failure ordering, or omitted dependency
|
|
@@ -284,7 +284,7 @@ Lead's responsibilities in this sub-step (in order):
|
|
|
284
284
|
|
|
285
285
|
For a new `implementation-planning` run, the fixed order is initial verification → one planner self-fix → targeted re-verification → lead decision or immediate user confirmation. The initial verification is round 1 and the targeted re-verification is round 2. A second automatic self-fix is a contract violation. When `okstra plan-items prepare` reports `"gating": false` (one-stage `no-design-inputs` plan), skip the self-fix loop and the sweep batch: extraction and round 1 still run, then go to the user gate. Two-or-more stages, a PREP item, or non-empty `designPreparation.items` keep `gating: true` and the full order.
|
|
286
286
|
|
|
287
|
-
1. Build the queue with `okstra plan-items prepare --narrative <
|
|
287
|
+
1. Build the queue with `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place the output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. The lead MUST NOT summarise, select, omit, reorder, or renumber the queue. Each prompt uses the compact subject plus the lossless payload, and asks every item:
|
|
288
288
|
|
|
289
289
|
```text
|
|
290
290
|
What concrete false-positive input, failure ordering, or omitted dependency
|