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.
Files changed (143) hide show
  1. package/README.md +15 -3
  2. package/dist/cli-registry.mjs +6 -0
  3. package/dist/cli-registry.mjs.map +1 -1
  4. package/dist/commands/memory/memory.mjs +9 -55
  5. package/dist/commands/memory/memory.mjs.map +1 -1
  6. package/dist/lib/memory-auto-register.d.mts +1 -0
  7. package/dist/lib/memory-auto-register.mjs +113 -0
  8. package/dist/lib/memory-auto-register.mjs.map +1 -0
  9. package/dist/lib/memory-entry-contract.d.mts +12 -0
  10. package/dist/lib/memory-entry-contract.mjs +46 -0
  11. package/dist/lib/memory-entry-contract.mjs.map +1 -0
  12. package/dist/lib/python-helper.d.mts +1 -1
  13. package/dist/lib/python-helper.mjs +3 -2
  14. package/dist/lib/python-helper.mjs.map +1 -1
  15. package/dist/lib/record-secrets.d.mts +1 -0
  16. package/dist/lib/record-secrets.mjs +28 -0
  17. package/dist/lib/record-secrets.mjs.map +1 -0
  18. package/dist/lib/types.d.mts +2 -1
  19. package/docs/architecture/storage-model.md +129 -2
  20. package/docs/architecture.md +11 -2
  21. package/docs/cli.md +234 -0
  22. package/docs/project-structure-overview.md +2 -1
  23. package/package.json +1 -1
  24. package/runtime/BUILD.json +2 -2
  25. package/runtime/agents/common.json +8 -8
  26. package/runtime/agents/roles/verifier.json +2 -4
  27. package/runtime/bin/okstra-provider-exec.py +10 -4
  28. package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
  29. package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
  30. package/runtime/prompts/coding-preflight/clean-code.md +85 -281
  31. package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
  32. package/runtime/prompts/coding-preflight/languages/java.md +3 -5
  33. package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
  34. package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
  35. package/runtime/prompts/coding-preflight/languages/python.md +2 -7
  36. package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
  37. package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
  38. package/runtime/prompts/coding-preflight/overview.md +25 -38
  39. package/runtime/prompts/coding-preflight/review-rules.json +30 -0
  40. package/runtime/prompts/duties/code-reviewer.json +15 -18
  41. package/runtime/prompts/duties/implementation-verifier.json +1 -0
  42. package/runtime/prompts/lead/convergence.md +3 -3
  43. package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
  44. package/runtime/prompts/lead/report-writer.md +1 -1
  45. package/runtime/prompts/lead/team-contract.md +1 -1
  46. package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
  47. package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
  48. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  49. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  50. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  51. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  52. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  53. package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
  54. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  55. package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
  56. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  57. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  58. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  59. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  60. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  61. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  62. package/runtime/python/okstra_ctl/consumers.py +12 -9
  63. package/runtime/python/okstra_ctl/convergence.py +112 -20
  64. package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
  65. package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
  66. package/runtime/python/okstra_ctl/correction_round.py +6 -1
  67. package/runtime/python/okstra_ctl/design_review.py +207 -0
  68. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  69. package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
  70. package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
  71. package/runtime/python/okstra_ctl/doctor.py +8 -25
  72. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  73. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  74. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  75. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  76. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  77. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  78. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  79. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  80. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  81. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  82. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  83. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  84. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  85. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  86. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  87. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  88. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  89. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  90. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  91. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  92. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  93. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  94. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  95. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  96. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  97. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  98. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
  99. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  100. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  101. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
  102. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  103. package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
  104. package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
  105. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  106. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  107. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  108. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  109. package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
  110. package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
  111. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  112. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  113. package/runtime/python/okstra_ctl/run.py +24 -1
  114. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  115. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  116. package/runtime/python/okstra_ctl/team.py +3 -1
  117. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  118. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  119. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  120. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  121. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  122. package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
  123. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  124. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  125. package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
  126. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  127. package/runtime/python/okstra_project/__init__.py +2 -0
  128. package/runtime/python/okstra_project/dirs.py +18 -0
  129. package/runtime/python/okstra_project/state.py +25 -20
  130. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  131. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  132. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  133. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  134. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  135. package/runtime/schemas/record-secret-patterns.json +41 -0
  136. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  137. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  138. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  139. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  140. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  141. package/runtime/templates/implementation-worker-preamble.md +4 -9
  142. package/runtime/templates/worker-prompt-preamble.md +4 -12
  143. package/runtime/validators/validate-run.py +17 -8
@@ -13,13 +13,48 @@ prompt through `prepare_agent_invocation()` before `worker-dispatch`.
13
13
 
14
14
  # Coding-conventions preflight (BLOCKING — runs before the first `Edit` / `Write`, and binds the TDD loop)
15
15
 
