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.
- package/README.md +12 -0
- 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 +127 -0
- package/docs/architecture.md +7 -0
- 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/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/attempt_evidence.py +10 -0
- 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/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- 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 +10 -0
- 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 +38 -10
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +25 -0
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +6 -0
- 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_synthesis_packet.py +11 -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/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_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- 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 +14 -2
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
|
|
@@ -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**:
|
|
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)
|