okstra 0.232.0 → 0.234.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 +14 -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 +55 -5
- package/docs/architecture.md +10 -4
- package/docs/cli.md +320 -3
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +34 -43
- 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/business_flow/cli.py +60 -6
- package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
- package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
- package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
- package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
- package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
- package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
- 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/cli.py +9 -9
- package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
- package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/fixed_text.py +10 -0
- 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/project_group.py +175 -0
- package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
- 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/business-flow-v1.schema.json +3 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
- 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 +33 -4
- 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/doyouknow/group-view.css +103 -0
- package/runtime/templates/doyouknow/group-view.js +317 -0
- package/runtime/templates/doyouknow/group-view.template.html +72 -0
- 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
|
@@ -23,6 +23,7 @@ from ..ports.verification_inputs import VerificationInputStore
|
|
|
23
23
|
from ..review_policy import render_review_policy, review_policy_context
|
|
24
24
|
from ..phases.catalog import PhaseAssetError, profile_markdown
|
|
25
25
|
from ..recap import assemble_group_recap, assemble_recap
|
|
26
|
+
from ..report_contract import report_authoring_format
|
|
26
27
|
from ..role_requirements import RoleProfileError, load_role_profile
|
|
27
28
|
from ..timeline_runs import current_run_facts
|
|
28
29
|
from .lines import (
|
|
@@ -214,6 +215,7 @@ def render_run_input(run_manifest: Path) -> str:
|
|
|
214
215
|
+ _line("Task type", run.get("taskType"))
|
|
215
216
|
+ _line("Run ID", run.get("runDateTimeSegment"))
|
|
216
217
|
+ _line("Work category", run.get("workCategory"))
|
|
218
|
+
+ _line("Report authoring format", report_authoring_format(run))
|
|
217
219
|
+ _line("Lead runtime", run.get("leadRuntime"))
|
|
218
220
|
+ _line("Lead adapter name", adapter.get("name"))
|
|
219
221
|
+ _line("Lead dispatch mode", adapter.get("dispatchMode"))
|
|
@@ -229,6 +231,7 @@ def render_run_input(run_manifest: Path) -> str:
|
|
|
229
231
|
+ _worker_prompt_lines(run)
|
|
230
232
|
+ _line("Worker results directory", run.get("workerResultsDirectoryPath"))
|
|
231
233
|
+ _line("Expected report", run.get("expectedReportRecordPath"))
|
|
234
|
+
+ _line("Report writer input", run.get("reportNarrativePath"))
|
|
232
235
|
+ _line("Expected status", run.get("expectedStatusPath"))
|
|
233
236
|
+ _line("Validator", run.get("validatorScriptPath"))
|
|
234
237
|
+ _line("Resume command", run.get("resumeCommandPath"))
|
|
@@ -17,7 +17,7 @@ from .contract_graph import (
|
|
|
17
17
|
ContractGraphValidator,
|
|
18
18
|
ContractSelection,
|
|
19
19
|
)
|
|
20
|
-
from .model_pool import ModelPool
|
|
20
|
+
from .model_pool import ModelPool, ResolvedModel
|
|
21
21
|
|
|
22
22
|
|
|
23
23
|
class OperationPreparationError(ValueError):
|
|
@@ -37,20 +37,8 @@ class OperationSlot:
|
|
|
37
37
|
display_name: str
|
|
38
38
|
|
|
39
39
|
|
|
40
|
-
def
|
|
41
|
-
|
|
42
|
-
*,
|
|
43
|
-
contract_root: Path,
|
|
44
|
-
pool: ModelPool,
|
|
45
|
-
count: int | None = None,
|
|
46
|
-
) -> Sequence[OperationSlot]:
|
|
47
|
-
"""작업 계약이 요구하는 칸과 각 칸의 모델.
|
|
48
|
-
|
|
49
|
-
모델은 런과 같은 기본값 사슬에서 고른다. 서로 다른 모델 참조를 요구한
|
|
50
|
-
수만큼 채우지 못하면 여기서 멈춘다 — 같은 모델을 반복하거나 워커 수를
|
|
51
|
-
몰래 줄이면 그 작업이 요구한 교차검증이 조용히 사라진다. `count` 는
|
|
52
|
-
호출자가 계약 상한 안에서 명시적으로 고른 수다.
|
|
53
|
-
"""
|
|
40
|
+
def _operation_contract(operation_id: str, contract_root: Path) -> tuple[str, str, int]:
|
|
41
|
+
"""The operation's duty, role and worker ceiling."""
|
|
54
42
|
graph_root = ContractGraphRoot.from_base(contract_root)
|
|
55
43
|
try:
|
|
56
44
|
graph = ContractGraphValidator().validate(
|
|
@@ -65,31 +53,222 @@ def resolve_operation_slots(
|
|
|
65
53
|
f"unknown operation: {operation_id} (known: {known})"
|
|
66
54
|
)
|
|
67
55
|
duty_id = str(operation.payload["dutyId"])
|
|
56
|
+
return duty_id, graph.duties[duty_id].role_id, int(operation.payload["count"])
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def operation_ceiling(operation_id: str, *, contract_root: Path) -> int:
|
|
60
|
+
"""The most workers the operation contract allows."""
|
|
61
|
+
return _operation_contract(operation_id, contract_root)[2]
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def resolve_operation_slots(
|
|
65
|
+
operation_id: str,
|
|
66
|
+
*,
|
|
67
|
+
contract_root: Path,
|
|
68
|
+
pool: ModelPool,
|
|
69
|
+
count: int | None = None,
|
|
70
|
+
deprioritized_provider: str | None = None,
|
|
71
|
+
) -> Sequence[OperationSlot]:
|
|
72
|
+
"""작업 계약이 요구하는 칸과 각 칸의 모델.
|
|
73
|
+
|
|
74
|
+
모델은 런과 같은 기본값 사슬에서 고른다. 서로 다른 모델 참조를 요구한
|
|
75
|
+
수만큼 채우지 못하면 여기서 멈춘다 — 같은 모델을 반복하거나 워커 수를
|
|
76
|
+
몰래 줄이면 그 작업이 요구한 교차검증이 조용히 사라진다. `count` 는
|
|
77
|
+
호출자가 계약 상한 안에서 명시적으로 고른 수다. `deprioritized_provider`
|
|
78
|
+
의 모델은 다른 공급자의 후보 뒤로 미룬다(같은 공급자 안의 순서는 유지).
|
|
79
|
+
"""
|
|
80
|
+
duty_id, role_id, ceiling = _operation_contract(operation_id, contract_root)
|
|
68
81
|
# 계약의 수는 상한이다. 더 적게 여는 것은 호출자가 명시할 때만이다.
|
|
69
|
-
ceiling = int(operation.payload["count"])
|
|
70
82
|
if count is None:
|
|
71
83
|
count = ceiling
|
|
72
84
|
elif not 1 <= count <= ceiling:
|
|
73
85
|
raise OperationPreparationError(
|
|
74
86
|
f"operation {operation_id!r} takes a count from 1 to {ceiling}, got {count}"
|
|
75
87
|
)
|
|
76
|
-
role_id = graph.duties[duty_id].role_id
|
|
77
88
|
|
|
78
89
|
candidates = pool.default_candidates(role_id)
|
|
90
|
+
if deprioritized_provider is not None:
|
|
91
|
+
candidates = tuple(sorted(candidates, key=lambda model: model.provider_id == deprioritized_provider))
|
|
79
92
|
if len(candidates) < count:
|
|
80
93
|
raise OperationPreparationError(
|
|
81
94
|
f"operation {operation_id!r} requires {count} distinct models for role "
|
|
82
95
|
f"{role_id!r}, available {len(candidates)}"
|
|
83
96
|
)
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
97
|
+
return _numbered_slots(operation_id, duty_id, role_id, candidates[:count])
|
|
98
|
+
|
|
99
|
+
|
|
100
|
+
def _numbered_slots(
|
|
101
|
+
operation_id: str, duty_id: str, role_id: str, models: Sequence[ResolvedModel],
|
|
102
|
+
) -> tuple[OperationSlot, ...]:
|
|
103
|
+
return tuple(
|
|
104
|
+
OperationSlot(
|
|
105
|
+
operation_id=operation_id, duty_id=duty_id, role_id=role_id, ordinal=ordinal,
|
|
106
|
+
model_ref=str(model.model_ref), provider_id=model.provider_id,
|
|
93
107
|
display_name=model.display_name,
|
|
94
|
-
)
|
|
95
|
-
|
|
108
|
+
)
|
|
109
|
+
for ordinal, model in enumerate(models, start=1)
|
|
110
|
+
)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def operation_contract_root() -> Path:
|
|
114
|
+
"""The directory holding `operations/<id>.json` contracts for this runtime."""
|
|
115
|
+
from .paths import find_asset_root
|
|
116
|
+
|
|
117
|
+
root = find_asset_root(("agents", "operations"), is_present=Path.is_dir)
|
|
118
|
+
if root is None:
|
|
119
|
+
raise OperationPreparationError(
|
|
120
|
+
"operation contracts not found: no agents/operations under OKSTRA_HOME or this checkout"
|
|
121
|
+
)
|
|
122
|
+
return root
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
def require_distinct_providers(providers: Sequence[str]) -> None:
|
|
126
|
+
"""Every team needs its own provider.
|
|
127
|
+
|
|
128
|
+
The operation asks for cross-model verification, and two models of one
|
|
129
|
+
provider do not provide it.
|
|
130
|
+
"""
|
|
131
|
+
if len(set(providers)) != len(providers):
|
|
132
|
+
raise OperationPreparationError(
|
|
133
|
+
"every team needs a different provider, got " + ", ".join(providers)
|
|
134
|
+
)
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def resolve_model_reference(pool: ModelPool, value: str) -> ResolvedModel:
|
|
138
|
+
"""A `provider/model` reference, or a provider alias such as `claude/opus`."""
|
|
139
|
+
from .domain.provider import UnknownModelError
|
|
140
|
+
|
|
141
|
+
try:
|
|
142
|
+
return pool.resolve(value)
|
|
143
|
+
except UnknownModelError:
|
|
144
|
+
provider, sep, alias = value.partition("/")
|
|
145
|
+
if not sep or not alias:
|
|
146
|
+
raise
|
|
147
|
+
return pool.resolve_alias(provider, alias)
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def resolve_operation_models(
|
|
151
|
+
operation_id: str, references: Sequence[str], *, contract_root: Path, pool: ModelPool,
|
|
152
|
+
) -> tuple[str, str, tuple[ResolvedModel, ...]]:
|
|
153
|
+
"""The duty, role and models a caller chose for an operation, one per team, in order."""
|
|
154
|
+
from .domain.provider import UnknownModelError
|
|
155
|
+
|
|
156
|
+
duty_id, role_id, ceiling = _operation_contract(operation_id, contract_root)
|
|
157
|
+
if not references:
|
|
158
|
+
raise OperationPreparationError(f"operation {operation_id!r} needs at least one model")
|
|
159
|
+
if len(references) > ceiling:
|
|
160
|
+
raise OperationPreparationError(
|
|
161
|
+
f"operation {operation_id!r} takes at most {ceiling} models, got {len(references)}"
|
|
162
|
+
)
|
|
163
|
+
try:
|
|
164
|
+
models = [resolve_model_reference(pool, value) for value in references]
|
|
165
|
+
except UnknownModelError as exc:
|
|
166
|
+
raise OperationPreparationError(str(exc)) from exc
|
|
167
|
+
require_distinct_providers([model.provider_id for model in models])
|
|
168
|
+
for model in models:
|
|
169
|
+
if not pool.resolve_provider(model.provider_id).supports_role(role_id):
|
|
170
|
+
raise OperationPreparationError(
|
|
171
|
+
f"provider {model.provider_id!r} does not support role {role_id!r}"
|
|
172
|
+
)
|
|
173
|
+
availability = pool.availability(str(model.model_ref), role_id)
|
|
174
|
+
if not availability.available:
|
|
175
|
+
raise OperationPreparationError(
|
|
176
|
+
f"model {model.model_ref} is not available: {availability.reason}"
|
|
177
|
+
)
|
|
178
|
+
return duty_id, role_id, tuple(models)
|
|
179
|
+
|
|
180
|
+
|
|
181
|
+
def select_operation_models(
|
|
182
|
+
operation_id: str, flags: Sequence[str], count: int | None, *, contract_root: Path, cwd: Path,
|
|
183
|
+
) -> tuple[tuple[str, ...], str]:
|
|
184
|
+
"""Which model references an operation's teams use, and where they came from.
|
|
185
|
+
|
|
186
|
+
Flags win, then project and then global `operationModels`, then adapter
|
|
187
|
+
defaults (an empty tuple with source `bundled`). A count is checked
|
|
188
|
+
against the contract range first; with flags it must equal their number,
|
|
189
|
+
with a config list it takes that many from the front.
|
|
190
|
+
"""
|
|
191
|
+
ceiling = operation_ceiling(operation_id, contract_root=contract_root)
|
|
192
|
+
if count is not None and not 1 <= count <= ceiling:
|
|
193
|
+
raise OperationPreparationError(
|
|
194
|
+
f"operation {operation_id!r} takes a count from 1 to {ceiling}, got {count}"
|
|
195
|
+
)
|
|
196
|
+
if flags:
|
|
197
|
+
if count is not None and count != len(flags):
|
|
198
|
+
raise OperationPreparationError("--count differs from the number of --model values")
|
|
199
|
+
return tuple(flags), "flag"
|
|
200
|
+
configured, scope = operation_model_defaults(operation_id, cwd)
|
|
201
|
+
if not configured or count is None:
|
|
202
|
+
return configured, scope
|
|
203
|
+
if count > len(configured):
|
|
204
|
+
raise OperationPreparationError(
|
|
205
|
+
f"{scope} operationModels names {len(configured)} models, fewer than --count {count}"
|
|
206
|
+
)
|
|
207
|
+
return configured[:count], scope
|
|
208
|
+
|
|
209
|
+
|
|
210
|
+
def resolve_operation_team(
|
|
211
|
+
operation_id: str, flags: Sequence[str], count: int | None, *,
|
|
212
|
+
contract_root: Path, pool: ModelPool, cwd: Path,
|
|
213
|
+
) -> tuple[tuple[OperationSlot, ...], str]:
|
|
214
|
+
"""The operation's slots for the selected models, and the models' source."""
|
|
215
|
+
references, source = select_operation_models(
|
|
216
|
+
operation_id, flags, count, contract_root=contract_root, cwd=cwd,
|
|
217
|
+
)
|
|
218
|
+
if not references:
|
|
219
|
+
return tuple(resolve_operation_slots(
|
|
220
|
+
operation_id, contract_root=contract_root, pool=pool, count=count,
|
|
221
|
+
)), source
|
|
222
|
+
duty_id, role_id, models = resolve_operation_models(
|
|
223
|
+
operation_id, references, contract_root=contract_root, pool=pool,
|
|
224
|
+
)
|
|
225
|
+
return _numbered_slots(operation_id, duty_id, role_id, models), source
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def operation_model_defaults(operation_id: str, cwd: Path) -> tuple[tuple[str, ...], str]:
|
|
229
|
+
"""The models `operationModels` names for an operation, and the scope that named them.
|
|
230
|
+
|
|
231
|
+
Project config wins over global config; neither merges with the other.
|
|
232
|
+
An empty tuple with scope `bundled` means no config names the operation.
|
|
233
|
+
"""
|
|
234
|
+
from okstra_project.dirs import okstra_home
|
|
235
|
+
|
|
236
|
+
from .model_defaults import ModelDefaultScopes, default_candidates, default_scope
|
|
237
|
+
|
|
238
|
+
scopes = ModelDefaultScopes(
|
|
239
|
+
project=_operation_models(_project_config(cwd)),
|
|
240
|
+
global_=_operation_models(okstra_home() / "config.json"),
|
|
241
|
+
bundled={},
|
|
242
|
+
)
|
|
243
|
+
refs = default_candidates(operation_id, scopes)
|
|
244
|
+
return refs, default_scope(operation_id, scopes) or "bundled"
|
|
245
|
+
|
|
246
|
+
|
|
247
|
+
def _project_config(cwd: Path) -> Path:
|
|
248
|
+
from okstra_project import project_json_path, resolve_project_root
|
|
249
|
+
|
|
250
|
+
try:
|
|
251
|
+
return project_json_path(resolve_project_root(cwd=str(cwd)))
|
|
252
|
+
except Exception:
|
|
253
|
+
return cwd / ".okstra" / "project.json"
|
|
254
|
+
|
|
255
|
+
|
|
256
|
+
def _operation_models(path: Path) -> dict[str, tuple[str, ...]]:
|
|
257
|
+
from .json_boundary import load_owned_object
|
|
258
|
+
from .model_defaults import ModelDefaultError, parse_model_lists
|
|
259
|
+
|
|
260
|
+
payload = load_owned_object(path, artifact="model configuration") if path.is_file() else {}
|
|
261
|
+
try:
|
|
262
|
+
return parse_model_lists(payload, "operationModels", path)
|
|
263
|
+
except ModelDefaultError as exc:
|
|
264
|
+
raise OperationPreparationError(str(exc)) from exc
|
|
265
|
+
|
|
266
|
+
|
|
267
|
+
def slot_payload(slot: OperationSlot) -> dict[str, object]:
|
|
268
|
+
"""The JSON row callers print for one slot."""
|
|
269
|
+
return {
|
|
270
|
+
"ordinal": slot.ordinal,
|
|
271
|
+
"provider": slot.provider_id,
|
|
272
|
+
"modelRef": slot.model_ref,
|
|
273
|
+
"model": slot.display_name,
|
|
274
|
+
}
|
|
@@ -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
|
|