16
+ When Verification inputs contains a Frozen Review Policy, apply its captured
17
+ sources and architecture declaration instead of live settings and installed
18
+ rules. Read the content through the verification-input projection; original
19
+ paths identify provenance, not permission to replace frozen content. Select the
20
+ applicable language/framework/architecture resources with the router below.
21
+ The captured `review-rules.json` supplies shared rule IDs and grading metadata.
22
+ External rule sources do not authorize posting reviews or spawning agents.
23
+ Use `okstra model-io verification-input --run-manifest <run-manifest>` with one
24
+ `--source-path <repository-relative-path>` per relevant changed file in that
25
+ single call. Its selected bodies are normative; the default available-resource
26
+ index is not proof that language/framework rules were read.
27
+ For applicable rules not established by path/manifest routing, such as embedded
28
+ SQL in an ORM query, add `--resource <pack-relative-id>` in the same call and use
29
+ only resources present in the captured archive.
30
+ For a source-writing assignment, also select `--resource authoring-checks.md`
31
+ when the frozen inventory lists it. Read that captured resource before editing.
32
+ Older captures keep those procedures in `overview.md`; use that captured text.
33
+ For an unfrozen legacy input, read `authoring-checks.md` beside the installed
34
+ overview when present, otherwise retain its older embedded procedures.
35
+
36
+ Use `clean-code.md` "Finding evidence and grading" and the shared catalog for
37
+ severity and timing. Fix current blocking findings before completion. A plan
38
+ placement restriction is a plan conflict, not a waiver of naming, responsibility
39
+ or test-quality rules; propose the conforming placement and preserve acceptance.
40
+ Use `overview.md` policy precedence: explicit repository instructions and declared
41
+ architecture, the common pack, then surrounding code conventions. A surrounding
42
+ pattern alone does not waive an explicit architecture rule.
43
+
44
+ Apply the captured `clean-code.md` "Five simultaneous quality outcomes" before
45
+ editing: correctness, coding principles, performance, safety and security all
46
+ retain their applicable acceptance conditions. Use existing plan, validation and
47
+ result fields for the expected outcomes, bounds and evidence. Missing required
48
+ policy, performance bounds or execution evidence stays explicit and unverified.
49
+ Read complete selected rule sections; never clip normative lines to save context.
50
+
16
51
  Load the applicable coding conventions for every language the diff will touch, then state in ONE line which conventions apply (e.g. `Applying TS + hexagonal overlay; domain at src/domains/*/domain/`). Lint/test green is necessary but NOT sufficient — self-mocked tests, interaction-only assertions, and untruthful names all pass a green pipeline; this gate is what keeps them out of the diff.
17
52
 
18
53
  - **Reuse tests for function changes:** search by function behavior and callers, then read candidate test bodies before editing. Strengthen an existing behavior test; if it already verifies the changed contract, run and retain it. Add a test only when no existing test covers that behavior, preferably in an existing file. Record the function and reused test location or the uncovered outcome. Do not create tests per helper or branch, repeat the same input/outcome, or generate model/provider/task-type combinations without distinct behavior. This rule also applies when routed resources are unavailable. Completion self-check and code review assess the evidence; there is no test-count target.
19
54
 
