scriptoriumadmin/claude-skills
1
0
Fork 0
mirror of https://github.com/alirezarezvani/claude-skills.git synced 2026-08-28 04:24:58 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs(agent-memory): mark UserPromptSubmit provisional in hooks.json itself

Browse source 
Round-38 review noticed that the committed contract files already encode
an answer to some of 9's open decisions -- hooks.json wires
UserPromptSubmit even though 9.5's option (c) is to delete that hook.

The doc knew: 9.5 already says "if (c) wins, hooks.json must shrink too."
But that only helps a reader holding both files. Read on its own a
hooks.json says "these three hooks exist", which is precisely the wrong
impression, and a contract file is exactly the artifact someone reads on
its own before implementing. Same lesson as round 36's contested-tag gap,
one level up: a cross-reference is not a contract, and that applies
between files as much as between sections.

hooks.json's own description now marks the entry PROVISIONAL, names the
open decision, gives the reason (the budget is dominated by interpreter
cold-start, not by the script's work), and says plainly that listing the
hook is a contract for the shape it would take IF it survives -- not
evidence the decision was made. SessionStart and SessionEnd are marked
not provisional so the warning stays scoped.

Verified: hooks.json parses; 69 checks, 0 failures; derive_counters.py
--check unchanged (363/89/663).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EM5xmJ7AmTMg31rq68BCym
This commit is contained in:
Claude 2026-08-09 07:57:13 +00:00
parent ae42235e5e
commit 67a1228828
No known key found for this signature in database
1 changed files with 1 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
engineering/agent-memory/hooks/hooks.json
View file

@ -1,5 +1,5 @@
{
"description": "CONTRACT ONLY — the referenced scripts are not yet implemented (see ../DESIGN.md). Three hooks implementing the L0-L3 memory tiers. SessionStart injects L3 (global persona) + L2 (current project context). UserPromptSubmit recalls relevant L1 atoms. SessionEnd asynchronously captures L0 into L1 and stages promotions for human adoption. Every hook fails open (exit 0, no memory) and never blocks. Disable individually with AGENT_MEMORY_SESSIONSTART=0, AGENT_MEMORY_USERPROMPTSUBMIT=0, AGENT_MEMORY_SESSIONEND=0. NOTE ON THE RECALL TIMEOUT: the hook 'timeout' field below is in SECONDS and 1 is its floor, so it is only a backstop against a wedged process. The real requirement is the 100ms internal self-budget that user_prompt_submit.py must enforce against its own monotonic clock, returning whatever it has when the budget expires. See DESIGN.md section 5.2 — finishing under 1s does NOT satisfy the spec, and section 9.5 tracks whether 100ms is achievable at all given python interpreter cold-start.",
"description": "CONTRACT ONLY — the referenced scripts are not yet implemented (see ../DESIGN.md). PROVISIONAL ENTRY: the UserPromptSubmit hook below is NOT a settled part of the design. DESIGN.md section 9.5 is an open decision whose option (c) is to drop this hook entirely, because its 100ms recall budget is dominated by python interpreter cold-start rather than by any work the script does. This file listing the hook is a contract for the shape it would take IF it survives that decision, not evidence the decision was made — read on its own, a hooks.json says \"these three hooks exist\", which is exactly the wrong impression here. SessionStart and SessionEnd are not provisional. Three hooks implementing the L0-L3 memory tiers. SessionStart injects L3 (global persona) + L2 (current project context). UserPromptSubmit recalls relevant L1 atoms. SessionEnd asynchronously captures L0 into L1 and stages promotions for human adoption. Every hook fails open (exit 0, no memory) and never blocks. Disable individually with AGENT_MEMORY_SESSIONSTART=0, AGENT_MEMORY_USERPROMPTSUBMIT=0, AGENT_MEMORY_SESSIONEND=0. NOTE ON THE RECALL TIMEOUT: the hook 'timeout' field below is in SECONDS and 1 is its floor, so it is only a backstop against a wedged process. The real requirement is the 100ms internal self-budget that user_prompt_submit.py must enforce against its own monotonic clock, returning whatever it has when the budget expires. See DESIGN.md section 5.2 — finishing under 1s does NOT satisfy the spec, and section 9.5 tracks whether 100ms is achievable at all given python interpreter cold-start.",
"hooks": {
"SessionStart": [
{