okstra 0.232.0 → 0.234.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -283
- package/dist/cli-registry.mjs +14 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.mjs +2 -17
- package/dist/lib/memory-auto-register.mjs.map +1 -1
- package/dist/lib/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/docs/architecture/storage-model.md +55 -5
- package/docs/architecture.md +10 -4
- package/docs/cli.md +320 -3
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +34 -43
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- package/runtime/prompts/coding-preflight/authoring-checks.md +1 -1
- package/runtime/prompts/coding-preflight/clean-code.md +18 -20
- package/runtime/prompts/coding-preflight/overview.md +1 -1
- package/runtime/prompts/duties/code-reviewer.json +1 -1
- package/runtime/prompts/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +2 -2
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +1 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +66 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +28 -10
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +12 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +22 -11
- package/runtime/python/okstra_ctl/business_flow/cli.py +60 -6
- package/runtime/python/okstra_ctl/business_flow/contracts.py +12 -1
- package/runtime/python/okstra_ctl/business_flow/engine.py +17 -5
- package/runtime/python/okstra_ctl/business_flow/history.py +60 -0
- package/runtime/python/okstra_ctl/business_flow/source.py +35 -2
- package/runtime/python/okstra_ctl/business_flow/store.py +51 -14
- package/runtime/python/okstra_ctl/business_flow/sweep.py +124 -0
- package/runtime/python/okstra_ctl/code_review_census.py +93 -2
- package/runtime/python/okstra_ctl/code_review_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +13 -0
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +140 -15
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- package/runtime/python/okstra_ctl/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +9 -9
- package/runtime/python/okstra_ctl/doyouknow/config.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/group_view.py +152 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +4 -3
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +2 -2
- package/runtime/python/okstra_ctl/doyouknow/sources/business.py +116 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +48 -9
- package/runtime/python/okstra_ctl/doyouknow/sync.py +34 -9
- package/runtime/python/okstra_ctl/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/fixed_text.py +10 -0
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +33 -6
- package/runtime/python/okstra_ctl/manager_cli.py +122 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +42 -3
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +3 -0
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +8 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +12 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +5 -5
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/project_group.py +175 -0
- package/runtime/python/okstra_ctl/project_group_cli.py +62 -0
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +38 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +179 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +86 -36
- package/runtime/python/okstra_ctl/run.py +43 -35
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_project/state.py +20 -0
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/business-flow-v1.schema.json +3 -0
- package/runtime/schemas/doyouknow-config-v1.schema.json +1 -1
- package/runtime/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +58 -50
- package/runtime/skills/okstra-code-review/references/census-rules.md +6 -6
- package/runtime/skills/okstra-code-review/references/review-calibration.md +8 -12
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +33 -4
- package/runtime/skills/okstra-manager/SKILL.md +24 -0
- package/runtime/skills/okstra-memory/SKILL.md +1 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/doyouknow/group-view.css +103 -0
- package/runtime/templates/doyouknow/group-view.js +317 -0
- package/runtime/templates/doyouknow/group-view.template.html +72 -0
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +93 -36
|
@@ -69,8 +69,7 @@ from okstra_ctl.plan_review_context import render_review_context
|
|
|
69
69
|
from okstra_ctl.stage_ledger import build_stage_ledger
|
|
70
70
|
from okstra_ctl.claim_reproduction import NOT_RUNNABLE, reproduce
|
|
71
71
|
from okstra_ctl.file_size_cap import headroom_text, planned_file_headroom
|
|
72
|
-
from okstra_ctl.
|
|
73
|
-
from okstra_ctl.report_narrative import parse_narrative
|
|
72
|
+
from okstra_ctl.report_narrative import load_writer_input
|
|
74
73
|
from okstra_ctl.report_assembly import validate_plan_draft
|
|
75
74
|
from okstra_ctl.error_log_write import record_runtime_failure
|
|
76
75
|
from okstra_ctl.user_response import parse_user_response_entries
|
|
@@ -194,9 +193,11 @@ def _parser() -> argparse.ArgumentParser:
|
|
|
194
193
|
commands = parser.add_subparsers(dest="command", required=True)
|
|
195
194
|
extract = commands.add_parser("extract")
|
|
196
195
|
_add_plan_source(extract)
|
|
196
|
+
extract.add_argument("--run-manifest", type=Path)
|
|
197
197
|
extract.add_argument("--output", type=Path, required=True)
|
|
198
198
|
validate = commands.add_parser("validate")
|
|
199
199
|
_add_plan_source(validate)
|
|
200
|
+
validate.add_argument("--run-manifest", type=Path)
|
|
200
201
|
validate.add_argument("--items", type=Path, required=True)
|
|
201
202
|
prepare = commands.add_parser("prepare")
|
|
202
203
|
_add_plan_source(prepare)
|
|
@@ -425,13 +426,13 @@ def _plan_source(args: argparse.Namespace) -> dict[str, Any]:
|
|
|
425
426
|
if args.data is not None:
|
|
426
427
|
return _load_json_object(args.data)
|
|
427
428
|
try:
|
|
428
|
-
|
|
429
|
+
return load_writer_input(
|
|
430
|
+
args.narrative, run_manifest=getattr(args, "run_manifest", None),
|
|
431
|
+
)
|
|
429
432
|
except (OSError, UnicodeError) as exc:
|
|
430
433
|
raise PlanItemContractError(
|
|
431
434
|
f"cannot read report narrative {args.narrative}: {exc}"
|
|
432
435
|
) from exc
|
|
433
|
-
try:
|
|
434
|
-
return parse_narrative(markdown, load_schema_version("3.0"))
|
|
435
436
|
except ValueError as exc:
|
|
436
437
|
raise PlanItemContractError(f"invalid report narrative: {exc}") from exc
|
|
437
438
|
|
|
@@ -1191,12 +1192,14 @@ def validate_current_review(run_manifest: Path) -> PreparedPlanReview:
|
|
|
1191
1192
|
name = authority.payload.get("reportNarrativePath")
|
|
1192
1193
|
if not isinstance(name, str) or not name:
|
|
1193
1194
|
raise PlanItemContractError("reportNarrativePath is missing")
|
|
1194
|
-
narrative =
|
|
1195
|
-
if not narrative.is_relative_to(authority.run_dir):
|
|
1195
|
+
narrative = authority.project_root / name
|
|
1196
|
+
if not narrative.resolve(strict=True).is_relative_to(authority.run_dir):
|
|
1196
1197
|
raise PlanItemContractError("plan narrative must stay inside the current run")
|
|
1197
1198
|
items_path = _prepared_items_path(run_manifest, require_regular=True)
|
|
1198
1199
|
prepared = _load_json_object(items_path)
|
|
1199
|
-
source = _plan_source(argparse.Namespace(
|
|
1200
|
+
source = _plan_source(argparse.Namespace(
|
|
1201
|
+
data=None, narrative=narrative, run_manifest=run_manifest,
|
|
1202
|
+
))
|
|
1200
1203
|
items = _envelope(source)["items"]
|
|
1201
1204
|
if prepared.get("items") != items:
|
|
1202
1205
|
raise PlanItemContractError("prepared plan items do not match the current narrative")
|
|
@@ -1224,7 +1227,7 @@ def finish_verification_round(
|
|
|
1224
1227
|
verified = subprocess.run(
|
|
1225
1228
|
[sys.executable, str(assets.joinpath(*RUN_VALIDATOR_RELATIVE)),
|
|
1226
1229
|
"--section", "plan-body", "--narrative", str(review.narrative),
|
|
1227
|
-
"--state", str(review.state)],
|
|
1230
|
+
"--state", str(review.state), "--run-manifest", str(review.manifest)],
|
|
1228
1231
|
capture_output=True, text=True, check=False, timeout=60,
|
|
1229
1232
|
)
|
|
1230
1233
|
if verified.returncode:
|
|
@@ -8,12 +8,9 @@ rules live in `prompts/profiles/`.
|
|
|
8
8
|
### Step 5.1 (implementation-planning only): user-confirmed TDD bypass offer
|
|
9
9
|
|
|
10
10
|
Every plan stage must open with a `RED:` step whose outcome is FAIL and reach a
|
|
11
|
-
later `GREEN:` step (validator S10c). `tddExemption` waives that
|
|
12
|
-
|
|
13
|
-
stage that
|
|
14
|
-
got through by filing the nearest category. That is the failure this flag
|
|
15
|
-
exists to remove: **a closed reason list with no escape makes the plan
|
|
16
|
-
misdescribe itself.**
|
|
11
|
+
later `GREEN:` step (validator S10c). `tddExemption` waives that for
|
|
12
|
+
`doc-only`, `config-only`, `pure-rename`, or a user-granted `user-bypass`. A
|
|
13
|
+
stage that fits none of these is not filed under the nearest category.
|
|
17
14
|
|
|
18
15
|
`render-bundle` accepts an optional `--tdd-bypass "<stage>:<reason>"` flag
|
|
19
16
|
(implementation-planning only). It records a **user-acknowledged** bypass into
|
|
@@ -10,6 +10,8 @@ Use the absolute common-contract paths in the lead prompt's `Okstra Runtime Reso
|
|
|
10
10
|
|
|
11
11
|
This contract defines a **second, independent** verification round that fires only for `task-type = implementation-planning`. The round verifies the *consolidated plan* that the report-writer worker has authored, not the worker findings that were already reconciled earlier.
|
|
12
12
|
|
|
13
|
+
Take every authoring input path below from the current run manifest's `reportNarrativePath`. Its declared `reportAuthoringFormat=json-v1` selects standard JSON with ordinary Markdown inside description strings; an absent field retains `markdown-v1` and its line grammar. Pass that same run manifest to `plan-items prepare`, `seed`, `extract`, `validate`, `validate-prepared`, `plan-verify`, and `incremental-carry` so each consumer selects the declared format. Keep the actual `.json` or `.md` extension when preserving a correction attempt. The final reader's Markdown and HTML remain derived outputs.
|
|
14
|
+
|
|
13
15
|
## Lifecycle position (BLOCKING)
|
|
14
16
|
|
|
15
17
|
Plan-body verification runs **after** finding convergence and **after** the report-writer draft is written. Sequence inside a single implementation-planning run:
|
|
@@ -17,7 +19,7 @@ Plan-body verification runs **after** finding convergence and **after** the repo
|
|
|
17
19
|
```
|
|
18
20
|
Phase 4 workers produce independent analyses (Findings F-001…)
|
|
19
21
|
→ Phase 5.5 FINDING convergence (`prompts/lead/convergence.md`, sections "Convergence Algorithm" through "Convergence State Artifact")
|
|
20
|
-
→ Phase 6 report-writer authors
|
|
22
|
+
→ Phase 6 report-writer authors the manifest-declared input (consolidated Option Candidates / Stepwise Execution Order / Dependency / Validation Checklist / Rollback)
|
|
21
23
|
→ okstra plan-items prepare + prompt + validate-prepared creates and projects the deterministic P-* queue
|
|
22
24
|
→ PLAN-BODY VERIFICATION ROUND ← this contract
|
|
23
25
|
→ final render/validation
|
|
@@ -64,9 +66,9 @@ Default values are emitted into the manifest by `scripts/okstra_ctl/render.py` (
|
|
|
64
66
|
From the report-writer's draft of `## 5.4 Implementation Plan Deliverables`, the lead creates the verification queue only through this sequence (see also `templates/reports/final-report-v2.template.md` §5.5.9):
|
|
65
67
|
|
|
66
68
|
```text
|
|
67
|
-
okstra plan-items prepare --narrative <
|
|
69
|
+
okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>
|
|
68
70
|
→ place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in every verifier prompt
|
|
69
|
-
→ okstra plan-items validate-prepared --narrative <
|
|
71
|
+
→ okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>
|
|
70
72
|
```
|
|
71
73
|
|
|
72
74
|
The persisted `items[]` are the sole queue. The lead MUST NOT freely summarise,
|
|
@@ -413,11 +415,11 @@ round before any host or provider process starts.
|
|
|
413
415
|
|
|
414
416
|
For contract 3.0, `prepare` checks the selected-direction draft with the same semantic validator as publication before writing the queue. Correct all reported references, coverage rows and planned commands through the writer correction procedure, then retry in this run. **Enforced:** `report_assembly.validate_plan_draft` and `plan_items_cli._prepare`; the retired Python suite previously checked that invalid coverage creates no prepared queue.
|
|
415
417
|
|
|
416
|
-
1. Lead runs `okstra plan-items prepare --narrative <
|
|
418
|
+
1. Lead runs `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, places the fixed output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then runs `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. A `File-size headroom` line that prepare prints, and that `okstra plan-items prompt` carries under `## File-size headroom`, is a report only: it names an existing file the plan writes, its lines left before the 500-line implementation limit and the stages that write it. It does not block, open a correction or count as a verdict. After a self-fix rewrite, and after `okstra incremental-carry` on a re-run, pass `--state <plan-body-verification.json>` on prepare and validate-prepared; validate-prepared needs the same `--state` the last prepare used, or it refuses with `prepared dispatch queue does not match` or `prepared review evidence changed`. The runtime reuses a verdict only when its body, complete declared evidence closure, shared analysis packet, plan metadata, reviewer assignments and review contract have the same fingerprint. A missing or uncertain dependency declaration, unresolved reference, non-result or executable fact probe stays in the re-verification queue. Detailed verdicts and their original rounds remain unchanged for reused items. File dependencies cover whole files; step items also include preceding steps; plan-wide and preparation items include all plan items. Python resolves the one convergence-owned state path from that run identity. Dispatch only after exact-match validation succeeds. `observed` / `deferred` stages remain omitted. An empty queue opens no worker dispatch and creates no verification round. **Enforced:** `implementation_planning.authoring._queue_for`, `plan_item_evidence.review_fingerprint`, `_validate_prepared` and the retired Python suite. An incremental carry without evidence snapshots keeps active items queued until prepare can validate their dependencies.
|
|
417
419
|
|
|
418
|
-
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <
|
|
420
|
+
**Then seed the landing table (BLOCKING):** `okstra plan-items seed --narrative <reportNarrativePath> --state <plan-body-verification.json> --run-manifest <run-manifest.json>`. `apply-verdicts` in step 8 refuses a verdict whose item has no `planBodyVerification.planItems[]` row. The report writer never owns that state, so the deterministic seed is the only creator of its rows. The seed is idempotent by id and never touches existing verdicts, so it is safe to re-run between rounds and after a self-fix re-extraction. It does refresh `contentHash` from the current extract. Skipping it makes step 8 fail with `plan-body state has no row for [...]`.
|
|
419
421
|
|
|
420
|
-
**On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry
|
|
422
|
+
**On a re-run, add `--prior-state <the previous run's plan-body-verification-<task-type>-<seq>.json>`.** An incremental re-run then runs `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> ...` and repeats prepare, prompt and validate-prepared with `--state` before dispatch (launch prompt "Incremental re-verification" step 7). A newly seeded item inherits verdicts only when its body and verified evidence fingerprint match the prepared snapshot for the same task. Reused rows carry `carriedForwardFromSeq`; their full verdicts are preserved. Legacy body-only records re-enter verification. A matching id alone never carries: `P-*` ids are positional. The flag requires `--state` and refuses another task's state. **Enforced:** `implementation_planning.authoring._carry_prior_run_verdicts` and `plan_item_evidence.reusable_item_ids`.
|
|
421
423
|
|
|
422
424
|
**`--run-manifest` is what scopes the gate to the stage you are starting.** Seed uses it to overlay disk `done` / `active` onto `planBodyVerification.stageLedger`. The current plan's depends-on fills `ready` / `blocked` when no prior plan exists, so a first run does not treat every stage as in-scope. **Enforced:** `okstra_ctl.plan_items.planning_stage_ledger`.
|
|
423
425
|
2. For each analyser worker in the roster, use `okstra plan-items prompt` output verbatim as the instruction body in the materialization sequence above. Read §"Re-verification rounds (round 2+)" before preparing a later round; read §"Plan-body reverify prompt" only when diagnosing a prompt-contract failure.
|
|
@@ -446,10 +448,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
|
|
|
446
448
|
- any advisory `dissent-isolated` / `needs-reverify` present, no `majority-disagree` → `passed-with-dissent`
|
|
447
449
|
- all items `full-consensus` → `passed`
|
|
448
450
|
|
|
449
|
-
**Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are in the
|
|
451
|
+
**Score the gate with `okstra plan-verify`, never by hand (BLOCKING).** Once this round's verdicts are recorded in the convergence-owned plan-body state, lead runs
|
|
450
452
|
|
|
451
453
|
```
|
|
452
|
-
okstra plan-verify --
|
|
454
|
+
okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>
|
|
453
455
|
```
|
|
454
456
|
|
|
455
457
|
and records what it returns: `gate.recomputed` is the round's gate value, `gate.blockedBy` its `gateBlockedBy` causes, `gate.blockingItems` the items that block. The same call runs every plan-body check a round can be judged on alone — provenance, fixability, subject substance, self-fix grouping, round recording, clarification matching, state-file rounds — and exits 2 with `failures[]` when the round is not contract-clean. **A round is not complete while that exit code is non-zero.**
|
|
@@ -485,10 +487,10 @@ For contract 3.0, `prepare` checks the selected-direction draft with the same se
|
|
|
485
487
|
- **Group the targets by cause before instructing (BLOCKING).** Blocked items are usually several derivatives of one defect. Lead partitions this round's targets into cause groups and instructs each group as **"remove this cause"**, naming the derivatives it accounts for. The convergence command owns the persisted group and correction fields; the lead does not edit JSON state.
|
|
486
488
|
- lead instructs report-writer to rewrite the items in each cause group (NOT a full draft regeneration): one `rewrite` entry per item in a corrections ledger, whose `rule` states the cause group's required outcome; procedure in `prompts/lead/report-writer.md` §"Corrective report-writer dispatch (ledger required)".
|
|
487
489
|
- missing or weak `P-Prep-*` contracts are repaired by adding kind-specific inline detail or an AI-prepared PREP item with a concrete proposal. Facts that require user or external authority remain `blocked` and keep their request material; never invent those facts during self-fix.
|
|
488
|
-
- **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract
|
|
490
|
+
- **Drop plan items whose element the round deleted.** A self-fix rewrite may remove a plan element (a validation check, a rollback row). `P-*` ids are positional, so a deletion shifts every later row and silently re-points surviving verdicts at their neighbours — and a verdict recorded against a removed element keeps blocking a gate while being unfindable in the plan, so reading the plan never reveals the cause. After each round, re-extract plan items with `okstra plan-items extract --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --output <extract-path>` and re-verify any item whose `subject` no longer matches; never carry the old vote forward across a shift. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdicts_match_current_subjects` (re-pointing) and `_validate_plan_item_extraction_completeness` (dangling ids).
|
|
489
491
|
- **Classify each cause group before instructing it (BLOCKING).** A group is either an *authoring* defect — the plan says something wrong, incomplete, or self-contradictory, which self-fix owns — or a *citation* defect, where the plan points at an analysis artifact incorrectly. Only the first is self-fix work. For the second the finding already exists and already went through convergence, so the fix is to re-cite the converged artifact; instructing report-writer to re-derive the fact means the author reads the source material and produces a **finding that never went through convergence**, which the plan then carries as if it had. That is the role boundary the lead contract draws ("keep analysis, execution, verification, and report authoring responsibilities distinct; return defects to the role that owns them"), and report-writer is authoring-only by its own contract. `P-Req-*` items with breakage kind `f` are where this goes wrong most often: the question is usually whether a coverage row points correctly at something already measured, not whether the measurement is right. State the classification in the group's instruction so the author knows which of the two it is being asked to do.
|
|
490
492
|
- **A verdict older than the last self-fix is not a verdict unless the item's content is unchanged (BLOCKING).** A verdict cast in round 1 judged the text before the only automatic rewrite. Once that rewrite runs, a changed item's judgement is about a plan that no longer exists. `--round <N>` on `apply-verdicts` stamps each row and copies `contentHash` onto `verifiedContentHash`. `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_verdict_rounds_outlive_self_fix` fails an in-scope item whose verdict round is at or before `selfFixRoundsApplied` **and** whose `contentHash` does not match `verifiedContentHash`. Matching hashes keep the prior verdict — that is what avoids a sweep round over unchanged stages. Deferred and observed items are out of the gate and do not need a post-self-fix verdict. **Enforced:** `_validate_verdict_rounds_outlive_self_fix`.
|
|
491
|
-
- Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --
|
|
493
|
+
- Lead re-runs plan-body verification, then records each worker Markdown result through `okstra plan-items apply-verdicts --state <plan-body-verification.json> --result <worker>=<result.md> --round <N>`. Score the result with `okstra plan-verify --run-manifest <current-run-manifest> --narrative <reportNarrativePath> --state <plan-body-verification.json>`, then call `okstra plan-items complete-round --state <plan-body-verification.json> --run-manifest <current-run-manifest.json> --round <N>`. These commands fail on an assigned item the worker left unanswered, on a verdict for an item outside the queue, and on a duplicate worker result. `apply-verdicts` without `--append` replaces every recorded row of the queued items, so it also refuses — before writing — when a row belongs to a round that `complete-round` never closed, naming the round to close first; the votes of a closed round live in `planItems[].rounds`. Skipping `complete-round` between rounds and applying the next one lost 19 items' round-1 votes (2026-09-09). `--discard-open-rounds` is only for re-applying the lost rounds from their result files in order: it also restores `dispatchQueue` to the items those result files answer, because the persisted queue is the latest round's and a verdict for an earlier, wider queue is otherwise refused as outside it (round 1 = 26 items, critic tie = 8, round 3 = 19 on that same run — only the 19 survived). Re-apply each lost round with the flag, `complete-round` it, then the next. **Enforced:** `okstra_ctl.plan_items_cli._reject_uncompleted_round_loss` and `_restore_queue_from_results`.
|
|
492
494
|
- For a self-fix, record the correction through the typed convergence command rather than writing `selfFixNote` or `selfFixGroups` JSON. A resolved item does not create a clarification.
|
|
493
495
|
- **Each round is a worker batch.** Before dispatching round N ≥ 2, reclaim the previous round's completed verifiers exactly as at any other batch boundary (`prompts/lead/okstra-lead-contract.md` "Run-scoped worker-resource lifecycle") and emit `PROGRESS: phase-batch-cleanup panes=<n>`, then announce the round with `PROGRESS: phase-5.5.9-plan-verify round=<N> items=<count>`. Saying a round will "reuse" the previous verifiers and then dispatching under fresh names leaves every prior round holding its panes — five rounds of that is what exhausts the pane budget and blocks the next dispatch. **Enforced:** `validators/validate_session_conformance.py` `_check_plan_verify_cleanup_checkpoints` requires both lines once the state file records two or more rounds.
|
|
494
496
|
- **Round completion.** A round is complete only after `okstra plan-verify` exits 0 and `okstra plan-items complete-round` succeeds. A round left with a non-zero exit carries its defect into the next round's inputs. Exit 0 with a non-empty `advisories[]` is a complete round: those findings are recorded, not round-blocking (step 5, §"`failures[]` carries only the blocking findings"). Report assembly and rendering occur only after the convergence state is terminal. **Enforced:** `scripts/okstra_ctl/phases/implementation_planning/plan_body.py` `_validate_plan_body_state_rounds` requires one stored round per round number and a corresponding item vote.
|
|
@@ -86,7 +86,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
86
86
|
- §5.5.9 plan-body verification runs with an **adversarial posture** (`scripts/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md` §"Adversarial plan-body posture"): verifiers open and confirm every cited path / command and put the burden of proof on the plan. The gate threshold is majority-based for kinds `b`/`c`/`e`, but a single `DISAGREE` blocks on its own for the concrete, safety-critical kind `a` (path/symbol mismatch) — and `f` on `P-Req-*` items. `P-Var-*` items are excepted from the kind-`a` exception: a variation-point defect takes a majority. Rollback ordering (`d`) is advisory and never blocks the gate — a rollback is executed by a human, not by okstra's workers or verifiers. A majority also needs ≥2 participating votes, so a lone dissent whose peer returned a non-result does not block on a majority-gated kind (see that contract's §"Adversarial plan-body posture").
|
|
87
87
|
- **Incremental re-verification scope (clarification re-runs):** when the lead's `okstra incremental-scope` decision is `mode == "incremental"` (procedure in `prompts/launch.template.md` §"Clarification Response Carried In"), workers re-analyze ONLY the stages listed in `reverify_stages` (the downstream closure of the impacted stages). Workers MUST NOT re-open, re-score, or re-judge any stage in `carry_stages` — those stages' prior plan-item verdicts are carried forward verbatim, and a worker never overwrites a carried verdict with its own judgement. When the decision is `mode == "full"` (the default), every stage is re-analyzed as usual.
|
|
88
88
|
- **Single incremental-scope decision:** the lead calls `okstra incremental-scope` once the inputs are complete, passing the answered `C-NNN` ids through `--answered-clarifications`, changed design-preparation IDs through `--prep-items`, and any lead-resolved stage numbers through `--impacted`; the CLI unions all three before applying the existing dependency closure and cutoff. The clarification ids are resolved to stages by the CLI from the prior report's own `planItems[].clarificationId` and `blocked C-NNN` coverage links — the lead does not map answers to stage numbers. An answer that changes the selected planning payload, Stage Map, or execution approach is not a local impact: pass `--full-reason`, which is the only structural path that still forces `mode == "full"`. A clarification id that traces to no stage returns `mode == "unresolved"` — ask the user for stage numbers and call again with `--impacted`; do not treat it as full and do not silently drop the id. **When this run only ADDS stages** — every prior stage is `done` and none of them is being re-opened — there are no stage numbers to give: pass `--carry-all-reason` instead. Pinning any prior stage as impacted makes `incremental-carry` demand plan-item verdicts from the current snapshot, which no longer holds them (a `done` stage's plan items are `observed`, so they are never dispatched or scored in this run), so that path has no answer that works. The stage's own row is still declared in the narrative — that is the numbering rule above, not a re-verification. `--carry-all-reason` still applies the base-ref check: if the branch moved, the decision degrades to `full` because the prior stages are no longer "as written". Unknown PREP IDs or invalid `stageRefs` still return an explicit full decision instead of being guessed. When the wizard pin is `auto` and the CLI returns `mode == "incremental"`, keep it — do not upgrade to full. When the user pinned a scope at the wizard (`REVERIFY_SCOPE_MODE` / `REVERIFY_SCOPE_STAGES` in `prompts/launch.template.md` §"Clarification Response Carried In" step 0), that pin is an input to this same call — `full` supplies the `--full-reason`, `carry-all` supplies the `--carry-all-reason`, and pinned stage numbers join `--impacted` — never a bypass of the CLI's closure and cutoff.
|
|
89
|
-
- **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --cur-narrative
|
|
89
|
+
- **Stage-aware carry:** for an incremental decision, `okstra incremental-scope` writes the decision to the record this run's manifest names in `incrementalDecisionPath`. The report writer's duty to copy each `carry_stages` stage row unchanged is not stated here — it is generated into that writer's own authoring contract from the same record, with this run's stage numbers in it (`okstra_ctl.report_synthesis_packet.ReportSynthesisPacket._carry_instructions`). After plan-item seeding, run `okstra incremental-carry --run-manifest <current-run-manifest> --cur-narrative <reportNarrativePath> --state ... --out-state ...` against that record. The helper rejects a changed or missing carried stage and copies prior `P-Step-*` / `P-Prep-*` verdicts for `carry_stages`, plus unchanged `P-Val-*` / `P-Req-*` / `P-Rb-*` rows whose extract `contentHash` still matches. It rewrites `dispatchQueue` and the sibling `plan-items-*.json` so the next prompt does not re-score a carried checklist row. Overlap, omissions, and canonical conflicts return `CarryError`. On that error, discard the partial state and run full re-verification.
|
|
90
90
|
{{INCLUDE:_coverage-critic.md}}
|
|
91
91
|
- Non-goals:
|
|
92
92
|
- code-level micro-optimization unless it changes the implementation approach
|
|
@@ -115,8 +115,8 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
115
115
|
- **`user-bypass` — the stage that is honestly none of the three.** Some stages have no failing-before state to write and no category that describes them (measured 2026-09-10: a stage whose product change was already committed and conformance-proved under a previous run of the same stage, so the only truthful reason was "this stage reconciles that stage's QA declaration"). Do **not** file the closest of the three; that makes the plan misdescribe itself and S10e passes on a reason that is not true. Declare `tddExemption: user-bypass — <the user's own words>` and stop: the value holds only while `<task-root>/qa/tdd-bypass.json` records the user's grant for that stage number. **You cannot write that record.** Ask the user, in your report's clarification row or directly, to re-run prepare with `--tdd-bypass "<stage>:<reason>"`; their reason is stored verbatim and the record shows the stage as bypassed by the user rather than as one of the three canned categories. **Enforced (S10e):** `collect_data_validation_errors` takes the granted stage numbers from `okstra_ctl.tdd_bypass.granted_stages`; a stage naming the token with no grant fails exactly as an arbitrary reason does, and the failure message carries the flag that produces a passing value.
|
|
116
116
|
- `stageMap[].dependsOn` must form a DAG (no self-dependency, no unknown stage, no cycle), each row's `stepCount` must equal its stage's actual `stepwiseExecution` row count, and two `(none)`-dependency stages must not name the same file in their `exitContract` — they run as concurrent implementation runs in separate worktrees. **Enforced (S8/S4/S9):** same function.
|
|
117
117
|
- Legacy candidate-comparison-only deliverable:
|
|
118
|
-
- The report writer records the plan body in
|
|
119
|
-
- **
|
|
118
|
+
- The report writer records the plan body under `implementationPlanning` in the input at the run manifest's `reportNarrativePath`, using its declared `reportAuthoringFormat`. `json-v1` uses exact JSON schema keys and native values, with ordinary Markdown allowed inside description strings. An absent field retains the `markdown-v1` line grammar. Report assembly adds machine-owned `designPreparation`, `designSurfaceCoverage`, and `planBodyVerification`, then validates the completed `data.json` against the frozen final-report schema.
|
|
119
|
+
- **Legacy Markdown field labels under `Implementation Planning`:** `Coverage Summary`, `Cross Project Dependencies`, `Decision Drafts`, `Dependency Migration Risk`, `Direction Invalidation`, `Direction Realization`, `Incremental Decision`, `Option Candidates`, `Outcome`, `Planning Contract`, `Recommended Option`, `Requirement Coverage`, `Rollback Strategy`, `Routing`, `Selected Direction Ref`, `Skipped ADR Candidates`, `Stage Map`, `Stages`, `Stepwise Execution`, `Supersession Ledger`, `Tradeoff Matrix`, `User Narrative`, `Validation Checklist`, `Variation Point Analysis`. For `json-v1`, use the exact keys in the synthesis packet's writer-owned schema instead, such as `implementationPlanning.requirementCoverage`. The `## 5.5.<i>` headings, the `step | action | ...` tables, and the `Slice value:` / `Test case (...):` lines described below are the shape of the **rendered report a reader sees**. JSON carries that content as structured values; only `markdown-v1` uses `- **Field**` / `- Item <N>` / `> value` rows. `designPreparation` and `planBodyVerification` belong to report assembly and are rejected in either format.
|
|
120
120
|
- Legacy candidate-comparison requires at least two implementation options. **Each option must include**:
|
|
121
121
|
- **File Structure**: an explicit list of files to create / modify / delete with each file's responsibility (one-line each). Use the form `Create: path — responsibility` / `Modify: path:line-range — change summary` / `Delete: path — reason`. Write every `path` in full and `<PROJECT_ROOT>`-relative — never ellipsis-abbreviated (`…` / `...` / a trailing `/…`); an abbreviated path does not resolve and is rejected by plan-body verification as a kind-b path mismatch.
|
|
122
122
|
- **Two-tier change description.** Each `fileStructure` row carries `summary` **and** optional `details`, and they are not interchangeable:
|
|
@@ -208,7 +208,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
208
208
|
- Selected-direction plans omit `implementation-option:` because `selectedDirectionRef` already fixes the direction; the legacy-only selector rule is owned by the legacy deliverable section above.
|
|
209
209
|
- **the frontmatter `approved: false` line is rendered unconditionally; if the plan-body verification gate (§5.5.9) returns `blocked-by-disagreement` or `aborted-non-result`, the writer MUST keep `approved: false` and the validator refuses any report that ships with `approved: true` under such a gate result.**
|
|
210
210
|
- every ambiguity flagged during pre-planning that the user must resolve before approval registered as a `Blocks=approval` row in the `## 1. Clarification Items` table (the unified table is the single home for these — the "no separate `Open Questions` block" rule is in the shared `_common-contract.md` clarification policy)
|
|
211
|
-
- **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <
|
|
211
|
+
- **Exact plan-item queue (BLOCKING).** Run `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place `okstra plan-items prompt --run-manifest <run-manifest>` output verbatim in the verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. Do not freely summarise, select, omit, reorder, or renumber the queue. Prompt headings use the compact subject and include the lossless payload. For every item, ask:
|
|
212
212
|
|
|
213
213
|
```text
|
|
214
214
|
What concrete false-positive input, failure ordering, or omitted dependency
|
|
@@ -284,7 +284,7 @@ Lead's responsibilities in this sub-step (in order):
|
|
|
284
284
|
|
|
285
285
|
For a new `implementation-planning` run, the fixed order is initial verification → one planner self-fix → targeted re-verification → lead decision or immediate user confirmation. The initial verification is round 1 and the targeted re-verification is round 2. A second automatic self-fix is a contract violation. When `okstra plan-items prepare` reports `"gating": false` (one-stage `no-design-inputs` plan), skip the self-fix loop and the sweep batch: extraction and round 1 still run, then go to the user gate. Two-or-more stages, a PREP item, or non-empty `designPreparation.items` keep `gating: true` and the full order.
|
|
286
286
|
|
|
287
|
-
1. Build the queue with `okstra plan-items prepare --narrative <
|
|
287
|
+
1. Build the queue with `okstra plan-items prepare --narrative <reportNarrativePath> --run-manifest <run-manifest>`, place the output of `okstra plan-items prompt --run-manifest <run-manifest>` verbatim in every verifier prompt, then run `okstra plan-items validate-prepared --narrative <reportNarrativePath> --run-manifest <run-manifest>`. Python resolves the one convergence-owned state path from that run identity. The lead MUST NOT summarise, select, omit, reorder, or renumber the queue. Each prompt uses the compact subject plus the lossless payload, and asks every item:
|
|
288
288
|
|
|
289
289
|
```text
|
|
290
290
|
What concrete false-positive input, failure ordering, or omitted dependency
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
"""Improvement discovery lens vocabulary and candidate bounds."""
|
|
2
2
|
from __future__ import annotations
|
|
3
3
|
|
|
4
|
+
from collections.abc import Sequence
|
|
5
|
+
|
|
4
6
|
LENSES: tuple[str, ...] = (
|
|
5
7
|
"performance",
|
|
6
8
|
"security",
|
|
@@ -16,6 +18,7 @@ DEFAULT_CANDIDATE_CAP = 8
|
|
|
16
18
|
ABSOLUTE_CANDIDATE_CAP = 12
|
|
17
19
|
MIN_PRIORITY_LENSES = 1
|
|
18
20
|
MAX_PRIORITY_LENSES = 4
|
|
21
|
+
RESOLVED_LENSES_POLICY = "resolved-lenses-v1"
|
|
19
22
|
|
|
20
23
|
# report-writer is the AUTHOR of the final report; it never produces source
|
|
21
24
|
# findings. validators reject `report-writer:<id>` entries in Source workers.
|
|
@@ -25,3 +28,12 @@ SOURCE_WORKERS: tuple[str, ...] = ("claude", "codex", "antigravity")
|
|
|
25
28
|
def is_valid_lens(value: str) -> bool:
|
|
26
29
|
return value in LENSES
|
|
27
30
|
|
|
31
|
+
|
|
32
|
+
def validate_priority_lenses(values: Sequence[str]) -> tuple[str, ...]:
|
|
33
|
+
lenses = tuple(values)
|
|
34
|
+
if not MIN_PRIORITY_LENSES <= len(lenses) <= MAX_PRIORITY_LENSES:
|
|
35
|
+
raise ValueError("resolved lenses must contain one to four lenses")
|
|
36
|
+
if len(set(lenses)) != len(lenses) or any(lens not in LENSES for lens in lenses):
|
|
37
|
+
raise ValueError("resolved lenses must be unique values from the lens whitelist")
|
|
38
|
+
return lenses
|
|
39
|
+
|
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
- this phase REQUIRES a codebase-scan brief whose frontmatter contains `scope: codebase`. A brief without that marker is rejected before worker dispatch.
|
|
7
7
|
- the brief's `priority-lenses` MUST be a non-empty subset (size 1..4) of the lens whitelist defined in `scripts/okstra_ctl/phases/improvement_discovery/lenses.py`. Lenses outside the whitelist are rejected.
|
|
8
8
|
- the brief's `scan-scope` defines the only paths workers may read for candidate evidence. `out-of-scope` paths MUST be ignored even when the codebase is otherwise reachable.
|
|
9
|
-
- the brief's `candidate-cap` (default 8 if absent, absolute cap 12) bounds the
|
|
9
|
+
- the brief's `candidate-cap` (default 8 if absent, absolute cap 12) bounds `improvementDiscovery.candidates[]` in structured reports and the candidate-table rows in legacy Markdown reports without a data file.
|
|
10
10
|
- Apply the shared reporter-confirmation precondition as written. For this phase any unresolved `intent-check:` / `conversion-block:` row uses `Blocks=next-phase`.
|
|
11
11
|
- read `Related Task Graph` before candidate discovery. If a candidate overlaps an existing linked task, preserve the edge in the candidate notes and prefer `related-to` / `follow-up-of` routing over emitting a duplicate standalone task.
|
|
12
12
|
- Primary focus areas:
|
|
@@ -33,6 +33,7 @@
|
|
|
33
33
|
- For each open question Lead asks ONE `AskUserQuestion` with a `(Recommended)` answer drawn from a codebase-first inspection. Budget: at most 12 questions in this phase.
|
|
34
34
|
- Stop conditions (OR): all questions resolved / budget exhausted / user signals proceed.
|
|
35
35
|
- Lead persists the round at `<RUN_DIR>/state/phase-1.5-grilling.md` with one section per question (question / recommended / user answer) and a closing `Resolved scope` / `Resolved lenses` block. Worker prompts use this resolved block as the authoritative scope and lens definition.
|
|
36
|
+
- In new runs declaring `coverageCensusPolicy: resolved-lenses-v1`, write exactly one `## Resolved lenses` section containing one bare `- <lens>` bullet per selected lens, in resolved order, with one to four distinct whitelist values. Keep explanations in other sections. Before the first analysis prompt is published, `resolved_census.prepare_resolved_lens_census()` freezes those cells and their source fingerprint into the run census and completes the packet. Subsequent prompt calls reuse that census; changing the resolved log or frozen packet is rejected. Do not manually edit either frozen artifact. Runs without this policy retain their saved worklist.
|
|
36
37
|
- The same log includes `## Primary Pass Assignments` with a `Worker ID | Primary lens` table. It contains every selected analyser exactly once in `workerRoles` order; the lead derives it from the resolved roster and lenses rather than provider catalog order.
|
|
37
38
|
- After writing the log and before Phase 4 dispatch, the lead injects its **absolute path** into every analyser prompt as the `**Phase 1.5 Grilling Log:** <absolute-path>` anchor header (see `okstra_ctl.worker_prompt_headers.worker_prompt_headers()`). This is the improvement-discovery counterpart to the `**Worktree:**` / `**Verification …:**` anchors that implementation / final-verification inject: workers read the log from this explicit path rather than re-deriving `<RUN_DIR>`. The path is byte-identical across all analysers, so it does not break the dispatch-prompt invariant.
|
|
38
39
|
- Decision-tree walk (bounded):
|
|
@@ -43,11 +44,11 @@
|
|
|
43
44
|
- uncertainty and overlap relationships kept explicit for downstream consensus classification
|
|
44
45
|
- every candidate's `Expected behavior after` is checked against the brief's `## Preserved Behavior` items before the row is written. A candidate whose observable change contradicts a `PB-NNN` item is dropped, or raised as a `## 1. Clarification Items` row — never softened into a vaguer cell. The scan brief's PB set is the upper bound on what this phase may propose changing.
|
|
45
46
|
- Report assembly instructions:
|
|
46
|
-
- current branch — `schemaVersion: 2.0
|
|
47
|
-
-
|
|
48
|
-
-
|
|
49
|
-
- `Consensus`
|
|
50
|
-
- Verdict Token —
|
|
47
|
+
- current branch — `schemaVersion: 3.0`, with structured 2.0 reading compatibility: author the structured data contract below and let the independent renderers produce the full reading copy and task-specific human HTML.
|
|
48
|
+
- legacy Markdown without a companion data file: preserve its `## 5.9 Improvement Candidates` table and legacy contract when validating or rerendering; do not implicitly migrate historical records. Structured reports do not need those numbered headings.
|
|
49
|
+
- `improvementDiscovery.candidates[]` retains 11 logical fields checked by `scripts/okstra_ctl/phases/improvement_discovery/validation.py`: ID `I-NNN`, Lens from whitelist, Title, Scope ⊆ scan-scope, Severity, Effort, Consensus, Source workers `<worker>:<id>` from {claude, codex, antigravity}, Recommended next-phase ∈ {requirements-discovery, implementation-option-selection, error-analysis}, Expected behavior after, and Evidence as path:line list. Legacy Markdown represents these fields as eleven table columns. `Expected behavior after` states, in one observable sentence, what becomes different once the candidate is applied — it is the seed of the downstream brief's `EB-NNN` / `EO-NNN`. A candidate without that observable change is dropped rather than filled with a restatement of its title.
|
|
50
|
+
- `Consensus` values use `full`, `partial`, `contested`, or `worker-unique`. Map convergence's `full-consensus` / `partial-consensus` labels to `full` / `partial` before writing the candidate.
|
|
51
|
+
- Verdict Token — structured 3.0 and 2.0 records use `analysis-complete` when every resolved lens was examined, `analysis-partial` when one could not be, and `blocked` when the scan itself could not run. Finding no candidates uses an empty `candidates[]` plus a `lensCoverage[]` row per lens with `status: no-candidate` and its evidence-backed rationale; the verdict stays `analysis-complete`. `candidates-ready` / `no-candidates` belong only to the legacy `## 7. Final Verdict` Markdown without a data file, where `validation.py` also checks the matching Verdict Card. Continuation guidance is owned by `prompts/lead/phase-routing.md`.
|
|
51
52
|
- Record each candidate's recommended next phase and scope as facts for the common lead routing policy.
|
|
52
53
|
- author the shared narrative fields plus `improvementDiscovery.candidates[]`, `improvementDiscovery.lensCoverage[]`, `improvementDiscovery.selectionLimit`, and `improvementDiscovery.userNarrative` in the report narrative. `candidates[]` carries the same 11 logical fields described above; `lensCoverage[]` records either candidate IDs or an evidence-backed no-candidate rationale for every resolved lens. `schemas/final-report-v3.0.schema.json`, `schemas/report-narrative-v3.0.schema.json`, and `scripts/okstra_ctl/phases/improvement_discovery/validation.py` enforce this contract. Phase 7 assembles the final record and derives the reading copy and human HTML.
|
|
53
54
|
- Clarification request policy (phase-specific addenda — shared policy is in `_common-contract.md`):
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
"""Freeze the resolved-lens worklist before publishing an analysis prompt."""
|
|
2
|
+
from __future__ import annotations
|
|
3
|
+
|
|
4
|
+
import hashlib
|
|
5
|
+
import os
|
|
6
|
+
import tempfile
|
|
7
|
+
from pathlib import Path
|
|
8
|
+
from typing import Any, Mapping
|
|
9
|
+
|
|
10
|
+
from ...analysis_packet import replace_analysis_packet_block
|
|
11
|
+
from ...coverage_census import (
|
|
12
|
+
CensusError, census_for_run, census_state_paths, render_census_section,
|
|
13
|
+
)
|
|
14
|
+
from ...json_boundary import load_owned_object, write_owned_object_atomic
|
|
15
|
+
from ...run_context import task_mutex
|
|
16
|
+
from .lenses import RESOLVED_LENSES_POLICY, validate_priority_lenses
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def improvement_census_policy_fields(
|
|
20
|
+
task_type: str, recorded_manifest: Mapping[str, Any] | None,
|
|
21
|
+
) -> dict[str, Any]:
|
|
22
|
+
if recorded_manifest is None:
|
|
23
|
+
return {"coverageCensusPolicy": RESOLVED_LENSES_POLICY} if task_type == "improvement-discovery" else {}
|
|
24
|
+
return (
|
|
25
|
+
{"coverageCensusPolicy": recorded_manifest["coverageCensusPolicy"]}
|
|
26
|
+
if "coverageCensusPolicy" in recorded_manifest else {}
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
def pending_census_section(run_manifest: str) -> str:
|
|
31
|
+
return (
|
|
32
|
+
"## Coverage Census\n\n"
|
|
33
|
+
"The resolved-lens census is pending Phase 1.5 and will be frozen "
|
|
34
|
+
"before the first analysis prompt is published.\n"
|
|
35
|
+
f"<!-- okstra:resolved-lens-census:{run_manifest}:pending -->"
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
def prepare_resolved_lens_census(
|
|
40
|
+
project_root: Path, manifest: Mapping[str, Any],
|
|
41
|
+
) -> None:
|
|
42
|
+
policy = manifest.get("coverageCensusPolicy")
|
|
43
|
+
if policy is None:
|
|
44
|
+
return
|
|
45
|
+
if manifest.get("taskType") != "improvement-discovery" or policy != RESOLVED_LENSES_POLICY:
|
|
46
|
+
raise CensusError(f"unsupported coverage census policy: {policy!r}")
|
|
47
|
+
paths = census_state_paths(project_root, manifest)
|
|
48
|
+
if paths is None:
|
|
49
|
+
raise CensusError("resolved-lens census requires the run state path")
|
|
50
|
+
census_path, _ = paths
|
|
51
|
+
_project_path(project_root, str(census_path), "census")
|
|
52
|
+
task_key = manifest.get("taskKey")
|
|
53
|
+
if not isinstance(task_key, str) or not task_key:
|
|
54
|
+
raise CensusError("resolved-lens census requires a task key")
|
|
55
|
+
with task_mutex(task_key):
|
|
56
|
+
_freeze_census(project_root, manifest, census_path)
|
|
57
|
+
|
|
58
|
+
|
|
59
|
+
def _project_path(root: Path, value: object, label: str) -> Path:
|
|
60
|
+
if not isinstance(value, str) or not value:
|
|
61
|
+
raise CensusError(f"missing {label} path")
|
|
62
|
+
path = (root / value).resolve()
|
|
63
|
+
if not path.is_relative_to(root.resolve()):
|
|
64
|
+
raise CensusError(f"{label} path escapes project root")
|
|
65
|
+
return path
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _resolved_lenses(text: str) -> tuple[str, ...]:
|
|
69
|
+
lines = text.splitlines()
|
|
70
|
+
headings = [index for index, line in enumerate(lines) if line == "## Resolved lenses"]
|
|
71
|
+
if len(headings) != 1:
|
|
72
|
+
raise CensusError("grilling log requires one '## Resolved lenses' section")
|
|
73
|
+
values: list[str] = []
|
|
74
|
+
for line in lines[headings[0] + 1:]:
|
|
75
|
+
if line.startswith("#"):
|
|
76
|
+
break
|
|
77
|
+
if not line.strip():
|
|
78
|
+
continue
|
|
79
|
+
if not line.startswith("- "):
|
|
80
|
+
raise CensusError("Resolved lenses must list one '- <lens>' entry per line")
|
|
81
|
+
values.append(line[2:])
|
|
82
|
+
try:
|
|
83
|
+
return validate_priority_lenses(values)
|
|
84
|
+
except ValueError as exc:
|
|
85
|
+
raise CensusError(str(exc)) from exc
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def _digest(value: bytes) -> str:
|
|
89
|
+
return hashlib.sha256(value).hexdigest()
|
|
90
|
+
|
|
91
|
+
|
|
92
|
+
def _freeze_census(root: Path, manifest: Mapping[str, Any], census_path: Path) -> None:
|
|
93
|
+
run_dir = _project_path(root, manifest.get("runDirectoryPath"), "run directory")
|
|
94
|
+
log = _project_path(root, str(run_dir / "state/phase-1.5-grilling.md"), "grilling log")
|
|
95
|
+
try:
|
|
96
|
+
log_bytes = log.read_bytes()
|
|
97
|
+
except OSError as exc:
|
|
98
|
+
raise CensusError(f"cannot read Phase 1.5 grilling log: {log}") from exc
|
|
99
|
+
lenses = _resolved_lenses(log_bytes.decode("utf-8"))
|
|
100
|
+
instruction_set = _project_path(root, manifest.get("instructionSetPath"), "instruction set")
|
|
101
|
+
packet_path = _project_path(root, manifest.get("analysisPacketPath"), "analysis packet")
|
|
102
|
+
census = census_for_run(
|
|
103
|
+
task_type="improvement-discovery",
|
|
104
|
+
profile_text=(instruction_set / "analysis-profile.md").read_text(encoding="utf-8"),
|
|
105
|
+
brief_path=instruction_set / "task-brief.md",
|
|
106
|
+
selected_lenses=lenses,
|
|
107
|
+
)
|
|
108
|
+
if census is None:
|
|
109
|
+
raise CensusError("resolved-lens profile has no census aspects")
|
|
110
|
+
census["scopeSource"] = {
|
|
111
|
+
"path": log.relative_to(root).as_posix(), "digest": _digest(log_bytes),
|
|
112
|
+
"selectedLenses": list(lenses),
|
|
113
|
+
}
|
|
114
|
+
packet = packet_path.read_bytes()
|
|
115
|
+
if census_path.exists():
|
|
116
|
+
saved = load_owned_object(census_path, artifact="resolved-lens census")
|
|
117
|
+
if any(saved.get(key) != value for key, value in census.items()):
|
|
118
|
+
raise CensusError("resolved lenses or frozen census changed; preserve the existing run")
|
|
119
|
+
if _digest(packet) == saved.get("analysisPacketDigest"):
|
|
120
|
+
return
|
|
121
|
+
if _digest(packet) != saved.get("analysisPacketBeforeDigest"):
|
|
122
|
+
raise CensusError("frozen analysis packet changed; preserve the existing run")
|
|
123
|
+
census = saved
|
|
124
|
+
_publish_frozen_census_and_packet(root, manifest, census_path, census, packet_path, packet)
|
|
125
|
+
|
|
126
|
+
|
|
127
|
+
def _publish_frozen_census_and_packet(
|
|
128
|
+
root: Path, manifest: Mapping[str, Any], census_path: Path,
|
|
129
|
+
census: dict[str, Any], packet_path: Path, packet: bytes,
|
|
130
|
+
) -> None:
|
|
131
|
+
prompt_paths = manifest.get("workerPromptPathByWorkerId")
|
|
132
|
+
if not isinstance(prompt_paths, Mapping):
|
|
133
|
+
raise CensusError("resolved-lens census requires worker prompt paths")
|
|
134
|
+
if any(_project_path(root, value, "worker prompt").exists() for value in prompt_paths.values()):
|
|
135
|
+
raise CensusError("cannot complete a pending census after worker prompt publication")
|
|
136
|
+
pending = pending_census_section(str(manifest.get("runManifestPath") or ""))
|
|
137
|
+
section = render_census_section(census, census_path.relative_to(root).as_posix())
|
|
138
|
+
try:
|
|
139
|
+
completed = replace_analysis_packet_block(packet.decode("utf-8"), pending, section).encode("utf-8")
|
|
140
|
+
except ValueError as exc:
|
|
141
|
+
raise CensusError(str(exc)) from exc
|
|
142
|
+
if census_path.exists():
|
|
143
|
+
if _digest(completed) != census.get("analysisPacketDigest"):
|
|
144
|
+
raise CensusError("pending analysis packet does not match the frozen census")
|
|
145
|
+
else:
|
|
146
|
+
census["analysisPacketBeforeDigest"] = _digest(packet)
|
|
147
|
+
census["analysisPacketDigest"] = _digest(completed)
|
|
148
|
+
write_owned_object_atomic(census_path, census, artifact="resolved-lens census")
|
|
149
|
+
temporary: Path | None = None
|
|
150
|
+
try:
|
|
151
|
+
with tempfile.NamedTemporaryFile(dir=packet_path.parent, delete=False) as handle:
|
|
152
|
+
temporary = Path(handle.name)
|
|
153
|
+
handle.write(completed)
|
|
154
|
+
handle.flush()
|
|
155
|
+
os.fsync(handle.fileno())
|
|
156
|
+
os.replace(temporary, packet_path)
|
|
157
|
+
finally:
|
|
158
|
+
if temporary is not None:
|
|
159
|
+
temporary.unlink(missing_ok=True)
|
|
@@ -10,7 +10,9 @@ Common analysis dispatch, convergence, clarification handling, report schemas an
|
|
|
10
10
|
|
|
11
11
|
`profile.md` directs the lead's bounded scope-and-lens discussion and records its resolved scope, lenses and primary-pass assignments in `state/phase-1.5-grilling.md`. The common worker-prompt policy supplies the explicit log anchor. Every analyser inspects every resolved lens. Candidate rows retain their scope, expected observable change, evidence and source-worker identities.
|
|
12
12
|
|
|
13
|
-
The run validator calls `validate_improvement_report` with the existing report path, run directory and parsed brief frontmatter.
|
|
13
|
+
The run validator calls `validate_improvement_report` with the existing report path, run directory and parsed brief frontmatter. Current 3.0 and historical 2.0 structured records select their own shared schema followed by the same candidate checks. Markdown without a companion data file uses the eleven-column candidate table and the matching Verdict Card and Final Verdict rows. Invalid data and unknown or missing data versions fail rather than falling back to Markdown.
|
|
14
|
+
|
|
15
|
+
New runs declare `coverageCensusPolicy: resolved-lenses-v1`. Preparation leaves a run-specific pending census block in the analysis packet. Before an initial analyser prompt is published, `resolved_census.prepare_resolved_lens_census` reads the log's single `## Resolved lenses` section as one bare `- <lens>` bullet per resolved lens. It freezes the one-to-four unique whitelist values, log fingerprint and packet fingerprints under the existing task mutex, then atomically completes the packet with a regenerated section index. The mutex serializes census finalization calls and is released before per-prompt publication locks; it does not cover preparation's entire instruction-set write. The roster and native prompt CLI use this same boundary before provider-specific publication. A partially written packet can be completed from the saved census before any worker prompt exists; changed scope or a missing census after publication cannot replace the frozen worklist. Existing runs without the policy retain their original census. Missing cell verdicts remain advisory.
|
|
14
16
|
|
|
15
17
|
The validator requires the resolved-log headings, but does not prove that each declared inspection or user conversation occurred. Primary-pass rotation and preserved-behavior reconciliation remain profile instructions reviewed during convergence.
|
|
16
18
|
|
|
@@ -23,7 +25,8 @@ The validator requires the resolved-log headings, but does not prove that each d
|
|
|
23
25
|
| ID-3 | The run log contains resolved scope and lens blocks. | `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_grilling_log` |
|
|
24
26
|
| ID-4 | Legacy verdict rows use the legacy vocabulary and match the Verdict Card. | `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_final_verdict`, `scripts/okstra_ctl/phases/improvement_discovery/validation.py::_check_verdict_card` |
|
|
25
27
|
| ID-5 | Codebase briefs use one to four priority lenses from the phase vocabulary. | `validators/validate-brief.py::check_codebase_scope` |
|
|
28
|
+
| ID-6 | New runs freeze one-to-four resolved lens cells before initial analyser publication; retries preserve the cells and reject changed sources. | `scripts/okstra_ctl/phases/improvement_discovery/resolved_census.py::prepare_resolved_lens_census`, `initial_prompt_materialization.py::_materialize_initial_prompts`, `agent/prompt_cli/materialize.py::_materialize_run` |
|
|
26
29
|
|
|
27
30
|
## Tests
|
|
28
31
|
|
|
29
|
-
`tests/
|
|
32
|
+
`tests/report/test_assembly.py` exercises current and historical report validation. `tests/run/test_prepare.py` checks deferred preparation, resolved cell counts, immutable retry, native prompt publication and partial-packet recovery, malformed lens input and legacy policy preservation. Report `lensCoverage` completeness and primary-pass rotation remain instruction-level contracts, not new report gates.
|
|
@@ -18,7 +18,8 @@ from .lenses import (
|
|
|
18
18
|
)
|
|
19
19
|
from okstra_ctl.final_report_paths import final_report_data_path
|
|
20
20
|
from okstra_ctl.final_report_schema import (
|
|
21
|
-
|
|
21
|
+
SchemaError,
|
|
22
|
+
load_schema_for_data,
|
|
22
23
|
validate as validate_final_report_data,
|
|
23
24
|
)
|
|
24
25
|
from okstra_ctl.md_table import split_pipe_row
|
|
@@ -291,7 +292,7 @@ def _check_verdict_card(
|
|
|
291
292
|
errors.append("Verdict Card row must byte-match `## 7. Final Verdict` row")
|
|
292
293
|
|
|
293
294
|
|
|
294
|
-
def
|
|
295
|
+
def _structured_candidate_rows(data: dict) -> list[list[str]]:
|
|
295
296
|
candidates = data["improvementDiscovery"]["candidates"]
|
|
296
297
|
return [
|
|
297
298
|
[
|
|
@@ -311,17 +312,31 @@ def _v2_candidate_rows(data: dict) -> list[list[str]]:
|
|
|
311
312
|
]
|
|
312
313
|
|
|
313
314
|
|
|
314
|
-
def
|
|
315
|
+
def _validate_structured_report(
|
|
315
316
|
data: dict,
|
|
316
317
|
run_dir: Path,
|
|
317
318
|
brief_frontmatter: dict,
|
|
318
319
|
) -> ValidationResult:
|
|
319
|
-
|
|
320
|
+
try:
|
|
321
|
+
schema = load_schema_for_data(data)
|
|
322
|
+
except SchemaError as exc:
|
|
323
|
+
return ValidationResult(ok=False, errors=[f"invalid report data: {exc}"])
|
|
324
|
+
if validate_final_report_data(data, schema):
|
|
325
|
+
return ValidationResult(
|
|
326
|
+
ok=False,
|
|
327
|
+
errors=["invalid report data: declared schema must pass before candidate validation"],
|
|
328
|
+
)
|
|
329
|
+
if data["header"]["taskType"] != "improvement-discovery":
|
|
330
|
+
return ValidationResult(
|
|
331
|
+
ok=False,
|
|
332
|
+
errors=["invalid report data: header.taskType must be improvement-discovery"],
|
|
333
|
+
)
|
|
334
|
+
errors: list[str] = []
|
|
320
335
|
_check_grilling_log(run_dir, errors)
|
|
321
336
|
if errors:
|
|
322
337
|
return ValidationResult(ok=False, errors=errors)
|
|
323
338
|
|
|
324
|
-
rows =
|
|
339
|
+
rows = _structured_candidate_rows(data)
|
|
325
340
|
_check_candidates_cap(len(rows), brief_frontmatter, errors)
|
|
326
341
|
_check_candidate_rows(
|
|
327
342
|
rows,
|
|
@@ -347,8 +362,7 @@ def validate_improvement_report(
|
|
|
347
362
|
data = load_owned_object(data_path, artifact="improvement report data")
|
|
348
363
|
except JsonBoundaryError as exc:
|
|
349
364
|
return ValidationResult(ok=False, errors=[f"invalid report data: {exc}"])
|
|
350
|
-
|
|
351
|
-
return _validate_v2_report(data, run_dir, brief_frontmatter)
|
|
365
|
+
return _validate_structured_report(data, run_dir, brief_frontmatter)
|
|
352
366
|
|
|
353
367
|
body = report_path.read_text(encoding="utf-8")
|
|
354
368
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"allowed": " - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n - the lead writes the report
|
|
2
|
+
"allowed": " - entering this phase only when the cited final-verification report's verdict is release-ready — `Verdict Token` exactly `accepted`, or exactly `conditional-accept` with every Conditional Acceptance Condition row declaring `blocksReleaseHandoff: false` (`okstra_ctl.release_gate.release_handoff_allowed`)\n - asking the user (via `AskUserQuestion` / interactive prompt) which delivery action to take: `local checkout`, `push + PR`, or `skip` (end the run)\n - asking the user to pick a PR base branch from `staging` | `preprod` | `prod` | `main` | `dev` | a user-supplied branch name\n - drafting PR title and PR body **inline as the Okstra lead** (no drafter worker and no delegated dispatch); the lead reviews its own draft with the user before any mutating git / gh command runs\n - read-only git inspection: `git status`, `git diff`, `git log`, `git rev-parse`\n - pushing the current feature branch to its origin remote via `git push -u origin <current-branch>` (the feature branch only — NEVER the base branch)\n - creating a pull request via `gh pr create --base <chosen-base> --head <current-branch>`; if a PR with the same head already exists, surface its URL and skip creation\n - the lead writes the report authoring input at the run manifest's `reportNarrativePath` directly (no `Report writer worker` dispatch), using standard JSON with exact writer-owned schema keys and native values when `reportAuthoringFormat=json-v1`, or the existing Markdown narrative line grammar when that field is absent; follow the complete format and frozen-schema instructions in this phase's Lead-only contract; `okstra report-finalize` assembles the final report from it",
|
|
3
3
|
"forbidden": [
|
|
4
4
|
"entering this phase when a cited final-verification verdict is not release-ready — `Verdict Token` `blocked` or any token other than `accepted` / `conditional-accept`, a `conditional-accept` with no Conditional Acceptance Condition row or with any row whose `blocksReleaseHandoff` is not `false` (`okstra_ctl.release_gate.release_handoff_allowed`) — or when no final-verification report is cited",
|
|
5
5
|
"local commit commands of any kind (`git add`, `git commit`, `git restore --staged`, `git stash`), and any direct `git merge` / `git rebase` / `git rebase --onto` / `git cherry-pick` / `git commit --amend` run by the lead. Runtime exceptions are dependency-ordered rebases by `okstra_ctl.stage_rebase` (which invalidate verification and stop PR delivery), and merge commits on a dedicated multi-predecessor `merge-base` branch. Never merge a moving predecessor or origin branch into a downstream stage to update its base.",
|