okstra 0.226.0 → 0.228.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 +2 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/wizard.mjs +12 -15
- package/dist/commands/execute/wizard.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +43 -7
- package/docs/project-structure-overview.md +13 -3
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/code-review.json +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -0
- package/runtime/prompts/lead/convergence.md +5 -19
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/prompts/wizard/prompts.ko.json +44 -0
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +63 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +3 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +5 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
- package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
- package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
- package/runtime/python/okstra_ctl/brief_sources.py +162 -44
- package/runtime/python/okstra_ctl/code_review_coverage.py +81 -19
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +115 -55
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/correction_cli.py +6 -5
- package/runtime/python/okstra_ctl/correction_round.py +1 -1
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- package/runtime/python/okstra_ctl/domain/worker_defaults.py +106 -0
- package/runtime/python/okstra_ctl/file_size_cap.py +56 -6
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
- package/runtime/python/okstra_ctl/fixed_text.py +31 -9
- package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
- package/runtime/python/okstra_ctl/json_registry.py +3 -18
- package/runtime/python/okstra_ctl/manager_split.py +201 -84
- package/runtime/python/okstra_ctl/model_io/references.py +31 -1
- package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
- package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
- package/runtime/python/okstra_ctl/path_hints.py +13 -1
- package/runtime/python/okstra_ctl/paths.py +4 -0
- package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
- package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +4 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +22 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/plan_items.py +9 -11
- package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
- package/runtime/python/okstra_ctl/ports/worker_defaults.py +25 -0
- package/runtime/python/okstra_ctl/prior_planning.py +6 -17
- package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
- package/runtime/python/okstra_ctl/qa_commands.py +66 -1
- package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
- package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
- package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
- package/runtime/python/okstra_ctl/registry/worker_defaults_store.py +8 -0
- package/runtime/python/okstra_ctl/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +123 -6
- package/runtime/python/okstra_ctl/stage_done.py +5 -4
- package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
- package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
- package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
- package/runtime/python/okstra_ctl/verification_plan.py +116 -0
- package/runtime/python/okstra_ctl/wizard/cli.py +16 -4
- package/runtime/python/okstra_ctl/wizard/confirmation.py +21 -0
- package/runtime/python/okstra_ctl/wizard/engine.py +25 -3
- package/runtime/python/okstra_ctl/wizard/ids.py +23 -0
- package/runtime/python/okstra_ctl/wizard/render.py +2 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +73 -23
- package/runtime/python/okstra_ctl/wizard/state.py +55 -14
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +5 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +334 -0
- package/runtime/python/okstra_ctl/worker_defaults.py +135 -0
- package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
- package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
- package/runtime/python/okstra_ctl/write_policy.py +33 -18
- package/runtime/python/okstra_project/dirs.py +22 -0
- package/runtime/python/okstra_project/resolver.py +10 -0
- package/runtime/schemas/final-report-v3.0.schema.json +5 -1
- package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
- package/runtime/skills/okstra-code-review/SKILL.md +59 -63
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +32 -9
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- package/runtime/skills/okstra-run/SKILL.md +21 -1
- package/runtime/skills/okstra-setup/SKILL.md +2 -0
- package/runtime/skills/okstra-setup/references/project-config.md +2 -0
- package/runtime/validators/validate-brief.py +21 -5
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md
CHANGED
|
@@ -29,7 +29,9 @@ A target mismatch or changed fingerprint invalidates this check's evidence. Reco
|
|
|
29
29
|
|
|
30
30
|
### Two-tier command lookup (NO auto-detection)
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
Follow the `**Verification inputs:**` declaration-source rule when that header is present. References to project `qaCommands` throughout this sidecar, including the DB gate, mean the baseline selected by that rule. The legacy lookup below supplies only the sources that rule leaves unfrozen. A missing or unreadable referenced snapshot is missing verification input, not permission to substitute current settings.
|
|
33
|
+
|
|
34
|
+
The legacy lookup obtains the QA command set from two declared sources, in order — there is **no fallback to guessing tools from manifest files**.
|
|
33
35
|
|
|
34
36
|
1. **Tier 1 — plan validation set (task-specific):** every command listed under the approved plan's `validation` block (pre / mid / post). The plan is the file at this prompt's `**Approved plan:**` anchor, scoped to the stage its `**Stage for this implementation run:**` anchor names; both are generated headers, so a missing one is `contract-violated`, never a value to infer. Each checklist row also carries `phase`, and the phase is part of what the row asserts: `pre` runs before the stage edits, `mid` between the edits and the stage commit, `post` after the commit. A `mid` diff-scope check (`git diff --name-only` listing the touched paths) is reproduced over the stage range — `git diff --name-only <stage base>...HEAD` — once the stage has committed; its empty output on the clean post-commit tree is the plan's own step order, not a divergence. A `Discrepancy` that cites a checklist row names the row and its phase as `VC-NNN (phase: mid)`; a verifier that reads the command without the phase has read half the row. **Enforced:** `_validate_verifier_discrepancy_names_checklist_phase` in `validators/validate-run.py` fails a divergence that cites a `VC-` row without that row's phase.
|
|
35
37
|
2. **Tier 2 — project baseline:** the project's standing QA baseline from the `Project QA Commands` section emitted by `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names).
|
|
@@ -214,9 +216,9 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
|
|
|
214
216
|
- **Non-separating test data:** two scenarios whose setup values and assertions are identical, so a wrong implementation passes both; or new test tooling added in this diff (mock, state setter, repository branch) that no test calls.
|
|
215
217
|
- **Effect claimed under its own mock:** a test presented as covering an effect whose producing path is replaced by a mock inside that same test. The mock's presence in the harness is not evidence the branch behind it works.
|
|
216
218
|
- **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape. Do NOT raise this on a function extracted purely to bring a body under the 50-line cap — that is principle 5 doing its job — nor on a pre-existing abstraction this diff merely edits.
|
|
217
|
-
- **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:
|
|
219
|
+
- **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:501 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 500 lines, or a file the diff took from 500 or fewer past 500. A file already over 500 at the stage base that the diff grows is not blocking; the command prints it as an advisory line. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target: a new file over 300, a file the diff took past 300, or a file already over 300 the diff grew, including one already over 500) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
|
|
218
220
|
- **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
|
|
219
|
-
- **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within
|
|
221
|
+
- **Advisory findings (recorded as recommendations; verdict MAY still PASS):** each `FILE-SIZE-ADVISORY:` line from the file-size command (a file over the 300-line target but within 500), function >50 effective lines, a single body mixing read+write stages, weak readability, a missing-but-non-critical outcome assertion, weak-but-not-misleading names, priority-between-inputs policy inlined in a service condition instead of a named domain function, an error message asserting a cause the code never observed, a memory / concurrency / batching change with no test pinning the bound it claims, or (hexagonal overlay only) a service dependency this diff adds or modifies that injects a concrete adapter instead of a port — record it with the port sketch; advisory only while the project has not declared `architecture.style = hexagonal`, since that declaration — and only that one — promotes exactly this item to blocking per the declared-style bullet above, while a declared `layered` binds dependency direction instead and leaves this item advisory; an existing convention of concrete injections does not convert this one to `clean`, it is the debt the rule pays down. These land in the verifier result as `should-fix` / `nit` recommendations, not as a `FAIL`.
|
|
220
222
|
- **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
|
|
221
223
|
|
|
222
224
|
### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
|
|
@@ -130,6 +130,20 @@ These outcomes are enforced by
|
|
|
130
130
|
|
|
131
131
|
## 4. executor and verifier
|
|
132
132
|
|
|
133
|
+
The generated `worker_prompt_headers.py::verification_input_headers` instruction
|
|
134
|
+
owns declaration-source selection when the run records frozen inputs. The
|
|
135
|
+
verifier follows it before the legacy lookup throughout its sidecar, including
|
|
136
|
+
the DB gate. The named `model-io verification-input` projection validates run
|
|
137
|
+
ownership, snapshot schema, cross-field constraints and digest before exposing
|
|
138
|
+
frozen scalar fields. Quoted strings preserve command and procedure characters.
|
|
139
|
+
`test_verification_input_projection_rejects_invalid_input_before_output` checks
|
|
140
|
+
the read boundary. Snapshot references
|
|
141
|
+
are not command-execution evidence; stage scope, checklist timing and independent
|
|
142
|
+
QA ownership remain in force. This is a worker guideline, not an execution-log
|
|
143
|
+
validator. `tests/contract/test_docs_runtime_contract.py::test_qa_phase_sources_follow_frozen_input_headers`
|
|
144
|
+
checks instruction/spec alignment, and the header and recovery tests cover the
|
|
145
|
+
generated reference contract.
|
|
146
|
+
|
|
133
147
|
```mermaid
|
|
134
148
|
flowchart TD
|
|
135
149
|
Lead[Okstra lead<br/>host native] --> Exec[Executor<br/>selected provider]
|
|
@@ -55,7 +55,8 @@ def requirement_instructions(original_requirement_ids: Sequence[str], participat
|
|
|
55
55
|
"`feasible`, `safetyBlockers` is empty, and every "
|
|
56
56
|
"`unresolvedFeasibilityFacts` entry is a `deferred-gate` fact that names "
|
|
57
57
|
"its `gate`. A candidate whose `splitAcceptance.clarificationRef` names "
|
|
58
|
-
"the user's `accept-risk` answer to
|
|
58
|
+
"the user's `accept-risk` answer to that candidate's own split needs one "
|
|
59
|
+
"`feasible` vote, "
|
|
59
60
|
"and its remaining facts stay on the row as the accepted risk; never set "
|
|
60
61
|
"`splitAcceptance` before that answer is recorded.",
|
|
61
62
|
("Classify each `unresolvedFeasibilityFacts` entry with `resolutionKind`: "
|
|
@@ -28,7 +28,7 @@
|
|
|
28
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 <report writer narrative>` 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
|
-
- **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>` (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. 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`.
|
|
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`.
|
|
32
32
|
{{INCLUDE:_clarification-recommendation.md}}
|
|
33
33
|
- Cross-verification mode:
|
|
34
34
|
- Phase 5.5 convergence runs in adversarial mode (`convergence.adversarial=true`).
|
|
@@ -7,7 +7,7 @@ import json
|
|
|
7
7
|
import re
|
|
8
8
|
from collections import Counter
|
|
9
9
|
from dataclasses import dataclass
|
|
10
|
-
from collections.abc import Mapping, Sequence
|
|
10
|
+
from collections.abc import Iterator, Mapping, Sequence
|
|
11
11
|
from typing import Any
|
|
12
12
|
|
|
13
13
|
from okstra_ctl.clarification_items.dispositions import (
|
|
@@ -269,6 +269,30 @@ def blocking_feasibility_facts(option: Mapping[str, object]) -> list[object]:
|
|
|
269
269
|
]
|
|
270
270
|
|
|
271
271
|
|
|
272
|
+
def _required_feasible_votes_for(
|
|
273
|
+
option: Mapping[str, object], participating_analysers: Sequence[str],
|
|
274
|
+
) -> int:
|
|
275
|
+
# 갈린 표는 같은 분석자들에게 다시 물어도 갈린다. 사용자가 위험 감수로
|
|
276
|
+
# 받아들인 후보는 `feasible` 한 표로 충분하다 — 방향을 낸 근거가 있어야
|
|
277
|
+
# 받아들일 대상이 있다.
|
|
278
|
+
if split_acceptance_ref(option):
|
|
279
|
+
return 1
|
|
280
|
+
return required_feasible_votes(participating_analysers)
|
|
281
|
+
|
|
282
|
+
|
|
283
|
+
def _ungated_deferred_fact_errors(
|
|
284
|
+
option_id: str, option: Mapping[str, object],
|
|
285
|
+
) -> list[str]:
|
|
286
|
+
return [
|
|
287
|
+
f"{option_id} unresolvedFeasibilityFacts[{index}]: a "
|
|
288
|
+
f"{DEFERRED_GATE_KIND} fact must name the gate that closes it"
|
|
289
|
+
for index, fact in enumerate(option.get("unresolvedFeasibilityFacts") or ())
|
|
290
|
+
if isinstance(fact, Mapping)
|
|
291
|
+
and fact.get("resolutionKind") == DEFERRED_GATE_KIND
|
|
292
|
+
and not _is_deferred_gate_fact(fact)
|
|
293
|
+
]
|
|
294
|
+
|
|
295
|
+
|
|
272
296
|
def _validate_option_feasibility(
|
|
273
297
|
option: Mapping[str, object],
|
|
274
298
|
participating_analysers: Sequence[str],
|
|
@@ -291,11 +315,7 @@ def _validate_option_feasibility(
|
|
|
291
315
|
isinstance(vote, Mapping) and vote.get("verdict") == "feasible"
|
|
292
316
|
for vote in votes
|
|
293
317
|
)
|
|
294
|
-
|
|
295
|
-
# 받아들인 후보는 `feasible` 한 표로 충분하다 — 방향을 낸 근거가 있어야
|
|
296
|
-
# 받아들일 대상이 있다.
|
|
297
|
-
accepted = bool(split_acceptance_ref(option))
|
|
298
|
-
required = 1 if accepted else required_feasible_votes(participating_analysers)
|
|
318
|
+
required = _required_feasible_votes_for(option, participating_analysers)
|
|
299
319
|
if require_valid and feasible < required:
|
|
300
320
|
errors.append(
|
|
301
321
|
f"{option_id} must have at least {required} feasible vote(s); a split "
|
|
@@ -311,16 +331,7 @@ def _validate_option_feasibility(
|
|
|
311
331
|
f"{DEFERRED_GATE_KIND} facts that name their gate, or accepted through "
|
|
312
332
|
"splitAcceptance"
|
|
313
333
|
)
|
|
314
|
-
|
|
315
|
-
if (
|
|
316
|
-
isinstance(fact, Mapping)
|
|
317
|
-
and fact.get("resolutionKind") == DEFERRED_GATE_KIND
|
|
318
|
-
and not _is_deferred_gate_fact(fact)
|
|
319
|
-
):
|
|
320
|
-
errors.append(
|
|
321
|
-
f"{option_id} unresolvedFeasibilityFacts[{index}]: a "
|
|
322
|
-
f"{DEFERRED_GATE_KIND} fact must name the gate that closes it"
|
|
323
|
-
)
|
|
334
|
+
errors.extend(_ungated_deferred_fact_errors(option_id, option))
|
|
324
335
|
copied = _copied_votes(votes)
|
|
325
336
|
for first, second in copied:
|
|
326
337
|
errors.append(
|
|
@@ -447,6 +458,15 @@ class VoteGap:
|
|
|
447
458
|
feasible_votes: int
|
|
448
459
|
|
|
449
460
|
|
|
461
|
+
def selection_candidates(
|
|
462
|
+
selection: Mapping[str, object],
|
|
463
|
+
) -> Iterator[Mapping[str, object]]:
|
|
464
|
+
for key in ("rankedOptions", "candidateAudit"):
|
|
465
|
+
for row in selection.get(key) or ():
|
|
466
|
+
if isinstance(row, Mapping):
|
|
467
|
+
yield row
|
|
468
|
+
|
|
469
|
+
|
|
450
470
|
def vote_gaps(
|
|
451
471
|
selection: Mapping[str, object],
|
|
452
472
|
participating_analysers: Sequence[str],
|
|
@@ -460,20 +480,15 @@ def vote_gaps(
|
|
|
460
480
|
IO-001·IO-002·IO-003 이 각각 `feasible` 2표를 받고도 빠진 분석자가 하나씩
|
|
461
481
|
달라 전부 탈락했고, 그 run 은 후보 0건으로 차단됐다.
|
|
462
482
|
|
|
463
|
-
여기서 세는 것은 **표만 모자란** 후보다. `safetyBlockers
|
|
464
|
-
`
|
|
465
|
-
|
|
483
|
+
여기서 세는 것은 **표만 모자란** 후보다. A candidate with `safetyBlockers`,
|
|
484
|
+
blocking facts (`blocking_feasibility_facts`), or copied votes is excluded,
|
|
485
|
+
because more votes would not make it valid. 남은 표를 다 받아도 `feasible` 이
|
|
466
486
|
`required_feasible_votes` 에 못 미치는 후보도 제외한다 — 부쳐 봐야 결과가
|
|
467
487
|
같다.
|
|
468
488
|
"""
|
|
469
489
|
roster = list(dict.fromkeys(str(name) for name in participating_analysers))
|
|
470
490
|
gaps: list[VoteGap] = []
|
|
471
|
-
for candidate in (
|
|
472
|
-
row
|
|
473
|
-
for key in ("rankedOptions", "candidateAudit")
|
|
474
|
-
for row in (selection.get(key) or ())
|
|
475
|
-
if isinstance(row, Mapping)
|
|
476
|
-
):
|
|
491
|
+
for candidate in selection_candidates(selection):
|
|
477
492
|
if candidate.get("safetyBlockers") or blocking_feasibility_facts(candidate):
|
|
478
493
|
continue
|
|
479
494
|
votes = candidate.get("feasibilityVotes") or ()
|
|
@@ -535,10 +550,7 @@ def validate_blocked_answer_channel(
|
|
|
535
550
|
)
|
|
536
551
|
}
|
|
537
552
|
errors: list[str] = []
|
|
538
|
-
for candidate in (
|
|
539
|
-
row for key in ("rankedOptions", "candidateAudit")
|
|
540
|
-
for row in (selection.get(key) or ()) if isinstance(row, Mapping)
|
|
541
|
-
):
|
|
553
|
+
for candidate in selection_candidates(selection):
|
|
542
554
|
for index, fact in enumerate(candidate.get("unresolvedFeasibilityFacts") or ()):
|
|
543
555
|
label = f"{candidate.get('id')} unresolvedFeasibilityFacts[{index}]"
|
|
544
556
|
if not isinstance(fact, Mapping):
|
|
@@ -571,6 +583,9 @@ def validate_split_acceptance(report_data: Mapping[str, object]) -> list[str]:
|
|
|
571
583
|
서술 검증(`validate_implementation_option_selection`)은 clarification 행을
|
|
572
584
|
보지 못한다. 리드 원장이 합쳐진 뒤에만 이 인용이 실제 `accept-risk` 답인지
|
|
573
585
|
알 수 있으므로 조립과 `validate-run.py` 가 이 함수를 따로 부른다.
|
|
586
|
+
|
|
587
|
+
The cited row must name the citing candidate in `candidateRef`: the user's
|
|
588
|
+
answer accepts the risk of one direction, not of every candidate that cites it.
|
|
574
589
|
"""
|
|
575
590
|
selection = report_data.get("implementationOptionSelection")
|
|
576
591
|
if not isinstance(selection, Mapping):
|
|
@@ -581,26 +596,27 @@ def validate_split_acceptance(report_data: Mapping[str, object]) -> list[str]:
|
|
|
581
596
|
if isinstance(row, Mapping)
|
|
582
597
|
}
|
|
583
598
|
errors: list[str] = []
|
|
584
|
-
for candidate in (
|
|
585
|
-
row for key in ("rankedOptions", "candidateAudit")
|
|
586
|
-
for row in (selection.get(key) or ()) if isinstance(row, Mapping)
|
|
587
|
-
):
|
|
599
|
+
for candidate in selection_candidates(selection):
|
|
588
600
|
ref = split_acceptance_ref(candidate)
|
|
589
601
|
if not ref and "splitAcceptance" not in candidate:
|
|
590
602
|
continue
|
|
603
|
+
candidate_id = candidate.get("id")
|
|
591
604
|
row = rows.get(ref)
|
|
592
605
|
if (
|
|
593
606
|
row is None
|
|
594
607
|
or str(row.get("blocks") or "").strip().lower() != "approval"
|
|
595
608
|
or str(row.get("status") or "").strip().lower() == "obsolete"
|
|
596
609
|
or clarification_disposition(row) != SPLIT_ACCEPTANCE_DISPOSITION
|
|
610
|
+
or row.get("candidateRef") != candidate_id
|
|
597
611
|
):
|
|
598
612
|
errors.append(
|
|
599
|
-
f"{
|
|
600
|
-
"`blocks: approval` clarification
|
|
613
|
+
f"{candidate_id} splitAcceptance {ref!r} must name a "
|
|
614
|
+
f"`blocks: approval` clarification opened for {candidate_id} "
|
|
615
|
+
f"(`candidateRef: {candidate_id}`) that the user answered with "
|
|
601
616
|
f"`{SPLIT_ACCEPTANCE_DISPOSITION}`; open it with `okstra "
|
|
602
|
-
"approval-decision open --ledger <approvalDecisionsPath
|
|
603
|
-
"the answer with `okstra
|
|
617
|
+
"approval-decision open --ledger <approvalDecisionsPath> "
|
|
618
|
+
f"--candidate-ref {candidate_id}`, record the answer with `okstra "
|
|
619
|
+
"approval-decision resolve`, then reassemble"
|
|
604
620
|
)
|
|
605
621
|
return errors
|
|
606
622
|
|
|
@@ -67,6 +67,7 @@ from okstra_ctl.plan_item_evidence import (
|
|
|
67
67
|
from okstra_ctl.plan_review_context import render_review_context
|
|
68
68
|
from okstra_ctl.stage_ledger import build_stage_ledger
|
|
69
69
|
from okstra_ctl.claim_reproduction import NOT_RUNNABLE, reproduce
|
|
70
|
+
from okstra_ctl.file_size_cap import headroom_text, planned_file_headroom
|
|
70
71
|
from okstra_ctl.final_report_schema import load_schema_version
|
|
71
72
|
from okstra_ctl.report_narrative import parse_narrative
|
|
72
73
|
from okstra_ctl.report_assembly import validate_plan_draft
|
|
@@ -538,12 +539,16 @@ def _prepare(args: argparse.Namespace) -> dict[str, Any]:
|
|
|
538
539
|
envelope.update(_reverify_carry(args, envelope["dispatchQueue"]))
|
|
539
540
|
gating = not advisory_plan_body_gating(_planning(source), envelope["items"])
|
|
540
541
|
_sync_task_manifest_gating(args.run_manifest, gating)
|
|
542
|
+
envelope["fileSizeHeadroom"] = planned_file_headroom(
|
|
543
|
+
_planning(source), authority.project_root,
|
|
544
|
+
)
|
|
541
545
|
write_json_atomic(output, envelope)
|
|
542
546
|
return {
|
|
543
547
|
"ok": True,
|
|
544
548
|
"operation": "prepare",
|
|
545
549
|
"path": str(output),
|
|
546
550
|
"gating": gating,
|
|
551
|
+
"fileSizeHeadroom": envelope["fileSizeHeadroom"],
|
|
547
552
|
}
|
|
548
553
|
|
|
549
554
|
|
|
@@ -1045,6 +1050,20 @@ def _render_inputs(run_manifest: Path) -> str:
|
|
|
1045
1050
|
return "\n## Inputs\n\n" + "".join(rows) if rows else ""
|
|
1046
1051
|
|
|
1047
1052
|
|
|
1053
|
+
def _render_file_size_headroom(rows: object) -> str:
|
|
1054
|
+
if not isinstance(rows, list) or not rows:
|
|
1055
|
+
return ""
|
|
1056
|
+
lines = [
|
|
1057
|
+
"\n## File-size headroom\n",
|
|
1058
|
+
"Existing files this plan writes, measured before any stage runs. Information "
|
|
1059
|
+
"only: it is not a verdict criterion.\n",
|
|
1060
|
+
]
|
|
1061
|
+
lines.extend(
|
|
1062
|
+
line("File-size headroom", headroom_text(row)) for row in rows if isinstance(row, Mapping)
|
|
1063
|
+
)
|
|
1064
|
+
return "".join(lines)
|
|
1065
|
+
|
|
1066
|
+
|
|
1048
1067
|
def _prompt(args: argparse.Namespace) -> str:
|
|
1049
1068
|
inputs = _checked_review_inputs(args.run_manifest)
|
|
1050
1069
|
envelope = _load_json_object(
|
|
@@ -1074,6 +1093,7 @@ def _prompt(args: argparse.Namespace) -> str:
|
|
|
1074
1093
|
rows.append(render_review_context(
|
|
1075
1094
|
[item["id"] for item in items], inputs, authority.payload, authority.project_root,
|
|
1076
1095
|
))
|
|
1096
|
+
rows.append(_render_file_size_headroom(envelope.get("fileSizeHeadroom")))
|
|
1077
1097
|
_checked_review_inputs(args.run_manifest)
|
|
1078
1098
|
for index, item in enumerate(items, 1):
|
|
1079
1099
|
if not isinstance(item, Mapping):
|
|
@@ -2566,6 +2586,8 @@ def main(argv: list[str] | None = None) -> int:
|
|
|
2566
2586
|
)
|
|
2567
2587
|
if "gating" in result:
|
|
2568
2588
|
rows += line("Gating", result["gating"])
|
|
2589
|
+
for row in result.get("fileSizeHeadroom", []):
|
|
2590
|
+
rows += line("File-size headroom", headroom_text(row))
|
|
2569
2591
|
print(rows, end="")
|
|
2570
2592
|
else:
|
|
2571
2593
|
print(json.dumps(result, ensure_ascii=False, indent=2))
|
|
@@ -413,7 +413,7 @@ round before any host or provider process starts.
|
|
|
413
413
|
|
|
414
414
|
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`; `tests/report/test_report_assembly.py` checks that invalid coverage creates no prepared queue.
|
|
415
415
|
|
|
416
|
-
1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --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 <report-writer-narrative.md> --run-manifest <run-manifest>`. After a self-fix rewrite, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. 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 `tests/run/test_plan_items.py`. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
|
|
416
|
+
1. Lead runs `okstra plan-items prepare --narrative <report-writer-narrative.md> --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 <report-writer-narrative.md> --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, pass `--state <plan-body-verification.json>` on prepare and validate-prepared. 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 `tests/run/test_plan_items.py`. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
|
|
417
417
|
|
|
418
418
|
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <report-writer-narrative.md> --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
419
|
|
|
@@ -148,7 +148,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
148
148
|
**Pick the cases by distinct outcome, not by line coverage.** When the stage writes or reconciles state, its meaningfully different outcomes are usually more than three — normal success, target already in the desired state (resume), existing data reused rather than created, a conflicting concurrent state, target absent, and mid-way failure with rollback. Enumerate the ones this stage actually implements and route them across the three lines (the `boundary` line is where resume / already-done / reuse belongs; `failure` carries conflict, absence, and rollback), naming each in the cell rather than collapsing them into "edge input". An implemented outcome with no declared case is a coverage gap the executor will not backfill.
|
|
149
149
|
- **Per-stage subsections** (`## 5.5.<i> Stage <i>: <title>` for each `i`), each containing the four required subsections:
|
|
150
150
|
- `### Carry-In` — for `depends-on (none)`: task-brief only. Otherwise: each depended-on stage's static exit contract + runtime sidecar path `runs/<impl-key>/carry/stage-<i>.json` placeholder.
|
|
151
|
-
- `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** **File size:** the implementation run aims for 300 physical lines per source and test file and enforces
|
|
151
|
+
- `### Stepwise Execution Order` — bite-sized table with `step | action | files | command | outcome | expected`. `outcome` is one word — `PASS` or `FAIL` — and `expected` is the sentence saying what that looks like here; a verdict written inside the sentence is not read as one. The `files` cell lists each touched path in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...`), which does not resolve and is rejected by plan-body verification as a kind-b path mismatch. **The narrative row additionally carries `plannedPaths`: the paths this step may write as an array, one repository-relative path per entry, with no globs, exclusions, counts or commentary. Read-only checks use `plannedPaths: []`; their working directory belongs in the command, not the write ledger. Never declare the repository or worktree root. Planning assembly and correction preflight enforce this through `write_policy.planned_path_declaration_errors`.** **File size:** the implementation run aims for 300 physical lines per source and test file and enforces 500 — a new file over 500 and an existing file taken from 500 or fewer past 500 are blocking findings the executor must split in a correction round; a file already over 500 that grows is advisory, as is a new, crossing or growing file over 300. When a step would add code or tests to a file near or over 300 lines (`wc -l`), plan a new module or test file for that responsibility in `plannedPaths` instead of appending to the existing one. **Enforced at implementation:** `okstra correction file-size` (`scripts/okstra_ctl/file_size_cap.py`), re-run by `okstra stage-done`. A plan does not say how many lines a step adds, so planning cannot apply the limit; instead `okstra plan-items prepare`, correction preflight (`check-corrections`) and the plan verifier prompt report one `File-size headroom` line per existing source or test file the plan's `plannedPaths` name that has more than 300 and at most 500 lines, with the lines left before 500 and every stage that writes it (`file_size_cap.planned_file_headroom`). The report is information for the plan's readers: it never blocks, and it is not a verdict criterion or a reason for a correction. Files the plan creates and files already over 500 are not listed. `files` is the sentence a reader sees; `plannedPaths` is the ledger report assembly preserves and the implementer write policy enforces. The design-surface detector maps every selected-option `fileStructure` path to the stage whose `files` or `plannedPaths` names it; a path neither names fails the draft check that correction preflight and `plan-items prepare` share (`scripts/okstra_ctl/report_assembly.py` `validate_plan_draft`). The one exception is an executor-owned conformance script under `qa/scripts/`: the detector skips it (`scripts/okstra_ctl/design_surfaces.py` `_stages_for_selected_path`), and no step lists it in `files` or `plannedPaths`, because the implementation run writes it (see `Conformance tests:` below). When a step legitimately covers a set too large to enumerate, split it or name the directory the set lives under. **Effective row count ≤ 8** (excluding header / divider / blank). Each step is one cohesive, self-contained change. **TDD ordering is MUST, not a preference:** the **first** effective step's `action` cell MUST start with the literal `RED:` and describe the failing test(s) that capture this stage's `Acceptance` **and the three declared `Test case (success|boundary|failure)` lines** (`outcome` = `FAIL`); at least one later `action` cell MUST start with the literal `GREEN:` and describe the minimal implementation that makes it pass (`outcome` = `PASS`); an optional refactor step starts with `REFACTOR:`. **Exemption:** doc-only / config-only / pure-rename stages with no observable runtime behaviour may omit RED/GREEN by declaring one line `TDD exemption: <reason>` in the stage section. A stage that is truthfully none of those three declares `TDD exemption: user-bypass — <the user's words>`, which holds only while the user has granted it for that stage with `okstra prepare --tdd-bypass "<stage>:<reason>"` — never file the nearest of the three instead. Validator S10c enforces RED-first + GREEN; the `outcome` cell agreeing with its prefix is a schema conditional. S10e rejects an unsupported exemption reason and a `user-bypass` with no user grant (`validators/validate-implementation-plan-stages.py`).
|
|
152
152
|
- **Real-IO tests stay out of the plan's committed steps (BLOCKING).** A step never creates, edits, or runs a test that opens a real database connection, makes a real network call, or talks to a real external service inside the project source test tree (`src/**`, `test/**`, `tests/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*`, `*.e2e-spec.*`), and no step's `PASS` depends on a reachable database or service. The implementation executor refuses such a step before its first edit (`_implementation-executor.md` "Real-IO test isolation"), so a plan that contains one stops the stage with zero changes (observed 2026-10-18, dev-11374: a live-MySQL `test/font-pairing.e2e-spec.ts` planned in steps 1, 4 and 5). The committed RED/GREEN steps test the adapter with its injected collaborator stubbed — the exact query text, its replacements, and the returned rows — and run without any backend. Real-backend verification is declared only as this stage's `Conformance tests:` line below (`requires=[db|http|external]`): the implementation run writes that script under `<task_root>/qa/scripts/`, runs it against a local or replica backend when one is reachable, never commits it, and records a non-PASS or unreachable backend as advisory. Read a brief line such as `verify: integration test against a test database` as that conformance declaration, not as a committed test. Do not plan a shared real-DB guard, a test DDL fixture, or an edit to an existing real-IO suite in source to support it. **Enforced:** every `P-Step-*` item of the §5.5.9 plan-body round carries this rule to its verifiers (`okstra_ctl.phases.implementation_planning.authoring._REAL_IO_STEP_NOTE`), which vote `DISAGREE(b)` on a step that breaks it; no path pattern tells a mocked test from a live one, so no validator checks it.
|
|
153
153
|
- **The `command` cell runs inside an okstra task worktree, not a bare checkout (BLOCKING).** okstra provisions `.okstra`, the configured sync entries (`.project-docs`, `.claude`, …), and — for `implementation` — a nested `stage-<N>/` worktree into the tree the step executes in. Two consequences bind every command you write:
|
|
154
154
|
- **Clean-tree assertions use `okstra worktree-status --check-clean`.** A bare `git status --porcelain` is never empty there, so an assertion built on one fails on okstra's scaffolding rather than on the stage's work. The okstra command asks the same question over source paths only and exits 1 when dirty, so it stands alone as a step's assertion: `okstra worktree-status --check-clean`. Validator S13 rejects the bare form. Do not add a `git tag stage-<N>-exit` to the step. Stage completion records the commit in the consumer ledger without creating or moving git tags.
|
|
@@ -13,7 +13,7 @@ from .build_tools import command_invokes_build_tool
|
|
|
13
13
|
from .design_snapshot import build_design_snapshot
|
|
14
14
|
from .design_surfaces import (
|
|
15
15
|
DesignSurfaceError,
|
|
16
|
-
|
|
16
|
+
detect_design_surfaces_in_unvalidated_plan,
|
|
17
17
|
expected_prep_plan_item_id,
|
|
18
18
|
)
|
|
19
19
|
|
|
@@ -104,7 +104,7 @@ def _item_block(source: str) -> str:
|
|
|
104
104
|
return "record" if source in _RECORD_SOURCES else "execution"
|
|
105
105
|
|
|
106
106
|
|
|
107
|
-
def
|
|
107
|
+
def stage_scope(row: Mapping[str, Any] | None, *coordinates: int) -> list[int] | None:
|
|
108
108
|
"""이 항목이 걸리는 스테이지. 어디에도 안 걸리면 ``None``.
|
|
109
109
|
|
|
110
110
|
게이트 범위를 다음 실행 스테이지로 좁히려면 항목마다 이 값이 있어야 한다.
|
|
@@ -228,7 +228,7 @@ def _extract_standard_items(planning: Mapping[str, Any]) -> list[dict[str, Any]]
|
|
|
228
228
|
{
|
|
229
229
|
"id": item_id,
|
|
230
230
|
"elementId": _natural_element_id(source, prefix, row, item_id),
|
|
231
|
-
"stageScope":
|
|
231
|
+
"stageScope": stage_scope(row),
|
|
232
232
|
"block": _item_block(source),
|
|
233
233
|
"subject": _subject(row, source),
|
|
234
234
|
"sourceSection": section,
|
|
@@ -253,7 +253,7 @@ def _extract_step_items(
|
|
|
253
253
|
# 평면 배열에는 좌표가 없어 위치 id 로 떨어진다.
|
|
254
254
|
"id": f"{prefix}-{index}",
|
|
255
255
|
"elementId": f"{prefix}-{index}",
|
|
256
|
-
"stageScope":
|
|
256
|
+
"stageScope": stage_scope(row),
|
|
257
257
|
"block": "execution", "subject": _subject(row, "stepwiseExecution"),
|
|
258
258
|
"sourceSection": section,
|
|
259
259
|
"ticketId": _ticket_id(row),
|
|
@@ -275,7 +275,7 @@ def _extract_step_items(
|
|
|
275
275
|
{
|
|
276
276
|
"id": f"{prefix}-{stage_number}.{step_number}",
|
|
277
277
|
"elementId": f"step:{stage_number}.{step_number}",
|
|
278
|
-
"stageScope":
|
|
278
|
+
"stageScope": stage_scope(None, stage_number),
|
|
279
279
|
"block": "execution",
|
|
280
280
|
"subject": _subject(row, "stepwiseExecution"),
|
|
281
281
|
"sourceSection": section,
|
|
@@ -292,15 +292,13 @@ def _extract_step_items(
|
|
|
292
292
|
def _extract_prep_items(
|
|
293
293
|
planning: Mapping[str, Any], items: list[dict[str, Any]]
|
|
294
294
|
) -> None:
|
|
295
|
-
if not planning.get("stages"):
|
|
296
|
-
return
|
|
297
295
|
# 계약 분기는 탐지기가 안다(`design_surfaces._planned_file_structure`).
|
|
298
296
|
# 여기서 레거시 모양을 흉내 내 넘기던 동안 그 지식은 이 호출부에만 있었고,
|
|
299
297
|
# 같은 탐지기를 부르는 나머지 세 곳은 선택 방향 계획에서 실패했다.
|
|
300
298
|
try:
|
|
301
|
-
triggers =
|
|
302
|
-
except
|
|
303
|
-
raise PlanItemContractError(
|
|
299
|
+
triggers = detect_design_surfaces_in_unvalidated_plan(planning)
|
|
300
|
+
except DesignSurfaceError as exc:
|
|
301
|
+
raise PlanItemContractError(str(exc)) from exc
|
|
304
302
|
for trigger in triggers:
|
|
305
303
|
item_id = expected_prep_plan_item_id(trigger.stage, trigger.kind)
|
|
306
304
|
_add_item(
|
|
@@ -308,7 +306,7 @@ def _extract_prep_items(
|
|
|
308
306
|
{
|
|
309
307
|
"id": item_id,
|
|
310
308
|
"elementId": f"prep:{trigger.stage}:{_element_key(trigger.kind)}",
|
|
311
|
-
"stageScope":
|
|
309
|
+
"stageScope": stage_scope(None, trigger.stage),
|
|
312
310
|
"block": "execution",
|
|
313
311
|
"subject": f"Stage {trigger.stage} {trigger.kind} design preparation",
|
|
314
312
|
"sourceSection": "5.5.10",
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
from typing import Protocol
|
|
5
|
+
|
|
6
|
+
from ..paths import RunRef
|
|
7
|
+
from ..verification_input_ref import VerificationInputReference
|
|
8
|
+
from ..verification_input_types import VerificationInputs
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
class VerificationInputStore(Protocol):
|
|
12
|
+
def freeze(
|
|
13
|
+
self, project: Path, source: Path, ref: RunRef,
|
|
14
|
+
*, approved_plan: Path | None,
|
|
15
|
+
) -> VerificationInputReference: ...
|
|
16
|
+
|
|
17
|
+
def read(self, path: Path, digest: str) -> VerificationInputs: ...
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
from __future__ import annotations
|
|
2
|
+
|
|
3
|
+
from collections.abc import Mapping
|
|
4
|
+
from pathlib import Path
|
|
5
|
+
from typing import Protocol
|
|
6
|
+
|
|
7
|
+
from ..domain.worker_defaults import (
|
|
8
|
+
WorkerDefaultScopes,
|
|
9
|
+
WorkerDefaultUpdates,
|
|
10
|
+
WorkerScope,
|
|
11
|
+
)
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class WorkerDefaultsStore(Protocol):
|
|
15
|
+
def scope_path(self, scope: WorkerScope, project_root: Path | None) -> Path: ...
|
|
16
|
+
|
|
17
|
+
def load_scopes(self, project_root: Path | None) -> WorkerDefaultScopes: ...
|
|
18
|
+
|
|
19
|
+
def save_scope(
|
|
20
|
+
self,
|
|
21
|
+
scope: WorkerScope,
|
|
22
|
+
project_root: Path | None,
|
|
23
|
+
updates: WorkerDefaultUpdates,
|
|
24
|
+
before: Mapping[str, object],
|
|
25
|
+
) -> dict[str, object]: ...
|
|
@@ -19,14 +19,13 @@ timeout 시킨 적이 있다(`clarification_items.carry` 참고).
|
|
|
19
19
|
"""
|
|
20
20
|
from __future__ import annotations
|
|
21
21
|
|
|
22
|
-
import re
|
|
23
22
|
from pathlib import Path
|
|
24
23
|
from typing import Any, Mapping
|
|
25
24
|
|
|
26
25
|
from .clarification_items import carried_clarification_rows
|
|
27
26
|
from .final_report_paths import final_report_data_path
|
|
28
|
-
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
29
27
|
from .paths import RunRef, infer_project_root, project_rel
|
|
28
|
+
from .prior_run_summary import load_prior_object, one_line
|
|
30
29
|
|
|
31
30
|
|
|
32
31
|
PLANNING_TASK_TYPE = "implementation-planning"
|
|
@@ -34,7 +33,6 @@ PLANNING_TASK_TYPE = "implementation-planning"
|
|
|
34
33
|
# 의 어휘를 그대로 쓴다 — 새 어휘를 만들면 같은 finding 이 run 마다 다르게 읽힌다.
|
|
35
34
|
UNSETTLED_CLASSIFICATIONS = ("contested", "worker-unique")
|
|
36
35
|
_SUMMARY_LIMIT = 200
|
|
37
|
-
_WHITESPACE_RE = re.compile(r"\s+")
|
|
38
36
|
|
|
39
37
|
|
|
40
38
|
def build_prior_planning_summary(task_root: Path) -> str:
|
|
@@ -138,20 +136,11 @@ def _load_object(path: Path) -> Mapping[str, Any]:
|
|
|
138
136
|
이 블록은 전부 최선 노력이다. 직전 run 의 산출물이 깨졌다고 새 run 의 준비를
|
|
139
137
|
막으면, 다시 도는 이유였던 그 실패가 재실행 자체를 못 하게 만든다.
|
|
140
138
|
"""
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
# 맥락일 뿐이라 없는 상태가 정상 분기고, 소비처는 해당 하위 블록을
|
|
146
|
-
# 생략한다.
|
|
147
|
-
return {}
|
|
148
|
-
return data if isinstance(data, Mapping) else {}
|
|
139
|
+
# A missing file is the normal case here (a run that ended before writing
|
|
140
|
+
# it), so the reason is not shown.
|
|
141
|
+
data, _reason = load_prior_object(path, artifact="prior planning artifact")
|
|
142
|
+
return data
|
|
149
143
|
|
|
150
144
|
|
|
151
145
|
def _one_line(value: object) -> str:
|
|
152
|
-
|
|
153
|
-
return ""
|
|
154
|
-
collapsed = _WHITESPACE_RE.sub(" ", value).strip()
|
|
155
|
-
if len(collapsed) <= _SUMMARY_LIMIT:
|
|
156
|
-
return collapsed
|
|
157
|
-
return collapsed[: _SUMMARY_LIMIT - 1].rstrip() + "…"
|
|
146
|
+
return one_line(value, _SUMMARY_LIMIT)
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
"""Shared pieces of the packet blocks that summarise an earlier run's artifacts."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import re
|
|
5
|
+
from collections.abc import Mapping
|
|
6
|
+
from pathlib import Path
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from .json_boundary import JsonBoundaryError, load_owned_object
|
|
10
|
+
|
|
11
|
+
_WHITESPACE_RE = re.compile(r"\s+")
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def one_line(value: object, limit: int) -> str:
|
|
15
|
+
"""``value`` as one line of at most ``limit`` characters; ``""`` if not a string."""
|
|
16
|
+
if not isinstance(value, str):
|
|
17
|
+
return ""
|
|
18
|
+
collapsed = _WHITESPACE_RE.sub(" ", value).strip()
|
|
19
|
+
if len(collapsed) <= limit:
|
|
20
|
+
return collapsed
|
|
21
|
+
return collapsed[: limit - 1].rstrip() + "…"
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def load_prior_object(
|
|
25
|
+
path: Path, *, artifact: str,
|
|
26
|
+
) -> tuple[Mapping[str, Any], str | None]:
|
|
27
|
+
"""The owned object at ``path``, or an empty mapping and why it could not be read.
|
|
28
|
+
|
|
29
|
+
A packet block is context for a new run, so a broken earlier artifact must not
|
|
30
|
+
stop that run's prepare; the caller decides whether to show the reason.
|
|
31
|
+
"""
|
|
32
|
+
try:
|
|
33
|
+
return load_owned_object(path, artifact=artifact), None
|
|
34
|
+
except JsonBoundaryError as exc:
|
|
35
|
+
return {}, exc.reason
|