20
- - **Resource selection — read the routed pack, never inline it here.** Use this worker prompt's `**Coding preflight pack:**` anchor header as the absolute path to the installed routed pack. Detect each touched file's language and framework from its extension or project manifest (`package.json`, `Cargo.toml`, `pyproject.toml`, `pom.xml`, `build.gradle*`, `prisma/schema.prisma`), then read that pack's resources via the Read tool by absolute path. Always read `overview.md` (the router) + `clean-code.md`, then select per the router's three ordered stages — Stage 1 language → `languages/<lang>.md`, Stage 2 framework → `frameworks/<fw>.md` (e.g. `frameworks/node-server.md` for server-side Node), Stage 3 architecture → `architectures/<arch>.md` (e.g. `architectures/hexagonal.md` for ports-and-adapters / NestJS-hex). Each stage is a list of rules; include EVERY matching resource (a change set can touch multiple languages/frameworks/architectures) — do not stop at the first match. These files are runtime resources, not Skill-tool skills, so always read them by path.
21
- - **Project policy projection:** before selecting resources, run `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` (the full `Task key` your dispatch prompt names). Consume its `Architecture style` and `Project Review Rule Packs` sections. Follow the `**Verification inputs:**` declaration-source rule when that header is present; use the named `okstra model-io verification-input --run-manifest <run-manifest>` projection for frozen declarations. The legacy lookup uses the projection's `Project QA Commands` only for an unfrozen baseline. Consume fixed text projections; do not open Okstra-owned JSON storage.
22
- - **Declared architecture style — an authoritative Stage 3 input, and it binds.** A projected `hexagonal` selects `architectures/hexagonal.md` even when none of Stage 3's layout signals matched, so the declaration — not the directory shape — decides. A projected `layered` has no pack resource; its invariant applies from this line: dependencies run one direction only — an upper layer may import a lower one, never the reverse — and a variation point is extracted onto a layer boundary. A declared style makes this overlay binding rather than advisory, and which rule binds follows the style: under `hexagonal` the overlay's otherwise-advisory concrete-adapter item is blocking, so a service dependency you add or modify goes through a port instead of a concrete implementation and that placement violation is fixed before the write rather than recorded as a note; under `layered` what binds is the direction invariant just stated — your own judgement over the import list of every file the diff touches, plus extracting a variation point onto a layer boundary — while the concrete-adapter item stays advisory, since `layered` has no ports to route it through. An absent or `none` projected style leaves Stage 3 detection-driven and its overlay advisory. The verifier re-grades the same diff under the same declaration (`_implementation-verifier.md` → Static design & test-quality review), so a placement violation missed here returns as a verdict `FAIL`.
23
- - **Project review rule packs:** a pack applies when either source names it — the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or the project-context projection lists it as a standing standard. The two sources are a union. Read only those files and the `references/*.md` files they directly name; a declared path that will not open is recorded as `project-review-rules: declared <path> unreadable`, never silently dropped. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
24
- - **Language-agnostic principles that ALWAYS bind (the TDD loop MUST satisfy them):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names — a `get*` / `find*` that writes/inserts, or a name encoding the caller's use-case (`*ForInit`) or hiding a domain rule (`findValid*`), is a defect; (4) single-purpose functions ≤50 effective lines, plain-English readability. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
25
- - **Graceful degradation (codex / antigravity executor runtimes, or any runtime where the resolved coding-preflight pack files are absent or unreadable):** do NOT skip the gate — apply the agnostic principles above plus the project's own `CLAUDE.md` / `CONTRIBUTING` / formatter+lint config, and record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>` in the final report. Never claim a resource read that did not happen.
55
+ - **Resource selection:** use the selected frozen policy above when present. Only legacy inputs without a frozen policy use the `**Coding preflight pack:**` installed path. Read `overview.md` and `clean-code.md`, then select every matching language, framework and architecture resource for the changed files and relevant manifests. Server-side Node includes both JavaScript/TypeScript and Node-server rules. A frozen resource's absence is a blocked input, not permission to substitute live content.
56
+ - **Project policy projection:** a `**Verification inputs:**` declaration supplies the policy and QA baseline through its named projection. Only an unfrozen legacy baseline uses `okstra model-io project-context --project-root <PROJECT_ROOT> --task-ref <TASK_KEY>` and its `Architecture style`, `Project Review Rule Packs` and `Project QA Commands` sections. Consume fixed text projections; do not open Okstra-owned JSON storage.
57
+ - **Declared architecture style — an authoritative Stage 3 input.** A projected `hexagonal` selects `architectures/hexagonal.md` even without layout signals. Apply H1–H6 and the policy precedence above; declaration also makes H5's otherwise-advisory concrete-adapter item binding. A projected `layered` selects no pack resource: dependencies run from upper to lower layers, never in reverse, and variation points sit on layer boundaries; ports are not required. An explicit `none` selects no architecture overlay. Only an 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. The verifier applies the same policy; an established current blocking placement violation returns `FAIL`.
58
+ - **Project 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, read their captured bodies and directly named captured `references/*.md` bodies through the verification-input projection, not live originals. A cited pack or reference missing from that capture is blocked input to report for recapture; do not omit it or substitute live content. Only unfrozen legacy inputs obtain standing standards from project-context and read those declared files and their directly named references; record an unreadable declaration as `project-review-rules: declared <path> unreadable`. Do not search parent directories or host skill catalogs. Apply those rules during implementation as a prevention pass, not a PR-comment generation workflow: do not dispatch reviewer subagents from the executor. For Fonts Ninja-style PR review packs, the executor must avoid newly introduced duplicate helper stacks, tautological tests that merely re-call the delegated helper, self-mocking, domain rules in adapters/ports, domain objects outside `domain/`, dead APIs, weak public names, and functions that fail the plain-English read.
59
+ - **Language-agnostic principles (apply under the policy precedence above):** (1) no self-mocking of the SUT — stub/spy only injected collaborators, never the subject's own methods; (2) behavioral assertions on outcomes (return value, state, persisted rows, events, boundary calls) — never `toHaveBeenCalled*` on an internal helper as the only/primary assertion; (3) truthful names that disclose caller-visible mutations and define business terms; domain-oriented query names alone are not defects when their port contract identifies the domain-owned policy; (4) cohesive responsibility, manageable complexity, consistent abstraction levels and plain-English readability. More than 50 effective lines prompts that review, not an automatic split or failure; record the reason for retaining a cohesive longer function. Self-mocking (1) — Enforced by `validators/detect_self_mock.py` (static), which the implementation **verifier** runs; it is never delegated to the executor (`_implementation-verifier.md` §"Self-mock detection"). Naming the enforcement here says who will check your diff, not that you should run the check: the executor's half is satisfying principle (1) in the code it writes, and it MUST NOT invoke the detector or write `<task_root>/qa/self-mock-*.json`. **Enforced:** that sidecar is not among the paths an executor attempt's `writePolicy.artifactPolicy.allowedPaths` carries, so writing it closes an otherwise-passing stage as `error` with `artifact-root change exceeds batch policy union` (`scripts/okstra_ctl/execution_mutation_audit.py`). The sidecar's absence BLOCKS at `validate-run.py` on the verifier's report.
60
+ - **Legacy graceful degradation:** if no frozen policy exists and installed resources are unreadable, apply the agnostic principles above and the project's local rules, record `coding-conventions: resource-unavailable → applied <project rules + agnostic principles>`, and keep unavailable verification explicit. Do not degrade a readable captured policy merely because its original installation is absent. Never claim an unperformed read.
@@ -12,7 +12,7 @@ from pathlib import Path
12
12
  from pathlib import PurePosixPath
13
13
  import re
14
14
  import tempfile
