docs(readme): document the green software engineering programme - #508

Why

Thirteen merged PRs (#475–#487, #506) and a full SCI-grounded energy harness under benchmarks/energy/ had no mention anywhere in the README. A reader had no way to know the programme existed — which also meant no way to hold it to its own evidence rule.

What the section says

A new ## Green software engineering section, placed before ## Verification so the claims-discipline sections sit together.

The harness, and what it does not establish. benchmarks/energy/ implements the GSF SCI specification (O = E × I, M = TE × TS × RS), functional unit = 1000 model input tokens counted from the tokenizer's own attention_mask. The section then spends equal space on the limits, taken from the harness's own README:

• its opening paragraph — the fixtures do not measure device energy and do not establish an energy improvement;
• no default carbon factors — --carbon-intensity and --embodied are mandatory operator inputs, validated before any model import, and the harness does not vouch for their provenance;
• a stated boundary — the sensor's combined CPU+GPU+ANE estimate, excluding memory, storage, screen, power-supply losses, warm-up and token counting;
• artifacts preserved (results.json, MANIFEST.json, the analyzed powermetrics.txt).

No energy figure is published, and the section says why: no energy results are committed here, because a number measured on one operator's machine, region and duty cycle is not a property of the software, and publishing it as one would be exactly the drift this programme exists to prevent.

What actually shipped — a table of the merged CI/build and runtime PRs, each linked.

Demand reduction is presented as the primary lever, and the paragraph is explicitly labelled a design rationale, not a measurement, with a closing sentence stating that Cortex publishes no token-savings or CO₂ figure for end-to-end agent sessions because it has not measured one.

The one quantitative claim

Hook boot ~0.05 s vs ~0.6 s for the full registry import (measured 2026-07-28) — an already-committed constant, cited to its call sites in mcp_server/hooks/auto_recall.py:247,300, per the no-invented-constants rule.

Verification

Each cited fact was checked against its source file, not against prose:

python3 scripts/check_doc_claims.py exits 0. Documentation only — no code, no behaviour change.

🤖 Generated with Claude Code

https://claude.ai/code/session_01StMBvNd7eVJGtpnC2zNsx1

Generated by Claude Code