okstra 0.227.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.
Files changed (74) hide show
  1. package/README.md +1 -1
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/docs/architecture/storage-model.md +77 -0
  5. package/docs/cli.md +15 -3
  6. package/docs/project-structure-overview.md +12 -2
  7. package/package.json +1 -1
  8. package/runtime/BUILD.json +2 -2
  9. package/runtime/prompts/duties/code-reviewer.json +1 -0
  10. package/runtime/prompts/lead/convergence.md +5 -19
  11. package/runtime/prompts/lead/okstra-lead-contract.md +1 -1
  12. package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
  13. package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
  14. package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
  15. package/runtime/python/okstra_ctl/analysis_packet.py +52 -21
  16. package/runtime/python/okstra_ctl/approval_decisions.py +30 -1
  17. package/runtime/python/okstra_ctl/approved_plan_stage_extract.py +100 -66
  18. package/runtime/python/okstra_ctl/brief_sources.py +162 -44
  19. package/runtime/python/okstra_ctl/code_review_coverage.py +11 -1
  20. package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
  21. package/runtime/python/okstra_ctl/code_review_target.py +46 -10
  22. package/runtime/python/okstra_ctl/conformance.py +9 -3
  23. package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
  24. package/runtime/python/okstra_ctl/final_report_schema.py +37 -30
  25. package/runtime/python/okstra_ctl/fixed_text.py +31 -9
  26. package/runtime/python/okstra_ctl/implementation_direction.py +18 -0
  27. package/runtime/python/okstra_ctl/initial_prompt_materialization.py +59 -21
  28. package/runtime/python/okstra_ctl/json_registry.py +3 -18
  29. package/runtime/python/okstra_ctl/manager_split.py +201 -84
  30. package/runtime/python/okstra_ctl/model_io/references.py +31 -1
  31. package/runtime/python/okstra_ctl/model_io/renderers.py +30 -1
  32. package/runtime/python/okstra_ctl/model_io_cli.py +9 -0
  33. package/runtime/python/okstra_ctl/path_hints.py +13 -1
  34. package/runtime/python/okstra_ctl/paths.py +4 -0
  35. package/runtime/python/okstra_ctl/phases/final_verification/prior_blockers.py +87 -45
  36. package/runtime/python/okstra_ctl/phases/final_verification/profile.md +2 -2
  37. package/runtime/python/okstra_ctl/phases/final_verification/spec.md +10 -2
  38. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +19 -11
  39. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-executor.md +3 -1
  40. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
  41. package/runtime/python/okstra_ctl/phases/implementation/spec.md +14 -0
  42. package/runtime/python/okstra_ctl/phases/implementation_option_selection/authoring.py +2 -1
  43. package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
  44. package/runtime/python/okstra_ctl/phases/implementation_option_selection/validation.py +53 -37
  45. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  46. package/runtime/python/okstra_ctl/plan_items.py +9 -11
  47. package/runtime/python/okstra_ctl/ports/verification_inputs.py +17 -0
  48. package/runtime/python/okstra_ctl/prior_planning.py +6 -17
  49. package/runtime/python/okstra_ctl/prior_run_summary.py +35 -0
  50. package/runtime/python/okstra_ctl/qa_commands.py +66 -1
  51. package/runtime/python/okstra_ctl/qa_commands_cli.py +67 -0
  52. package/runtime/python/okstra_ctl/qa_procedures.py +235 -0
  53. package/runtime/python/okstra_ctl/registry/verification_inputs_store.py +8 -0
  54. package/runtime/python/okstra_ctl/render.py +10 -0
  55. package/runtime/python/okstra_ctl/report_assembly.py +12 -12
  56. package/runtime/python/okstra_ctl/run.py +108 -5
  57. package/runtime/python/okstra_ctl/verification_input_ref.py +80 -0
  58. package/runtime/python/okstra_ctl/verification_input_types.py +32 -0
  59. package/runtime/python/okstra_ctl/verification_inputs.py +162 -0
  60. package/runtime/python/okstra_ctl/verification_plan.py +116 -0
  61. package/runtime/python/okstra_ctl/worker_prompt_body.py +12 -6
  62. package/runtime/python/okstra_ctl/worker_prompt_contract.py +5 -1
  63. package/runtime/python/okstra_ctl/worker_prompt_headers.py +50 -1
  64. package/runtime/python/okstra_project/dirs.py +22 -0
  65. package/runtime/python/okstra_project/resolver.py +10 -0
  66. package/runtime/schemas/final-report-v3.0.schema.json +5 -1
  67. package/runtime/skills/okstra-brief-gen/SKILL.md +10 -4
  68. package/runtime/skills/okstra-code-review/SKILL.md +39 -45
  69. package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
  70. package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
  71. package/runtime/skills/okstra-manager/SKILL.md +2 -2
  72. package/runtime/skills/okstra-setup/SKILL.md +2 -0
  73. package/runtime/skills/okstra-setup/references/project-config.md +2 -0
  74. package/runtime/validators/validate-brief.py +21 -5
@@ -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
- for index, fact in enumerate(option.get("unresolvedFeasibilityFacts") or ()):
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
- `unresolvedFeasibilityFacts` 가 있거나 베낀 표가 있으면 표를 더 받아도
465
- 유효해지지 않으므로 제외한다. 남은 표를 다 받아도 `feasible` 이
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"{candidate.get('id')} splitAcceptance {ref!r} must name a "
600
- "`blocks: approval` clarification the user answered with "
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>`, record "
603
- "the answer with `okstra approval-decision resolve`, then reassemble"
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
 
@@ -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 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`). 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`).
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
- detect_design_surfaces,
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 _stage_scope(row: Mapping[str, Any] | None, *coordinates: int) -> list[int] | None:
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": _stage_scope(row),
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": _stage_scope(row),
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": _stage_scope(None, stage_number),
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 = detect_design_surfaces(planning)
302
- except (DesignSurfaceError, TypeError, AttributeError) as exc:
303
- raise PlanItemContractError(f"design-surface detection failed: {exc}") from exc
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": _stage_scope(None, trigger.stage),
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: ...
@@ -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
- try:
142
- data = load_owned_object(path, artifact="prior planning artifact")
143
- except (JsonBoundaryError, OSError):
144
- # expected-miss: 직전 run 이 남기지 못했거나 깨뜨린 파일. 이 블록은
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
- if not isinstance(value, str):
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
@@ -18,7 +18,8 @@ from __future__ import annotations
18
18
 
19
19
  import re
20
20
  import shlex
21
- from typing import Iterable
21
+ from pathlib import PurePosixPath
22
+ from typing import Iterable, Mapping
22
23
 
23
24
  # 카테고리 화이트리스트. 알 수 없는 카테고리는 오타 가능성이 높으므로 거부.
24
25
  # `db-test` 는 DB/IO/SQL 변경의 실제 DB(또는 충실한 복제) 실행 테스트 전용 카테고리 —
@@ -26,6 +27,11 @@ from typing import Iterable
26
27
  # `test` 와 분리한다. implementation verifier / final-verification 의 DB 실제실행 게이트가
27
28
  # diff 가 DB 를 건드릴 때 이 카테고리(또는 plan validation 의 db 스텝)를 요구한다.
28
29
  ALLOWED_CATEGORIES: tuple[str, ...] = ("lint", "format", "typecheck", "test", "db-test")
30
+ QA_COMMAND_EXECUTING_TASK_TYPES = ("implementation", "final-verification")
31
+ QA_RELATIVE_PATH_DESCRIPTION = (
32
+ "non-blank relative POSIX path with at least one component after normalization, "
33
+ "without traversal or backslashes"
34
+ )
29
35
 
30
36
  # Mutation 을 유발하거나 lockfile 을 갱신하는 토큰. 각 토큰은 `cmd` 문자열을
31
37
  # 공백으로 단순 분해한 결과 또는 부분 일치 패턴(prefix/suffix sensitive) 로 검출한다.
@@ -185,6 +191,7 @@ def validate_qa_commands(qa: object) -> list[str]:
185
191
  여기서는 raise 하지 않고 메시지를 모아서 호출자가 일괄 보고할 수 있게 한다.
186
192
  """
187
193
  errors: list[str] = []
194
+ seen_ids: set[str] = set()
188
195
  if qa is None:
189
196
  return errors # 옵션 필드 — 미선언은 합법.
190
197
  if not isinstance(qa, dict):
@@ -209,6 +216,10 @@ def validate_qa_commands(qa: object) -> list[str]:
209
216
  continue
210
217
  label = entry.get("label")
211
218
  cmd = entry.get("cmd")
219
+ errors.extend(
220
+ f"qaCommands.{category}[{idx}]: {error}"
221
+ for error in qa_metadata_errors(entry, seen_ids)
222
+ )
212
223
  if not isinstance(label, str) or not label.strip():
213
224
  errors.append(
214
225
  f"qaCommands.{category}[{idx}].label must be a non-empty string"
@@ -228,6 +239,60 @@ def validate_qa_commands(qa: object) -> list[str]:
228
239
  return errors
229
240
 
230
241
 
242
+ def qa_metadata_errors(entry: Mapping[str, object], seen_ids: set[str]) -> list[str]:
243
+ errors: list[str] = []
244
+ identifier = entry.get("id")
245
+ if identifier is not None:
246
+ if not isinstance(identifier, str) or not re.fullmatch(
247
+ r"[A-Za-z0-9][A-Za-z0-9._-]*", identifier
248
+ ):
249
+ errors.append("qaCommands id must be a safe non-empty identifier")
250
+ elif identifier in seen_ids:
251
+ errors.append(f"duplicate qaCommands id: {identifier}")
252
+ else:
253
+ seen_ids.add(identifier)
254
+ if "procedurePath" in entry:
255
+ if not identifier:
256
+ errors.append("procedurePath requires an id")
257
+ if not qa_relative_path_valid(entry["procedurePath"]):
258
+ errors.append(f"procedurePath must be a {QA_RELATIVE_PATH_DESCRIPTION}")
259
+ for key in ("sourcePaths", "resourceKeys"):
260
+ if key not in entry:
261
+ continue
262
+ values = entry[key]
263
+ if not isinstance(values, list) or any(
264
+ not isinstance(value, str) or not value.strip() for value in values
265
+ ):
266
+ errors.append(f"{key} must be an array of non-empty strings")
267
+ continue
268
+ if len(values) != len(set(values)):
269
+ errors.append(f"{key} must not contain duplicates")
270
+ if key == "sourcePaths" and any(
271
+ not qa_relative_path_valid(value) for value in values
272
+ ):
273
+ errors.append(
274
+ "each sourcePaths item must be a " + QA_RELATIVE_PATH_DESCRIPTION
275
+ )
276
+ if key == "resourceKeys" and any(
277
+ "://" in value or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9:._/-]*", value)
278
+ for value in values
279
+ ):
280
+ errors.append("resourceKeys must be non-secret resource identifiers")
281
+ digest = entry.get("sourceBaselineDigest")
282
+ if digest is not None and (
283
+ not isinstance(digest, str) or not re.fullmatch(r"sha256:[0-9a-f]{64}", digest)
284
+ ):
285
+ errors.append("sourceBaselineDigest must be a sha256 digest")
286
+ return errors
287
+
288
+
289
+ def qa_relative_path_valid(value: object) -> bool:
290
+ if not isinstance(value, str) or not value.strip() or "\\" in value:
291
+ return False
292
+ path = PurePosixPath(value)
293
+ return bool(path.parts) and not path.is_absolute() and ".." not in path.parts
294
+
295
+
231
296
  def format_errors(errors: Iterable[str]) -> str:
232
297
  """`PrepareError` 등에 그대로 박을 수 있는 멀티라인 문자열."""
233
298
  lines = list(errors)
@@ -0,0 +1,67 @@
1
+ """Typed command inputs and fixed text projections for `okstra qa`."""
2
+ from __future__ import annotations
3
+
4
+ import argparse
5
+ import sys
6
+ from pathlib import Path
7
+
8
+ from .fixed_text import line
9
+ from .qa_procedures import inspect_commands, register_command
10
+
11
+
12
+ def main(argv: list[str] | None = None) -> int:
13
+ parser = argparse.ArgumentParser(prog="okstra qa")
14
+ parser.add_argument("operation", choices=("register", "show", "check"))
15
+ parser.add_argument("--project-root", type=Path, required=True)
16
+ parser.add_argument("--source-root", type=Path)
17
+ parser.add_argument("--id")
18
+ parser.add_argument("--category", choices=("test", "db-test"))
19
+ parser.add_argument("--label")
20
+ parser.add_argument("--cmd")
21
+ parser.add_argument("--procedure-input", type=Path)
22
+ parser.add_argument("--source-path", action="append", default=[])
23
+ parser.add_argument("--resource-key", action="append", default=[])
24
+ parser.add_argument("--expected-entry-digest")
25
+ args = parser.parse_args(argv)
26
+ source = args.source_root or args.project_root
27
+ try:
28
+ if args.operation == "register":
29
+ required = ("id", "category", "label", "cmd", "procedure_input")
30
+ if any(getattr(args, key) is None for key in required):
31
+ parser.error(
32
+ "register requires --id, --category, --label, --cmd "
33
+ "and --procedure-input"
34
+ )
35
+ entry = {"id": args.id, "label": args.label, "cmd": args.cmd}
36
+ if args.source_path:
37
+ entry["sourcePaths"] = args.source_path
38
+ if args.resource_key:
39
+ entry["resourceKeys"] = args.resource_key
40
+ digest = register_command(
41
+ args.project_root, source, args.category, entry,
42
+ args.procedure_input, expected_digest=args.expected_entry_digest,
43
+ )
44
+ print(line("Registered entry digest", digest), end="")
45
+ return 0
46
+ rows = inspect_commands(args.project_root, source)
47
+ print(line("Source root", str(source.resolve())), end="")
48
+ selection = "explicit" if args.source_root else "original project"
49
+ print(line("Source selection", selection), end="")
50
+ for row in rows:
51
+ print("".join(line(key, row.get(field)) for key, field in (
52
+ ("Category", "category"), ("ID", "id"), ("Label", "label"),
53
+ ("Command", "cmd"), ("Procedure", "procedurePath"),
54
+ ("Entry digest", "entryDigest"), ("Source status", "sourceStatus"),
55
+ ("Execution evidence", "evidenceStatus"))), end="")
56
+ errors = [row["error"] for row in rows if "error" in row]
57
+ if errors:
58
+ raise ValueError("; ".join(errors))
59
+ stale = any(row["sourceStatus"] == "changed" for row in rows)
60
+ return int(args.operation == "check" and stale)
61
+ except (OSError, ValueError) as exc:
62
+ print(f"qa: {exc}", file=sys.stderr)
63
+ return 2
64
+
65
+
66
+ if __name__ == "__main__":
67
+ raise SystemExit(main())