Skip to content

ROI & Insights Report + Conformance Trend (P2-22)

cortexbuild report aggregates existing CortexBuild signals into a single deterministic ROI report and tracks the conformance score over time. It emits:

  • .cortexbuild/ROI_REPORT.md — human-readable insights.
  • .cortexbuild/roi_report.json — machine-readable summary.

What it reports

Signal Source Degrades to
Risk hotspots analyser.debt.compute_heatmap (.cortexbuild/analysis/*.json) empty + note
Adaptive rules proposed file count under .cortexbuild/proposed-rules/ 0
Context completeness context.score.compute_completeness 0
Conformance score conformance.compute_conformance (P2-21) 0
Conformance trend hash-chained trend store (below) "no trend yet"

Conformance trend store (S3)

The trend store at .cortexbuild/insights/trend.jsonl is a tamper-evident, append-only ledger of numeric maturity snapshots:

  • Append-only + hash-chained — each record carries the previous record's hash (prev) and its own content hash (hash). verify_chain() recomputes the chain; any edit, deletion, or reordering is detected and surfaced as a trend_intact = false note in the report.
  • Commit-anchored ordinals, never wall-clock — records are ordered by a monotonic integer ordinal plus an optional commit anchor. No timestamps are stored, so the bytes stay deterministic.
  • Numeric-only, no PII / secrets / raw rule text — only the whitelisted metrics in TREND_METRICS are persisted; any other key (or non-numeric value) is dropped before writing.
  • Offline — reads/writes one local file and nothing remote.

Record a snapshot:

cortexbuild report --record-trend            # append a numeric snapshot
cortexbuild report --record-trend --commit $(git rev-parse --short HEAD)

Empty history renders as "no trend yet"; two or more snapshots yield a conformance delta versus the first recorded point.

Determinism & egress safety (S1 / P2-23)

  • Offline, no wall-clock in the emitted bytes.
  • Debt hotspots are relativised via render.ownership.relpath and routed through the egress redactor (security.egress.redact_for_egress), so absolute paths and OS usernames never leak into the report.
  • Two checkouts at different absolute paths with identical evidence emit byte-identical reports.

Backward-compat (S4)

An unconfigured repo never crashes: every signal degrades to a safe default and the report still renders with explanatory notes.