docs(core): the specs state the caps, ranges, and formats the binary enforces

[Max17190]

Why

Round-7 contract audit (F6 plus three one-liners). The skills spec already establishes the principle, with a test demanding it: a spec that omits the real limit sends an author hunting for one they have not hit while the real one silently ate their file. Four enforced limits were undocumented on their surfaces, two clamp ranges were written in Rust exclusive-range notation for inclusive clamps, the memory spec's index template showed a separator the binary never emits, and the skills byte-cap wording described first-fit omission as a suffix cut.

Summary

• --spec tools: names the 64-tool load cap, the 4096-byte serialized-params cap (rejected, not truncated), the required params.type = "object" root, and unknown-key rejection.
• --spec hooks: names the 32-per-event cap (the least visible: hooks have no prompt trailer, only --check names the drop) and unknown-key rejection.
• Both timeout_secs lines read "clamped between 1 and N, inclusive".
• --spec memory: the index template quotes the emitted separator exactly.
• --spec skills: the byte cap is described as first-fit in name order, with the practical consequence (shortening a description beats renaming a skill).

Test Plan

Four drift tests tie the statements to their constants (MAX_EXTERNAL_TOOLS, MAX_EXTERNAL_PARAMS_BYTES, MAX_HOOKS_PER_EVENT) and phrases: spec_tools_names_the_caps_that_drop_or_reject, spec_hooks_names_the_per_event_cap, spec_memory_shows_the_emitted_index_line, spec_skills_states_first_fit_omission. All four shown red against the previous text in one revert run. Full workspace green (exit 0), clippy zero warnings.

Greptile Summary

The extension specifications document enforced limits, validation behavior, emitted formats, and skill-index ordering. The reported skill-index guidance issue was disproved: with earlier entries occupying the byte budget, shortening only an initially omitted skill changed its line enough for the real CLI to include it.

Confidence Score: 5/5

No blocking failure remains.

The exercised skill-index behavior matches the current documentation: an entry that initially does not fit can be included when its own description is shortened.

T-Rex Logs

What T-Rex did

• The real release CLI was run with the initial 200-byte z-omitted skill and reported it was outside the frozen index.
• After shortening z-omitted to a one-byte description, the CLI reported the z-omitted as indexed.
• The focused Rust test spec_skills_states_first_fit_omission was executed and passed.
• A separate disproof execution record showed that shortening an omitted target can affect inclusion, contradicting the earlier claim; the same focused test also passed.

_{Ran code and verified through T-Rex}

_{Reviews (2): Last reviewed commit: "docs(core): the first-fit remediation do..." | Re-trigger Greptile}