okstra 0.231.0 → 0.232.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +15 -3
- package/dist/cli-registry.mjs +6 -0
- package/dist/cli-registry.mjs.map +1 -1
- package/dist/commands/memory/memory.mjs +9 -55
- package/dist/commands/memory/memory.mjs.map +1 -1
- package/dist/lib/memory-auto-register.d.mts +1 -0
- package/dist/lib/memory-auto-register.mjs +113 -0
- package/dist/lib/memory-auto-register.mjs.map +1 -0
- package/dist/lib/memory-entry-contract.d.mts +12 -0
- package/dist/lib/memory-entry-contract.mjs +46 -0
- package/dist/lib/memory-entry-contract.mjs.map +1 -0
- package/dist/lib/python-helper.d.mts +1 -1
- package/dist/lib/python-helper.mjs +3 -2
- package/dist/lib/python-helper.mjs.map +1 -1
- package/dist/lib/record-secrets.d.mts +1 -0
- package/dist/lib/record-secrets.mjs +28 -0
- package/dist/lib/record-secrets.mjs.map +1 -0
- package/dist/lib/types.d.mts +2 -1
- package/docs/architecture/storage-model.md +129 -2
- package/docs/architecture.md +11 -2
- package/docs/cli.md +234 -0
- package/docs/project-structure-overview.md +2 -1
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/agents/common.json +8 -8
- package/runtime/agents/roles/verifier.json +2 -4
- package/runtime/bin/okstra-provider-exec.py +10 -4
- package/runtime/prompts/coding-preflight/architectures/hexagonal.md +23 -30
- package/runtime/prompts/coding-preflight/authoring-checks.md +17 -0
- package/runtime/prompts/coding-preflight/clean-code.md +85 -281
- package/runtime/prompts/coding-preflight/frameworks/node-server.md +2 -3
- package/runtime/prompts/coding-preflight/languages/java.md +3 -5
- package/runtime/prompts/coding-preflight/languages/javascript-typescript.md +5 -12
- package/runtime/prompts/coding-preflight/languages/kotlin.md +2 -4
- package/runtime/prompts/coding-preflight/languages/python.md +2 -7
- package/runtime/prompts/coding-preflight/languages/rust.md +2 -8
- package/runtime/prompts/coding-preflight/languages/sql.md +2 -4
- package/runtime/prompts/coding-preflight/overview.md +25 -38
- package/runtime/prompts/coding-preflight/review-rules.json +30 -0
- package/runtime/prompts/duties/code-reviewer.json +15 -18
- package/runtime/prompts/duties/implementation-verifier.json +1 -0
- package/runtime/prompts/lead/convergence.md +3 -3
- package/runtime/prompts/lead/okstra-lead-contract.md +2 -2
- package/runtime/prompts/lead/report-writer.md +1 -1
- package/runtime/prompts/lead/team-contract.md +1 -1
- package/runtime/prompts/profiles/_clarification-recommendation.md +3 -2
- package/runtime/prompts/profiles/_coding-conventions-preflight.md +41 -6
- package/runtime/python/okstra_ctl/agent/invocation.py +121 -36
- package/runtime/python/okstra_ctl/agent/prompt_cli/cli.py +6 -0
- package/runtime/python/okstra_ctl/agent/prompt_cli/materialize.py +30 -4
- package/runtime/python/okstra_ctl/agent/standalone.py +3 -0
- package/runtime/python/okstra_ctl/analysis_packet.py +2 -19
- package/runtime/python/okstra_ctl/approval_decisions.py +16 -0
- package/runtime/python/okstra_ctl/attempt_evidence.py +10 -0
- package/runtime/python/okstra_ctl/business_flow/invocation.py +35 -3
- package/runtime/python/okstra_ctl/code_review_census.py +71 -7
- package/runtime/python/okstra_ctl/code_review_coverage.py +4 -274
- package/runtime/python/okstra_ctl/code_review_integrity.py +154 -0
- package/runtime/python/okstra_ctl/code_review_invocation.py +212 -0
- package/runtime/python/okstra_ctl/code_review_scope.py +36 -9
- package/runtime/python/okstra_ctl/code_review_target.py +85 -11
- package/runtime/python/okstra_ctl/consumers.py +12 -9
- package/runtime/python/okstra_ctl/convergence.py +112 -20
- package/runtime/python/okstra_ctl/convergence_engine.py +1 -0
- package/runtime/python/okstra_ctl/convergence_provenance.py +27 -11
- package/runtime/python/okstra_ctl/correction_round.py +6 -1
- package/runtime/python/okstra_ctl/design_review.py +207 -0
- package/runtime/python/okstra_ctl/design_review_evidence.py +297 -0
- package/runtime/python/okstra_ctl/dispatch_checkpoints.py +28 -5
- package/runtime/python/okstra_ctl/dispatch_core.py +3 -11
- package/runtime/python/okstra_ctl/doctor.py +8 -25
- package/runtime/python/okstra_ctl/doyouknow/__init__.py +9 -0
- package/runtime/python/okstra_ctl/doyouknow/cli.py +91 -0
- package/runtime/python/okstra_ctl/doyouknow/config.py +58 -0
- package/runtime/python/okstra_ctl/doyouknow/contracts.py +184 -0
- package/runtime/python/okstra_ctl/doyouknow/identity.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/paths.py +22 -0
- package/runtime/python/okstra_ctl/doyouknow/pending.py +72 -0
- package/runtime/python/okstra_ctl/doyouknow/registration.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/source_contracts.py +128 -0
- package/runtime/python/okstra_ctl/doyouknow/source_store.py +172 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/io.py +36 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/manager.py +261 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/memory.py +179 -0
- package/runtime/python/okstra_ctl/doyouknow/sources/task.py +95 -0
- package/runtime/python/okstra_ctl/doyouknow/store.py +260 -0
- package/runtime/python/okstra_ctl/doyouknow/sync.py +58 -0
- package/runtime/python/okstra_ctl/execution_mutation_audit.py +18 -2
- package/runtime/python/okstra_ctl/file_size_cap.py +3 -4
- package/runtime/python/okstra_ctl/json_boundary.py +21 -2
- package/runtime/python/okstra_ctl/jsonl.py +21 -0
- package/runtime/python/okstra_ctl/manager_cli.py +26 -0
- package/runtime/python/okstra_ctl/manager_registration.py +29 -0
- package/runtime/python/okstra_ctl/manager_sync.py +3 -22
- package/runtime/python/okstra_ctl/model_io/renderers.py +13 -2
- package/runtime/python/okstra_ctl/model_io_cli.py +7 -1
- package/runtime/python/okstra_ctl/phases/final_verification/validation.py +20 -0
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-deliverable.md +12 -2
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-diff-review.md +19 -6
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-self-check.md +5 -3
- package/runtime/python/okstra_ctl/phases/implementation/instructions/_implementation-verifier.md +39 -11
- package/runtime/python/okstra_ctl/phases/implementation/report_assets/implementation.template.html +13 -0
- package/runtime/python/okstra_ctl/phases/implementation/spec.md +26 -1
- package/runtime/python/okstra_ctl/phases/implementation/validation.py +86 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +4 -0
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +1 -1
- package/runtime/python/okstra_ctl/report_assembly.py +15 -0
- package/runtime/python/okstra_ctl/report_narrative.py +3 -0
- package/runtime/python/okstra_ctl/report_prose_keys.py +7 -0
- package/runtime/python/okstra_ctl/report_synthesis_packet.py +19 -2
- package/runtime/python/okstra_ctl/review_policy.py +359 -0
- package/runtime/python/okstra_ctl/review_verdicts.py +291 -0
- package/runtime/python/okstra_ctl/run.py +24 -1
- package/runtime/python/okstra_ctl/stage_done.py +11 -0
- package/runtime/python/okstra_ctl/standalone_review_audit.py +28 -0
- package/runtime/python/okstra_ctl/team.py +3 -1
- package/runtime/python/okstra_ctl/verification_generation.py +23 -1
- package/runtime/python/okstra_ctl/verification_input_types.py +15 -1
- package/runtime/python/okstra_ctl/verification_inputs.py +28 -6
- package/runtime/python/okstra_ctl/verification_invocation.py +7 -1
- package/runtime/python/okstra_ctl/verification_target.py +2 -0
- package/runtime/python/okstra_ctl/worker_dispatch.py +3 -1
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +24 -9
- package/runtime/python/okstra_ctl/worker_runner.py +66 -10
- package/runtime/python/okstra_ctl/wrapper_status.py +16 -0
- package/runtime/python/okstra_ctl/write_policy.py +34 -1
- package/runtime/python/okstra_project/__init__.py +2 -0
- package/runtime/python/okstra_project/dirs.py +18 -0
- package/runtime/python/okstra_project/state.py +25 -20
- package/runtime/schemas/doyouknow-config-v1.schema.json +20 -0
- package/runtime/schemas/doyouknow-v1.schema.json +65 -0
- package/runtime/schemas/final-report-v2.0.schema.json +157 -0
- package/runtime/schemas/final-report-v3.0.schema.json +157 -0
- package/runtime/schemas/memory-entry-contract-v1.json +11 -0
- package/runtime/schemas/record-secret-patterns.json +41 -0
- package/runtime/skills/okstra-code-review/SKILL.md +71 -123
- package/runtime/skills/okstra-code-review/references/census-rules.md +29 -105
- package/runtime/skills/okstra-code-review/references/review-calibration.md +34 -54
- package/runtime/skills/okstra-manager/SKILL.md +7 -0
- package/runtime/skills/okstra-memory/SKILL.md +7 -0
- package/runtime/templates/implementation-worker-preamble.md +4 -9
- package/runtime/templates/worker-prompt-preamble.md +4 -12
- package/runtime/validators/validate-run.py +17 -8
|
@@ -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 coordinator or specialty subset; 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-one-to-three-model-teams-with-six-specialists-each).
|
|
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 coordinator 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 the specialty 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. If the census is large,
|
|
92
|
+
report its size and confirm dispatch without truncating the stored worklist.
|
|
@@ -1,38 +1,37 @@
|
|
|
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 |
|
|
@@ -44,15 +43,15 @@ Grade the established consequence, not your confidence. An unsupported candidate
|
|
|
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 pack rule, quote the violating code, and describe its concrete design or maintenance consequence in `impact`, supported by `evidence`. A runtime failure is not required.
|
|
46
|
+
- `design-violation`: identify the applicable pack rule, quote the violating code, and describe its 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
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 workload and bound; 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 account for each input dimension, changed loops and downstream scans, parsing or allocation, with bounds before expensive work; 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
|
|
|
@@ -100,9 +99,7 @@ The test does not empty the `nit` tier. A `nit` says the defect is small because
|
|
|
100
99
|
|
|
101
100
|
## Every finding carries its fix
|
|
102
101
|
|
|
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.
|
|
102
|
+
- **Readability findings** carry a 4–6-line pseudocode sketch demonstrating the clearer flow, not a full refactor.
|
|
106
103
|
- **Naming findings** carry a concrete alternative name, and one clause saying what the new name encodes that the old one did not.
|
|
107
104
|
- **Structural findings** name the destination: which layer, module, or existing symbol the code should move to or call.
|
|
108
105
|
|
|
@@ -112,7 +109,7 @@ Loose typing in test files (`any`, dynamic casts, untyped fixtures) is a **typin
|
|
|
112
109
|
|
|
113
110
|
## The report
|
|
114
111
|
|
|
115
|
-
|
|
112
|
+
After [consolidation](../SKILL.md#consolidate-within-each-model-then-across-models) 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
113
|
|
|
117
114
|
```yaml
|
|
118
115
|
mode: stage | branch
|
|
@@ -127,33 +124,16 @@ packs: [<applied coding-preflight pack paths>]
|
|
|
127
124
|
generatedAt: <YYYY-MM-DD HH:MM>
|
|
128
125
|
```
|
|
129
126
|
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
```
|
|
133
|
-
## Coverage
|
|
134
|
-
## Must-fix
|
|
135
|
-
## Should-fix
|
|
136
|
-
## Nits
|
|
137
|
-
## Parked
|
|
138
|
-
## Rejected
|
|
139
|
-
## Score
|
|
140
|
-
```
|
|
127
|
+
Use these level-two sections in order: `Coverage`, `Must-fix`, `Should-fix`, `Nits`, `Parked`, `Rejected`, `Score`. Omit empty sections except `Coverage` and `Score`.
|
|
141
128
|
|
|
142
129
|
- **Must-fix / Should-fix / Nits** — confirmed `now` findings only.
|
|
143
130
|
- **Parked** — `park` findings, with their severity, not scored.
|
|
144
131
|
- **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
132
|
|
|
146
|
-
- **Coverage** — the
|
|
133
|
+
- **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/specialty assignments, expected/covered cells and rule IDs per child, empty-specialty acknowledgments, each team's `(cell ID, rule ID)` union and coordinator audit. Preserve verified child-to-team-to-final provenance, settlement outcomes and gap-fill rounds. State complete or incomplete and list every unevaluated pair with team, specialty 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
134
|
- **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
|
-
```
|
|
135
|
+
- **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.
|
|
136
|
+
- **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
137
|
|
|
158
138
|
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
139
|
|
|
@@ -54,6 +54,13 @@ okstra manager view --manager-id <manager-id>
|
|
|
54
54
|
|
|
55
55
|
## Removal Rule
|
|
56
56
|
|
|
57
|
+
Successful native state changes also register that manager's saved sources in
|
|
58
|
+
doyouknow when automatic registration is enabled. Read commands and removal dry
|
|
59
|
+
runs do not register anything. A registration warning leaves the original command
|
|
60
|
+
successful; recover with `okstra doyouknow retry --source manager` or
|
|
61
|
+
`okstra doyouknow sync --source manager`. Do not replay a state change solely to
|
|
62
|
+
repair its graph registration.
|
|
63
|
+
|
|
57
64
|
`remove project`, `remove task`, `remove task-group` and `task remove-child` change nothing without `--confirm`; they print what would be removed (`Removed: no — dry run`). Run the command without `--confirm` first, show the user the listed project, path, tasks or kept children, and rerun with `--confirm` only after the user approves that exact target. These commands touch manager files only; project `.okstra/` state and briefs written by `task split` stay.
|
|
58
65
|
|
|
59
66
|
- `task status` shows the snapshot as of `Synced at` with its `Sync age`; a child marked `changed since sync: yes` has a project task manifest written after that sync, so run `task sync` before reporting its state.
|
|
@@ -94,6 +94,13 @@ okstra memory add --content "<summary markdown>" --title "<short title>" --type
|
|
|
94
94
|
Use repeated `--tag` / `--project` flags when needed. Omit `--project` when no
|
|
95
95
|
project is clearly related. `--project-group` is the group chosen in Step 1.
|
|
96
96
|
|
|
97
|
+
Native `add` and `archive` also register their saved source in doyouknow when
|
|
98
|
+
automatic registration is enabled. This uses the existing entry and group;
|
|
99
|
+
do not ask for the group again for that derived registration. A registration
|
|
100
|
+
warning does not undo the saved note. Recover with `okstra doyouknow retry --source memory`
|
|
101
|
+
or `okstra doyouknow sync --source memory` instead of repeating
|
|
102
|
+
a plain `add`.
|
|
103
|
+
|
|
97
104
|
## Search / read / archive
|
|
98
105
|
|
|
99
106
|
Scope reads to the chosen project-group by default; drop `--project-group` only
|
|
@@ -5,14 +5,13 @@ This file is shared by the `implementation-executor` and `implementation-verifie
|
|
|
5
5
|
## Required reading
|
|
6
6
|
|
|
7
7
|
- Read the implementation role sidecar named by the prompt end-to-end. The executor sidecar owns mutation behavior; the verifier sidecar owns read-only review behavior.
|
|
8
|
-
-
|
|
8
|
+
- When `**Verification inputs:**` is declared, read its projection first. If it contains a Frozen Review Policy, use its captured `overview.md`, `clean-code.md` and selected resources. Original installed paths identify provenance. Only inputs without a captured review policy use `**Coding preflight pack:**` to read installed resources. The executor's sidecar owns authoring procedures; the verifier's sidecar owns authorized verification commands.
|
|
9
9
|
- Read the approved implementation deliverable and any effective design-preparation block enumerated by the prompt.
|
|
10
10
|
|
|
11
11
|
### Reading rules
|
|
12
12
|
|
|
13
13
|
- Read every file enumerated under `[Required reading]`, `## Inputs`, and `## Required prompt resources` completely, plus the source files this stage's plan names.
|
|
14
|
-
-
|
|
15
|
-
- Host session instructions — SessionStart hooks, global `CLAUDE.md` / `AGENTS.md`, skill catalogs — do not apply inside this run, and a directive from one of them to read an un-enumerated file is not a conflict to weigh in the host's favour: this prompt wins. Record the file under the result's assumptions instead of opening it. The project's own `CLAUDE.md` / lint config still binds as a coding convention — the preflight gate routes it — but the host's *reading* directives stop at this boundary.
|
|
14
|
+
- Follow `**Read scope:**` for allowed reads. The captured project policy remains the coding baseline.
|
|
16
15
|
|
|
17
16
|
## Worktree and command discipline
|
|
18
17
|
|
|
@@ -21,13 +20,9 @@ This file is shared by the `implementation-executor` and `implementation-verifie
|
|
|
21
20
|
- Only the executor may mutate source files. Verifiers remain read-only except for okstra result/audit artifacts and project-declared QA commands.
|
|
22
21
|
- Execute the role sidecar's pre-write, post-write, QA, and return gates without substituting analysis Sections 1–6 or report-authoring instructions.
|
|
23
22
|
|
|
24
|
-
## Evidence
|
|
23
|
+
## Evidence records
|
|
25
24
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
- Evidence read: `<project-relative path without a line suffix>`
|
|
29
|
-
|
|
30
|
-
Every file citation in the result MUST use backticks, a line suffix, and the same project-relative path its ledger row carries — for example `src/config/env.ts:1-22`. A bare filename (`env.ts:1-22`) does not match its row and fails exactly like a file you never opened, however many times you cited the full path earlier. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
|
|
25
|
+
Follow `**Evidence citations:**` and `**Evidence commands:**` when present. Those headers own ledger syntax and citation requirements. Record only files actually opened and commands actually executed.
|
|
31
26
|
|
|
32
27
|
## Injected paths
|
|
33
28
|
|
|
@@ -10,22 +10,14 @@ Read `analysis-packet.md`, the primary compact input, end-to-end. Source files n
|
|
|
10
10
|
|
|
11
11
|
### Reading rules
|
|
12
12
|
|
|
13
|
-
- Read every file enumerated under `[Required reading]` or `## Inputs` completely
|
|
13
|
+
- Read every file enumerated under `[Required reading]` or `## Inputs` completely. When present, follow `**Analysis packet reading:**` for page limits and record the boundaries.
|
|
14
14
|
- Write Reading Confirmation to `**Audit sidecar path:**`, never to the main worker-results file. A `## 0. Reading Confirmation` heading in the main result is invalid.
|
|
15
|
-
-
|
|
15
|
+
- Follow `**Read scope:**` for allowed reads.
|
|
16
16
|
- Resolve every `.okstra/...` path against `**Project Root:**`, including when a worktree is present.
|
|
17
17
|
|
|
18
|
-
## Evidence
|
|
18
|
+
## Evidence records
|
|
19
19
|
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
- Evidence read: `<project-relative path without a line suffix>`
|
|
23
|
-
|
|
24
|
-
Every file citation in the result MUST use backticks, a line suffix, and the same project-relative path its ledger row carries — for example `src/config/env.ts:1-22`. A bare filename (`env.ts:1-22`) does not match its row and fails exactly like a file you never opened, however many times you cited the full path earlier. A cited path without a matching ledger row fails Phase 7 in `validators/validate-run.py` `validate_worker_results_audit()`. Do not add a row for a file you did not open.
|
|
25
|
-
|
|
26
|
-
## Evidence command ledger
|
|
27
|
-
|
|
28
|
-
Follow the `**Evidence commands:**` header in the dispatch prompt. That header is the worker-facing rule.
|
|
20
|
+
Follow `**Evidence citations:**` and `**Evidence commands:**` when present. Those headers own ledger syntax and citation requirements. Record only files actually opened and commands actually executed.
|
|
29
21
|
|
|
30
22
|
## Injected paths
|
|
31
23
|
|
|
@@ -180,7 +180,6 @@ from okstra_ctl.phases.implementation_planning.plan_body import (
|
|
|
180
180
|
from okstra_ctl.phases.error_analysis.validation import _validate_error_analysis_consistency
|
|
181
181
|
from okstra_project import project_json_path # noqa: E402
|
|
182
182
|
from okstra_project.dirs import tasks_root as _okstra_tasks_root # noqa: E402
|
|
183
|
-
from okstra_project.resolver import resolve_architecture # noqa: E402
|
|
184
183
|
|
|
185
184
|
from okstra_ctl.conformance import (
|
|
186
185
|
conformance_entry_mismatches,
|
|
@@ -3308,6 +3307,12 @@ def validate_final_report_data(
|
|
|
3308
3307
|
validate_command_log_execution_evidence(
|
|
3309
3308
|
data, project_root, run_manifest_path, manifest, failures,
|
|
3310
3309
|
)
|
|
3310
|
+
try:
|
|
3311
|
+
from okstra_ctl.phases.final_verification.validation import validate_implementation_review_evidence
|
|
3312
|
+
|
|
3313
|
+
validate_implementation_review_evidence(project_root, run_manifest_path)
|
|
3314
|
+
except (OSError, ValueError) as exc:
|
|
3315
|
+
failures.append(f"design-review BLOCKING: {exc}")
|
|
3311
3316
|
elif task_type == "implementation-planning":
|
|
3312
3317
|
active_report_contracts = report_contracts or set()
|
|
3313
3318
|
planning = data.get("implementationPlanning") or {}
|
|
@@ -3354,9 +3359,16 @@ def validate_final_report_data(
|
|
|
3354
3359
|
_validate_approval_clarification_backtrace(data, failures)
|
|
3355
3360
|
_validate_rerun_guidance(data, failures)
|
|
3356
3361
|
_validate_approval_guidance(data, failures)
|
|
3362
|
+
try:
|
|
3363
|
+
from okstra_ctl.review_policy import read_review_architecture
|
|
3364
|
+
|
|
3365
|
+
architecture_style = read_review_architecture(_project_root_from_report(report_path), manifest)
|
|
3366
|
+
except (OSError, ValueError) as exc:
|
|
3367
|
+
failures.append(f"review-policy BLOCKING: {exc}")
|
|
3368
|
+
architecture_style = "undeclared"
|
|
3357
3369
|
_validate_variation_point_analysis(
|
|
3358
3370
|
(data.get("implementationPlanning") or {}).get("variationPointAnalysis"),
|
|
3359
|
-
|
|
3371
|
+
architecture_style,
|
|
3360
3372
|
failures,
|
|
3361
3373
|
)
|
|
3362
3374
|
if not selected_direction_contract:
|
|
@@ -3430,11 +3442,6 @@ def _validate_no_opaque_id_references(data: dict, failures: list[str]) -> None:
|
|
|
3430
3442
|
)
|
|
3431
3443
|
|
|
3432
3444
|
|
|
3433
|
-
# A stringified null is not prose. Lowercase `none` is a token the clarification
|
|
3434
|
-
# option contract uses on purpose ("reverses nothing"), so only the capitalised
|
|
3435
|
-
# and language-native spellings count — 2026-09-05 audit: `"None"` in 16
|
|
3436
|
-
# trade-off cells and 2 option fields across the shipped reports.
|
|
3437
|
-
_NULL_LITERALS = frozenset({"None", "null", "undefined", "NaN"})
|
|
3438
3445
|
_FINDING_REF_RE = re.compile(r"^F-\d{3,}$")
|
|
3439
3446
|
# Citation lists the human page renders as links or plain text.
|
|
3440
3447
|
_CITATION_LIST_KEYS = ("evidenceRefs", "supportingEvidence", "falsifyingEvidenceChecked")
|
|
@@ -3462,10 +3469,12 @@ def _validate_no_null_literals_in_prose(data: dict, failures: list[str]) -> None
|
|
|
3462
3469
|
`None` under Test cost and Rollout cost. An empty value is spelled by
|
|
3463
3470
|
omitting the field or leaving it empty, never by naming the language's
|
|
3464
3471
|
null."""
|
|
3472
|
+
from okstra_ctl.report_prose_keys import NULL_LITERALS
|
|
3473
|
+
|
|
3465
3474
|
offenders = [
|
|
3466
3475
|
f"{pointer} = {value.strip()!r}"
|
|
3467
3476
|
for pointer, value in _prose_pointers(data)
|
|
3468
|
-
if value.strip() in
|
|
3477
|
+
if value.strip() in NULL_LITERALS
|
|
3469
3478
|
]
|
|
3470
3479
|
if offenders:
|
|
3471
3480
|
failures.append(
|