feat(constraints): a comment narrates as well as instructs

[ojassug]

§51 (merged in #20) measured where the fallbacks actually are: 29 of 29 code-bucket fallbacks on the frozen corpus are CONSTRAINT_DIRECTIVE_LOST. Not drift, not AST — this gate, every time. This is the first pass at it.

§42 scoped the gate by region: an instruction lives in a comment, never in an expression, which stopped it firing on logger.critical(exc). This scopes it by mood within that region, because a comment is also where a codebase narrates its own history.

What it was refusing

Inspecting the matched text behind those 29 fallbacks, roughly twelve read like this:

"The MCP branch of runCli has always read these two"
"It never did: this branch bypassed pruning entirely"
"HTTP_PROXY and HTTPS_PROXY … could never have worked"
"a saving that never reached the wire (audit C4)"

Losing one of those costs a reader some history. Losing "never hash items matching preserveKinds" costs a caller a rule. The keyword is identical, and the gate refused the whole file for either.

Narrowed in the safe direction, three ways

This gate protects content — unlike §48 and §50, where a wrong call costs output size, a wrong call here silently deletes an instruction.

1. Only never and always, the two keywords equally comfortable describing and instructing. must, must not, do not, required, critical, only if, except when, make sure to are untouched — "must have been called before" is a requirement about a past state, and a perfect-tense test applied to must would drop it.
2. Only provable perfect/past constructions — a preceding have/has/had, or a following past-tense verb. "is always deterministic" and "do not support" are descriptive too and are left firing on purpose: there the line between describing a constraint and stating one is genuinely blurry.
3. Unanimity before dropping. A segment goes only if every keyword in it is narrative-capable, so "this has always been true, so you must call it first" still fires.

The negative control is the load-bearing test

test/unit/narrative-directive-scope.test.ts asserts the eight narrative sentences stop firing — and that sixteen real instructions still do, several verbatim from this repository. A rule that drops one of those is not a better rule at any reduction figure, and the test says so directly rather than leaving it to a reduction number two layers away.

Measured — per-row, 576 rows, both routes, target 0.3, against v1.4.0

	result
rows byte-identical	572 of 576
fallbacks fixed / new	4 / 0
rows newly reducing / stopped	4 / 0
rows already reducing that changed at all	0

TypeScript file route: 39 reduced / 16 fallbacks → 43 / 12, aggregate 18.52% → 24.58%. The four are adapters/mcp/tools.ts, cli/main.ts, gateway/exec.ts and gateway/proxy.ts — exec.ts being the file that literally contains "could never have worked".

The caveat matters more than the headline

Python gained nothing — 0 of the 4. Every recovered file is this repository's own source, and this repository is unusually narrative: M11 measured 32.8% of src/ as comment prose, written in a what-used-to-be-true style. pip's comments describe behaviour in the present tense and were never caught.

So the 6pp on the TypeScript bucket is not a portable estimate. It is the corpus-bias trap CLAUDE.md warns about, showing up as a favourable number instead of an unfavourable one — the harder direction to notice. What is portable is the shape: zero regressions, and four files that produced nothing now produce something.

Still open on this axis, deliberately

Descriptive present-tense uses still raise directives. §50's other open item is the same gate: it is why the better sub-region coverage setting costs two working files.

657 tests, typecheck, lint and build green.

🤖 Generated with Claude Code