Dimensional analysis

Contract

Field	Bound contract
Trigger	A financial, scientific, DeFi, blockchain, or off-chain codebase contains mixed units, fixed-point precisions, scaling factors, rates, prices, shares, or conversions and needs full annotation plus validation.
Authority	Reversible local: writes only comment-only dimensional annotations in in-scope source files plus DIMENSIONAL_SCOPE.json, DIMENSIONAL_UNITS.md, and a findings report in the project root; rollback is version control (revert comments) or undo (delete the three generated artifacts). No remote mutation.
Side effect	Comment-only annotations in all in-scope source files; DIMENSIONAL_SCOPE.json, DIMENSIONAL_UNITS.md, and a final findings/coverage report in the project root. No executable code, types, or logic are changed.
Done	Every in-scope file has terminal annotation, propagation, and validation status; no PENDING entries remain; blocked files reconcile exactly; only comments changed; confirmed and refuted mismatches are separated.

Inputs

• Project root path (required).
• Optional pre-existing DIMENSIONAL_UNITS.md and DIMENSIONAL_SCOPE.json for reuse, only when their project_root matches this repo and they contain the required structure.
• No mode argument is honored; the full four-phase pipeline always runs end to end.

Procedure

1. Bound scope. Confirm the project root. Identify every file containing numeric arithmetic with mixed units, precisions, scaling factors, rates, prices, shares, or conversions, and prioritize each as CRITICAL, HIGH, MEDIUM, or LOW. Write DIMENSIONAL_SCOPE.json to the project root with project_root, in_scope_files (all priorities), discoverer_focus_files (narrowed to CRITICAL/HIGH only when more than 50 arithmetic files are found), recommended_discovery_order, and every in-scope file initialized to step2: "PENDING", step3: "PENDING", step4: "PENDING". If no arithmetic files exist, write an empty manifest and skip to Output with zero findings. Done when: DIMENSIONAL_SCOPE.json is written with every in-scope file initialized to PENDING, or an empty manifest is written with zero findings.

2. Discover vocabulary. Read DIMENSIONAL_SCOPE.json as the source of truth. Infer base units, derived units, and precision prefixes from naming, interfaces, constants, and decimal scaling. Write DIMENSIONAL_UNITS.md to the project root with Base Units, Derived Units, and Precision Prefixes sections; write the same empty headings when in_scope_files is empty. Reuse a valid existing DIMENSIONAL_UNITS.md only when it matches this repo; otherwise discard and regenerate. If in_scope_files is empty after this step, skip to Output with zero findings. Done when: DIMENSIONAL_UNITS.md is written with the three sections, or the empty-headings case skips to Output.

3. Annotate anchors (Step 2). For every in_scope_files entry, add dimensional comments at anchor points (state variables, struct fields, function parameters, return values, inline arithmetic) using the vocabulary and the D{decimals}{dimension} format. Batch files: 10 or fewer in one batch; 11-30 in one batch per category; more than 30 in one batch per category, splitting categories larger than 10 files into sub-batches of about 8. Process categories in recommended_discovery_order: math libraries, then oracles, then core logic, then peripheral. Set step2 = "PENDING" for every in-scope file before launch and persist the manifest. After each batch, persist exactly one status per file: ANNOTATED, REVIEWED_NO_ANCHOR_CHANGES, or BLOCKED; for BLOCKED also persist step2_reason and step2_retry_count. Retry each BLOCKED file once with a focused prompt. Do not advance while any step2 is PENDING. Done when: no step2 entry is PENDING; each file is ANNOTATED, REVIEWED_NO_ANCHOR_CHANGES, or BLOCKED with reason and retry count.

4. Propagate dimensions (Step 3). For every in_scope_files entry, extend annotations through arithmetic, function calls, and assignments using dimension algebra (multiplication combines dimensions, division inverts, addition requires matching dimensions). Use the same batching and category order as Step 2. Confirm every file has a non-pending step2 status before launch; then set step3 = "PENDING" and persist. After each batch, persist exactly one status per file: PROPAGATED, REVIEWED_NO_PROPAGATION_CHANGES, or BLOCKED; for BLOCKED also persist step3_reason and step3_retry_count. Retry each BLOCKED file once. Aggregate annotations by confidence (CERTAIN, INFERRED, UNCERTAIN), mismatches with severities, and coverage gaps that could not be inferred. Do not advance while any step3 is PENDING. Done when: no step3 entry is PENDING; each file is PROPAGATED, REVIEWED_NO_PROPAGATION_CHANGES, or BLOCKED with reason and retry count.

5. Validate and detect bugs (Step 4). Validate every in_scope_files entry. Process in this priority order without skipping lower tiers: (a) files with CRITICAL or HIGH Step 3 mismatches, (b) remaining CRITICAL and HIGH scanner-priority files, (c) remaining MEDIUM and LOW files. Confirm every file has a non-pending step3 status before launch; then set step4 = "PENDING" and persist. Validate one file per unit, running in waves of roughly 10-30 files. Reject rationalizations of mismatches; a dimension that does not balance is a finding, not an explanation. After each wave, persist exactly one status per file: VALIDATED or BLOCKED; for BLOCKED also persist step4_reason and step4_retry_count. Retry each BLOCKED file once. Deduplicate findings: confirmed Step 3 mismatches keep their original IDs and severities; refuted Step 3 mismatches are noted as false positives and excluded from final counts; genuinely new findings receive new DIM-XXX IDs. Step 4 is complete only when no step4 entry is PENDING. Done when: no step4 entry is PENDING; every file is VALIDATED or BLOCKED, and findings are deduplicated with confirmed and refuted separated.

6. Reconcile. Derive coverage.unprocessed_files from terminal BLOCKED entries as { "path": "...", "blocked_step": "step2|step3|step4", "reason": "...", "retry_count": 1 }. If the final report and DIMENSIONAL_SCOPE.json disagree, continue processing or reconcile the report until they match. Completion is determined by manifest coverage and final reported statuses, not by intent. Done when: coverage.unprocessed_files matches the terminal BLOCKED set and the report and manifest agree.

Failure and recovery

• BLOCKED file: persist the blocking reason and retry count; retry once with a focused prompt; if still BLOCKED, keep the documented reason and continue. Never finalize while any in-scope file remains PENDING in any step.
• Stale or malformed manifest or vocabulary: discard reuse and rerun the phase that owns the artifact (scanner owns DIMENSIONAL_SCOPE.json; discoverer owns DIMENSIONAL_UNITS.md).
• Non-converged run: if a phase cannot clear PENDING after its one retry, the run is non-converged; report every blocked file with its reason and retry count; do not claim the done predicate holds.
• Rollback: only comments were changed. Revert comments through version control and delete DIMENSIONAL_SCOPE.json, DIMENSIONAL_UNITS.md, and the findings report to restore prior state.
• Never swallow errors, invent evidence, or substitute ad-hoc dimensional reasoning for a skipped or unlaunched phase.

Output

A structured summary in the project root carrying mode, project_root, vocabulary (base_units, derived_units, precision_prefixes), annotations (total_added, by_file), findings (critical, high, medium, details), uncertainties_resolved, and coverage (in_scope_files, anchor/propagation/validation reviewed ratios, annotated functions and variables, unprocessed_files matching the terminal BLOCKED set), with confirmed and refuted mismatches separated and a list of modified files when edits occurred, ordered bound → discover → annotate → propagate → validate → reconcile.