okstra 0.231.1 → 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 (126) hide show
  1. package/README.md +12 -0
  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 +127 -0
  20. package/docs/architecture.md +7 -0
  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/profiles/_coding-conventions-preflight.md +41 -6
  43. package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
  44. package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
  45. package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
  46. package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
  47. package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
  48. package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
  49. package/runtime/python/okstra_ctl/code_review_census.py +71 -7
  50. package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
  51. package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
  52. package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
  53. package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
  54. package/runtime/python/okstra_ctl/code_review_target.py +85 -11
  55. package/runtime/python/okstra_ctl/consumers.py +12 -9
  56. package/runtime/python/okstra_ctl/design_review.py +207 -0
  57. package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
  58. package/runtime/python/okstra_ctl/doctor.py +8 -25
  59. package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
  60. package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
  61. package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
  62. package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
  63. package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
  64. package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
  65. package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
  66. package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
  67. package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
  68. package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
  69. package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
  70. package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
  71. package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
  72. package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
  73. package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
  74. package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
  75. package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
  76. package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
  77. package/runtime/python/okstra_ctl/json_boundary.py +21 -2
  78. package/runtime/python/okstra_ctl/jsonl.py +21 -0
  79. package/runtime/python/okstra_ctl/manager_cli.py +26 -0
  80. package/runtime/python/okstra_ctl/manager_registration.py +29 -0
  81. package/runtime/python/okstra_ctl/manager_sync.py +3 -22
  82. package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
  83. package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
  84. package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
  85. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +10 -0
  86. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
  87. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
  88. package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +38 -10
  89. package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
  90. package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
  91. package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
  92. package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
  93. package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
  94. package/runtime/python/okstra_ctl/report_assembly.py +15 -0
  95. package/runtime/python/okstra_ctl/report_narrative.py +3 -0
  96. package/runtime/python/okstra_ctl/report_synthesis_packet.py +11 -2
  97. package/runtime/python/okstra_ctl/review_policy.py +359 -0
  98. package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
  99. package/runtime/python/okstra_ctl/run.py +24 -1
  100. package/runtime/python/okstra_ctl/stage_done.py +11 -0
  101. package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
  102. package/runtime/python/okstra_ctl/verification_generation.py +23 -1
  103. package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
  104. package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
  105. package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
  106. package/runtime/python/okstra_ctl/verification_target.py +2 -0
  107. package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
  108. package/runtime/python/okstra_ctl/worker_runner.py +66 -10
  109. package/runtime/python/okstra_ctl/write_policy.py +34 -1
  110. package/runtime/python/okstra_project/__init__.py +2 -0
  111. package/runtime/python/okstra_project/dirs.py +18 -0
  112. package/runtime/python/okstra_project/state.py +25 -20
  113. package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
  114. package/runtime/schemas/doyouknow-v1.schema.json +65 -0
  115. package/runtime/schemas/final-report-v2.0.schema.json +157 -0
  116. package/runtime/schemas/final-report-v3.0.schema.json +157 -0
  117. package/runtime/schemas/memory-entry-contract-v1.json +11 -0
  118. package/runtime/schemas/record-secret-patterns.json +41 -0
  119. package/runtime/skills/okstra-code-review/SKILL.md +71 -123
  120. package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
  121. package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
  122. package/runtime/skills/okstra-manager/SKILL.md +7 -0
  123. package/runtime/skills/okstra-memory/SKILL.md +7 -0
  124. package/runtime/templates/implementation-worker-preamble.md +4 -9
  125. package/runtime/templates/worker-prompt-preamble.md +4 -12
  126. package/runtime/validators/validate-run.py +14 -2
@@ -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
@@ -428,6 +428,12 @@ def validate_verifier_execution_evidence(
428
428
  attempt of the invocation bound to the newest generation, with the bytes and
429
429
  observation it recorded; a `not-run` row is not read.
430
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}")
431
437
  try:
432
438
  evidence = collect_report_evidence(project_root, manifest_path)
433
439
  except ValueError as exc:
