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.
- package/README.md +1 -1
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/docs/architecture/storage-model.md +77 -0
- package/docs/cli.md +15 -3
- package/docs/project-structure-overview.md +12 -2
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- 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 +1 -1
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +1 -1
- package/runtime/python/okstra_ctl/adapters/verification_inputs.py +22 -0
- package/runtime/python/okstra_ctl/adapters/worker_defaults.py +2 -2
- 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 +11 -1
- package/runtime/python/okstra_ctl/code_review_scope.py +157 -0
- package/runtime/python/okstra_ctl/code_review_target.py +46 -10
- package/runtime/python/okstra_ctl/conformance.py +9 -3
- package/runtime/python/okstra_ctl/design_surfaces.py +51 -19
- 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-executor.md +3 -1
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +3 -1
- 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/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/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/render.py +10 -0
- package/runtime/python/okstra_ctl/report_assembly.py +12 -12
- package/runtime/python/okstra_ctl/run.py +108 -5
- 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/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_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 +39 -45
- package/runtime/skills/okstra-code-review/references/census-rules.md +14 -2
- package/runtime/skills/okstra-code-review/references/review-calibration.md +31 -8
- package/runtime/skills/okstra-manager/SKILL.md +2 -2
- 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
|
@@ -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
|
|
|
@@ -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
|
-
|
|
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: ...
|
|
@@ -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
|
|
@@ -18,7 +18,8 @@ from __future__ import annotations
|
|
|
18
18
|
|
|
19
19
|
import re
|
|
20
20
|
import shlex
|
|
21
|
-
from
|
|
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())
|