okstra 0.231.1 → 0.233.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +19 -271
- package/dist/cli-registry.mjs +14 -1
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/execute/render-bundle.d.mts +6 -1
- package/dist/commands/execute/render-bundle.mjs +139 -32
- package/dist/commands/execute/render-bundle.mjs.map +1 -1
- package/dist/commands/lifecycle/config.mjs +6 -74
- package/dist/commands/lifecycle/config.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/commands/trace/capacity.d.mts +12 -0
- package/dist/commands/trace/capacity.mjs +21 -0
- package/dist/commands/trace/capacity.mjs.map +1 -0
- package/dist/commands/trace/model.d.mts +89 -0
- package/dist/commands/trace/model.mjs +251 -0
- package/dist/commands/trace/model.mjs.map +1 -0
- package/dist/commands/trace/progression.d.mts +11 -0
- package/dist/commands/trace/progression.mjs +194 -0
- package/dist/commands/trace/progression.mjs.map +1 -0
- package/dist/commands/trace/review.d.mts +7 -0
- package/dist/commands/trace/review.mjs +51 -0
- package/dist/commands/trace/review.mjs.map +1 -0
- package/dist/commands/trace/task-link.d.mts +18 -0
- package/dist/commands/trace/task-link.mjs +72 -0
- package/dist/commands/trace/task-link.mjs.map +1 -0
- package/dist/commands/trace/trace.d.mts +1 -0
- package/dist/commands/trace/trace.mjs +293 -0
- package/dist/commands/trace/trace.mjs.map +1 -0
- package/dist/lib/bounded-file.d.mts +1 -0
- package/dist/lib/bounded-file.mjs +36 -0
- package/dist/lib/bounded-file.mjs.map +1 -0
- package/dist/lib/config-store.d.mts +34 -0
- package/dist/lib/config-store.mjs +70 -0
- package/dist/lib/config-store.mjs.map +1 -0
- package/dist/lib/file-lock.mjs +4 -5
- package/dist/lib/file-lock.mjs.map +1 -1
- package/dist/lib/input-limit.d.mts +4 -0
- package/dist/lib/input-limit.mjs +8 -0
- package/dist/lib/input-limit.mjs.map +1 -0
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +98 -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/report-language-tag.d.mts +1 -0
- package/dist/lib/report-language-tag.mjs +4 -0
- package/dist/lib/report-language-tag.mjs.map +1 -0
- package/dist/lib/report-language.d.mts +1 -0
- package/dist/lib/report-language.mjs +50 -0
- package/dist/lib/report-language.mjs.map +1 -0
- package/dist/lib/skill-catalog.mjs +3 -0
- package/dist/lib/skill-catalog.mjs.map +1 -1
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +163 -5
- package/docs/architecture.md +17 -4
- package/docs/cli.md +511 -0
- package/docs/contributor-change-matrix.md +1 -2
- package/docs/project-structure-overview.md +33 -42
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/operations/trace-interface-review.json +6 -0
- package/runtime/agents/operations/trace-scope-review.json +6 -0
- 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 +88 -286
- 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/duties/interface-reviewer.json +32 -0
- package/runtime/prompts/host-orchestration/README.md +18 -9
- package/runtime/prompts/launch.template.md +3 -2
- package/runtime/prompts/lead/context-loader.md +2 -0
- package/runtime/prompts/lead/okstra-lead-contract.md +7 -7
- package/runtime/prompts/lead/report-writer.md +6 -6
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/prompts/profiles/_common-contract.md +1 -1
- package/runtime/python/okstra_ctl/agent/invocation.py +122 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +72 -26
- package/runtime/python/okstra_ctl/agent/prompt_cli/corrections.py +23 -8
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +58 -14
- package/runtime/python/okstra_ctl/agent/prompt_cli/results.py +8 -11
- package/runtime/python/okstra_ctl/agent/standalone.py +15 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +24 -30
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/code_review_census.py +162 -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_prepare.py +381 -0
- package/runtime/python/okstra_ctl/code_review_run.py +384 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +49 -9
- package/runtime/python/okstra_ctl/code_review_supervisor.py +41 -0
- package/runtime/python/okstra_ctl/code_review_target.py +212 -13
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/coverage_census.py +11 -2
- 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/design_snapshot.py +16 -9
- package/runtime/python/okstra_ctl/direct_work.py +45 -3
- package/runtime/python/okstra_ctl/dispatch_core.py +31 -15
- package/runtime/python/okstra_ctl/dispatch_state.py +9 -2
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/domain/role.py +1 -0
- 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 +300 -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/final_report_schema.py +37 -34
- package/runtime/python/okstra_ctl/incremental_carry.py +6 -7
- package/runtime/python/okstra_ctl/initial_prompt_materialization.py +9 -2
- package/runtime/python/okstra_ctl/json_boundary.py +51 -5
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +148 -1
- package/runtime/python/okstra_ctl/manager_journal.py +126 -0
- package/runtime/python/okstra_ctl/manager_launch.py +3 -3
- package/runtime/python/okstra_ctl/manager_log.py +221 -0
- package/runtime/python/okstra_ctl/manager_paths.py +8 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_resume.py +59 -0
- package/runtime/python/okstra_ctl/manager_split.py +2 -2
- package/runtime/python/okstra_ctl/manager_store.py +116 -17
- package/runtime/python/okstra_ctl/manager_sync.py +45 -25
- package/runtime/python/okstra_ctl/manager_view.py +35 -2
- package/runtime/python/okstra_ctl/material.py +2 -0
- package/runtime/python/okstra_ctl/model_cli.py +64 -14
- package/runtime/python/okstra_ctl/model_defaults.py +22 -0
- package/runtime/python/okstra_ctl/model_io/renderers.py +16 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/operation_invocation.py +207 -28
- package/runtime/python/okstra_ctl/path_hints.py +14 -3
- package/runtime/python/okstra_ctl/paths.py +6 -1
- package/runtime/python/okstra_ctl/phases/catalog.py +24 -7
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/host-rules.md +3 -3
- 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 +23 -8
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +6 -4
- 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_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/votes.py +11 -11
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +16 -9
- package/runtime/python/okstra_ctl/phases/implementation_planning/host-rules.md +3 -6
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +12 -10
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +6 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/lenses.py +12 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/profile.md +7 -6
- package/runtime/python/okstra_ctl/phases/improvement_discovery/resolved_census.py +159 -0
- package/runtime/python/okstra_ctl/phases/improvement_discovery/spec.md +5 -2
- package/runtime/python/okstra_ctl/phases/improvement_discovery/validation.py +21 -7
- package/runtime/python/okstra_ctl/phases/release_handoff/boundary.json +1 -1
- package/runtime/python/okstra_ctl/phases/release_handoff/profile.md +4 -1
- package/runtime/python/okstra_ctl/plan_verify_cli.py +6 -4
- package/runtime/python/okstra_ctl/render.py +28 -2
- package/runtime/python/okstra_ctl/report_assembly.py +53 -11
- package/runtime/python/okstra_ctl/report_contract.py +26 -0
- package/runtime/python/okstra_ctl/report_corrections.py +36 -20
- package/runtime/python/okstra_ctl/report_inputs.py +1 -0
- package/runtime/python/okstra_ctl/report_language.py +4 -1
- package/runtime/python/okstra_ctl/report_narrative.py +182 -7
- package/runtime/python/okstra_ctl/report_projections.py +64 -18
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +97 -38
- 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 +67 -36
- package/runtime/python/okstra_ctl/run_context.py +10 -1
- package/runtime/python/okstra_ctl/set_work_status.py +4 -15
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/task_list_cli.py +34 -8
- package/runtime/python/okstra_ctl/task_query.py +239 -0
- package/runtime/python/okstra_ctl/trace_review.py +264 -0
- package/runtime/python/okstra_ctl/trace_tasks.py +197 -0
- package/runtime/python/okstra_ctl/user_authorization.py +14 -0
- package/runtime/python/okstra_ctl/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/wizard/confirmation.py +7 -3
- package/runtime/python/okstra_ctl/wizard/launch.py +52 -0
- package/runtime/python/okstra_ctl/wizard/launch_cli.py +39 -0
- package/runtime/python/okstra_ctl/wizard/outcome.py +17 -16
- package/runtime/python/okstra_ctl/wizard/registry.py +1 -1
- package/runtime/python/okstra_ctl/wizard/render.py +8 -0
- package/runtime/python/okstra_ctl/wizard/state.py +2 -1
- package/runtime/python/okstra_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 +45 -20
- package/runtime/python/okstra_token_usage/blocks.py +74 -0
- package/runtime/python/okstra_token_usage/cli.py +23 -10
- package/runtime/python/okstra_token_usage/collect.py +25 -22
- package/runtime/python/okstra_token_usage/policy.py +193 -0
- package/runtime/schemas/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/schemas/report-synthesis-packet-v1.0.schema.json +1 -1
- package/runtime/skills/_fragments/wizard-confirm-step.md +1 -1
- package/runtime/skills/_fragments/wizard-preflight.md +1 -1
- package/runtime/skills/_fragments/wizard-prompt-loop.md +3 -5
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/_fragments/wizard-render-bundle.md +15 -29
- package/runtime/skills/okstra-brief-gen/SKILL.md +7 -7
- package/runtime/skills/okstra-brief-gen/references/tracker-recursion.md +1 -1
- package/runtime/skills/okstra-code-review/SKILL.md +92 -136
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +37 -61
- package/runtime/skills/okstra-discussion/SKILL.md +22 -38
- package/runtime/skills/okstra-explain-flow/SKILL.md +6 -2
- package/runtime/skills/okstra-manager/SKILL.md +31 -0
- package/runtime/skills/okstra-memory/SKILL.md +8 -1
- package/runtime/skills/okstra-pr-gen/SKILL.md +1 -1
- package/runtime/skills/okstra-run/SKILL.md +55 -183
- package/runtime/skills/okstra-schedule-gen/SKILL.md +9 -13
- package/runtime/skills/okstra-setup/SKILL.md +3 -2
- package/runtime/skills/okstra-setup/references/project-config.md +2 -4
- package/runtime/skills/okstra-tdd/SKILL.md +187 -0
- package/runtime/skills/okstra-user-response/SKILL.md +4 -2
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/manager/view.template.html +4 -0
- package/runtime/templates/report-writer-prompt-preamble.md +15 -3
- package/runtime/templates/trace/trace.template.md +42 -0
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/checks/fixtures-02.py +25 -33
- package/runtime/validators/validate-run.py +107 -38
|
@@ -1,76 +1,18 @@
|
|
|
1
1
|
# Census rules — turning a diff into the worklist
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
## Cell granularity — one rule group per axis
|
|
6
|
-
|
|
7
|
-
**Each axis carries exactly one rule group, and that group is the axis itself.** A cell is `target × <axis>`, never `target × <individual rule>`. Twelve changed files therefore produce twelve `structural` cells, not one per file per rule.
|
|
8
|
-
|
|
9
|
-
This is what makes the cell count reproducible: the axis list is fixed at four, so the census size depends only on the diff. Splitting an axis per individual rule would make the count depend on how many rules the reader chose to enumerate that day — the exact variance this census exists to remove.
|
|
10
|
-
|
|
11
|
-
The specific rule a finding violates is named **inside the verdict**, in its `rule` field (`review-calibration.md`), not in the cell label. One cell can therefore carry findings from several rules of its group, and it still counts as one cell. Rule coverage is represented inside each grouped verdict below.
|
|
3
|
+
Build one census for the fixed comparison range selected in [Step 1](../SKILL.md#step-1--resolve-the-review-target). This file owns target membership, stable IDs, exclusions and pack allocation. The selected frozen policy supplies coding/project rules and captured calibration. Execution and review-scope decisions belong to [SKILL.md](../SKILL.md); verdicts and report fields belong to [review calibration](review-calibration.md).
|
|
12
4
|
|
|
13
5
|
## Shared rule catalog and grouped cells
|
|
14
6
|
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
Use these named review criteria. Each criterion includes the relevant subconditions and carve-outs in its canonical pack; those bullets do not get separate verdict IDs:
|
|
7
|
+
Use `prompts/coding-preflight/review-rules.json` under the runtime asset root as the catalog for `code-review census --rules`. The generator resolves pack references and emits `## Rules` with `Rule | Group | Reference` columns and `## Cells` with `Cell | Target | Group` columns. Project-specific references may supplement it; do not retype a parallel base catalog.
|
|
18
8
|
|
|
19
|
-
|
|
20
|
-
|---|---|
|
|
21
|
-
| `structural` | `S1` reuse/DRY; `S2` simplicity/KISS; `S3` responsibilities/SOLID; `S4` current scope/YAGNI; when an architecture pack is routed: `S5` thin ports, `S6` I/O-only adapters, `S7` domain-object placement, `S8` dependency direction, `S9` boundary ports, `S10` domain-owned business rules |
|
|
22
|
-
| `semantic` | `M1` truthful and specific names, including result tags and diagnostic values; `M2` single-purpose readable flow, including size and nesting; `M3` comments and explanatory values |
|
|
23
|
-
| `state-and-tests` | `T1` state and mutation boundaries; `T2` no self-mocking; `T3` behavioral outcome assertions; `T4` discriminating fixtures, test titles and branch coverage |
|
|
24
|
-
| `general` | `G1` correctness and regressions; `G2` error handling and third-party wrappers; `G3` untrusted-input and resource bounds; `G4` performance; `G5` routed language/framework and project conventions |
|
|
25
|
-
|
|
26
|
-
Write the selected IDs with their absolute pack/section references under `## Rules`. Multiple references for a criterion go in the same Reference field, separated by semicolons. Include the observed-fact error guidance with G2, and list the routed normative clause locations together under G5 instead of citing only a pack's first line. Do not turn every heading, bullet, formatter instruction or example into another rule. Read the original references rather than restating their bodies.
|
|
27
|
-
|
|
28
|
-
Write targets under `## Cells`; each has a stable `C-CR-...` ID, the target and its group. A function target includes its path and position, e.g. `src/orders/pricing.py:42 calculate_price`. Distinguish same-line anonymous functions with their columns. Targets are repository-relative; no absolute or parent-traversal paths.
|
|
29
|
-
|
|
30
|
-
```markdown
|
|
31
|
-
## Rules
|
|
32
|
-
| Rule | Group | Reference |
|
|
33
|
-
|---|---|---|
|
|
34
|
-
| S1 | structural | /absolute/pack/clean-code.md#DRY |
|
|
35
|
-
| S2 | structural | /absolute/pack/clean-code.md#KISS |
|
|
9
|
+
A cell is one `target × axis`, not one target per rule or pack bullet. Its group contains all selected rule IDs; [compact coverage](review-calibration.md#compact-rule-coverage) accounts for those IDs within one row. Select `S5`–`S10` only for a routed architecture pack; the base catalog otherwise has 16 criteria. Preserve the generated `Review policy digest` and `Review resources` metadata in every specialist's assigned census; dividing an assignment does not select another shared policy.
|
|
36
10
|
|
|
37
|
-
|
|
38
|
-
| Cell | Target | Group |
|
|
39
|
-
|---|---|---|
|
|
40
|
-
| C-CR-0001 | src/orders/pricing.py | structural |
|
|
41
|
-
| C-CR-0002 | src/orders/totals.py | structural |
|
|
42
|
-
```
|
|
43
|
-
|
|
44
|
-
The example is abbreviated; the actual catalog includes the named criteria above for every used group. Add `S5` through `S10` only for a routed architecture pack; otherwise the base catalog has 16 criteria. Freeze the full catalog and cell IDs before dispatch. Every model team receives that entire census independently, then delegates its rule subsets by the six-specialty mapping in SKILL.md. A child's assigned census retains only its specialty's rules and all cells of their group, preserving IDs, targets, references and order. Semantic cells appear in both naming and readability assignments; state-and-tests cells appear in both state and tests assignments. Their rule IDs are disjoint. Within each team, reconcile `(cell ID, rule ID)` pairs, not cell IDs alone, against the full census. Across models, repeat the full set independently.
|
|
45
|
-
|
|
46
|
-
The command `code-review check-coverage` enforces catalog membership, rule accounting and source-anchor validity against each child's subset census and, after consolidation, each coordinator's full census. It does not merge partial-rule rows across children. Coordinators combine complementary rule statuses into complete rows, preserving findings, observations, dependencies and child completion provenance. The lead checks delegation, pair coverage, aggregation fidelity, reference completeness and verdict truth; these are not enforced by the coverage parser.
|
|
47
|
-
|
|
48
|
-
Do not omit a cell because a rule seems inapplicable. Record that criterion under `N/A` with its reason in the compact row. The normal case lists checked rule IDs once with one inspected source anchor for the cell. This preserves rule-level omission checks without repeating paths and explanations for every rule.
|
|
49
|
-
|
|
50
|
-
## Inspection before compression
|
|
51
|
-
|
|
52
|
-
Keep discovery separate from output accounting. Read the changed constructs and applicable canonical clauses, trace their dependencies, identify findings, then compress the result into the existing grouped rows. The table is the output format, not the inspection procedure.
|
|
53
|
-
|
|
54
|
-
Use these inspection guides for general cells:
|
|
55
|
-
|
|
56
|
-
| Criterion | Inspection guide |
|
|
57
|
-
|---|---|
|
|
58
|
-
| G2 | Enumerate the dependency's possible outcomes and compare their meanings with the returned tags, diagnostic values and error text. Trace existing callees and types when the changed mapping depends on them. |
|
|
59
|
-
| G3 | Identify each input dimension and the work performed inside changed loops or repeated calls. Follow existing callees to account for scans, parsing and allocation; a type-only callee diff does not remove newly amplified work at its caller. Locate the enforcing bound before the expensive work, or report the unbounded path. |
|
|
60
|
-
| G5 | Inspect every applicable normative clause of the routed language, framework and project policy for the changed constructs. Name those clauses and observed conformance. Evaluate explicit conventions independently of formatter, linter and behavioral-test results. |
|
|
11
|
+
Keep absolute pack/section references under `## Rules`. Separate multiple references with semicolons, including observed-fact error guidance for G2 and the routed normative clauses for G5 rather than just a pack's first line. Reviewers read the selected frozen clauses delivered with their invocation; the absolute source references identify provenance.
|
|
61
12
|
|
|
62
|
-
|
|
13
|
+
Each `## Cells` row has a stable `C-CR-...` ID, a repository-relative target and its group. Function targets include path, position and name; distinguish same-line anonymous functions by column. Absolute and parent-traversal target paths are invalid. Freeze the catalog, cells and ordering before the [team assignment](../SKILL.md#step-3--select-model-teams-and-prepare-every-specialist).
|
|
63
14
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
**Membership is mechanical; judgment only ever decides a cell's verdict.**
|
|
67
|
-
|
|
68
|
-
Never ask "does this rule apply to this file?" while building the census — that question is the reviewer's, and its answer is a verdict (`n/a` with a reason when the rule turns out not to apply). Over-inclusion is cheap: a clean verdict costs one line. A judged exclusion is variance — it is the exact failure this census exists to remove, because the next run judges differently and the review changes shape.
|
|
69
|
-
|
|
70
|
-
Two consequences:
|
|
71
|
-
|
|
72
|
-
- A cell exists because a mechanical test matched (file extension, path, "the diff touched this function"), never because the orchestrator expected a violation.
|
|
73
|
-
- Read whole files at the frozen head to locate function boundaries; membership still depends only on changed lines, not on an expected violation. Use `git -C <gitRoot> show <headCommit>:<path>` from Step 1, or parse that content with an available language parser. Do not use the working tree or a hunk header as the complete function inventory.
|
|
15
|
+
Membership follows the mechanical tests below, never an expected violation or a judgment that a rule is irrelevant. Keep such cells and let the reviewer record reasoned `N/A` statuses. Read frozen whole-file source to locate boundaries; neither working files nor hunk headers are a complete function inventory.
|
|
74
16
|
|
|
75
17
|
## The four axes
|
|
76
18
|
|
|
@@ -81,49 +23,45 @@ Two consequences:
|
|
|
81
23
|
| `state-and-tests` | non-test source file × `state-and-tests`, test file × `state-and-tests` | every changed non-test source file gets one cell; every changed test file gets one cell |
|
|
82
24
|
| `general` | non-test source file × `general` | every changed non-test source file |
|
|
83
25
|
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) are censused on `state-and-tests` only. They are not excluded: they are covered by a different rule group.
|
|
26
|
+
Test files (the project's test-path or test-suffix convention — `*_test.*`, `*.test.*`, `*.spec.*`, `tests/`, `spec/`) receive `state-and-tests` cells and semantic cells for changed named functions/helpers. Test-case bodies remain subject to test-quality review; named helper readability is not exempt. `code_review_census.py` enumerates Python functions; other supported code suffixes remain unresolved until a manual inventory supplies their spans.
|
|
87
27
|
|
|
88
|
-
|
|
28
|
+
Intersect frozen signature/body spans with changed lines, including enclosing and nested functions. Use base-side spans for deletion-only changes and map surviving functions to head positions. Removed functions and changes outside functions (imports, wiring, declarations and class-level constants) belong to file-level cells. If boundaries cannot be established, stop before dispatch with an incomplete census. Boundary completeness remains a lead source-inspection check.
|
|
89
29
|
|
|
90
30
|
## Exclusions
|
|
91
31
|
|
|
92
|
-
Only these are excluded
|
|
32
|
+
Only these are excluded, each with a recorded reason:
|
|
93
33
|
|
|
94
34
|
- lockfiles (`package-lock.json`, `poetry.lock`, `Cargo.lock`, `*.sum`, …)
|
|
95
35
|
- generated code (anything under a build/output directory, or carrying a "do not edit" generation header)
|
|
96
|
-
- pure configuration and
|
|
36
|
+
- pure data files (`.csv`); handwritten configuration and workflow files remain included even when they contain no executable statements
|
|
97
37
|
- prose documentation with no executable or agent-directive content
|
|
98
38
|
- binary files and vendored third-party trees
|
|
99
39
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
To keep that mechanical rather than judged, a path allowlist overrides the extension list: anything under `skills/**`, `prompts/**`, `agents/**`, or `templates/**` is **always censused**, whatever its extension.
|
|
103
|
-
|
|
104
|
-
Everything else is censused. When a file is arguably code — a build script, a shell entrypoint, a template that carries logic — it is censused, not excluded; if the rules turn out not to apply, that is a `clean` verdict.
|
|
105
|
-
|
|
106
|
-
An exclusion without a stated reason is a defect in the census: it is indistinguishable from a file that was forgotten.
|
|
40
|
+
Agent-directive Markdown is included. `AGENTS.md` and `CLAUDE.md` are included at every depth; handwritten JSON, YAML, TOML, INI and CFG remain included even without executable statements. Generated-output and binary exclusions still apply to these files. A path allowlist overrides extension exclusions: everything under `skills/**`, `prompts/**`, `agents/**` or `templates/**` is censused. Include everything else, including build scripts, shell entrypoints and logic-bearing templates; inapplicable rules receive `N/A`, not an omitted target.
|
|
107
41
|
|
|
108
42
|
## Pack allocation
|
|
109
43
|
|
|
110
|
-
Step 2
|
|
44
|
+
Step 2 captures and selects the coding-preflight resources once. Allocate the selected frozen bodies across the axes like this:
|
|
111
45
|
|
|
112
46
|
| Pack | Goes to |
|
|
113
47
|
|---|---|
|
|
114
48
|
| `clean-code.md` | all four axes — it is language-agnostic and every axis draws from a different part of it |
|
|
115
|
-
| `overview.md` core principles |
|
|
49
|
+
| `overview.md` core principles | `structural`: 1–3; `semantic`: 4–5; `general`: 6; all reviewers read its applicability and policy-precedence guidance |
|
|
116
50
|
| routed `languages/*.md` | `state-and-tests` (self-mock signals) and `general` (language-specific traps) |
|
|
117
51
|
| routed `frameworks/*.md` | `general` |
|
|
118
52
|
| routed `architectures/*.md` | `structural` |
|
|
119
53
|
|
|
120
|
-
A pack
|
|
54
|
+
A pack not selected for the assignment is not handed to its reviewer; selected applicable clauses are read completely before verdicting. Source-writing procedures in `authoring-checks.md` remain author-only. Materialization delivers calibration with the selected policy, not orchestrator execution instructions.
|
|
55
|
+
|
|
56
|
+
The catalog owns each criterion's source binding: S1–S4 cover DRY/KISS/SOLID/YAGNI, routed S5–S10 cover H1–H6, M1–M3 cover naming/readability/comments, T1–T4 cover state and test quality, and G1–G5 cover correctness/errors/security/performance/routed conventions. Keep `clean-code.md`'s DRY domain-literal and variant checks with `structural`, and the observation requirements in [compact coverage](review-calibration.md#compact-rule-coverage) with `general`.
|
|
57
|
+
|
|
58
|
+
General inspection also applies the captured `clean-code.md` "Five simultaneous quality outcomes" through existing groups. G1 establishes caller-visible expectations and a reachable distinguishing state; G3 follows input through access, sinks, disclosure and downstream cost. G4 identifies workload, declared latency/throughput/resource limits and baseline, then compares applicable measurements or bound tests. A necessary missing limit or measurement stays unverified. These checks add no axes or duplicate reviewers; route evidence outside a specialist's axis to its owner.
|
|
121
59
|
|
|
122
60
|
## Unregistered language
|
|
123
61
|
|
|
124
|
-
When no Stage 1
|
|
62
|
+
When changed executable code uses a language with no Stage 1 rule in `overview.md`, that language has no pack. Do not invent one. Configuration-only and agent-directive changes use `clean-code.md` and the project's applicable rules without asking for a programming-language guide.
|
|
125
63
|
|
|
126
|
-
1. Ask the user for the project's canonical style guide (a path, a URL, or a named standard)
|
|
64
|
+
1. Ask the user for the project's canonical style guide (a path, a URL, or a named standard). If they name one, capture the applicable guide through Step 2's `--policy` input before dispatch and allocate its frozen body to `state-and-tests` and `general` in place of the language pack.
|
|
127
65
|
2. If the user does not answer, run all four axes anyway with `clean-code.md` alone, and state in the report's Coverage section that language-specific rules were not applied and why.
|
|
128
66
|
|
|
129
67
|
Never skip an axis for a missing pack, and never silently proceed as if the language pack existed.
|
|
@@ -139,30 +77,16 @@ Both must hold exactly, and both are shown in the response before dispatch:
|
|
|
139
77
|
|
|
140
78
|
## Follow-up review
|
|
141
79
|
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
Keep all six specialty assignments stable within each selected model team. Run scope/coverage checks separately for each `(model-team slot, specialty)` against its current and previous subset census, then check each coordinator's consolidated report against the full census. Do not substitute another specialty's or model's completions. Each model independently covers the full census through its children. An empty assignment is acknowledged by its coordinator as described in SKILL.md, not passed to these commands.
|
|
145
|
-
|
|
146
|
-
The `code-review scope` command proposes carry candidates per reviewer. It verifies prior completion integrity, role/model consistency within the prior results, ancestor history, exact base/head baseline, catalog references, and rule/policy content fingerprints. It reopens cells with prior findings, changed targets or changed recorded inputs, and cells the prior results left unverified. Missing dependency records reopen their cells. A changed path outside the prior inventory reopens only the cells that list it and is named in the scope reason so reviewers search it for further effects. Changed rules/base, rewritten history, unknown prior cell IDs or a missing baseline fall back to full review. Invalid completion integrity stops scope calculation. These checks are enforced by `code_review_scope.py::review_scope` and the standalone completion scope tests.
|
|
147
|
-
|
|
148
|
-
Record each inspected cell's repository-relative input files under `Review Dependencies`: its whole target file, definitions/callees, callers, outcome consumers, relevant tests and contracts read to justify the verdict. Include transitive dependencies. Paths describe files, not line ranges; changing any part reopens the dependent cell. An external rule or instruction belongs in the repeated `--policy` inputs instead. A gap-fill retains the same baseline and records dependencies for its inspected cells.
|
|
149
|
-
|
|
150
|
-
The inventory's completeness is a reviewer/lead judgment, not mechanically proven. Before accepting carry candidates, independently search the delta's changed symbols and wiring for effects beyond that inventory. Include changed behavior, error/result mappings, state, test assumptions, public contracts and downstream work. Newly affected cells reopen even when their own bytes did not change. Reopen all affected axes for the target file; expand to callers/tests outside the original census as supporting inspection without dropping or inventing census cells. Unknown reachability, dynamic dispatch, configuration-driven wiring or unexplained test failures require broader inspection, up to full review.
|
|
151
|
-
|
|
152
|
-
Read whole target files, relevant callers/callees, contracts and tests on the first review and on follow-ups. A smaller re-evaluation scope never means reading only changed lines or ignoring another layer. Route newly affected cells in other specialties through the lead to their owners. Unknown impact expands inspection; obtain any required scope authorization before additional model calls. Reusing an unchanged verdict requires a current impact check, not just unchanged source bytes.
|
|
153
|
-
|
|
154
|
-
Reviewers return the complete current coverage table, identifying inherited cells separately in `Review Carry`. They attest that the current impact inspection supports each inheritance. The lead verifies that attestation and the boundary evidence. Prior `checked` labels alone never satisfy current coverage. Continue using the existing current materialize/verify/result/complete/verify-completion and check-coverage boundaries; scope output cannot mark a cell clean. This boundary audit is a review criterion, not a machine guarantee of defect absence.
|
|
155
|
-
|
|
156
|
-
A count that does not balance means a file was dropped, not that the diff was odd. Find it before dispatching.
|
|
80
|
+
Build only the selected range from [Step 1](../SKILL.md#step-1--resolve-the-review-target). `--previous-census` preserves IDs for matching targets/groups; new targets receive new IDs and unrelated IDs are never renumbered to fill gaps. ID reuse or a target's absence from this census does not resolve a finding or reuse a verdict. Follow [inspection scope and briefing](../SKILL.md#inspection-scope-and-briefing) for verified reuse and [follow-up decisions](../SKILL.md#follow-up-decisions) for the retained ledger and cumulative PR evidence.
|
|
157
81
|
|
|
158
82
|
## What to emit
|
|
159
83
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
- the exclusion list, one line per file, each with its reason
|
|
164
|
-
- the shared rule catalog, grouped cell table and total cells per axis
|
|
165
|
-
- the applied pack list (absolute paths)
|
|
166
|
-
- the two completion criteria with their actual numbers
|
|
84
|
+
Preserve the complete rule catalog, grouped cells and every exclusion with its
|
|
85
|
+
reason in the census file. Keep the applied pack paths with that review's
|
|
86
|
+
evidence. Every invocation still receives its complete assigned census through typed materialization.
|
|
167
87
|
|
|
168
|
-
|
|
88
|
+
Before Step 3, summarize the fixed comparison range, cell counts per axis,
|
|
89
|
+
included/excluded file counts and exclusion categories, applied packs, and the
|
|
90
|
+
two completion criteria with their actual numbers. Link the complete census and
|
|
91
|
+
pack list rather than reprinting their tables in chat. Report a large census's
|
|
92
|
+
size without truncation; dispatch follows the [existing authorization](../SKILL.md#authorization-and-recovery), not a size-only confirmation.
|
|
@@ -1,58 +1,57 @@
|
|
|
1
1
|
# Review calibration — verdicts, severity, and the report
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
This file owns verdict fields, grading and report layout; [SKILL.md](../SKILL.md) owns execution and adjudication, and [census rules](census-rules.md) own targets and IDs. Read this captured copy and selected frozen rule bodies delivered with the invocation. Source paths identify provenance, not permission to replace frozen guidance with a mutable installation.
|
|
4
4
|
|
|
5
5
|
## One verdict per cell
|
|
6
6
|
|
|
7
|
-
Return
|
|
7
|
+
Return one [compact coverage](#compact-rule-coverage) row per assigned cell. Do not repeat clean summaries elsewhere. Return detailed finding records in census order, one record per finding even when several share a cell:
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
| Fields | Content |
|
|
10
|
+
|---|---|
|
|
11
|
+
| `cell`, `id`, `verdict`, `rule` | the census's `target × axis`, a unique finding ID, `finding`, and the violated rule spelled as its pack spells it |
|
|
12
|
+
| `line`, `snippet` | a location this diff changed and its verbatim code; use the source-side forms below |
|
|
13
|
+
| `kind`, `failure`, `impact` | `execution-error` with a reachable wrong result in `failure`, or `design-violation` with a concrete consequence in `impact` |
|
|
14
|
+
| `severity`, `timing` | the grade and `now` or `park` under the rubric below |
|
|
15
|
+
| `evidence` | opened `path:line` locations, including definitions needed to establish the claim |
|
|
16
|
+
| `note` | 1–2 sentences stating the problem and a concrete fix |
|
|
10
17
|
|
|
11
|
-
|
|
12
|
-
- cell: src/orders/pricing.py × structural
|
|
13
|
-
verdict: finding
|
|
14
|
-
id: F-001
|
|
15
|
-
kind: design-violation
|
|
16
|
-
rule: DRY
|
|
17
|
-
line: 42
|
|
18
|
-
severity: must-fix
|
|
19
|
-
timing: now
|
|
20
|
-
snippet: `discount = subtotal * 0.15 if tier == "gold" else 0`
|
|
21
|
-
impact: the same tier-to-rate decision has two homes; changing the gold rate requires coordinating both implementations.
|
|
22
|
-
evidence: `domain/tiers.py:18`
|
|
23
|
-
note: The same tier→rate table is already in `domain/tiers.py:18`; a rate change now has two homes. Call the existing lookup instead of re-expressing it here.
|
|
24
|
-
```
|
|
18
|
+
Do not omit a real finding to shorten the result. Unread definitions, unavailable evidence and unaccounted rules remain unevaluated, never clean or low-severity findings. Report the blocker and follow [Step 3.5](../SKILL.md#step-35--audit-the-coverage).
|
|
25
19
|
|
|
26
|
-
|
|
20
|
+
## Source citations
|
|
27
21
|
|
|
28
|
-
|
|
22
|
+
Use repository-relative `path:line` at the frozen head by default and `base:path:line` for removed base lines. An empty regular file permits `path:0` with an empty snippet; it is a file-level anchor. A deletion within a surviving file may also use its head anchor before the cut. Read snippets at their declared side and trace surviving callers and contracts at the head.
|
|
29
23
|
|
|
30
|
-
|
|
24
|
+
These forms apply to finding bodies, coverage Evidence and G2/G3/G5 observations. `check-lines` checks changed finding anchors; `check-coverage --base` checks source existence and permits line 0 only for an empty regular file. A coverage anchor need not itself be a changed line.
|
|
31
25
|
|
|
32
|
-
|
|
26
|
+
Apply the policy's five simultaneous quality outcomes in the existing evidence and findings. Correctness does not excuse a coding-principle, performance, safety or security failure. Missing required execution or a necessary performance bound remains unverified, not a clean guarantee. Explain evidence-backed inapplicability without adding new verdict rows. The coverage parser validates accounting and anchors; the lead judges these semantic claims against source and execution evidence.
|
|
33
27
|
|
|
34
28
|
## Severity and points
|
|
35
29
|
|
|
30
|
+
Use `prompts/coding-preflight/review-rules.json` and its `gradingReference` as
|
|
31
|
+
the shared implementation/verifier/review baseline. The rubric below renders
|
|
32
|
+
those meanings for this report. A restrictive approved plan is not a rule waiver;
|
|
33
|
+
return the concrete plan conflict instead of downgrading a current violation.
|
|
34
|
+
|
|
36
35
|
| Severity | Meaning | Points |
|
|
37
36
|
|---|---|---|
|
|
38
37
|
| `must-fix` | a defect, or a rule violation that will cost real work later — wrong behavior, a swallowed error, a duplicated decision, a self-mocked test that proves nothing | 3 |
|
|
39
|
-
| `should-fix` |
|
|
38
|
+
| `should-fix` | an explicit applicable project rule breach or evidenced design or maintenance impact without immediate breakage — a name that hides units callers need, business policy placed against the declared architecture | 2 |
|
|
40
39
|
| `nit` | real but small; the fix is cheap and obviously better | 1 |
|
|
41
40
|
|
|
42
|
-
Grade the established consequence, not your confidence. An unsupported candidate is not a finding; incomplete inspection remains a coverage gap.
|
|
41
|
+
Grade the established consequence, not your confidence or a preferred style. Function length, nesting depth, numeric literals and alternative names alone do not establish a finding. An unsupported candidate is not a finding; incomplete inspection remains a coverage gap.
|
|
43
42
|
|
|
44
43
|
## Separate execution errors from design violations
|
|
45
44
|
|
|
46
45
|
- `execution-error`: establish a reachable input or state, the expected behavior, and the actual wrong result in `failure`, supported by opened code in `evidence`.
|
|
47
|
-
- `design-violation`: identify the applicable
|
|
46
|
+
- `design-violation`: identify the applicable rule, quote the violating code, and establish an explicit applicable project requirement or concrete design or maintenance consequence in `impact`, supported by `evidence`. A runtime failure is not required.
|
|
48
47
|
|
|
49
48
|
Both kinds carry a concrete fix. An axis does not determine the kind. Severity and timing are independent of kind: a design violation can be `should-fix` and `now` even when current outputs are correct. Neither an alternative implementation nor a preferred name alone establishes a violation. An unreachable defensive scenario does not establish an execution error. The orchestrator checks these criteria in Step 3.7; semantic correctness is a review judgment, not a machine-validated guarantee.
|
|
50
49
|
|
|
51
50
|
## Compact rule coverage
|
|
52
51
|
|
|
53
|
-
Every current response and gap-fill copies the
|
|
52
|
+
Every current response and gap-fill copies the literal `Review base:`, `Review head:` and `Review rules:` lines from `code-review scope` exactly once outside tables. Append `## Review Dependencies` with `Cell | Inputs` columns: list literal repository-relative paths separated by semicolons, including the target and every inspected caller, callee, outcome consumer, test and contract, with transitive dependencies. Paths represent whole files, not line ranges. External policies go in the scope command's `--policy` inputs.
|
|
54
53
|
|
|
55
|
-
For inherited
|
|
54
|
+
For inherited cells, retain prior rule statuses and observations, record their input paths, and append `## Review Carry` with `Cell | Previous head | Boundary evidence` columns. Identify the current inspected delta/caller/test boundary supporting each inheritance; an unchanged-source claim alone is insufficient. Follow [inspection scope and briefing](../SKILL.md#inspection-scope-and-briefing) for the reuse decision.
|
|
56
55
|
|
|
57
56
|
Return one compact Coverage Verdicts row per cell under `## Coverage Verdicts`. Keep detailed prose for findings; normal checks share one inspected source location. Rule IDs refer to the shared catalog, not to individual pack bullets.
|
|
58
57
|
|
|
@@ -65,19 +64,19 @@ Return one compact Coverage Verdicts row per cell under `## Coverage Verdicts`.
|
|
|
65
64
|
| C-CR-0003 | - | T1=no state mutation; T2=non-test source; T3=non-test source; T4=no tests or new branches | - | src/orders/schema.py:1 |
|
|
66
65
|
```
|
|
67
66
|
|
|
68
|
-
|
|
67
|
+
`Checked` means inspected with no actionable finding. A criterion includes all applicable subconditions; one inapplicable bullet does not make the whole criterion N/A. List every expected ID exactly once across `Checked`, `N/A` (`rule=reason`) and `Findings` (`rule=finding-id`). `all`, counts and ID ranges are invalid. Separate assignments with semicolons and finding IDs for one rule with commas; only a semicolon before the next `RULE=` starts a new assignment. Use `-` for empty fields and never infer omitted rules as clean.
|
|
69
68
|
|
|
70
|
-
Every row supplies one literal repository-relative source `path:line` for that cell's target file. The citation may be backtick-quoted and followed by
|
|
69
|
+
Every row supplies one literal repository-relative source `path:line` for that cell's target file. The citation may be backtick-quoted and followed by a short observation, separated by a space or ` — `, before any ` :: ` rule observations. A bare citation remains valid. Do not use line ranges or substitute a rule-pack citation such as `cc:5`, a global alias such as `E01`, or another target's path. The checker verifies the declared source side and location; `base:` requires the frozen `--base`, and line 0 requires an empty regular file. These explicit forms override the head-line default above. Additional definitions and evidence remain in finding bodies. `review_verdicts.py` enforces the source grammar; `tests/verification/test_design_review.py` covers described anchors and invalid source rejection.
|
|
71
70
|
|
|
72
|
-
For `general` cells, checked G2, G3 and G5 each carry a compact observation in that same Evidence field: `target/path:line :: G2=source/path:line observed outcome mapping; G3=source/path:line observed
|
|
71
|
+
For `general` cells, checked G2, G3 and G5 each carry a compact observation in that same Evidence field: `target/path:line :: G2=source/path:line observed outcome mapping; G3=source/path:line observed input path through access checks, sinks, disclosure and work bounds; G5=source/path:line applicable clauses and observed conformance`. Each observation begins with an existing project-source citation; it may cite a relevant callee. Keep rule-pack references in the catalog or the observation text, not in the project-source citation slot. Separate assignments with semicolons; the same `RULE=` boundary applies, so a semicolon inside an observation stays part of it. Findings and reasoned N/A already explain their criteria and need no duplicate clean observation.
|
|
73
72
|
|
|
74
|
-
|
|
73
|
+
Inspect before compressing results into rows. G2 observations trace possible dependency outcomes into returned tags, diagnostics and errors. G3 observations trace outside-process input through access checks, sinks and disclosure, and the bounds applied before expensive work (changed loops, downstream scans, parsing, allocation); a type-only callee change does not remove amplified caller work. G5 observations identify each applicable normative clause and observed conformance, independently of passing tests or linters. Trace shared predicates before calling similar orchestration duplicated policy.
|
|
75
74
|
|
|
76
|
-
|
|
75
|
+
`checked`, `clean` and `no issues` alone are verdict labels, not observations. `review_verdicts.py::_checked_rule_evidence` rejects missing observations, notes for unchecked criteria and invalid source locations. It validates structure and source existence, not the observation's truth.
|
|
77
76
|
|
|
78
77
|
A finding ID names a body outside this section, in this reviewer's original or gap-fill result. N/A reasons are short inline applicability explanations, not aliases or rule references. Missing sources, unread rules and blocked inspection remain unaccounted checks and name their blocker. A partial row is rejected with the missing rule IDs; gap-fill rechecks that grouped cell, not every individual rule as a separate output row.
|
|
79
78
|
|
|
80
|
-
The
|
|
79
|
+
The lead checks semantic truth and applicability under [Steps 3.5–3.7](../SKILL.md#step-35--audit-the-coverage).
|
|
81
80
|
|
|
82
81
|
## Timing — `now` or `park`
|
|
83
82
|
|
|
@@ -94,15 +93,9 @@ Every finding carries `timing`. For `now`, establish either an execution error o
|
|
|
94
93
|
- **The rule does not apply to this cell.** Record the rule ID and applicability reason under `N/A`; other rules in the row may still be checked.
|
|
95
94
|
- **The change is mechanical for this rule.** A behavior-preserving signature-only or type-annotation-only edit does not reopen unrelated body-level rules. Leave pre-existing naming issues outside the review. A behavior change can make an unchanged name misleading; review that newly introduced mismatch against the applicable naming rule and anchor the finding on the changed behavior.
|
|
96
95
|
|
|
97
|
-
**The hedge test breaks a borderline `must-fix` or `should-fix`.** At those two severities the finding is one you would defend without qualifiers. If your draft note reaches for a softener that questions whether the point is worth raising at all — "marginal", "arguably", "if you are touching it anyway" — you are looking at a `nit` or at nothing: downgrade it or verdict `clean`, but never ship a hedged `should-fix`.
|
|
98
|
-
|
|
99
|
-
The test does not empty the `nit` tier. A `nit` says the defect is small because that is the tier's definition, not because the reviewer is hedging — it still names a concrete defect on a changed line and a concrete fix.
|
|
100
|
-
|
|
101
96
|
## Every finding carries its fix
|
|
102
97
|
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
- **Readability findings** carry a pseudocode sketch — 4 to 6 lines that convey the intended reading experience, not a full refactor. If the sketch does not make a reader think "yes, that reads like prose", rewrite the sketch.
|
|
98
|
+
- **Readability findings** identify the concrete comprehension or maintenance problem and carry a short pseudocode sketch showing how the fix addresses it.
|
|
106
99
|
- **Naming findings** carry a concrete alternative name, and one clause saying what the new name encodes that the old one did not.
|
|
107
100
|
- **Structural findings** name the destination: which layer, module, or existing symbol the code should move to or call.
|
|
108
101
|
|
|
@@ -112,7 +105,7 @@ Loose typing in test files (`any`, dynamic casts, untyped fixtures) is a **typin
|
|
|
112
105
|
|
|
113
106
|
## The report
|
|
114
107
|
|
|
115
|
-
|
|
108
|
+
After [the team audits](../SKILL.md#audit-each-team-then-compare-teams) and [adjudication](../SKILL.md#step-37--settle-the-findings), write `reviewPath` using Step 1's values and dispatched slots. Keep this frontmatter order, with `taskKey` and `stage` only in stage mode and `branch` only in branch mode. `baseCommit` and `headCommit` name the current comparison range, not a separate PR merge base.
|
|
116
109
|
|
|
117
110
|
```yaml
|
|
118
111
|
mode: stage | branch
|
|
@@ -127,33 +120,16 @@ packs: [<applied coding-preflight pack paths>]
|
|
|
127
120
|
generatedAt: <YYYY-MM-DD HH:MM>
|
|
128
121
|
```
|
|
129
122
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
```
|
|
133
|
-
## Coverage
|
|
134
|
-
## Must-fix
|
|
135
|
-
## Should-fix
|
|
136
|
-
## Nits
|
|
137
|
-
## Parked
|
|
138
|
-
## Rejected
|
|
139
|
-
## Score
|
|
140
|
-
```
|
|
123
|
+
Use these level-two sections in order: `Coverage`, `Must-fix`, `Should-fix`, `Nits`, `Parked`, `Rejected`, `Score`. Omit empty sections except `Coverage` and `Score`.
|
|
141
124
|
|
|
142
125
|
- **Must-fix / Should-fix / Nits** — confirmed `now` findings only.
|
|
143
126
|
- **Parked** — `park` findings, with their severity, not scored.
|
|
144
127
|
- **Rejected** — findings the orchestrator's adjudication disproved or that cite no changed line: the reviewer's claim in one line, then the contradicting `path:line` and what it shows. Not scored.
|
|
145
128
|
|
|
146
|
-
- **Coverage** — the
|
|
129
|
+
- **Coverage** — record the fixed range, PR merge-target branch/base, review kind, supporting impact paths and prior head/report where applicable; apply the ledger rules in [follow-up decisions](../SKILL.md#follow-up-decisions). List changed-file and per-axis cell counts, exclusions with reasons, applied/unavailable packs, selected team/specialist assignments, expected/covered cells and rule IDs per specialist, empty-specialist acknowledgments and each team's full-census audit. Preserve verified specialist-to-team-to-final provenance, settlement outcomes and gap-fill rounds. State complete or incomplete and list every unevaluated pair with team, specialist and blocker under [Step 3.5](../SKILL.md#step-35--audit-the-coverage); those checks have no kind, grade, timing or points. On follow-ups distinguish inspected/inherited cells, scope fallback/expansion reasons and new-finding origins. Never label inherited cells newly inspected or rule flags independent targets.
|
|
147
130
|
- **Test evidence inside Coverage** — record each shared test command, tested head, environment, exit code and log path, identifying reused results and their matching inputs. Distinguish test-source inspection from actual execution. State failed, missing or blocked required checks; a completed code inspection does not imply the implementation passed its release gate. Do not claim an unexecuted test passed or count duplicate reviewer runs as independent evidence.
|
|
148
|
-
- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator`
|
|
149
|
-
- **Score** —
|
|
150
|
-
|
|
151
|
-
```
|
|
152
|
-
| # | Location | Rule | Severity | Points |
|
|
153
|
-
|---|---|---|---|---|
|
|
154
|
-
| 1 | `src/orders/pricing.py:42` | DRY | must-fix | 3 |
|
|
155
|
-
| | | | **Total** | **3** |
|
|
156
|
-
```
|
|
131
|
+
- **Findings** — each one opens with `` `path/to/file.py:42` `` + the verdict's `rule` name + `kind` + severity + points, then the snippet as a blockquote, then the 1–2 sentence note with its fix, the execution `failure` or design `impact`, and supporting `evidence`. Its note then says how it was settled: `agreed`, `graded by orchestrator`, or `confirmed by orchestrator`. Any grade correction retains every reporting reviewer's severity/timing pair, the final pair, the applicable rubric and the source-cited impact or scope reason. A corrected grade may differ from every reported value; the original responses remain immutable.
|
|
132
|
+
- **Score** — use `# | Location | Rule | Severity | Points` columns. Count each confirmed `now` finding once after citation and evidence checks, using the severity points above. End with a Total row, including Total 0 when there are no scored findings. Parked, rejected and unevaluated checks do not score; Total 0 does not make an incomplete review clean.
|
|
157
133
|
|
|
158
134
|
The report's prose is written in the `Report language` the target CLI returned (the project's `reportLanguage`). Paths, identifiers, rule names, and quoted code stay verbatim.
|
|
159
135
|
|