@@ -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**: a pack applies when either source names it — the task brief's `Source Material` / `Reporter Confirmations` cites its exact `SKILL.md` path, or `<PROJECT_ROOT>/.okstra/project.json` lists it under `reviewRulePacks` (the project's standing standard, applying whether or not the brief mentions it). The two sources are a union. Read only those files and the `references/*.md` files they directly name. Do not search parent directories or host skill catalogs. Do not run the PR-review workflow here; extract only the rules. For Fonts Ninja-style TS/NestJS review packs, this means planning away known review findings before code exists: shared transforms instead of duplicate helper stacks, behavioral tests instead of collaborator-tautology assertions, domain rules in domain modules rather than repositories/adapters, domain objects under `domain/`, plain-English functions, truthful/specific names, and no dead APIs introduced by the plan.
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)
@@ -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,7 +266,7 @@ 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 "
@@ -273,7 +282,7 @@ class ReportSynthesisPacket:
273
282
  "verdict as an unresolved divergence.",
274
283
  ]
275
284
  if self.task_type != "implementation-option-selection":
276
- return []
285
+ return [design_note] if design_note else []
277
286
  return selection_requirement_instructions(
278
287
  self.original_requirement_ids, self.participating_analysers,
279
288
  )
@@ -0,0 +1,359 @@
1
+ from __future__ import annotations
2
+
3
+ import re
4
+ import json
5
+ from pathlib import Path, PurePosixPath
6
+ from typing import Mapping, Sequence, cast
7
+
8
+ from .json_boundary import load_owned_object
9
+ from .qa_procedures import canonical_json_digest, content_digest
10
+ from .qa_commands import QA_SOURCE_DIGEST_PATTERN, qa_relative_path_valid
11
+ from .paths import find_asset_root
12
+ from .verification_input_types import FrozenProcedure, FrozenReviewPolicy
13
+
14
+
15
+ def capture_review_policy(
16
+ project: Path, config: Mapping[str, object], *, additional_sources: Sequence[Path] = (),
17
+ ) -> FrozenReviewPolicy:
18
+ architecture = config.get("architecture", {})
19
+ if not isinstance(architecture, dict):
20
+ raise ValueError("review policy: architecture must be an object")
21
+ style = architecture.get("style", "undeclared")
22
+ if style not in ("undeclared", "none", "layered", "hexagonal"):
23
+ raise ValueError("review policy: invalid architecture style")
24
+ declared = config.get("reviewRulePacks", [])
25
+ if not isinstance(declared, list):
26
+ raise ValueError("review policy: reviewRulePacks must be a list")
27
+ paths = [project / name for name in ("AGENTS.md", "CLAUDE.md")
28
+ if (project / name).exists()]
29
+ paths.extend(additional_sources)
30
+ for entry in declared:
31
+ if not isinstance(entry, str) or not entry.strip():
32
+ raise ValueError("review policy: rule path must be a non-blank string")
33
+ path = Path(entry).expanduser()
34
+ if not path.is_absolute():
35
+ raise ValueError("review policy: rule path must be absolute")
36
+ paths.append(path)
37
+ sources: dict[str, FrozenProcedure] = {}
38
+ for path in dict.fromkeys(paths):
39
+ _capture_rule_source(path, sources)
40
+ root = find_asset_root(("prompts", "coding-preflight", "review-rules.json"))
41
+ if root is None:
42
+ raise ValueError("review policy: coding preflight catalog is unavailable")
43
+ pack = root / "prompts" / "coding-preflight"
44
+ for path in sorted(pack.rglob("*.md")):
45
+ _capture_rule_source(path, sources)
46
+ _capture_rule_source(pack / "review-rules.json", sources)
47
+ return {"schemaVersion": "1.0", "architecture": style, "sources": sources}
48
+
49
+
50
+ def _capture_rule_source(path: Path, sources: dict[str, FrozenProcedure]) -> None:
51
+ identity = str(path.absolute())
52
+ if identity in sources:
53
+ return
54
+ try:
55
+ raw = path.read_bytes()
56
+ body = raw.decode("utf-8")
57
+ except (OSError, UnicodeError) as exc:
58
+ raise ValueError(f"review policy: cannot read {path}: {exc}") from exc
59
+ sources[identity] = {"body": body, "digest": content_digest(raw)}
60
+ for reference in re.findall(r"\]\((references/[^)\s#]+\.md)(?:#[^)]*)?\)", body):
61
+ relative = Path(reference)
62
+ if ".." in relative.parts:
63
+ raise ValueError(f"review policy: reference escapes rule directory: {reference}")
64
+ _capture_rule_source(path.parent / relative, sources)
65
+
66
+
67
+ def review_policy_errors(policy: object) -> list[str]:
68
+ required = {"schemaVersion", "architecture", "sources"}
69
+ if (not isinstance(policy, dict) or not required.issubset(policy)
70
+ or set(policy).difference(required | {"authorPolicyDigest"})):
71
+ return ["review policy: invalid fields"]
72
+ if "authorPolicyDigest" in policy and (
73
+ not isinstance(policy["authorPolicyDigest"], str)
74
+ or not QA_SOURCE_DIGEST_PATTERN.fullmatch(policy["authorPolicyDigest"])):
75
+ return ["review policy: invalid author policy digest"]
76
+ if policy["schemaVersion"] != "1.0":
77
+ return ["review policy: unsupported version"]
78
+ if policy["architecture"] not in ("undeclared", "none", "layered", "hexagonal"):
79
+ return ["review policy: invalid architecture style"]
80
+ sources = policy["sources"]
81
+ if not isinstance(sources, dict):
82
+ return ["review policy: sources must be an object"]
83
+ for path, source in sources.items():
84
+ if not isinstance(path, str) or not Path(path).is_absolute():
85
+ return ["review policy: source path must be absolute"]
86
+ if (not isinstance(source, dict) or set(source) != {"body", "digest"}
87
+ or not isinstance(source["body"], str)):
88
+ return ["review policy: invalid source"]
89
+ if content_digest(source["body"].encode("utf-8")) != source["digest"]:
90
+ return [f"review policy: source digest mismatch: {path}"]
91
+ return []
92
+
93
+
94
+ def read_review_policy(path: Path) -> FrozenReviewPolicy:
95
+ return cast(FrozenReviewPolicy, load_owned_object(
96
+ path, artifact="frozen review policy", schema={"type": "object"},
97
+ validate_cross_fields=review_policy_errors,
98
+ ))
99
+
100
+
101
+ def publish_review_policy(
102
+ project: Path, destination: Path, policy: FrozenReviewPolicy,
103
+ ) -> tuple[Path, str]:
104
+ from .verification_inputs import publish_verification_snapshot
105
+
106
+ return publish_verification_snapshot(
107
+ project, destination, capture=lambda: dict(policy), artifact="frozen review policy",
108
+ schema={"type": "object"}, validate_cross_fields=review_policy_errors,
109
+ comparison_key=dict,
110
+ )
111
+
112
+
113
+ def code_review_guidance_paths(policy: FrozenReviewPolicy) -> tuple[str, ...]:
114
+ paths: list[str] = []
115
+ for source in policy["sources"]:
116
+ if source.endswith("/skills/okstra-code-review/SKILL.md"):
117
+ folder = Path(source).parent
118
+ paths.extend(str(path) for path in (
119
+ folder / "SKILL.md", folder / "references/census-rules.md",
120
+ folder / "references/review-calibration.md",
121
+ ) if str(path) in policy["sources"])
122
+ return tuple(paths)
123
+
124
+
125
+ def capture_code_review_policy(
126
+ project: Path, config: Mapping[str, object], *,
127
+ additional_sources: Sequence[Path] = (), policy: FrozenReviewPolicy | None = None,
128
+ ) -> FrozenReviewPolicy:
129
+ root = find_asset_root(("skills", "okstra-code-review", "SKILL.md"))
130
+ skill = ((root / "skills/okstra-code-review") if root
131
+ else Path.home() / ".agents/skills/okstra-code-review")
132
+ sources = (skill / "SKILL.md", skill / "references/census-rules.md",
133
+ skill / "references/review-calibration.md", *additional_sources)
134
+ if policy is None:
135
+ policy = capture_review_policy(project, config)
136
+ errors = review_policy_errors(policy)
137
+ if errors:
138
+ raise ValueError("; ".join(errors))
139
+ captured = {path: dict(source) for path, source in policy["sources"].items()}
140
+ for source in sources:
141
+ _capture_rule_source(source, captured)
142
+ return {"schemaVersion": policy["schemaVersion"], "architecture": policy["architecture"],
143
+ "sources": captured, "authorPolicyDigest": canonical_json_digest(policy)}
144
+
145
+
146
+ def render_review_rule_catalog(policy: FrozenReviewPolicy) -> str:
147
+ from .code_review_census import render_rule_catalog
148
+
149
+ path = review_policy_catalog_path(policy)
150
+ root = str(path.parent)
151
+ catalog = policy["sources"][str(path)]
152
+ return render_rule_catalog(
153
+ catalog["body"], Path(root),
154
+ include_architecture=root + "/architectures/hexagonal.md" in policy["sources"],
155
+ )
156
+
157
+
158
+ _LANGUAGE_SUFFIXES = {
159
+ ".js": "javascript-typescript", ".jsx": "javascript-typescript",
160
+ ".ts": "javascript-typescript", ".tsx": "javascript-typescript",
161
+ ".mjs": "javascript-typescript", ".cjs": "javascript-typescript",
162
+ ".mts": "javascript-typescript", ".cts": "javascript-typescript",
163
+ ".py": "python", ".rs": "rust", ".java": "java",
164
+ ".kt": "kotlin", ".kts": "kotlin", ".sql": "sql",
165
+ }
166
+ _LANGUAGE_MANIFESTS = {
167
+ "package.json": "javascript-typescript", "pyproject.toml": "python",
168
+ "requirements.txt": "python", "setup.py": "python", "setup.cfg": "python",
169
+ "Cargo.toml": "rust", "pom.xml": "java", "build.gradle": "java",
170
+ "build.gradle.kts": "kotlin",
171
+ }
172
+
173
+
174
+ def review_policy_catalog_path(policy: FrozenReviewPolicy) -> Path:
175
+ paths = [Path(path) for path in policy["sources"]
176
+ if path.endswith("/prompts/coding-preflight/review-rules.json")]
177
+ if len(paths) != 1:
178
+ raise ValueError("required frozen review resource is missing or ambiguous: review-rules.json")
179
+ return paths[0]
180
+
181
+
182
+ def _language_resources(source_paths: Sequence[str]) -> set[str]:
183
+ languages: set[str] = set()
184
+ for source in source_paths:
185
+ path = PurePosixPath(source)
186
+ if not qa_relative_path_valid(source):
187
+ raise ValueError("review source paths must be repository-relative")
188
+ language = _LANGUAGE_SUFFIXES.get(path.suffix) or _LANGUAGE_MANIFESTS.get(path.name)
189
+ if language:
190
+ languages.add(language)
191
+ if ("migration" in source.lower() or path.name == "schema.prisma"):
192
+ languages.add("sql")
193
+ return {f"languages/{language}.md" for language in languages}
194
+
195
+
196
+ def review_policy_context(
197
+ project: Path, head: str, source_paths: Sequence[str], *, base: str = "",
198
+ ) -> tuple[tuple[str, ...], dict[str, str]]:
199
+ paths, manifests, _ = _review_context_side(project, head, source_paths)
200
+ if base:
201
+ previous, old_manifests, commit = _review_context_side(project, base, source_paths)
202
+ paths = tuple(dict.fromkeys((*paths, *previous)))
203
+ for path, body in old_manifests.items():
204
+ if manifests.get(path) != body:
205
+ manifests[f"base:{commit}/{path}"] = body
206
+ return paths, manifests
207
+
208
+
209
+ def _review_context_side(
210
+ project: Path, head: str, source_paths: Sequence[str],
211
+ ) -> tuple[tuple[str, ...], dict[str, str], str]:
212
+ from .review_verdicts import _head_tree
213
+
214
+ _language_resources(source_paths)
215
+ tree = _head_tree(project, head)
216
+ files = tree._git("ls-tree", "-r", "--name-only", tree.commit)
217
+ if files.returncode:
218
+ raise ValueError("cannot read the frozen review project layout")
219
+ paths = tuple(files.stdout.decode("utf-8").splitlines())
220
+ manifests: set[str] = set()
221
+ for source in source_paths:
222
+ directory = PurePosixPath(source).parent
223
+ for parent in (directory, *directory.parents):
224
+ candidate = (parent / "package.json").as_posix()
225
+ if candidate in paths:
226
+ manifests.add(candidate)
227
+ break
228
+ contents: dict[str, str] = {}
229
+ for manifest in sorted(manifests):
230
+ result = tree._git("show", f"{tree.commit}:{manifest}")
231
+ if result.returncode:
232
+ raise ValueError("cannot read the frozen review package manifest")
233
+ contents[manifest] = result.stdout.decode("utf-8")
234
+ return paths, contents, tree.commit
235
+
236
+
237
+ def _node_server_work(source_paths: Sequence[str], manifests: Mapping[str, str]) -> bool:
238
+ if any(PurePosixPath(path).suffix in (".mjs", ".cjs", ".mts", ".cts")
239
+ or PurePosixPath(path).name in ("server.js", "server.ts", "nest-cli.json")
240
+ or any(part in ("server", "api", "controllers", "commands")
241
+ for part in PurePosixPath(path).parts) for path in source_paths):
242
+ return True
243
+ for path, body in manifests.items():
244
+ if PurePosixPath(path).name != "package.json":
245
+ continue
246
+ package = json.loads(body)
247
+ if not isinstance(package, dict):
248
+ raise ValueError("review package manifest must be an object")
249
+ dependencies = package.get("dependencies", {})
250
+ dev_dependencies = package.get("devDependencies", {})
251
+ if not isinstance(dependencies, dict) or not isinstance(dev_dependencies, dict):
252
+ raise ValueError("review package dependencies must be objects")
253
+ dependencies = {**dependencies, **dev_dependencies}
254
+ if any(name in ("express", "fastify", "koa", "hapi") or name.startswith("@nestjs/")
255
+ for name in dependencies):
256
+ return True
257
+ if package.get("bin"):
258
+ return True
259
+ return False
260
+
261
+
262
+ def _hexagonal_work(policy: FrozenReviewPolicy, project_paths: Sequence[str]) -> bool:
263
+ style = policy["architecture"]
264
+ if style != "undeclared":
265
+ return style == "hexagonal"
266
+ parts = {part for path in project_paths for part in PurePosixPath(path).parts}
267
+ return (any(".port." in PurePosixPath(path).name for path in project_paths)
268
+ or {"domain", "ports", "adapters"} <= parts
269
+ or {"core", "infrastructure", "application"} <= parts)
270
+
271
+
272
+ def select_review_policy(
273
+ policy: FrozenReviewPolicy, source_paths: Sequence[str] = (), *,
274
+ project_paths: Sequence[str] = (), manifest_contents: Mapping[str, str] | None = None,
275
+ guidance_paths: Sequence[str] = (),
276
+ resources: Sequence[str] = (),
277
+ ) -> FrozenReviewPolicy:
278
+ errors = review_policy_errors(policy)
279
+ if errors:
280
+ raise ValueError("; ".join(errors))
281
+ selected_resources = {"overview.md", "clean-code.md", "review-rules.json"}
282
+ selected_resources.update(_language_resources(source_paths))
283
+ root = str(review_policy_catalog_path(policy).parent)
284
+ for resource in resources:
285
+ if (not qa_relative_path_valid(resource) or root is None
286
+ or root + "/" + resource not in policy["sources"]):
287
+ raise ValueError(f"review resource was not captured in the frozen pack: {resource}")
288
+ if resource == "architectures/hexagonal.md" and policy["architecture"] in ("none", "layered"):
289
+ raise ValueError("review resource conflicts with the declared architecture")
290
+ selected_resources.add(resource)
291
+ if "frameworks/node-server.md" in selected_resources:
292
+ selected_resources.add("languages/javascript-typescript.md")
293
+ if any(name.endswith("javascript-typescript.md") for name in selected_resources):
294
+ if _node_server_work(source_paths, manifest_contents or {}):
295
+ selected_resources.add("frameworks/node-server.md")
296
+ if _hexagonal_work(policy, (*source_paths, *project_paths)):
297
+ selected_resources.add("architectures/hexagonal.md")
298
+ missing = [name for name in sorted(selected_resources)
299
+ if root + "/" + name not in policy["sources"]]
300
+ if missing:
301
+ raise ValueError("required frozen review resources are missing: " + ", ".join(missing))
302
+ selected: dict[str, FrozenProcedure] = {}
303
+ for path, source in policy["sources"].items():
304
+ if path in guidance_paths and not path.endswith("/references/review-calibration.md"):
305
+ continue
306
+ if root and path.startswith(root + "/") and path[len(root) + 1:] not in selected_resources:
307
+ continue
308
+ selected[path] = dict(source)
309
+ return {"schemaVersion": policy["schemaVersion"], "architecture": policy["architecture"],
310
+ "sources": selected}
311
+
312
+
313
+ def render_review_policy(
314
+ policy: FrozenReviewPolicy, source_paths: Sequence[str] = (), *,
315
+ project_paths: Sequence[str] = (), manifest_contents: Mapping[str, str] | None = None,
316
+ guidance_paths: Sequence[str] = (),
317
+ resources: Sequence[str] = (),
318
+ ) -> str:
319
+ selected = select_review_policy(
320
+ policy, source_paths, project_paths=project_paths,
321
+ manifest_contents=manifest_contents, guidance_paths=guidance_paths,
322
+ resources=resources,
323
+ )
324
+ body = render_selected_review_policy(selected)
325
+ omitted = policy["sources"].keys() - selected["sources"].keys()
326
+ if not omitted:
327
+ return body
328
+ rows = [body, "\n### Available archived resources (not loaded)\n\n"]
329
+ rows.extend(f"- {path} ({policy['sources'][path]['digest']})\n" for path in sorted(omitted))
330
+ rows.append("\nUse verification-input --source-path for each changed source file and "
331
+ "--resource for additional applicable pack resources. "
332
+ "Do not treat this inventory as read content.\n")
333
+ return "".join(rows)
334
+
335
+
336
+ def render_selected_review_policy(policy: FrozenReviewPolicy) -> str:
337
+ errors = review_policy_errors(policy)
338
+ if errors:
339
+ raise ValueError("; ".join(errors))
340
+ rows = ["\n## Frozen Review Policy\n\n",
341
+ f"Architecture style: {policy['architecture']}\n"]
342
+ for path, source in policy["sources"].items():
343
+ rows.extend([f"\n### Rule source: {path}\n",
344
+ f"Digest: {source['digest']}\n\n", source["body"], "\n"])
345
+ return "".join(rows)
346
+
347
+
348
+ def read_review_architecture(project: Path, manifest: Mapping[str, object]) -> str:
349
+ from okstra_project.resolver import resolve_architecture
350
+ from .qa_procedures import safe_qa_path
351
+ from .verification_input_ref import VerificationInputReference
352
+ from .verification_inputs import read_verification_inputs
353
+
354
+ reference = VerificationInputReference.from_artifact_fields(manifest)
355
+ if reference is not None:
356
+ inputs = read_verification_inputs(safe_qa_path(project, reference.relative_path), reference.digest)
357
+ if "reviewPolicy" in inputs:
358
+ return inputs["reviewPolicy"]["architecture"]
359
+ return resolve_architecture(project)