docs(retro): move the #437 learnings from private memory into repo records

[KbWen]

Summary

/retro for #437. That unit's durable learnings had been written into Claude-private memory, which Codex and Gemini sessions cannot read. This moves them into the repo's own record surfaces, where every host looks.

Records only. No skill wording, workflow, rule, metadata or token-ceiling change.

Surface	Change	Why there
current_state.md Global Lessons	+1 [skill-description-cost][HIGH][editing-skill-md]	A behavioural pattern. As a HIGH lesson it surfaces in the /implement pre-execution review on every host - exactly when someone is about to edit a SKILL.md
current_state.md Global Lessons	−1 [classification-flow] (MEDIUM, the GENESIS entry), archived	Registry was at cap 20 with zero LOW entries, so /retro's LOW-only path could not free a slot. Chosen by the repo owner; bootstrap.md:25 already encodes it as a rule
.agent/rules/repo-gotchas.md §16	+1 paragraph	A mechanical fact: the SKILL.md frontmatter description is consumed host-side. Codex selects on it; openai.yaml is UI metadata; Claude Code does not read .agents/skills in this layout
Ship History	new entry + rotation of the 2 oldest into archive/ship-history-2026.md	The #437 ship had taken the section to 11 without rotating; owed by that unit

The new lesson

Each character added to a .agents/skills/*/SKILL.md costs ~2.33 tokens against the aggregate lifecycle ceiling (~8.9x its own size), with 113 tokens of headroom. On #437 the targeted tests, both validators and two review rounds stayed green on a tree that breached it; only the full suite caught it. Backlog #199 is the open decision.

Why one lesson rather than four

Two of #437's record errors violated lessons already in the registry ([signal-preservation] for a swallowed exit code, [audit-verification] for trusting a reviewer's claim). Adding near-duplicates to a full registry adds length, not obedience. The other two are recorded in the committed review documents and archived Work Logs.

A defect I introduced and fixed before opening this

The first version of the §16 paragraph cited check_skill_provenance.py by bare filename. repo-gotchas.md ships force-update core tier and that tool is not in the deploy set, so every adopter would have been pointed at a file they do not have - another instance of #192. test_deployed_governance_referenced_tools_are_deployed stayed green because it matches only full .agentcortex/tools/<name>.py paths; #192 already records that bare basenames evade it. Fixed in 80401a7 by stating the fact without the citation.

Verification

All run after the last write, against the branch tip:

Check	Result
validate.sh / validate.ps1	both exit 0, pass=99 warn=4 fail=0 skip=3, WARN sets identical
check_lesson_chain.py	intact, 20 lessons
check_audit_chain.py	intact, including the archive bridge record
test_repo_gotchas_discoverability.py, test_deploy_tiering.py (whole file), test_lesson_chain_archival.py	51 passed, 1 skipped
analyze_token_lifecycle.py aggregate	354887 before and after - delta 0, measured
Directive-keyword scan of repo-gotchas.md	0 hits

The 4 WARNs are pre-existing. pass reads 99 because no Work Log is active after archival. No subagent review was run; review is optional for quick-win and this is stated rather than implied.

🤖 Generated with Claude Code