okstra 0.231.0 → 0.232.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 +15 -3
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +113 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +129 -2
- package/docs/architecture.md +11 -2
- package/docs/cli.md +234 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +85 -281
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
- package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/code_review_census.py +71 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
- package/runtime/python/okstra_ctl/code_review_target.py +85 -11
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/json_boundary.py +21 -2
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +26 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_sync.py +3 -22
- package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/report_assembly.py +15 -0
- package/runtime/python/okstra_ctl/report_narrative.py +3 -0
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +24 -1
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/team.py +3 -1
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +25 -20
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/skills/okstra-code-review/SKILL.md +71 -123
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
- package/runtime/skills/okstra-manager/SKILL.md +7 -0
- package/runtime/skills/okstra-memory/SKILL.md +7 -0
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/validate-run.py +17 -8
package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md
CHANGED
|
@@ -204,22 +204,49 @@ The final report keeps both — executor's `Validation evidence` AND each verifi
|
|
|
204
204
|
|
|
205
205
|
### Static design & test-quality review (gate — runs after the command re-run, before the verdict)
|
|
206
206
|
|
|
207
|
+
When the dispatch supplies Frozen Design Review, its census is the assigned worklist.
|
|
208
|
+
Return the binding lines, grouped Coverage Verdicts and Design Findings format it
|
|
209
|
+
specifies. Do not substitute file-level summaries or the executor's self-check for
|
|
210
|
+
function-level M1/M2/M3 judgments. Missing accounting remains incomplete.
|
|
211
|
+
|
|
212
|
+
When Verification inputs contains a Frozen Review Policy, apply its captured
|
|
213
|
+
rule sources, architecture declaration and `review-rules.json` metadata instead
|
|
214
|
+
of current project settings and installed rules. Read them through the
|
|
215
|
+
verification-input projection. Original paths identify provenance, not a live
|
|
216
|
+
baseline. Select applicable resources with the router below. Legacy inputs
|
|
217
|
+
without this policy continue to use the lookup below.
|
|
218
|
+
For the captured policy, repeat `--source-path <repository-relative-path>` for
|
|
219
|
+
the relevant changed files in one `okstra model-io verification-input
|
|
220
|
+
--run-manifest <run-manifest>` call. Read complete selected rule bodies, not only
|
|
221
|
+
the available-resource index, and do not clip normative lines.
|
|
222
|
+
|
|
223
|
+
Apply the captured `clean-code.md` "Five simultaneous quality outcomes" to the
|
|
224
|
+
actual diff: correctness, coding principles, performance, safety and security
|
|
225
|
+
retain their applicable acceptance conditions. Reuse declared bounds and shared
|
|
226
|
+
execution evidence. A necessary missing bound or check remains unverified;
|
|
227
|
+
neither a green command nor complete grouped rows establish all five outcomes.
|
|
228
|
+
|
|
229
|
+
Resolve conflicts by `overview.md` policy precedence: explicit repository
|
|
230
|
+
instructions and declared architecture, the common pack, then surrounding code
|
|
231
|
+
conventions. Cite the governing instruction for an exception; an existing code
|
|
232
|
+
pattern alone does not waive an explicit architecture rule.
|
|
233
|
+
|
|
207
234
|
Re-running commands proves the diff *builds and passes*; it does NOT prove the diff is *well-designed*. Lint/test green is necessary but not sufficient — self-mocked tests, interaction-only assertions, and untruthful names all survive a green pipeline. This gate is the filter for exactly those defects, so the executor's design errors are caught here instead of in post-merge PR review. It is a real gate, not a checklist: it enumerates the full diff and a blocking hit forces `FAIL`. This blocking-check taxonomy is the **gate counterpart** of the executor's `Pre-commit diff review sweep` (`_implementation-diff-review.md`) prevention pass — the same defect families, different action (executor fixes in place; verifier fails the verdict). Both lists are inlined on purpose: each sidecar is delivered stand-alone into a flat CLI prompt (lazy-read, not INCLUDE-expanded), so neither can factor the taxonomy into a shared fragment.
|
|
208
235
|
|
|
209
|
-
- **Scope (no silent sampling).** Enumerate every changed
|
|
210
|
-
- **Load the
|
|
211
|
-
- **Load the project's review rule packs.**
|
|
212
|
-
- **Declared architecture style
|
|
236
|
+
- **Scope (no silent sampling).** Enumerate every changed file via `git diff --name-only <base>...HEAD`, apply the shared census exclusion policy and review every retained file, including executable configuration. Record each exclusion and its reason; extension alone does not establish one. Skipping a retained changed file silently is a `contract-violated` outcome. If a file's language has no reference and is not covered by the agnostic checks below, record `design-review skipped: <file> (language=<x> no reference)` — never pass it silently.
|
|
237
|
+
- **Load the executor's selected frozen conventions.** Use the captured projection above when available and record `coding-conventions: resources=<...>`. Only legacy inputs without that policy use the `**Coding preflight pack:**` installed path and its router, including every matching language/framework/architecture resource. A missing required captured source is blocked input; never replace it with live content. For unreadable legacy resources only, retain the agnostic checks and record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`.
|
|
238
|
+
- **Load the project's review rule packs.** Union the policy's standing standards with exact `SKILL.md` paths cited by the task brief's `Source Material` / `Reporter Confirmations`. With a frozen policy, use their captured bodies and directly named captured `references/*.md` bodies from the verification-input projection. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or read live originals. Only unfrozen legacy inputs run project-context for `Project Review Rule Packs` and read those declared files and their directly named references. Do not search parent directories or host skill catalogs. Apply the rules as an overlay on this static review, but do NOT dispatch extra reviewer agents unless the task explicitly configured them. Record `project-review-rules: <paths read>`, `project-review-rules: declared <path> unreadable`, or `project-review-rules: none declared or cited` in the worker result — an unreadable declared pack is a recorded gap, not a skip.
|
|
239
|
+
- **Declared architecture style selects the placement overlay.** Take `Architecture style` from the captured projection, or the legacy project-context projection, and record `architecture-style: <hexagonal|layered|none|undeclared>` beside `coding-conventions:`. A declared `hexagonal` selects H1–H6 even without layout signals and makes H5's otherwise-advisory concrete-adapter item binding. A declared `layered` selects no pack resource; its invariant is upper-to-lower dependency direction and variation points on layer boundaries. Cite changed reverse dependencies from their imports. Explicit `none` selects no overlay; only absent or `undeclared` style uses layout detection. An inferred hexagonal overlay retains each rule's criteria and severity, including H5's undeclared-style advisory exception. Apply policy precedence and shared grading; an established current blocking finding requires `FAIL`. `review_policy.py` selects the declared overlay and `_validate_verifier_fail_blocks_verdict` prevents a recorded `FAIL` from being dropped during synthesis; neither proves boundary interpretation.
|
|
213
240
|
- **Blocking checks (any hit → verdict `FAIL`, cited `path:line` + rule name, recommended fix recorded — the verifier does NOT apply it):**
|
|
214
241
|
- **Security (every changed file that reads input from outside the process or acts on its behalf — `clean-code.md` "Untrusted input and security"):** work that grows faster than the input — pairwise uniqueness, nested scans, a backtracking regex, input-driven recursion — reachable before a size/count bound has rejected oversized input (read the validation framework's configuration: class-validator without `stopAtFirstError` still runs `@ArrayUnique` after `@ArrayMaxSize` fails, and a byte-size body limit does not bound element count); input concatenated into SQL, a shell command, a file path, a server-side fetch target, a template or a regex; a new route / handler / resolver without the project's auth guard, or a lookup by an input-chosen id that never compares the caller with the owner; a secret, full token, password or personal data written to source, logs, an error message or a response; `eval`, dynamic code, or unsafe deserialization applied to input. Cite the input that triggers it and its effect — for unbounded work, the input size and the measured or derived cost.
|
|
215
242
|
- **New duplication / DRY:** two or more newly added or meaningfully modified blocks implement the same helper stack, transform, or domain rule. Literal copy-paste is always blocking; semantically equivalent transforms across services are blocking unless the approved plan explicitly justified keeping them separate. The comparison is not limited to this diff: a newly added block that is byte-identical to a block already in the repository — base code, or a copy an earlier stage landed — is the same blocking finding, cited at both the new `path:line` and the existing one, because `final-verification` grades that cross-stage copy as an Acceptance Blocker and a per-stage `clean` only defers it. Test helpers and test support code count. Recommend the shared module location.
|
|
216
243
|
- **Self-mocking:** a test for `Foo` stubs/spies a method on the `Foo` instance under test (`jest.spyOn(sut, ...)`, `spyOn(FooService.prototype, ...)` in `foo.*.spec.*`, `vi.mocked(sut)` + stub). Mocking injected collaborators is fine.
|
|
217
244
|
- **Interaction-only assertion:** a test whose only/primary assertion is `toHaveBeenCalled*` / `toHaveBeenCalledTimes` on an internal helper or a non-side-effecting collaborator, with no assertion on the returned value / resulting state / persisted row / emitted event.
|
|
218
245
|
- **Tautological delegation assertion:** a test asserts the SUT result equals a direct call to the same pure helper/collaborator that the SUT delegates to, instead of asserting an independent literal value or observable state.
|
|
219
|
-
- **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that
|
|
220
|
-
- **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. The failure modes the plan lists are the floor of this trace, not its ceiling: a verdict scoped to "the modeled failures" is not a verdict on the file. For every `try` whose `catch` / `finally` cleans up, check at each call inside it that can throw (a property write, a read, a call that starts other work) whether the thing to clean up is already registered at that point; when the diff moves or restructures existing code, compare that order with the base version and cite the base `path:line` when it changed. A failure the test fakes cannot produce (a throwing setter or read the fake does not model) is recorded as unverified with the failure named, never folded into `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every file
|
|
221
|
-
- **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that
|
|
222
|
-
- **Hexagonal (only when the overlay is loaded):** business
|
|
246
|
+
- **Untruthful name:** a read-named function (`get*` / `find*` / `load*`) that performs caller-visible mutations its name does not disclose, or an undefined or misleading business term. Inspect the port contract and governing policy before judging a domain-oriented query name; `findValid*` / `findActive*` and complex SQL alone do not establish a violation.
|
|
247
|
+
- **Wrong-result trace (every changed source file):** follow the paths this diff creates or alters to their end — error, partial, concurrent, selection — and name the input or state that produces a wrong result (`clean-code.md` §"Trace what this change can do wrong"). This one is an obligation, not a pattern: the defects that reach production are usually ordinary code with no name on this list. The bar is also the noise filter — a finding names the failing input; an alternative structure, a guard for a state no caller reaches, or a "consider extracting" is an improvement and verdicts `clean`. The failure modes the plan lists are the floor of this trace, not its ceiling: a verdict scoped to "the modeled failures" is not a verdict on the file. For every `try` whose `catch` / `finally` cleans up, check at each call inside it that can throw (a property write, a read, a call that starts other work) whether the thing to clean up is already registered at that point; when the diff moves or restructures existing code, compare that order with the base version and cite the base `path:line` when it changed. A failure the test fakes cannot produce (a throwing setter or read the fake does not model) is recorded as unverified with the failure named, never folded into `clean`. **The unit is the changed source file**: record `clean` or findings for each one, list every excluded file and its reason under the shared census exclusion policy, and close the section with `general: <N> files — all verdicted, <M> excluded`. Configuration that controls executable behavior is reviewed under that policy rather than excluded by extension alone.
|
|
248
|
+
- **Business rules in an application service (only when the hexagonal overlay is loaded):** changed service code that implements a business decision instead of orchestrating a domain-owned one (`architectures/hexagonal.md` Rule H6). Inspect the implementation and governing rule; a private method's domain-oriented name alone is not evidence. Orchestration control flow, DTO mapping and calling a domain predicate are not violations. Apply shared grading when declaration or layout selects the overlay; a substantial embedded rule such as money, permissions or a state machine remains blocking.
|
|
249
|
+
- **Hexagonal (only when the overlay is loaded):** executable business decisions inside a port body; business policy invented or changed in an adapter rather than owned by the domain; misplaced domain objects or outward domain dependencies contrary to the applicable architecture. An adapter may translate domain-owned query specifications into efficient SQL, including compound predicates and joins. Complex SQL, a domain-oriented query name or post-fetch processing alone is not a violation; do not require `findAll` plus in-memory filtering. Inspect the governing policy, port contract and imports, and apply `overview.md` precedence and H1–H6 whether declaration or layout selected the overlay. Existing code conventions alone cannot waive an applicable boundary. Grade established current violations with the shared rubric; H5 alone retains its undeclared-style advisory exception.
|
|
223
250
|
- **gitignored file committed to the branch:** any path in the `git diff --name-only <base>...HEAD` enumeration that `.gitignore` excludes — enumerate them by piping that list through `git check-ignore --stdin --no-index`. A committed ignored file means the executor bulk-added (`git add .`/`-A`) or force-staged (`git add -f`) it, leaking build output, scratch files, or verification artifacts into the eventual PR. This explicitly includes `.okstra/` paths (and `.project-docs/` when the legacy symlink is present): `.okstra/**` is gitignored, so a committed okstra file (qa scripts, conformance results) is always this defect. Cite each path; recommend `git rm --cached <path>` to untrack it while keeping the file on disk. Conformance/qa evidence belongs in the carry sidecar / verifier result, never in git history.
|
|
224
251
|
- **Real-IO test in source tree:** a changed/added test under the project source test tree — `src/**`, `test/**`, `tests/**`, `**/__test__/**`, `**/__tests__/**`, `*.spec.*`, `*.test.*` — that opens a **real** DB connection / DSN, makes a real `fetch` / `axios` / `http` request, or otherwise hits real external IO without mocking the injected collaborator (a live handle, not a stub/spy). Real-IO tests MUST live under `<task_root>/qa/scripts/` per the executor's *Real-IO test isolation* rule — a live-IO test in source silently breaks the project's CI suite and violates the artifact-home rule. Cite the test file + the real-IO line; recommend moving it to `<task_root>/qa/scripts/` (or declaring it as a Tier 3 conformance script). Mock-only unit tests in source are NOT a hit.
|
|
225
252
|
- **Proxy-based identity decision:** a move / ownership / re-parenting decision taken from a status field or flag while the source and destination identifiers were available and never compared. Cite the condition and the identifiers it should have compared, and show the opposite case the condition also reads true for.
|
|
@@ -231,11 +258,12 @@ Re-running commands proves the diff *builds and passes*; it does NOT prove the d
|
|
|
231
258
|
- **Positional mock-argument access:** `mock.calls[<n>][<m>]` (or the framework equivalent) used to inspect arguments instead of an intent-revealing `toHaveBeenCalledWith` / explicit-absence assertion. Detect with `rg 'mock\.calls'` over the changed test files.
|
|
232
259
|
- **Non-separating test data:** two scenarios whose setup values and assertions are identical, so a wrong implementation passes both; or new test tooling added in this diff (mock, state setter, repository branch) that no test calls.
|
|
233
260
|
- **Effect claimed under its own mock:** a test presented as covering an effect whose producing path is replaced by a mock inside that same test. The mock's presence in the harness is not evidence the branch behind it works.
|
|
234
|
-
- **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape.
|
|
261
|
+
- **Single-caller abstraction (KISS):** an abstraction layer this diff introduces — a helper module, a strategy / factory / builder, an indirection or wrapper layer, an interface or abstract base — that has exactly one caller after the change, where inlining it at that call site would be simpler. The rule is `overview.md` core principle 2: name the second caller now, or inline. Four exits are legitimate and each must **cite its evidence**: the approved plan declares it (a `testSeams[]` boundary or a variation-point extraction — cite the plan step); the project declares `architecture.style = hexagonal` and this is a port at the domain boundary (a port with one adapter is the normal shape, not a violation); it breaks a real import cycle (name both modules); or its single caller is the public API of a published package. Absent one of those, cite `path:line` and recommend the inlined shape. This targets reusable layers, not a local helper that names a cohesive step or separates mixed abstraction levels, nor a pre-existing abstraction this diff merely edits. Line count alone does not justify extraction.
|
|
235
262
|
- **File-size limit (every verifier, not only the stage QA owner):** run `okstra correction file-size --base <base>` from the worktree cwd and log it in the `Read-only command log`. Each `FILE-SIZE:<path>:501 <before>-><after>` line it prints is a blocking finding cited exactly as printed — a new file over 500 lines, or a file the diff took from 500 or fewer past 500. A file already over 500 at the stage base that the diff grows is not blocking; the command prints it as an advisory line. Recommended fix: move whole responsibilities into new modules or test files beside it. The command writes nothing and its result is the same for every verifier, so the finding converges and the lead sends it to a correction round. Each `FILE-SIZE-ADVISORY:<path>:301` line (the 300-line target: a new file over 300, a file the diff took past 300, or a file already over 300 the diff grew, including one already over 500) goes under the advisory findings below, not here. Do not judge size yourself: a file it does not print is not a finding (lockfiles, data, Markdown, fixtures, snapshots, generated files and languages without a coding preflight are exempt by `scripts/okstra_ctl/file_size_cap.py` `capped_path`).
|
|
236
263
|
- **Caller-less identifier (YAGNI / orphan):** an identifier this diff leaves with zero callers — either newly added and never called (a speculative parameter, an optional config object, a "future-proof" hook, an exported helper whose only caller is hypothetical), or pre-existing code orphaned because this diff removed its last caller. Grep the identifier across the whole repository rather than the diff alone; a hit inside its own declaration, its own test, or a commented-out line is not a caller. Two exits are legitimate and must be **stated with their evidence**, never assumed: an identifier the approved plan reserves for a named later stage (cite the plan step), and a contract point something other than project code calls (a framework entrypoint, an implemented interface method, a migration hook, the public API of a published package — cite the caller or the registration). Anything else is work no requirement asked for: recommend deleting it, or folding an added parameter back into its single call site. A caller-less identifier is the one YAGNI violation that survives a green pipeline unchanged, which is why it grades here rather than as a recommendation.
|
|
237
|
-
- **
|
|
238
|
-
- **
|
|
264
|
+
- **Shared grading:** use the captured catalog and `clean-code.md` "Finding evidence and grading". A clear M1/M2 violation (misleading name, mixed responsibility, excessive complexity or mixed abstraction levels) can be `should-fix` / `now` and forces `FAIL` even when commands pass. More than 50 effective function lines prompts inspection; it does not establish a violation or force a split. Name the rule, source and design consequence; a preferred alternative alone is not a finding. Apply the same evidence test to state policy, unobserved error causes and missing resource-bound tests rather than automatically downgrading them. Restrictive plan placement returns a plan conflict, never permission to pass a current violation.
|
|
265
|
+
- **Nonblocking findings:** `nit`, justified `park`, and size-only target advisories may accompany `PASS`. An already oversized file's size advisory does not exempt its added responsibilities from S3/M2. Architecture-specific latitude follows the declared style and the applicable project rule; record its cited basis. Do not demand unrelated legacy cleanup.
|
|
266
|
+
- **Output.** Every finding — blocking or advisory — is a structured item in the verifier's worker result (`path:line`, rule, severity, suggested fix) so it carries into Phase 5.5 convergence and the final report. Each item, advisory items included, carries an item id as `prompts/profiles/_common-contract.md` "Cross-worker traceability" defines it for worker output. The lead cites a finding by that id, and `okstra convergence seed` refuses a cited id that does not occur in the result, so an unnumbered item cannot enter convergence and drops out of the report. This is a guideline: nothing parses a verifier result for missing ids. A blocking hit sets the verifier verdict to `FAIL` with the rule cited, using the same verdict machinery as the Discrepancy rule above. The Okstra lead MUST NOT silently downgrade a cited blocking finding to advisory during synthesis; an override requires a concrete cited reason, exactly as for the Discrepancy rule.
|
|
239
267
|
|
|
240
268
|
### Fix-run incremental scope (applies when the profile carries a "Fix-Run Carry" block)
|
|
241
269
|
|
package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html
CHANGED
|
@@ -26,6 +26,19 @@
|
|
|
26
26
|
{% for row in implementation.verifierResults %}<article class="summary-card tone-{{ row.verdict | lower }}"><p class="eyebrow">{{ row.verifier | inline_code }} · <span class="status status-{{ row.verdict | lower }}">{{ row.verdict }}</span></p>{% for label, text in ((t('tasks.implementation.independent-rerun'), row.get("independentValidationRerun")), (t('tasks.implementation.command-log'), row.get("readOnlyCommandLog"))) if text %}<details><summary><strong>{{ label }}</strong> {{ t('tasks.implementation.entry-count') | replace('{count}', text.strip().splitlines() | select | list | length | string) }}</summary><pre>{{ text }}</pre></details>{% endfor %}{% if row.get("executionEvidence") %}<p><strong>{{ t('tasks.implementation.execution-records') }}</strong></p><ul class="evidence-refs" data-report-field="implementation.verifierResults.executionEvidence">{% for ref in row.executionEvidence %}<li><code>{{ ref.checkRef }}</code> run {{ ref.checkRun }} · {% if ref.collection == "complete" %}{{ t('tasks.implementation.exit-code') }} {{ ref.exitCode if ref.exitCode is not none else ref.signal }}{% else %}<span class="status status-incomplete">{{ t('tasks.implementation.incomplete-collection') }}</span> {{ ref.defect | inline_code }}{% endif %} · <code>{{ ref.recordPath }}</code></li>{% endfor %}</ul>{% endif %}{% if row.get("discrepancy") %}<p class="evidence-refs">{{ t('tasks.implementation.discrepancy') }} {{ row.discrepancy | inline_code }}</p>{% endif %}{% if row.get("declinedFixRecommendations") %}<p>{{ row.declinedFixRecommendations | inline_code }}</p>{% endif %}</article>{% endfor %}
|
|
27
27
|
</section>
|
|
28
28
|
|
|
29
|
+
{% for verifier in implementation.verifierResults if verifier.get("designReview") %}
|
|
30
|
+
<section data-report-field="implementation.verifierResults.designReview">
|
|
31
|
+
<h2>{{ verifier.verifier | e }} · Design review</h2>
|
|
32
|
+
{% set review = verifier.designReview %}
|
|
33
|
+
<p>{{ review.collection | e }} · {{ review.get("coveredCells", 0) | e }}/{{ review.get("expectedCells", 0) | e }} cells · {{ review.verdict | e }}</p>
|
|
34
|
+
{% if review.get("reason") %}<p>{{ review.reason | e }}</p>{% endif %}
|
|
35
|
+
{% for finding in review.get("findings", []) %}<article><h3>{{ finding.id | e }} · {{ finding.rule | e }} · {{ finding.severity | e }} · {{ finding.timing | e }}</h3><p>{{ finding.source | e }}: {{ finding.consequence | e }}</p><p>{{ finding.fix | e }}</p><p>{{ finding.disposition | e }} · {{ finding.basis | e }}</p></article>{% endfor %}
|
|
36
|
+
{% for disposition in review.get("carry", []) %}<p>{{ disposition.finding | e }} · {{ disposition.disposition | e }} · {{ disposition.basis | e }}</p>{% endfor %}
|
|
37
|
+
{% for prior in review.get("history", []) %}{% for finding in prior.get("findings", []) %}<p>Earlier {{ prior.generationNumber | e }}:{{ finding.id | e }} · {{ finding.rule | e }} · {{ finding.severity | e }} · {{ finding.timing | e }} · {{ finding.consequence | e }}</p>{% endfor %}{% endfor %}
|
|
38
|
+
{% if review.get("missing") %}<pre>{{ review.missing | e }}</pre>{% endif %}
|
|
39
|
+
</section>
|
|
40
|
+
{% endfor %}
|
|
41
|
+
|
|
29
42
|
{% if implementation.get("leadFixes") %}<section data-report-section="lead-fixes" data-report-field="implementation.leadFixes">
|
|
30
43
|
<h2>{{ t('tasks.implementation.lead-fixes') }}</h2>
|
|
31
44
|
<p>{{ t('tasks.implementation.lead-fixes-intro') }}</p>
|
|
@@ -17,6 +17,31 @@
|
|
|
17
17
|
|
|
18
18
|
`implementation` executes an approved `implementation-planning` final report into actual code changes and local commits. Source edit is allowed only in this phase, but scope is limited to the approved plan and recorded out-of-plan justification.
|
|
19
19
|
|
|
20
|
+
### Independent design-review evidence
|
|
21
|
+
|
|
22
|
+
New approved-plan preparations use verification-input version 4.0. The frozen
|
|
23
|
+
policy, pre-execution base and generation head define every verifier's identical
|
|
24
|
+
file/function worklist. A missing cell/rule remains incomplete for that verifier;
|
|
25
|
+
another verifier or executor self-check cannot fill it. The existing Python AST
|
|
26
|
+
census includes named test helpers; other supported code languages require a
|
|
27
|
+
source-bound manual inventory before dispatch. Inventory completeness remains
|
|
28
|
+
lead judgment. `design_review.py` and generation capture check these contracts.
|
|
29
|
+
|
|
30
|
+
The shared catalog and grading reference classify clear naming/readability
|
|
31
|
+
violations without requiring runtime failure. `design_review_evidence.py`
|
|
32
|
+
authenticates the reserved invocation, latest attempt and sealed result bytes.
|
|
33
|
+
Report assembly derives the evidence and verdict rather than accepting a writer
|
|
34
|
+
summary; current blocking findings and incomplete accounting prevent acceptance.
|
|
35
|
+
`stage_done.py` and phase validation re-derive the same evidence. Final
|
|
36
|
+
verification checks the prepared source reports for consistency, without a
|
|
37
|
+
global style review. Existing input versions keep their resume contract.
|
|
38
|
+
|
|
39
|
+
Each correction generation re-inspects the full stage diff and dispositions
|
|
40
|
+
every earlier blocking finding in `Design Carry`. Old findings remain in the
|
|
41
|
+
machine-owned history, including nits and parked items. No rule judgments are
|
|
42
|
+
inherited without dependency evidence. Regression owners are
|
|
43
|
+
`tests/verification/test_design_review.py` and `tests/report/test_assembly.py`.
|
|
44
|
+
|
|
20
45
|
## 2. okstra-run wizard flow
|
|
21
46
|
|
|
22
47
|
```mermaid
|
|
@@ -257,4 +282,4 @@ This phase does not declare final acceptance. It says only ready for final-verif
|
|
|
257
282
|
| I-2 | A verifier cannot report a discrepancy with a PASS verdict. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_verifier_discrepancy_is_not_passed` |
|
|
258
283
|
| I-3 | Frozen legacy instruction pointers resolve within the selected installation without rewriting the frozen profile. | unenforced |
|
|
259
284
|
| I-4 | In a run marked `verificationEvidenceVersion: "1.0"`, each verifier's `executionEvidence` is the latest run of every check under its latest attempt of the invocation bound to the newest generation, with the recorded bytes and observation; a record that is not `completed` is incomplete collection. | `scripts/okstra_ctl/phases/implementation/validation.py::validate_verifier_execution_evidence` |
|
|
260
|
-
| I-5 | In a marked run, a `leadFixes` entry blocks the report, and a stage settled after correction round N shows
|
|
285
|
+
| I-5 | In a marked run, a `leadFixes` entry blocks the report, and a stage settled after correction round N shows the records of generation N + 1 of each verifier that generation gives a check it may run. Unmarked runs keep the lead-fix reading. | `scripts/okstra_ctl/phases/implementation/validation.py::_validate_lead_fixes`, `validate_settled_round_was_reverified` |
|
|
@@ -3,16 +3,23 @@ from __future__ import annotations
|
|
|
3
3
|
|
|
4
4
|
import re
|
|
5
5
|
from collections.abc import Callable, Mapping
|
|
6
|
+
from dataclasses import dataclass
|
|
6
7
|
from pathlib import Path
|
|
7
8
|
from typing import Any
|
|
8
9
|
|
|
10
|
+
from ...agent.invocation import AgentInvocationError, reserved_generation_reference
|
|
9
11
|
from ...correction_round import correction_round
|
|
12
|
+
from ...json_boundary import load_owned_object
|
|
10
13
|
from ...report_execution_evidence import (
|
|
11
14
|
EXECUTION_EVIDENCE_BLOCKING, collect_report_evidence, omitted_records, reference_errors,
|
|
12
15
|
)
|
|
13
16
|
from ...paths import RunRef
|
|
17
|
+
from ...qa_procedures import safe_qa_path
|
|
18
|
+
from ...registry.verification_inputs_store import default_verification_input_store
|
|
14
19
|
from ...verification_dispatch import generation_sealed_after_round
|
|
15
20
|
from ...verification_evidence import roster_verifier_role_execution_ref
|
|
21
|
+
from ...verification_generation import read_verification_generation
|
|
22
|
+
from ...worker_prompt_policy import stage_qa_owner
|
|
16
23
|
|
|
17
24
|
_PASSING_VERDICT_TOKENS = frozenset({"accepted", "conditional-accept"})
|
|
18
25
|
_CHECKLIST_ID_RE = re.compile(r"\bVC-\d{3,}\b")
|
|
@@ -421,6 +428,12 @@ def validate_verifier_execution_evidence(
|
|
|
421
428
|
attempt of the invocation bound to the newest generation, with the bytes and
|
|
422
429
|
observation it recorded; a `not-run` row is not read.
|
|
423
430
|
"""
|
|
431
|
+
from ...design_review_evidence import validate_design_review_report
|
|
432
|
+
|
|
433
|
+
try:
|
|
434
|
+
validate_design_review_report(data, project_root, manifest_path)
|
|
435
|
+
except (OSError, ValueError) as exc:
|
|
436
|
+
failures.append(f"design-review BLOCKING: {exc}")
|
|
424
437
|
try:
|
|
425
438
|
evidence = collect_report_evidence(project_root, manifest_path)
|
|
426
439
|
except ValueError as exc:
|
|
@@ -453,13 +466,74 @@ def validate_verifier_execution_evidence(
|
|
|
453
466
|
f"verifier's execution records {omitted}")
|
|
454
467
|
|
|
455
468
|
|
|
469
|
+
@dataclass(frozen=True)
|
|
470
|
+
class _GenerationChecks:
|
|
471
|
+
qa: bool
|
|
472
|
+
conformance: bool
|
|
473
|
+
|
|
474
|
+
def owed_by(self, *, conformance_owner: bool) -> bool:
|
|
475
|
+
"""Whether a verifier has a check of this generation that evidence
|
|
476
|
+
mode lets it run: any frozen qaCommands entry, or a sealed conformance
|
|
477
|
+
stage for the stage QA owner."""
|
|
478
|
+
return self.qa or (self.conformance and conformance_owner)
|
|
479
|
+
|
|
480
|
+
|
|
481
|
+
def _generation_checks(
|
|
482
|
+
project_root: Path, manifest: Mapping[str, Any], generation_path: str,
|
|
483
|
+
) -> _GenerationChecks | None:
|
|
484
|
+
"""The kinds of check the generation at `generation_path` holds; None when
|
|
485
|
+
no verifier invocation is bound to it, so no verifier was dispatched after
|
|
486
|
+
the fix and every one still owes a record."""
|
|
487
|
+
root = project_root.resolve()
|
|
488
|
+
digest = _bound_generation_digest(root, manifest, generation_path)
|
|
489
|
+
if digest is None:
|
|
490
|
+
return None
|
|
491
|
+
generation_record = read_verification_generation(
|
|
492
|
+
safe_qa_path(root, generation_path), digest,
|
|
493
|
+
)
|
|
494
|
+
inputs = default_verification_input_store().read(
|
|
495
|
+
safe_qa_path(root, generation_record["verificationInputsPath"]),
|
|
496
|
+
generation_record["verificationInputsDigest"],
|
|
497
|
+
)
|
|
498
|
+
return _GenerationChecks(
|
|
499
|
+
qa=any(inputs["qaCommands"].values()),
|
|
500
|
+
conformance=bool(generation_record.get("conformanceStages")),
|
|
501
|
+
)
|
|
502
|
+
|
|
503
|
+
|
|
504
|
+
def _bound_generation_digest(
|
|
505
|
+
project_root: Path, manifest: Mapping[str, Any], generation_path: str,
|
|
506
|
+
) -> str | None:
|
|
507
|
+
"""The digest an invocation reservation of this run binds the generation at
|
|
508
|
+
`generation_path` to; None when no reservation binds it."""
|
|
509
|
+
contract = manifest.get("agentContract")
|
|
510
|
+
reservations = (contract.get("invocationReservationRootPath")
|
|
511
|
+
if isinstance(contract, Mapping) else None)
|
|
512
|
+
if not isinstance(reservations, str):
|
|
513
|
+
return None
|
|
514
|
+
for path in sorted(safe_qa_path(project_root, reservations).glob("*.json")):
|
|
515
|
+
reservation = load_owned_object(path, artifact="invocation reservation")
|
|
516
|
+
reference = reserved_generation_reference(
|
|
517
|
+
project_root, manifest, reservation["invocationRef"], reservation["attempt"],
|
|
518
|
+
)
|
|
519
|
+
if reference is not None and reference.path == generation_path:
|
|
520
|
+
return reference.digest
|
|
521
|
+
return None
|
|
522
|
+
|
|
523
|
+
|
|
456
524
|
def validate_settled_round_was_reverified(
|
|
457
525
|
data: dict, project_root: Path, manifest_path: Path,
|
|
458
526
|
manifest: Mapping[str, Any], failures: list[str],
|
|
459
527
|
) -> None:
|
|
460
528
|
"""A stage settled after correction round N in an evidence-contract run
|
|
461
|
-
shows
|
|
462
|
-
|
|
529
|
+
shows the records of generation N + 1, the one sealed after the executor's
|
|
530
|
+
fix, of each verifier that generation gives a check it may run.
|
|
531
|
+
|
|
532
|
+
Evidence mode refuses a `conformance:` check from anyone but the stage QA
|
|
533
|
+
owner, so with no frozen `qaCommands` entry the other verifiers can write no
|
|
534
|
+
record at all; requiring one from them made such a stage impossible to
|
|
535
|
+
settle.
|
|
536
|
+
"""
|
|
463
537
|
implementation = data.get("implementation")
|
|
464
538
|
if not isinstance(implementation, dict) or not _stage_settled(implementation):
|
|
465
539
|
return
|
|
@@ -470,9 +544,19 @@ def validate_settled_round_was_reverified(
|
|
|
470
544
|
generation = generation_sealed_after_round(max(rounds))
|
|
471
545
|
expected = RunRef.from_manifest(manifest_path, manifest).verification_generation(
|
|
472
546
|
generation).resolve().relative_to(project_root.resolve()).as_posix()
|
|
547
|
+
try:
|
|
548
|
+
checks = _generation_checks(project_root, manifest, expected)
|
|
549
|
+
except (AgentInvocationError, OSError, ValueError, KeyError) as exc:
|
|
550
|
+
failures.append(f"{_CORRECTION_BLOCKING} generation {generation} "
|
|
551
|
+
f"(`{expected}`) could not be read: {exc}")
|
|
552
|
+
return
|
|
553
|
+
owner = stage_qa_owner(manifest)
|
|
473
554
|
for who, row in _verifier_rows(data):
|
|
474
555
|
if row.get("verdict") == "not-run":
|
|
475
556
|
continue
|
|
557
|
+
if checks is not None and not checks.owed_by(
|
|
558
|
+
conformance_owner=row.get("verifier") == owner):
|
|
559
|
+
continue
|
|
476
560
|
references = [reference for reference in row.get("executionEvidence") or []
|
|
477
561
|
if isinstance(reference, dict)]
|
|
478
562
|
if not references or any((reference.get("generation") or {}).get("path")
|
|
@@ -1049,6 +1049,10 @@ def _render_file_size_headroom(rows: object) -> str:
|
|
|
1049
1049
|
return ""
|
|
1050
1050
|
lines = [
|
|
1051
1051
|
"\n## File-size headroom\n",
|
|
1052
|
+
"\nA negative headroom identifies an already oversized file, not permission to add "
|
|
1053
|
+
"unrelated responsibilities. Apply S3/M2 to the proposed placement. If the plan's "
|
|
1054
|
+
"file restrictions prevent a conforming change, return a plan conflict with the "
|
|
1055
|
+
"proposed module/test location and the acceptance behavior it preserves.\n",
|
|
1052
1056
|
"Existing files this plan writes, measured before any stage runs. Information "
|
|
1053
1057
|
"only: it is not a verdict criterion.\n",
|
|
1054
1058
|
]
|
|
@@ -63,7 +63,7 @@ Plan for the actual worktree layout before approval. Shared documentation direct
|
|
|
63
63
|
- **Follow established patterns**: in existing codebases, conform to current conventions. Targeted cleanup of a file you are already modifying is acceptable; unrelated refactors are not.
|
|
64
64
|
- **Variation-point extraction (OCP)**: when the same behavior is served by two or more resources / implementations — stated in the brief, or foreseeable from a sibling task or the code you inspected — the plan MUST record it in `variationPointAnalysis` and make an evidence-backed `extractionDecision` that preserves the chosen direction's architecture boundaries. Reject a realization that branches on resource identity inside a service (one `if` / `switch` arm per implementation): adding the next implementation then means editing that same call site again, which is the closed-for-extension shape this principle exists to catch. This does not contradict YAGNI below: YAGNI drops *speculative* variation (a second implementation nobody named), while a behavior with two implementations already on the table is a present fact, not a forecast. **Enforced:** the `variationPointAnalysis` bullet under `Required deliverable shape` names the schema / validator / `P-Var-*` enforcement points.
|
|
65
65
|
- **YAGNI ruthlessly**: drop features, abstractions, and configuration knobs that do not serve the stated requirement. The test is a *present* caller, not a plausible one — an abstraction whose only justification is a requirement nobody has stated is this rule's target, while a behavior with two implementations already on the table belongs to `Variation-point extraction` above. **Enforced:** the §5.5.9 plan-body verification round raises a hidden direction expansion on selected-direction `P-Dir-1`, and retains legacy `P-Opt-*` `DISAGREE(e)` semantics. One phase later the `implementation` verifier's Static design gate fails the stage on a caller-less identifier.
|
|
66
|
-
- **Project review-rule preflight**:
|
|
66
|
+
- **Project review-rule preflight**: use the Frozen Review Policy when verification inputs supplies one; legacy inputs retain the union of declared packs and exact brief-cited paths. Apply `clean-code.md` "Finding evidence and grading" and the shared catalog. Plan conforming names, function responsibilities, module placement and behavioral tests before code exists. A file restriction or test-preservation instruction that conflicts with a rule returns a plan conflict naming the proposed location and preserved acceptance behavior; it does not waive the rule. Do not run the PR-review workflow or search host skill catalogs here. Semantic conformance is judged by plan-body verification; freezing and input validity are checked by verification-input preparation.
|
|
67
67
|
- Expected output emphasis:
|
|
68
68
|
- feasible realization of the selected direction or legacy choice
|
|
69
69
|
- dependency and risk visibility
|
|
@@ -560,6 +560,7 @@ def _compose(
|
|
|
560
560
|
data["verificationScope"] = scope
|
|
561
561
|
data["agentActivity"] = activities
|
|
562
562
|
_attach_execution_evidence(data, project_root, manifest_path, manifest, inputs)
|
|
563
|
+
_attach_design_review_evidence(data, project_root, manifest_path, inputs)
|
|
563
564
|
data["evidence"] = {"primary": _promoted_evidence([
|
|
564
565
|
*(("convergence", item) for item in convergence_data["promotedEvidence"]),
|
|
565
566
|
*round_evidence,
|
|
@@ -578,6 +579,20 @@ def _compose(
|
|
|
578
579
|
return data
|
|
579
580
|
|
|
580
581
|
|
|
582
|
+
def _attach_design_review_evidence(
|
|
583
|
+
data: dict[str, Any], project: Path, manifest_path: Path, inputs: Mapping[str, ReportInputPath],
|
|
584
|
+
) -> None:
|
|
585
|
+
from .design_review_evidence import attach_design_reviews, collect_design_reviews
|
|
586
|
+
|
|
587
|
+
try:
|
|
588
|
+
attach_design_reviews(data, collect_design_reviews(project, manifest_path))
|
|
589
|
+
from .phases.final_verification.validation import validate_implementation_review_evidence
|
|
590
|
+
|
|
591
|
+
validate_implementation_review_evidence(project, manifest_path)
|
|
592
|
+
except (OSError, ValueError) as exc:
|
|
593
|
+
_fail("design-review", inputs["narrative"].path, "implementation.verifierResults", exc)
|
|
594
|
+
|
|
595
|
+
|
|
581
596
|
def _attach_execution_evidence(
|
|
582
597
|
data: dict[str, Any], project_root: Path, manifest_path: Path,
|
|
583
598
|
manifest: Mapping[str, Any], inputs: Mapping[str, ReportInputPath],
|
|
@@ -23,6 +23,7 @@ _NESTED_FORBIDDEN = frozenset(
|
|
|
23
23
|
"implementationPlanning.planBodyVerification",
|
|
24
24
|
# Report assembly derives these from the verification execution records.
|
|
25
25
|
"implementation.verifierResults.executionEvidence",
|
|
26
|
+
"implementation.verifierResults.designReview",
|
|
26
27
|
"finalVerification.readonlyCommandLog.executionEvidence",
|
|
27
28
|
}
|
|
28
29
|
)
|
|
@@ -244,6 +245,8 @@ def writer_owned_data(data: Mapping[str, Any]) -> dict[str, Any]:
|
|
|
244
245
|
if key in _allowed_top_level()
|
|
245
246
|
}
|
|
246
247
|
planning = owned.get("implementationPlanning")
|
|
248
|
+
for row in (owned.get("implementation") or {}).get("verifierResults", []):
|
|
249
|
+
row.pop("designReview", None)
|
|
247
250
|
if isinstance(planning, dict):
|
|
248
251
|
planning.pop("designPreparation", None)
|
|
249
252
|
planning.pop("planBodyVerification", None)
|
|
@@ -151,3 +151,10 @@ PROSE_KEYS = frozenset({
|
|
|
151
151
|
"whyItMatters",
|
|
152
152
|
"workingAssumption",
|
|
153
153
|
})
|
|
154
|
+
|
|
155
|
+
|
|
156
|
+
# A stringified null is not prose. Lowercase `none` is a token the clarification
|
|
157
|
+
# option contract uses on purpose ("reverses nothing"), so only the capitalised
|
|
158
|
+
# and language-native spellings count — 2026-09-05 audit: `"None"` in 16
|
|
159
|
+
# trade-off cells and 2 option fields across the shipped reports.
|
|
160
|
+
NULL_LITERALS = frozenset({"None", "null", "undefined", "NaN"})
|
|
@@ -230,6 +230,15 @@ class ReportSynthesisPacket:
|
|
|
230
230
|
return []
|
|
231
231
|
|
|
232
232
|
def _task_instructions(self) -> list[str]:
|
|
233
|
+
if self.task_type == "implementation":
|
|
234
|
+
design_note = (
|
|
235
|
+
"Report assembly derives verifierResults[].designReview and overall verifier verdicts "
|
|
236
|
+
"from current sealed verifier returns when the run uses design-review input 4.0. "
|
|
237
|
+
"Do not author that field, omit findings to obtain acceptance or treat incomplete "
|
|
238
|
+
"coverage as clean. Preserve reported nits, parked findings and accepted-risk bases."
|
|
239
|
+
)
|
|
240
|
+
else:
|
|
241
|
+
design_note = ""
|
|
233
242
|
if self.task_type == "technical-verification":
|
|
234
243
|
return [
|
|
235
244
|
"Copy sourceReport, sourceDataSha256, scope and every fact identity "
|
|
@@ -257,15 +266,23 @@ class ReportSynthesisPacket:
|
|
|
257
266
|
source.label.startswith(f"{CONVERGENCE_STATE_LABEL} (correction-r")
|
|
258
267
|
for source in self.sources
|
|
259
268
|
):
|
|
260
|
-
return [
|
|
269
|
+
return [design_note,
|
|
261
270
|
"Each `Convergence state (correction-r<N>)` source is correction round N's "
|
|
262
271
|
"re-convergence of the verifiers' re-verification; the plain `Convergence "
|
|
263
272
|
"state` is the initial round's. Describe the stage's open findings from the "
|
|
264
273
|
"last round's re-convergence, not the initial one; report what each round "
|
|
265
274
|
"fixed through `implementation.correctionRounds`.",
|
|
275
|
+
"`implementation.verifierResults[]` holds each verifier's last-round "
|
|
276
|
+
"verdict. Its `implementation.verifierResults[].discrepancy` records only "
|
|
277
|
+
"a divergence between that verifier's last-round rerun and the executor's "
|
|
278
|
+
"reported result: leave it empty when that rerun matched. A verdict that "
|
|
279
|
+
"changed between rounds (an initial `FAIL`, then `PASS`) is not a "
|
|
280
|
+
"discrepancy; `implementation.correctionRounds[].verifierVerdicts` records "
|
|
281
|
+
"it. `validate-run` reads any text in `discrepancy` beside a `PASS` "
|
|
282
|
+
"verdict as an unresolved divergence.",
|
|
266
283
|
]
|
|
267
284
|
if self.task_type != "implementation-option-selection":
|
|
268
|
-
return []
|
|
285
|
+
return [design_note] if design_note else []
|
|
269
286
|
return selection_requirement_instructions(
|
|
270
287
|
self.original_requirement_ids, self.participating_analysers,
|
|
271
288
|
)
|