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,47 +1,33 @@
|
|
|
1
1
|
# Clean Code Principles (language-agnostic)
|
|
2
2
|
|
|
3
|
-
Apply these on every change.
|
|
3
|
+
Apply these on every change using the policy precedence in `overview.md`: explicit repository instructions and declared architecture, this common resource pack, then surrounding code conventions. Personal preference and existing violations do not waive an applicable rule.
|
|
4
4
|
|
|
5
|
-
##
|
|
6
|
-
|
|
7
|
-
A second copy of the same logic is a signal to extract. Two callers of the same algorithm should call the same function.
|
|
5
|
+
## Five simultaneous quality outcomes
|
|
8
6
|
|
|
9
|
-
|
|
10
|
-
```javascript
|
|
11
|
-
let total = 0;
|
|
12
|
-
for (let i = 0; i < prices.length; i++) total += prices[i];
|
|
13
|
-
// later, elsewhere:
|
|
14
|
-
let t = 0;
|
|
15
|
-
for (let i = 0; i < prices.length; i++) t += prices[i];
|
|
16
|
-
```
|
|
7
|
+
Correctness, coding principles, performance, safety and security are separate acceptance conditions. Satisfying one does not waive another. Identify the applicable expectations from the approved acceptance conditions, project policy, callers and dependency contracts; retain them in the existing plan, validation commands and test evidence rather than creating another checklist artifact.
|
|
17
8
|
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
9
|
+
- **Correctness:** establish reachable inputs and states, the expected result and side effects, and the observable result that would distinguish a defect. Exercise relevant success, boundary and failure outcomes.
|
|
10
|
+
- **Coding principles:** apply the documented responsibility, reuse, dependency-direction, naming and language rules to the design before writing it, then to the actual diff. Correct outputs and passing tests do not excuse an applicable rule violation.
|
|
11
|
+
- **Performance:** identify the affected workload and any declared latency, throughput, memory, allocation or concurrency limits. Compare appropriate evidence with those limits and the relevant baseline. Reuse existing measurements and resource-bound tests; do not invent a universal benchmark for every helper. If a necessary bound or measurement is unavailable, report that part as unverified instead of claiming a performance guarantee.
|
|
12
|
+
- **Safety:** preserve the intended state and primary failure through partial success, cleanup failure, retries, cancellation and concurrent work. Trace which writes remain, whether replay duplicates an effect, and whether abandoned work can continue changing state.
|
|
13
|
+
- **Security:** follow untrusted input to its operations and outputs. Check operation-specific access, input and resource bounds, injection sinks and disclosure of secrets or personal data against the project's policy.
|
|
22
14
|
|
|
23
|
-
|
|
15
|
+
Select the existing shared-catalog criteria that own these checks: correctness and error semantics under G1/G2, coding principles under S/M/G5, performance under G4, state safety under T1 with G1/G2, and security under G3. These are inspection dimensions, not five new verdict rows or five additional reviewers. Cite a reason when a dimension does not apply; a missing required input is not evidence of inapplicability.
|
|
24
16
|
|
|
25
|
-
|
|
17
|
+
The author and assigned reviewers judge these outcomes from source and execution evidence. The grouped-verdict parser checks accounting and source anchors, not semantic truth; required command execution retains its existing evidence checks. Preserve failed, waived and unverified checks in the existing result fields. Do not claim all five outcomes verified from a complete table or a green test command alone.
|
|
26
18
|
|
|
27
|
-
|
|
28
|
-
- **Documented forks** — two deliberate variants of one capability kept as parallel implementations "because the delta is commented". If the delta is genuinely parametric (a few orthogonal options), collapse into one implementation with explicit option parameters; if not, split into two distinctly named capabilities. The commented fork itself is never the end state.
|
|
19
|
+
## DRY — Don't Repeat Yourself
|
|
29
20
|
|
|
30
|
-
|
|
21
|
+
Reuse or move an existing capability, including test helpers, rather than copying it. Extract shared logic when current callers implement the same capability and would change together; similar syntax or a hypothetical second caller is insufficient.
|
|
31
22
|
|
|
32
|
-
|
|
23
|
+
- Search touched domain enum values and predicates across queries, filters and branches, not only their identifiers. Consolidate a shared business decision into one named constant or query builder in the domain layer; leave independent decisions separate even when their literal values match.
|
|
24
|
+
- Read deliberate variants together. Consolidate genuinely parametric differences with explicit options when that simplifies the implementation. Otherwise retain distinctly named capabilities; a comment documenting the divergence does not justify duplicate implementations of one capability.
|
|
33
25
|
|
|
34
|
-
|
|
35
|
-
```javascript
|
|
36
|
-
const canSubmit = isReady ? true : false;
|
|
37
|
-
```
|
|
26
|
+
## KISS — Keep It Simple
|
|
38
27
|
|
|
39
|
-
|
|
40
|
-
```javascript
|
|
41
|
-
const canSubmit = isReady;
|
|
42
|
-
```
|
|
28
|
+
Choose the simplest direct solution meeting current requirements under `overview.md` precedence. Reuse-driven abstraction needs current callers; a local helper may name a cohesive step or separate abstraction levels with one caller.
|
|
43
29
|
|
|
44
|
-
|
|
30
|
+
Simplification preserves semantics: replace explicit null, undefined or empty-string checks with truthiness only when rejecting `0`, `false` and `NaN` is also intended.
|
|
45
31
|
|
|
46
32
|
## SOLID
|
|
47
33
|
|
|
@@ -51,320 +37,191 @@ Here `isReady` is already a boolean, so both versions preserve the same value. D
|
|
|
51
37
|
- **I**nterface Segregation — many small interfaces beat one fat one.
|
|
52
38
|
- **D**ependency Inversion — depend on abstractions, not concrete implementations.
|
|
53
39
|
|
|
54
|
-
Bad (SRP):
|
|
55
|
-
```python
|
|
56
|
-
class User:
|
|
57
|
-
def save(self): ...
|
|
58
|
-
def send_email(self, msg): ...
|
|
59
|
-
```
|
|
60
|
-
|
|
61
|
-
Good (SRP):
|
|
62
|
-
```python
|
|
63
|
-
class UserRepository:
|
|
64
|
-
def save(self, user): ...
|
|
65
|
-
|
|
66
|
-
class EmailService:
|
|
67
|
-
def send(self, user, msg): ...
|
|
68
|
-
```
|
|
69
|
-
|
|
70
40
|
## YAGNI — You Aren't Gonna Need It
|
|
71
41
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
Bad:
|
|
75
|
-
```javascript
|
|
76
|
-
function calculator(a, b, op) {
|
|
77
|
-
switch (op) {
|
|
78
|
-
case 'add': return a + b;
|
|
79
|
-
case 'multiply': return a * b; // not asked for
|
|
80
|
-
case 'divide': return a / b; // not asked for
|
|
81
|
-
}
|
|
82
|
-
}
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
Good:
|
|
86
|
-
```javascript
|
|
87
|
-
const add = (a, b) => a + b;
|
|
88
|
-
```
|
|
42
|
+
Add no speculative parameters, configuration, hooks, layers or pre-1.0 compatibility shims. Every new identifier serves a current internal use, established external contract, runtime entry point or explicit user requirement; cite that evidence rather than a hypothetical future consumer.
|
|
89
43
|
|
|
90
44
|
## Meaningful naming
|
|
91
45
|
|
|
92
|
-
Names reveal intent. `d` and `crtUsrAcct()` are bugs; `elapsedTimeInDays` and `createUserAccount()` are documentation.
|
|
93
|
-
|
|
94
46
|
### Names must be truthful
|
|
95
47
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
Flag and rename:
|
|
48
|
+
Names describe intent and actual behavior across branches:
|
|
99
49
|
|
|
100
|
-
- `get*` / `fetch*` / `find*`
|
|
101
|
-
- `is*` / `has*` / `can*`
|
|
102
|
-
-
|
|
103
|
-
- Names that describe the implementation, not the intent: `loopOverUsers` → `notifyActiveUsers`, `runQuery` → `listOverdueInvoices`.
|
|
104
|
-
- Names that say the opposite of what they do under some branch: `enableFoo` that disables when a flag is off, with no hint in the name.
|
|
50
|
+
- `get*` / `fetch*` / `find*` disclose caller-visible mutation or creation. Documented lookup failures and diagnostic logging alone do not invalidate a read name.
|
|
51
|
+
- `is*` / `has*` / `can*` return `false` for ordinary negative answers; operational failures may propagate under a documented contract.
|
|
52
|
+
- Name the operation's purpose rather than its loop or query mechanics, and disclose opposite actions under conditional branches.
|
|
105
53
|
|
|
106
54
|
### Names must stand alone
|
|
107
55
|
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
- Names missing the noun: `createPending()` → `createPendingInstallation()`. The verb is fine; the object is missing.
|
|
111
|
-
- Generic verbs with no information: `handle`, `process`, `execute`, `doStuff`, `manage`. If the function deletes-then-inserts, name it `replace`, not `update`.
|
|
112
|
-
- Constants that will collide with siblings later: `BUCKET` → `FONTS_BUCKET`, `TIMEOUT` → `HTTP_READ_TIMEOUT_MS`, `URL` → `AUTH_SERVICE_URL`.
|
|
113
|
-
- Repository / port methods named after the rule they enforce, not the data they fetch: `findValid*` / `findActive*` / `findEligible*` — the adjective encodes a business rule the caller can't inspect from the name. Prefer `findDesktopLibrariesForUser(userId)` + a domain predicate applied by the caller.
|
|
114
|
-
- Near-twin siblings a caller can't tell apart from the names alone (`parseRows` vs `parseRowsFromItems`): if a comment must explain which to pick, rename — encode the distinguishing fact (e.g., input shape: `parseRowsFromFlatItems`). Matching the existing sibling's style does not excuse the ambiguity.
|
|
56
|
+
Public methods, exports and port names identify their operation, object and distinguishing facts without file context. Compare exported siblings: if callers need a comment to choose one, encode the distinction in the name. Constants include their domain and units where needed; private helpers in tight scopes get more slack.
|
|
115
57
|
|
|
116
|
-
|
|
58
|
+
Business-oriented repository or port names are valid when their contract defines the term and governing policy or specification. Inspect policy ownership; an adjective alone neither proves a violation nor requires an unfiltered fetch.
|
|
117
59
|
|
|
118
60
|
### One identifier, one meaning per file
|
|
119
61
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
Bad:
|
|
123
|
-
```ts
|
|
124
|
-
findFullAccount(account: string) // a primary key
|
|
125
|
-
update(idAccount: string, account: AccountRow) // the row — same word, four lines away
|
|
126
|
-
```
|
|
127
|
-
|
|
128
|
-
Good: `findFullAccount(idAccount: string)` — the key takes the name the file already uses for keys.
|
|
129
|
-
|
|
130
|
-
The test: grep the identifier across the file. If two occurrences carry different types or different roles, rename the newer one to the distinguishing fact and follow whatever name the file already uses for that role.
|
|
62
|
+
Search the identifier across the file. If occurrences carry different types or roles, rename the newer one to distinguish them and follow existing names for that role; do not use the entity's name for its key.
|
|
131
63
|
|
|
132
64
|
## Functions do one thing
|
|
133
65
|
|
|
134
|
-
A name containing "and" or a
|
|
135
|
-
|
|
136
|
-
A short orchestrator may call several already-named steps at the same abstraction level:
|
|
137
|
-
```javascript
|
|
138
|
-
function handleData() {
|
|
139
|
-
fetchData();
|
|
140
|
-
processData();
|
|
141
|
-
displayData();
|
|
142
|
-
}
|
|
143
|
-
```
|
|
144
|
-
|
|
145
|
-
The body above does not need further splitting: each step is already a separate function. The generic name `handleData` is a naming issue; choose a name for the overall operation based on the caller's purpose.
|
|
146
|
-
|
|
147
|
-
### Plain-English summary test
|
|
148
|
-
|
|
149
|
-
For every function you add or meaningfully modify, ask:
|
|
150
|
-
|
|
151
|
-
> Can I summarize what this function does, line by line, as a short English sentence per line — and does the resulting summary read as prose?
|
|
152
|
-
|
|
153
|
-
If the answer is "no, I'd have to group several lines together and invent a name for the group", **that grouping should already exist in the code as a named helper or named intermediate value**. The fact that you had to invent the name is the signal to extract. A local readability helper can have one caller; the second-caller requirement applies to reuse-driven abstraction layers.
|
|
66
|
+
Judge cohesion, complexity and abstraction levels. Split mixed responsibilities or levels when extraction improves the flow. A name containing "and" or a scrolling body prompts inspection, not automatic splitting. An orchestrator may call several named steps at one abstraction level; name their overall purpose.
|
|
154
67
|
|
|
155
68
|
### Inspect for readability problems
|
|
156
69
|
|
|
157
|
-
-
|
|
158
|
-
-
|
|
159
|
-
-
|
|
160
|
-
-
|
|
161
|
-
- Boolean expressions long enough that intent is buried — `if (a && b && !c && (d || e.f > 0) && ...)` without a named predicate.
|
|
162
|
-
- A function that orchestrates 4+ distinct logical phases inline (*fetch → resolve → branch → persist → publish*), each more than a line or two. Even without deep nesting, that's enough work to warrant named sub-methods.
|
|
163
|
-
- A chain of `if (x === SomeEnum.A) return …` over the values of one enum — that's a hand-rolled switch. Use a real `switch (x)` so the cases line up and exhaustiveness is visible; it also drops the trailing fall-through `return` that an if-chain needs.
|
|
164
|
-
- A dense data literal — an object/struct/`{...}` carrying several inline ternaries or conditional spreads (`...(cond ? { x } : {})`) — assembled inline in a method that also does other work. Extract a named builder (`buildX(...)`) so the method reads as "compute X → assign X", and each conditional field gets a place to be understood.
|
|
70
|
+
- Inspect mixed responsibilities or abstraction levels, anonymous temporaries, unnamed non-obvious transformation stages and boolean expressions with buried intent. Trace what a reader or caller must understand and identify the concrete ambiguity or maintenance consequence.
|
|
71
|
+
- Name inline phases when that exposes a cohesive step or separates unrelated responsibilities; a count of phases or temporaries alone does not require extraction.
|
|
72
|
+
- For branches over one enum, inspect whether cases and exhaustiveness are clear; use a `switch` when it improves them.
|
|
73
|
+
- Extract a named builder when dense conditional fields obscure a distinct construction responsibility. Apply "Limit nesting depth" below as an inspection signal.
|
|
165
74
|
|
|
166
|
-
###
|
|
75
|
+
### Function size review signal
|
|
167
76
|
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
Crossing the cap is an extraction signal, not a style nit. Before declaring a function complete, count effective body lines; if over 50, split, or surface the violation and confirm with the user before continuing.
|
|
77
|
+
Review newly added or substantially edited functions beyond 50 effective body lines, excluding blanks, comments and pure data declarations. Record why a longer function remains cohesive or identify its concrete problem and improved shape. Length alone is not a violation, an automatic gate or grounds for a user exception; split only when it improves understanding or maintenance. Explicit repository limits follow `overview.md` precedence.
|
|
171
78
|
|
|
172
79
|
### What's fine
|
|
173
80
|
|
|
174
|
-
|
|
175
|
-
- Short functions (< ~10 lines) with a clear purpose and readable flow. Shortness does not exempt a function from the nesting-depth rule or other applicable checks.
|
|
176
|
-
- Idiomatic framework patterns used clearly (a 30-line controller method obviously doing its job).
|
|
177
|
-
- Guard clauses at the top — they *help* readability, they don't count against you.
|
|
81
|
+
Straight sequences of named steps, clear idiomatic framework patterns and guard clauses are acceptable. Short functions still require inspection when they obscure a decision or mix responsibilities.
|
|
178
82
|
|
|
179
83
|
## Mutation and state boundaries
|
|
180
84
|
|
|
181
|
-
These defects survive a green suite because the test reads the same object the code mutated. State the fact you actually verified, at the moment you verified it.
|
|
182
|
-
|
|
183
85
|
### Decide on the direct fact, not a proxy
|
|
184
86
|
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
The test: construct the opposite case and ask whether your condition still reads true. `status === 'DONE'` holds both for "already moved here" and "moved somewhere else"; `row.parentId === target.parentId` does not.
|
|
87
|
+
For identity, ownership or destination decisions, compare the source and destination identifiers rather than status or processed flags. Check that the opposite case does not satisfy the condition. If the direct fact is unavailable, surface it without performing the change.
|
|
188
88
|
|
|
189
89
|
### Capture before-state before the mutating boundary
|
|
190
90
|
|
|
191
|
-
|
|
192
|
-
|
|
193
|
-
Never re-read a before-field off the original object after that boundary, and never reconstruct it from the post-state. Pass before-state and result-state as two explicit values.
|
|
91
|
+
Capture all before-values for a diagnostic in one snapshot before any call, write, reload or handoff that can mutate the object. Pass before-state and result-state separately; never re-read or reconstruct before-state after that boundary.
|
|
194
92
|
|
|
195
93
|
### Update only the fields this work owns
|
|
196
94
|
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
The test: for every field this change writes, grep the other sites that write the same field in the same flow — a later pass of the same loop, a final persist, a sibling handler — and put them in order. If a later write clears what an earlier one recorded, the clear needs a condition, not a default.
|
|
95
|
+
Keep create-versus-reuse information through the final write. For an existing row, allowlist only fields this operation owns; overwriting provenance, ownership or externally managed values requires an explicit requirement. Search and order all writes to each changed field in the flow. A later clear of an earlier value needs a condition, not a default.
|
|
200
96
|
|
|
201
97
|
### Zero affected rows is a question, not an answer
|
|
202
98
|
|
|
203
|
-
|
|
99
|
+
After a conditional write affects zero rows, re-read state to distinguish already-desired state, conflict and deletion. Handle and report each case separately rather than inferring success or a cause from the row count.
|
|
204
100
|
|
|
205
101
|
### Priority between competing inputs is policy, not an if-chain
|
|
206
102
|
|
|
207
|
-
|
|
103
|
+
A service collects inputs; a named domain function decides which wins. Its name identifies the priority policy instead of hiding it in service control flow.
|
|
208
104
|
|
|
209
105
|
### An error message states only what you observed
|
|
210
106
|
|
|
211
|
-
|
|
107
|
+
Report only observed facts. Failures with different remedies, including deletion, state mismatch and concurrent change, get distinct messages and tests on their paths.
|
|
212
108
|
|
|
213
109
|
## Wrapping a third-party call
|
|
214
110
|
|
|
215
111
|
### The wrapper must add something the library does not already do
|
|
216
112
|
|
|
217
|
-
Before
|
|
218
|
-
|
|
219
|
-
The test: name the condition under which your branch runs and the library's does not. If you cannot name it from the library's source, the branch is dead. Delete it, or make it do something the library provably does not — a locking read where the library read without a lock, a different isolation level, a retry the library never attempts.
|
|
113
|
+
Before adding recovery, retry or fallback, read the installed library's handling of that case. Identify the condition or behavior your branch adds beyond the library's handling; delete or change a branch that only repeats it.
|
|
220
114
|
|
|
221
115
|
### A comment may not name a condition the code does not run under
|
|
222
116
|
|
|
223
|
-
|
|
117
|
+
Cite the call site establishing any condition a recovery comment relies on; remove claims that no caller establishes.
|
|
224
118
|
|
|
225
119
|
### Rethrowing keeps the original error
|
|
226
120
|
|
|
227
|
-
|
|
121
|
+
When replacing an error, retain the original as its cause, including its diagnostic details and stack. Preserve its type when callers branch on it.
|
|
228
122
|
|
|
229
123
|
## Testing discipline
|
|
230
124
|
|
|
231
|
-
|
|
232
|
-
|
|
233
|
-
Follow the testing-waiver policy in `overview.md` "Tests planned". An explicit waiver applies only to the named behavior or check, including its branch-test, branch-deletion, or resource-bound requirement. Record that scope as unverified. All checks outside the waiver and the quality rules for tests that are written or edited still apply.
|
|
125
|
+
Apply these rules to every test file; language-specific detection patterns are in `languages/*.md`. Changed core behavior and meaningful failure outcomes require tests unless the user explicitly waives them for this change and project rules permit it. Record the exact waived behavior or check as unverified, including any explicit project-required mutation check or resource-bound requirement. A waiver neither weakens existing tests nor establishes coverage; all other checks and quality rules for written or edited tests still apply.
|
|
234
126
|
|
|
235
127
|
### Reuse tests before adding coverage
|
|
236
128
|
|
|
237
|
-
Before
|
|
129
|
+
Before function edits or new test plans, search names, behavior, callers and assertions, then read candidate bodies. Strengthen an existing behavior test, or run and retain it if it already covers the changed contract. Add only for an uncovered behavior, preferably in an existing file; a new file needs distinct ownership or a boundary reason.
|
|
238
130
|
|
|
239
|
-
|
|
131
|
+
Record the changed function, search terms, existing test locations and grounds for retaining, extending, adding or retiring coverage. Use `extend <path:line>`, `new (nothing covers <behavior>)` or `retire <path:line> (behavior moved to <where>)`. New tests without survey evidence are unfinished. Retire a test in the same commit only when its behavior is gone or a replacement asserts it more strongly through the same seam; otherwise retain it.
|
|
240
132
|
|
|
241
|
-
|
|
133
|
+
Keep distinct outcomes and meaningful failures, not parallel cases or cases per helper, branch, model, provider or task-type combination. Each behavior has one primary test owner; integration cases need separate wiring risks. Selective mutation checks reuse this coverage. Completion self-check and code review assess the mapping.
|
|
242
134
|
|
|
243
135
|
### No self-mocking
|
|
244
136
|
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
Why it matters: when you mock a method on the subject under test (SUT), the test no longer verifies that method's behavior — it verifies that *some* version of the class (the one you wired up) calls the mocked method. If someone deletes the real implementation, the test still passes. The test has become a proof of its own shape.
|
|
248
|
-
|
|
249
|
-
Bad (pseudo, language-agnostic):
|
|
250
|
-
```
|
|
251
|
-
sut = new Foo(deps)
|
|
252
|
-
mock(sut.calculateTotal).returns(100) // mocking the SUT's own method
|
|
253
|
-
result = sut.checkout()
|
|
254
|
-
assert result.total == 100 // proves wiring, not logic
|
|
255
|
-
```
|
|
256
|
-
|
|
257
|
-
Good:
|
|
258
|
-
```
|
|
259
|
-
sut = new Foo(deps) // real Foo, real calculateTotal
|
|
260
|
-
mock(deps.payment.charge).returns(ok) // mock the collaborator at the boundary
|
|
261
|
-
result = sut.checkout()
|
|
262
|
-
assert result.total == expectedTotal // proves the logic
|
|
263
|
-
```
|
|
137
|
+
Exercise the real subject under test (SUT); do not stub, spy on or replace its methods. Mocking injected collaborators, including repositories, ports and clocks, is allowed.
|
|
264
138
|
|
|
265
139
|
### Behavioral, not implementation tests
|
|
266
140
|
|
|
267
|
-
|
|
141
|
+
Assert return values, errors, persisted state, events or genuine external boundary calls, including mail, payment and repository writes. Do not make internal-helper or pure-collaborator calls the primary proof, assert private helpers through reflection or casts, or couple tests to private names or internal call order. A suite dominated by spy assertions merits inspection of whether those spies represent outcome boundaries.
|
|
268
142
|
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
- `expect(spy).toHaveBeenCalledWith(...)` as the *only* or *primary* assertion, when the spy is on an internal helper or a pure collaborator with no side effects.
|
|
272
|
-
- Tests that would break if you renamed a private method without changing behavior.
|
|
273
|
-
- Assertions on private methods reached via reflection, cast-to-any, or bracket access — the issue is *reaching into privates*, not the language escape hatch itself.
|
|
274
|
-
- A test file where most assertions are on spies rather than on results.
|
|
275
|
-
|
|
276
|
-
Legitimately behavioral (these are fine):
|
|
277
|
-
|
|
278
|
-
- `expect(mailerSpy).toHaveBeenCalledWith(...)` — sending mail *is* the behavior.
|
|
279
|
-
- `expect(paymentGateway.charge).toHaveBeenCalledWith(...)` — charging a card *is* the behavior.
|
|
280
|
-
- `expect(orderRepo.save).toHaveBeenCalledWith(...)` in an application-service test — producing the right save call *is* the point of the service.
|
|
281
|
-
|
|
282
|
-
The judgment call: is the mocked thing an **outcome boundary** (port, external service, side-effecting adapter) or an **internal helper**? Asserting on boundaries is behavioral; asserting on helpers is implementation-coupled.
|
|
143
|
+
Do not inspect mock-call arguments by positional indexing; use intent-revealing assertions. Follow the language pack's stated exception for unavoidable access.
|
|
283
144
|
|
|
284
145
|
### Assert the last write, not the first
|
|
285
146
|
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
The test: list every write in this flow that touches the field you assert, and confirm the one you assert is the last. If it is not, assert the last one too.
|
|
147
|
+
List all writes to the asserted field in the flow. Assert the last write as well as any relevant earlier write; an intermediate assertion alone does not establish final state.
|
|
289
148
|
|
|
290
149
|
### An effect under its own mock is not evidence
|
|
291
150
|
|
|
292
|
-
|
|
293
|
-
|
|
294
|
-
### Every branch you add gets a test that dies with it
|
|
151
|
+
Claim an effect's coverage only where its real producing path runs. Reaching a mock that replaces that path does not verify the effect behind it.
|
|
295
152
|
|
|
296
|
-
|
|
153
|
+
### Focus regression tests on changed outcomes
|
|
297
154
|
|
|
298
|
-
|
|
155
|
+
Use retained or strengthened tests to distinguish changed core behavior and meaningful failure outcomes from an incorrect implementation. Merely reaching the method is insufficient, especially when recovery is the behavior added beyond a library's happy path.
|
|
299
156
|
|
|
300
|
-
|
|
157
|
+
Use a targeted mutation check when uncertainty remains about whether a test detects a regression, particularly for security, concurrency or recovery paths. Change the suspected behavior, confirm the focused test fails for that reason, then restore the source and rerun it. A manual mutation check for every syntactic branch is not required by this common pack; explicit project requirements retain their precedence.
|
|
301
158
|
|
|
302
159
|
### Shared fixtures keep the ordinary default
|
|
303
160
|
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
The test: does the no-argument fixture call still describe the ordinary case?
|
|
161
|
+
Keep shared fixture defaults on the ordinary path. Pass exceptional conditions explicitly in their tests, and search all call sites before changing a default.
|
|
307
162
|
|
|
308
163
|
### Test data must actually separate the paths
|
|
309
164
|
|
|
310
|
-
|
|
165
|
+
Use distinguishing inputs for source/destination, existing/incoming and success/conflict paths; identical setup and outcome do not justify separate cases. State each test's distinguishing input and inspect whether its assertions depend on that difference; defaults must not let an incorrect implementation pass.
|
|
311
166
|
|
|
312
167
|
### A test title names the unit and the one condition it isolates
|
|
313
168
|
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
- Name the unit when the file covers more than one. `'returns the primary-key lookup result'` fits every by-key read in the class; `'findFullAccount returns …'`, or a `describe('findFullAccount', …)` wrapper, fits one.
|
|
317
|
-
- Credit only the condition the case actually isolates. A parameterised case that trips two guards at once must not name one of them in the title — split it into one case per guard.
|
|
318
|
-
|
|
319
|
-
The test: delete from the setup the input the title credits. If the case still passes, the title describes a guard the test never reached — retitle it, or fix the setup so it does.
|
|
169
|
+
The failure line identifies the unit and isolated condition, using a grouping name where appropriate. If a parameterized case trips two guards, separate them before naming one. Match the setup and title to the behavior the assertions actually verify.
|
|
320
170
|
|
|
321
171
|
### Test tooling you add is used in the same change
|
|
322
172
|
|
|
323
|
-
|
|
173
|
+
Search every new mock, state setter, helper or repository branch for a test use in the same change. Unused tooling is unfinished; check that repository mocks do not only return success.
|
|
324
174
|
|
|
325
175
|
### Resource bounds need their own regression test
|
|
326
176
|
|
|
327
|
-
|
|
177
|
+
Changes to memory use, concurrency, batching or streaming need a regression test pinning the claimed bound, such as peak size, concurrent count or chunk count. Small-input functional success alone is insufficient.
|
|
328
178
|
|
|
329
179
|
## Trace what this change can do wrong
|
|
330
180
|
|
|
331
|
-
|
|
181
|
+
For every changed source file, trace changed paths to their outcomes, including failures beyond those listed in the plan:
|
|
332
182
|
|
|
333
|
-
|
|
183
|
+
- **error** — each new call's failures and what the caller can distinguish.
|
|
184
|
+
- **partial** — writes left behind and what a retry sees.
|
|
185
|
+
- **concurrent** — competing writes or work continuing after a deadline.
|
|
186
|
+
- **selection** — whose evidence survives when several candidates fail.
|
|
334
187
|
|
|
335
|
-
|
|
336
|
-
- **partial** — the change succeeded halfway; what is left written, and what the next run sees.
|
|
337
|
-
- **concurrent** — something else is still writing, or the deadline fired and the work did not stop.
|
|
338
|
-
- **selection** — when several candidates fail, which one's evidence survives.
|
|
188
|
+
Inside a cleaning `try` / `catch` / `finally`, register cleanup targets before throwing reads, writes or calls, including work that cleanup must await. Compare throwing-call and cleanup-registration order with the base when moving code; changed order is a behavior change. Name failures test fakes cannot produce as unverified, not clean.
|
|
339
189
|
|
|
340
|
-
|
|
190
|
+
Use "Finding evidence and grading" below. Unreachable-state guards and extra tests of already-covered behavior are optional unless another applicable rule is violated. Small, cheap-to-fix failures remain findings.
|
|
341
191
|
|
|
342
|
-
|
|
343
|
-
- **order changed by a move** — when the change moves or restructures existing code, compare the order of throwing calls and cleanup registration with the base version; a refactor that swaps them is a behaviour change.
|
|
192
|
+
## Finding evidence and grading
|
|
344
193
|
|
|
345
|
-
|
|
194
|
+
Implementation, independent verification and review use `review-rules.json` for rule IDs and blocking severity/timing. Referenced rules define applicability; `overview.md` defines precedence.
|
|
346
195
|
|
|
347
|
-
|
|
196
|
+
- An `execution-error` establishes a reachable input/state, expected behavior and actual wrong result.
|
|
197
|
+
- A `design-violation` establishes the violating source and either an explicit applicable project requirement or a concrete maintenance or design consequence under the applicable rule; no runtime failure is required. A preferred implementation, name or style alone is insufficient.
|
|
198
|
+
- `must-fix` means a defect or a violation with substantial consequences; `should-fix` requires an explicit applicable project rule breach or an evidenced maintenance or design impact without immediate breakage; `nit` is a small, demonstrable improvement. Grade the established impact rather than generic style preference or confidence; missing inspection is incomplete coverage.
|
|
199
|
+
- `now` is introduced or changed by this change. `park` needs a cited scope or accepted-risk basis, not cost, passing tests or a restrictive plan. Reclassifying explicitly accepted product behavior requires new evidence.
|
|
200
|
+
- Unresolved blocking `now` findings prevent acceptance: executors fix them, verifiers return `FAIL`, and reviewers preserve them for settlement. Record `nit` and justified `park` findings without blocking. Semantic grading remains worker judgment.
|
|
201
|
+
|
|
202
|
+
M1 covers truthful, specific, standalone names; M2 covers cohesion, complexity, abstraction levels and comprehensible control flow. Size, nesting depth and counts of inline stages prompt inspection; they do not establish a finding by themselves. Correct execution does not waive an explicit project requirement or an evidenced design or maintenance impact. Cite the construct and the governing project rule or concrete consequence; do not demand unrelated legacy cleanup.
|
|
203
|
+
|
|
204
|
+
`file_size_cap.py` measures physical size; reviewers judge responsibility. An oversized legacy file need not be cleaned wholesale, but adding unrelated responsibility still violates S3 or M2. Small wiring edits may remain with a cited rationale. Restrictive plan placement does not waive these rules: return a plan conflict with a conforming location and preserved acceptance behavior, and obtain plan repair before writing outside authorized scope.
|
|
348
205
|
|
|
349
206
|
## Untrusted input and security
|
|
350
207
|
|
|
351
|
-
|
|
208
|
+
Treat outside-process input as sender-controlled, authenticated or not. Apply these checks to every changed file reading or acting on it. Findings name the input and its effect; generic hardening preferences are insufficient.
|
|
352
209
|
|
|
353
210
|
### Bound the work before the expensive check
|
|
354
211
|
|
|
355
|
-
|
|
212
|
+
Reject oversized input before work that grows faster than input size, including nested scans, backtracking regexes and input-driven expansion. Verify actual execution order: a failed size rule may not stop other validators. Guard inside the costly check or configure first-failure stopping. Byte limits do not replace element-count bounds. Test prompt rejection well beyond the limit and the claimed resource bound, as required by "Resource bounds need their own regression test".
|
|
356
213
|
|
|
357
214
|
### Input never builds code
|
|
358
215
|
|
|
359
|
-
|
|
216
|
+
Pass input to SQL, shells, paths, server-side fetches, templates and regexes through sink-specific parameters, allowlists or escaping, never direct concatenation or interpolation. Resolve input paths and verify confinement to their root; allowlist fetch hosts.
|
|
360
217
|
|
|
361
218
|
### Every new entry point checks the caller's access rights
|
|
362
219
|
|
|
363
|
-
|
|
220
|
+
Before returning or changing per-user data, new routes, handlers, resolvers and jobs establish identity through project authentication and check operation-specific permissions. Ownership, shared access, tenant membership or authorized administration may grant access; an input-chosen ID does not. Explicitly public operations follow the project's public-access policy.
|
|
364
221
|
|
|
365
222
|
### Protect secrets and limit personal-data disclosure
|
|
366
223
|
|
|
367
|
-
Keep real secrets, tokens
|
|
224
|
+
Keep real secrets, tokens and credentials out of source and production fixtures. Logs and errors do not disclose secrets or personal data, including through echoed requests or upstream errors. Personal-data responses require an authorized recipient and fields needed for the documented purpose. Return credentials only from operations designed to issue them to authorized recipients.
|
|
368
225
|
|
|
369
226
|
### No execution of input
|
|
370
227
|
|
|
@@ -372,73 +229,18 @@ No `eval`, `Function(...)`, dynamic `import()` of an input-chosen path, or deser
|
|
|
372
229
|
|
|
373
230
|
## No magic numbers
|
|
374
231
|
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
Bad: `if (age > 18)`
|
|
378
|
-
Good: `const LEGAL_AGE = 18; if (age > LEGAL_AGE)`
|
|
232
|
+
Name values when their units, governing policy or repeated use carry meaning that callers or maintainers need. Keep clear idiomatic literals, such as zero for an empty count or one for an increment, inline. A numeric literal alone does not establish a finding; identify the obscured meaning, policy drift risk or explicit project rule that requires a name.
|
|
379
233
|
|
|
380
234
|
## Limit nesting depth
|
|
381
235
|
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
Bad:
|
|
385
|
-
```javascript
|
|
386
|
-
function process(user) {
|
|
387
|
-
if (user) {
|
|
388
|
-
if (user.isActive) {
|
|
389
|
-
if (user.hasPermission) {
|
|
390
|
-
// ...
|
|
391
|
-
}
|
|
392
|
-
}
|
|
393
|
-
}
|
|
394
|
-
}
|
|
395
|
-
```
|
|
396
|
-
|
|
397
|
-
Good:
|
|
398
|
-
```javascript
|
|
399
|
-
function process(user) {
|
|
400
|
-
if (!user) return;
|
|
401
|
-
if (!user.isActive) return;
|
|
402
|
-
if (!user.hasPermission) return;
|
|
403
|
-
// ...
|
|
404
|
-
}
|
|
405
|
-
```
|
|
236
|
+
Deeply nested control flow, including four or more nested control-flow blocks, prompts inspection of the decisions, state and exit paths a reader must track. The function, class and module bodies do not count. Flatten with early returns or extract a named step when that resolves a concrete comprehension or maintenance problem; depth alone does not require a rewrite. Explicit project limits retain their precedence. Enforcement is the preflight self-check and code review.
|
|
406
237
|
|
|
407
238
|
## Comments explain *why*, not *what*
|
|
408
239
|
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
Interface documentation may describe caller-visible contracts that the signature cannot express: error versus ordinary negative results, missing-input behavior, side effects, or security constraints. This is not redundant narration of an implementation. Verify the documented behavior against implementations, callers, and relevant tests; do not infer it from the documentation alone. When the contract requires non-obvious work, explain its reason if that reason is established by evidence.
|
|
412
|
-
|
|
413
|
-
Bad:
|
|
414
|
-
```javascript
|
|
415
|
-
// increment i
|
|
416
|
-
i++;
|
|
417
|
-
```
|
|
418
|
-
|
|
419
|
-
Good:
|
|
420
|
-
```javascript
|
|
421
|
-
// User may be soft-deleted; invalidate cache so stale reads vanish.
|
|
422
|
-
cache.invalidate(user.id);
|
|
423
|
-
```
|
|
424
|
-
|
|
425
|
-
**A comment is not a change log.** Never record change history in code — ticket IDs (`FU-003`, `DEV-9185`), verification logs (`verified parity-neutral on the real DB`), `retained from …`, or the reason something *changed*. That belongs to git blame, the commit message, and the PR; the code reader six months later does not have those tickets open. A comment earns its place only by stating a constraint or invariant that is **still true and load-bearing for someone reading the code cold, with zero knowledge of the diff that introduced it**. If it stops making sense once that diff is forgotten, delete it.
|
|
426
|
-
|
|
427
|
-
Bad (change-log noise — delete):
|
|
428
|
-
```javascript
|
|
429
|
-
// FU-003 read-path deltas — verified parity-neutral against the publish grid
|
|
430
|
-
// on the real DB (DEV-9185 Stage 1). Retained as read-side display alignment.
|
|
431
|
-
applyYearlyMultiplier(rows);
|
|
432
|
-
```
|
|
433
|
-
|
|
434
|
-
Good (constraint a cold reader needs):
|
|
435
|
-
```javascript
|
|
436
|
-
// Publish callers omit both fields, so the 0 multiplier is intentional here.
|
|
437
|
-
applyYearlyMultiplier(rows);
|
|
438
|
-
```
|
|
240
|
+
Default to no implementation comment. Explain only constraints, workarounds or tradeoffs a future reader needs; do not narrate executable code.
|
|
439
241
|
|
|
440
|
-
|
|
242
|
+
Interface documentation may state caller-visible failure, missing-input, side-effect and security contracts that names and types cannot express. Verify them against implementations, callers and tests; explain non-obvious required work only from established evidence.
|
|
441
243
|
|
|
442
|
-
|
|
244
|
+
Keep change history, ticket IDs and verification logs in commits or PRs, not code comments. A retained comment states a current constraint or invariant that remains useful without the introducing diff.
|
|
443
245
|
|
|
444
|
-
|
|
246
|
+
Remove dead or commented-out code; version control preserves its history.
|