15
- from typing import Any, Iterator, Literal, Mapping, get_args
15
+ from typing import TYPE_CHECKING, Any, Iterator, Literal, Mapping, get_args
16
16
 
17
17
  from ..domain.role import RoleCatalogError, role_for_duty
18
18
  from ..verification_invocation import (
@@ -26,6 +26,9 @@ from ..json_boundary import (
26
26
  load_owned_object,
27
27
  )
28
28
 
29
+ if TYPE_CHECKING:
30
+ from ..code_review_invocation import CodeReviewInputs
31
+
29
32
 
30
33
  AgentAudience = Literal[
31
34
  "lead",
@@ -190,6 +193,7 @@ class AgentInvocationRequest:
190
193
  # dispatch has used it. See `_publish_or_reuse`.
191
194
  replace_undispatched: bool = False
192
195
  verification_generation: VerificationGenerationReference | None = None
196
+ review_inputs: CodeReviewInputs | None = None
193
197
 
194
198
 
195
199
  @dataclass(frozen=True)
@@ -648,6 +652,9 @@ def prepare_agent_invocation(
648
652
  """Materialize one immutable prompt and its adjacent completion metadata."""
649
653
  request = _bind_generation_request(request)
650
654
  _validate_request(request)
655
+ from ..code_review_invocation import bind_review_invocation
656
+
657
+ request = bind_review_invocation(request)
651
658
  materialized = _materialize(request)
652
659
  if materialized.reservation_root is None:
653
660
  with _exclusive_lock(_prompt_lock_path(request.prompt_path)):
@@ -944,8 +951,9 @@ def publish_standalone_completion(
944
951
  invocation_id=invocation_id,
945
952
  metadata_path=canonical_metadata,
946
953
  )
954
+ review_audit = _complete_standalone_review_audit(project_root, canonical_metadata)
947
955
  completion = {
948
- "schemaVersion": 1,
956
+ "schemaVersion": 2 if review_audit is not None else 1,
949
957
  "purpose": purpose,
950
958
  "invocationId": invocation_id,
951
959
  "status": "completed",
@@ -962,10 +970,34 @@ def publish_standalone_completion(
962
970
  "resultEnvelopeDigest": _sha256(envelope_bytes),
963
971
  "completedAt": completed,
964
972
  }
973
+ if review_audit is not None:
974
+ completion["reviewAuditDigest"] = review_audit
965
975
  _publish_exclusive(completion_path, _canonical_json(completion))
966
976
  return completion_path
967
977
 
968
978
 
979
+ def _complete_standalone_review_audit(project_root: Path, metadata_path: Path) -> str | None:
980
+ from ..code_review_invocation import complete_review_audit
981
+
982
+ try:
983
+ return complete_review_audit(
984
+ project_root, metadata_path,
985
+ _load_json_object(metadata_path, "agent invocation metadata"),
986
+ )
987
+ except (OSError, ValueError, KeyError) as exc:
988
+ raise AgentInvocationError(f"standalone review integrity failed: {exc}") from exc
989
+
990
+
991
+ @dataclass(frozen=True)
992
+ class _StandaloneCompletion:
993
+ payload: Mapping[str, Any]
994
+ invocation_id: str
995
+ root: Path
996
+ metadata_path: Path
997
+ result_path: Path
998
+ completion_path: Path
999
+
1000
+
969
1001
  def verify_standalone_completion(
970
1002
  completion_path: Path,
971
1003
  *,
@@ -973,6 +1005,49 @@ def verify_standalone_completion(
973
1005
  expected_purpose: str,
974
1006
  ) -> VerifiedStandaloneResult:
975
1007
  """Verify a completion marker and return its already-read immutable body."""
1008
+ context = _read_standalone_completion(completion_path, project_root, expected_purpose)
1009
+ with _exclusive_lock(context.root / f"{context.invocation_id}.result.publish.lock"):
1010
+ authority_id, _authority_root, canonical_metadata = _standalone_authority(
1011
+ project_root=project_root,
1012
+ purpose=expected_purpose,
1013
+ metadata_path=context.metadata_path,
1014
+ )
1015
+ if authority_id != context.invocation_id:
1016
+ raise AgentInvocationError("standalone completion identity does not match")
1017
+ envelope_bytes, returned_body = _verified_result_envelope(
1018
+ context.result_path,
1019
+ project_root=project_root,
1020
+ purpose=expected_purpose,
1021
+ invocation_id=context.invocation_id,
1022
+ metadata_path=canonical_metadata,
1023
+ )
1024
+ digest = _sha256(envelope_bytes)
1025
+ if context.payload.get("resultEnvelopeDigest") != digest:
1026
+ raise AgentInvocationError("result envelope digest does not match completion")
1027
+ from ..code_review_invocation import verify_review_completion
1028
+
1029
+ try:
1030
+ verify_review_completion(
1031
+ project_root, canonical_metadata,
1032
+ _load_json_object(canonical_metadata, "agent invocation metadata"),
1033
+ context.payload,
1034
+ )
1035
+ except (OSError, ValueError, KeyError) as exc:
1036
+ raise AgentInvocationError(f"standalone review integrity is invalid: {exc}") from exc
1037
+ return VerifiedStandaloneResult(
1038
+ purpose=expected_purpose,
1039
+ invocation_id=context.invocation_id,
1040
+ prompt_metadata_path=context.metadata_path,
1041
+ result_path=context.result_path,
1042
+ completion_path=context.completion_path,
1043
+ result_envelope_digest=digest,
1044
+ returned_body=returned_body,
1045
+ )
1046
+
1047
+
1048
+ def _read_standalone_completion(
1049
+ completion_path: Path, project_root: Path, expected_purpose: str,
1050
+ ) -> _StandaloneCompletion:
976
1051
  _validate_slug(expected_purpose, "standalone purpose")
977
1052
  completion = _load_json_object(completion_path, "standalone completion")
978
1053
  expected_keys = {
@@ -985,7 +1060,9 @@ def verify_standalone_completion(
985
1060
  "resultEnvelopeDigest",
986
1061
  "completedAt",
987
1062
  }
988
- if set(completion) != expected_keys or completion.get("schemaVersion") != 1:
1063
+ if completion.get("schemaVersion") == 2:
1064
+ expected_keys.add("reviewAuditDigest")
1065
+ if set(completion) != expected_keys or completion.get("schemaVersion") not in (1, 2):
989
1066
  raise AgentInvocationError("standalone completion schema is invalid")
990
1067
  if completion.get("purpose") != expected_purpose:
991
1068
  raise AgentInvocationError("standalone completion purpose does not match")
@@ -1013,32 +1090,8 @@ def verify_standalone_completion(
1013
1090
  must_exist=True,
1014
1091
  ):
1015
1092
  raise AgentInvocationError("standalone completion result path does not match")
1016
- with _exclusive_lock(root / f"{invocation_id}.result.publish.lock"):
1017
- authority_id, _authority_root, canonical_metadata = _standalone_authority(
1018
- project_root=project_root,
1019
- purpose=expected_purpose,
1020
- metadata_path=metadata_path,
1021
- )
1022
- if authority_id != invocation_id:
1023
- raise AgentInvocationError("standalone completion identity does not match")
1024
- envelope_bytes, returned_body = _verified_result_envelope(
1025
- result_path,
1026
- project_root=project_root,
1027
- purpose=expected_purpose,
1028
- invocation_id=invocation_id,
1029
- metadata_path=canonical_metadata,
1030
- )
1031
- digest = _sha256(envelope_bytes)
1032
- if completion.get("resultEnvelopeDigest") != digest:
1033
- raise AgentInvocationError("result envelope digest does not match completion")
1034
- return VerifiedStandaloneResult(
1035
- purpose=expected_purpose,
1036
- invocation_id=invocation_id,
1037
- prompt_metadata_path=metadata_path,
1038
- result_path=result_path,
1039
- completion_path=canonical_completion,
1040
- result_envelope_digest=digest,
1041
- returned_body=returned_body,
1093
+ return _StandaloneCompletion(
1094
+ completion, invocation_id, root, metadata_path, result_path, canonical_completion,
1042
1095
  )
1043
1096
 
1044
1097
 
@@ -1090,6 +1143,8 @@ def _verified_result_envelope(
1090
1143
  invocation_id: str,
1091
1144
  metadata_path: Path,
1092
1145
  ) -> tuple[bytes, str]:
1146
+ project_root = project_root.resolve(strict=True)
1147
+ result_path = result_path.parent.resolve(strict=True) / result_path.name
1093
1148
  try:
1094
1149
  body = result_path.read_bytes()
1095
1150
  envelope = load_external_json(
@@ -1184,11 +1239,30 @@ def _bind_generation_request(request: AgentInvocationRequest) -> AgentInvocation
1184
1239
  try:
1185
1240
  manifest = _load_request_manifest(request)
1186
1241
  reference = _typed_generation_reference(request)
1187
- _require_sealed_generation(
1242
+ generation = read_invocation_generation(
1188
1243
  request.project_root, request.run_manifest_path, manifest,
1189
1244
  reference, request.audience,
1190
1245
  )
1191
- return _with_generation_anchors(request, reference)
1246
+ bound = _with_generation_anchors(request, reference)
1247
+ if generation is not None and "designReview" in generation:
1248
+ from ..design_review import render_design_review
1249
+
1250
+ supplement = render_design_review(generation["designReview"])
1251
+ from ..design_review_evidence import prior_design_review_prompt
1252
+
1253
+ supplement += prior_design_review_prompt(
1254
+ request.project_root, request.run_manifest_path,
1255
+ request.role_execution_ref, generation["generation"],
1256
+ request.invocation_ref, request.attempt,
1257
+ )
1258
+ body = bound.instruction.body
1259
+ if not body.rstrip().endswith(supplement.rstrip()):
1260
+ if "\n## Frozen Design Review\n" in body:
1261
+ raise ValueError("design review body differs from sealed generation")
1262
+ bound = replace(bound, instruction=replace(
1263
+ bound.instruction, body=body.rstrip() + "\n" + supplement,
1264
+ ))
1265
+ return bound
1192
1266
  except (OSError, ValueError) as exc:
1193
1267
  raise AgentInvocationError(str(exc)) from exc
1194
1268
 
@@ -1973,6 +2047,9 @@ def _verify_prompt_file(
1973
2047
  errors.extend(_verify_model_header(metadata, body))
1974
2048
  errors.extend(_verify_execution_delivery(metadata, path, body))
1975
2049
  errors.extend(_verify_generation_reference(metadata, project_root, body))
2050
+ from ..code_review_invocation import review_policy_errors_for_prompt
2051
+
2052
+ errors.extend(review_policy_errors_for_prompt(project_root, metadata, body))
1976
2053
  return errors
1977
2054
 
1978
2055
 
@@ -2010,6 +2087,16 @@ def reserved_generation_reference(
2010
2087
  The reservation names the metadata, so a reader does not take a generation
2011
2088
  file on the strength of the path its dispatch kind computes.
2012
2089
  """
2090
+ metadata_path = reserved_invocation_metadata_path(project_root, manifest, invocation_ref, attempt)
2091
+ if metadata_path is None:
2092
+ return None
2093
+ metadata = _load_json_object(metadata_path, "agent invocation metadata")
2094
+ return metadata_generation_reference(metadata)
2095
+
2096
+
2097
+ def reserved_invocation_metadata_path(
2098
+ project_root: Path, manifest: Mapping[str, object], invocation_ref: str, attempt: int,
2099
+ ) -> Path | None:
2013
2100
  contract = manifest.get("agentContract")
2014
2101
  if not isinstance(contract, Mapping):
2015
2102
  return None
@@ -2020,17 +2107,15 @@ def reserved_generation_reference(
2020
2107
  if not path.is_file():
2021
2108
  return None
2022
2109
  reservation = _load_json_object(path, "invocation reservation")
2023
- metadata = _load_json_object(
2024
- _project_path(project_root, reservation.get("metadataPath"), must_exist=True),
2025
- "agent invocation metadata",
2026
- )
2110
+ metadata_path = _project_path(project_root, reservation.get("metadataPath"), must_exist=True)
2111
+ metadata = _load_json_object(metadata_path, "agent invocation metadata")
2027
2112
  for payload in (reservation, metadata):
2028
2113
  if (payload.get("invocationRef"), payload.get("attempt")) != (
2029
2114
  invocation_ref, attempt):
2030
2115
  raise AgentInvocationError(
2031
2116
  f"invocation reservation {path} names another invocation attempt"
2032
2117
  )
2033
- return metadata_generation_reference(metadata)
2118
+ return metadata_path
2034
2119
 
2035
2120
 
2036
2121
  def _attempt_invocation_id(invocation_ref: str, attempt: int) -> str:
@@ -129,6 +129,12 @@ def _add_materialize_parser(commands: argparse._SubParsersAction) -> None:
129
129
  materialize.add_argument("--model-role", help=standalone_only)
130
130
  materialize.add_argument("--model", default="", help=standalone_only)
131
131
  materialize.add_argument("--purpose", help=standalone_only)
132
+ materialize.add_argument("--review-policy", help=standalone_only + "; frozen shared code-review policy")
133
+ materialize.add_argument("--review-census", help=standalone_only + "; assigned code-review census")
134
+ materialize.add_argument("--review-base", help=standalone_only + "; fixed review base")
135
+ materialize.add_argument("--review-head", help=standalone_only + "; fixed review head")
136
+ materialize.add_argument("--review-resource", action="append", default=[],
137
+ help=standalone_only + "; additional frozen pack-relative resource")
132
138
  materialize.add_argument(
133
139
  "--replace-undispatched",
134
140
  action="store_true",
@@ -32,6 +32,7 @@ from ..invocation import (
32
32
  )
33
33
  from ...assignment_environment import load_assignment_context
34
34
  from ..standalone import StandaloneInvocationRequest, prepare_standalone_invocation
35
+ from ...code_review_invocation import CodeReviewInputs
35
36
  from ...path_hints import hydrate_active_run_context
36
37
  from ...worker_prompt_headers import worker_prompt_headers
37
38
  from ...worker_prompt_contract import (
@@ -134,6 +135,9 @@ def _materialize_run(
134
135
  "model-role": args.model_role,
135
136
  "model": args.model,
136
137
  "purpose": args.purpose,
138
+ **{f"review-{name}": getattr(args, f"review_{name}", None)
139
+ for name in ("policy", "census", "base", "head")},
140
+ "review-resource": getattr(args, "review_resource", ()),
137
141
  }
138
142
  present = [name for name, value in forbidden.items() if value]
139
143
  if present:
@@ -922,10 +926,9 @@ def _roster_result_path(
922
926
  return None
923
927
 
924
928
 
925
- def _materialize_standalone(
926
- args: argparse.Namespace,
927
- project_root: Path,
928
- ) -> PreparedAgentInvocation:
929
+ def _standalone_input_paths(
930
+ args: argparse.Namespace, project_root: Path,
931
+ ) -> tuple[Path, Path]:
929
932
  required = {
930
933
  "host-runtime": args.host_runtime,
931
934
  "provider": args.provider,
@@ -967,15 +970,38 @@ def _materialize_standalone(
967
970
  expected_prompt = root / f"{args.invocation_id}.prompt.md"
968
971
  instruction_path = _exact_path(args.instruction, expected_instruction, True, "instruction")
969
972
  prompt_path = _exact_path(args.prompt, expected_prompt, False, "prompt")
973
+ return instruction_path, prompt_path
974
+
975
+
976
+ def _materialize_standalone(
977
+ args: argparse.Namespace,
978
+ project_root: Path,
979
+ ) -> PreparedAgentInvocation:
980
+ instruction_path, prompt_path = _standalone_input_paths(args, project_root)
970
981
  assignment_context = load_assignment_context(
971
982
  host_runtime=args.host_runtime,
972
983
  terminal_backend=args.terminal_backend or detect_terminal_backend(),
973
984
  execution_provider_ids=(args.provider,),
974
985
  include_native_provider=False,
975
986
  )
987
+ review_values = [getattr(args, f"review_{name}", None)
988
+ for name in ("policy", "census", "base", "head")]
989
+ review_inputs = None
990
+ if args.audience == "code-reviewer" or any(review_values):
991
+ if args.audience != "code-reviewer" or not all(review_values):
992
+ raise AgentPromptCliError(
993
+ "code-reviewer requires --review-policy, --review-census, --review-base and --review-head"
994
+ )
995
+ review_inputs = CodeReviewInputs(
996
+ _project_input(project_root, args.review_policy, "review policy"),
997
+ _project_input(project_root, args.review_census, "review census"),
998
+ args.review_base, args.review_head,
999
+ tuple(getattr(args, "review_resource", ())),
1000
+ )
976
1001
  return prepare_standalone_invocation(StandaloneInvocationRequest(
977
1002
  project_root=project_root, invocation_id=args.invocation_id, audience=args.audience,
978
1003
  purpose=args.purpose, context=assignment_context, provider=args.provider,
979
1004
  model_role=args.model_role, model=args.model, instruction_path=instruction_path,
980
1005
  prompt_path=prompt_path, requested_runner=args.execution_runner,
1006
+ review_inputs=review_inputs,
981
1007
  ))
@@ -7,6 +7,7 @@ from dataclasses import dataclass
7
7
  from pathlib import Path
8
8
 
9
9
  from ..assignment_resolver import AssignmentContext, resolve_dispatch_assignment
10
+ from ..code_review_invocation import CodeReviewInputs
10
11
  from .invocation import (
11
12
  AgentAudience,
12
13
  AgentInstruction,
@@ -33,6 +34,7 @@ class StandaloneInvocationRequest:
33
34
  instruction_path: Path
34
35
  prompt_path: Path
35
36
  requested_runner: str | None = None
37
+ review_inputs: CodeReviewInputs | None = None
36
38
 
37
39
 
38
40
  def prepare_standalone_invocation(
@@ -83,6 +85,7 @@ def prepare_standalone_invocation(
83
85
  duty_id=None,
84
86
  invocation_ref=None,
85
87
  attempt=1,
88
+ review_inputs=request.review_inputs,
86
89
  )
87
90
  )
88
91
 
@@ -5,6 +5,8 @@ import hashlib
5
5
  import re
6
6
  from pathlib import Path
7
7
 
8
+ from okstra_project.dirs import contained_relative_path as project_relative_ref
9
+
8
10
  from . import group_context
9
11
 
10
12
 
@@ -575,25 +577,6 @@ def exceeds_cited_document_limit(size: int) -> bool:
575
577
  return size > MAX_CITED_DOCUMENT_BYTES
576
578
 
577
579
 
578
- def project_relative_ref(ref: str, root: Path) -> str | None:
579
- """The posix path of a Source Material `ref` relative to the resolved `root`.
580
-
581
- None when the ref resolves outside the root, or names the home directory of
582
- a user this machine does not know (`~200` in prose). Every reader and
583
- writer of a `### Source N — file` ref goes through here so they agree on
584
- which file it names.
585
- """
586
- try:
587
- candidate = Path(ref).expanduser()
588
- except RuntimeError:
589
- return None
590
- path = (candidate if candidate.is_absolute() else root / candidate).resolve()
591
- try:
592
- return path.relative_to(root).as_posix()
593
- except ValueError:
594
- return None
595
-
596
-
597
580
  def _by_reference_file_refs(source_material: str) -> list[str]:
598
581
  refs = [ref for ref, fmt in file_source_entries(source_material) if fmt == BY_REFERENCE_FORMAT]
599
582
  return list(dict.fromkeys(refs))
@@ -21,6 +21,7 @@ from .convergence_store import write_json_atomic
21
21
  from .final_report_schema import load_schema_version
22
22
  from .json_boundary import JsonBoundaryError, load_owned_object
23
23
  from .report_contract import CURRENT_REPORT_SCHEMA_VERSION
24
+ from .report_prose_keys import NULL_LITERALS
24
25
 
25
26
 
26
27
  @lru_cache(maxsize=None)
@@ -73,6 +74,19 @@ def _required(value: str, field: str) -> str:
73
74
  return value.strip()
74
75
 
75
76
 
77
+ def _refuse_null_literal(value: str, field: str) -> None:
78
+ """Refuse a stringified null in an impact field and name the `none` token.
79
+
80
+ Report assembly copies the ledger row into the published report
81
+ unchanged, and `validate-run` sees the value only after publication, so
82
+ the ledger write is where the author can still replace it."""
83
+ if value.strip() in NULL_LITERALS:
84
+ raise ApprovalDecisionError(
85
+ f"{field} holds the null literal {value.strip()!r}; write `none` when "
86
+ "the option adds no work or reverses nothing"
87
+ )
88
+
89
+
76
90
  @dataclass(frozen=True)
77
91
  class DecisionOption:
78
92
  role: str
@@ -89,6 +103,8 @@ class DecisionOption:
89
103
  raise ApprovalDecisionError(f"invalid option role: {self.role}")
90
104
  for field in ("answer", "rationale", "added_work", "direction_change"):
91
105
  _required(getattr(self, field), field)
106
+ for field in ("added_work", "direction_change"):
107
+ _refuse_null_literal(getattr(self, field), field)
92
108
  if self.disposition not in DISPOSITIONS:
93
109
  raise ApprovalDecisionError(f"invalid disposition: {self.disposition}")
94
110
  if self.reach not in REACHES:
@@ -164,6 +164,16 @@ def _stream_payload(path: Path) -> dict[str, Any]:
164
164
  }
165
165
 
166
166
 
167
+ def read_sealed_artifact(seal: AttemptEvidenceSeal, path: Path) -> bytes:
168
+ row = next((row for row in seal.artifacts if row.get("normalizedPath") == str(path)), None)
169
+ if row is None or path.is_symlink() or not path.is_file():
170
+ raise AttemptEvidenceError(f"artifact is absent from the attempt seal: {path}")
171
+ data = path.read_bytes()
172
+ if len(data) != row.get("byteLength") or _sha(data) != row.get("sha256"):
173
+ raise AttemptEvidenceError(f"sealed artifact bytes changed: {path}")
174
+ return data
175
+
176
+
167
177
  def _build_seal(
168
178
  attempt_ref: str, terminal: TerminalObservation
169
179
  ) -> AttemptEvidenceSeal:
@@ -24,8 +24,13 @@ from ..registry.provider_registry import default_provider_registry
24
24
  from ..worker_request import build_request
25
25
  from ..worker_runner import QUIET, run_worker
26
26
  from ..write_policy import build_write_policy, derive_write_enforcement
27
+ from ..wrapper_status import WrapperStatus, read_log_tail, read_wrapper_status
27
28
  from .contracts import OPERATION, BusinessFlowError, FlowRequest
28
29
 
30
+ # The message lands in the execution record's `error` field, so it carries
31
+ # the CLI's last lines rather than its whole transcript.
32
+ _EXIT_LOG_TAIL_BYTES = 800
33
+
29
34
 
30
35
  @dataclass(frozen=True)
31
36
  class PreparedCall:
@@ -111,14 +116,16 @@ class ProviderFlowExecutor:
111
116
  pool = ModelPool.from_registry(registry)
112
117
  selected = pool.resolve_alias(assignment["provider"], assignment["model"])
113
118
  request = _read_only_worker_request(call, assignment)
119
+ log_path = call.prompt_path.with_suffix(".log")
120
+ status_path = call.prompt_path.with_suffix(".status.json")
114
121
  output, errors = io.StringIO(), io.StringIO()
115
122
  with contextlib.redirect_stdout(output), contextlib.redirect_stderr(errors):
116
123
  code = run_worker(
117
124
  provider.exec_strategy,
118
125
  request,
119
126
  presentation=QUIET,
120
- log_path=call.prompt_path.with_suffix(".log"),
121
- status_path=call.prompt_path.with_suffix(".status.json"),
127
+ log_path=log_path,
128
+ status_path=status_path,
122
129
  status_extra={
123
130
  "writePolicy": request.policy.write_policy.to_payload(),
124
131
  "writeEnforcement": request.policy.write_enforcement.to_payload(),
@@ -130,11 +137,36 @@ class ProviderFlowExecutor:
130
137
  )
131
138
  if code:
132
139
  raise BusinessFlowError(
133
- f"business investigator exited {code}: {errors.getvalue().strip()}"
140
+ f"business investigator exited {code}: "
141
+ + _exit_cause(errors.getvalue(), status_path, log_path)
134
142
  )
135
143
  return output.getvalue().encode("utf-8")
136
144
 
137
145
 
146
+ def _exit_cause(stderr: str, status_path: Path, log_path: Path) -> str:
147
+ """run_worker writes the CLI's own output to the log, not to this
148
+ process's stderr, so the cause is read back from the status sidecar and
149
+ the log tail, with the log path for the rest."""
150
+ status = read_wrapper_status(status_path)
151
+ parts = (
152
+ stderr.strip(),
153
+ _sidecar_cause(status) if status is not None else "",
154
+ read_log_tail(log_path, _EXIT_LOG_TAIL_BYTES) or "",
155
+ f"log: {log_path}",
156
+ )
157
+ return "; ".join(part for part in parts if part)
158
+
159
+
160
+ def _sidecar_cause(status: WrapperStatus) -> str:
161
+ """An idle-watchdog kill records `timeout` and `idle_seconds` but no
162
+ `failure` (worker_runner.run_worker), so it is named separately."""
163
+ if not status.timeout:
164
+ return status.failure
165
+ idle = status.raw.get("idle_seconds")
166
+ timeout = f"idle timeout after {idle}s" if isinstance(idle, int) else "idle timeout"
167
+ return "; ".join(part for part in (status.failure, timeout) if part)
168
+
169
+
138
170
  def _read_only_worker_request(
139
171
  call: PreparedCall, assignment: dict[str, str]
140
172
  ) -> WorkerExecRequest: