docs(core): the guide and specs state the executed-call refreeze and hook turn granularity

[Max17190]

Why

Round-7 contract audit (F2, F5). PR #242 made the mid-turn refreeze fire after every EXECUTED mutating call, a failed one included, because a bash write-then-selftest that exits nonzero has still persisted the file. Three surfaces still described the old trigger: the frozen prompt's self-extension guide, --spec tools, and --spec skills ("after a successful mutating call"), while --spec permissions, --spec settings, and --spec memory already state the executed/any/writing-call truth. Inside one turn a model could hold a receipt saying its new tool is live and a guide saying the refreeze it needed did not happen.

The guide also said "Hooks, permissions, and templates apply on their next use". Hooks are discovered per turn; the receipt ("approved hooks apply from the next turn") and --spec hooks ("re-discovered every turn") both say so. Lumping the three invited the install-the-gate-then-prove-it shape at a granularity hooks do not have.

Summary

• Guide: "re-freezes after every executed mutating call", and "Permissions and templates apply on next use; hooks from the next turn." The failed-call nuance lives in the two specs (pay-on-read); the guide is an index and carries the trigger only, inside the frozen prompt budget (frozen_prompt_fits_token_budget still passes; the first draft that carried the nuance in the prompt failed it and was tightened).
• --spec tools and --spec skills: "after every executed mutating call (a failed call that wrote the file still activates it)".
• The stale declaration comment above extensions_touched now says executed, citing fix(core): refreeze after a mutating call that wrote a file and then failed #242.

Test Plan

• the_guide_states_executed_call_and_turn_granular_hooks: pins the two guide claims and bans the stale phrase. Red against the old wording.
• no_spec_surface_requires_a_successful_mutating_call: iterates every static --spec surface, bans the phrase everywhere. Red against the old tools/skills sentences.
• Full workspace suite green (exit 0), clippy zero warnings, frozen prompt budget gate green.

Greptile Summary

This change updates the self-extension guide and rendered specifications to accurately explain activation timing. Tools and skills refresh after every executed mutating call, including a call that writes a file and then fails; permissions and templates apply on their next use; and newly installed hooks are discovered for the next turn.

The focused runtime test confirmed that a tool written by a script that exits nonzero is included in the following model request. The focused hook test confirmed that the currently discovered hook set remains in effect during a turn and that a fresh discovery controls the following turn. The updated guide and specification assertions passed. No defects were found.

Confidence Score: 5/5

Safe to merge: the product-facing documentation and static specifications now match the exercised runtime behavior.

Focused runtime checks covered a failed mutating writer, next-request refreeze, and hook behavior across a turn boundary; guide and specification regression checks also passed. No actionable findings remain.

Files Needing Attention: No files need follow-up attention.

T-Rex Logs

What T-Rex did

• Ran cargo test -p open-max-core --lib a_failed_mutating_call_that_wrote_a_tool_still_activates_it -- --nocapture; it exited successfully with one passing test, and the exercised shell tool wrote a tool file and exited with status 1, while the test verified that the second model request contained the newly written tool.
• Ran the focused guide and specification regression tests; each exited successfully and passed.
• Ran cargo test -p open-max-core --lib hooks::tests::swapping_an_approved_gates_script_fails_closed_instead_of_passing -- --exact --nocapture; it exited successfully with one passing test, and it verified that the already-discovered hook remains effective during the current turn and that fresh discovery defines the next-turn state.
• Compared the prior and revised wording and inspected the relevant implementation paths; the observed runtime behavior supports the new executed-call and next-turn hook wording.
• Publish recommendation: evidence supports publishing this documentation/spec correction.

_{Ran code and verified through T-Rex}

_{Reviews (1): Last reviewed commit: "docs(core): the guide and specs state th..." | Re-trigger Greptile}