docs: update hook module references

Author: ScriptedAlchemy

docs/AGENT-MEMORY-INTERCEPTION.md

@@ -91,7 +91,7 @@ hashes recorded under `[hooks.state]` in `config.toml`):
 **Key asymmetry vs Cursor:** Codex's `UserPromptSubmit` hook receives the
 prompt text *and* can inject `additionalContext` — a true per-prompt memory
 recall channel. TraceDecay already exploits this channel for tool-routing
-hints (`src/hooks.rs::hook_codex_user_prompt_submit` →
+hints (`src/hooks/codex.rs::hook_codex_user_prompt_submit` →
 `codex_user_prompt_submit_context_for_event` →
 `codex_additional_context_json("UserPromptSubmit", …)`), just not for facts.
 
@@ -138,7 +138,7 @@ cursor.com/docs/hooks): `sessionStart`/`sessionEnd`, `preToolUse`/`postToolUse`/
 `afterAgentResponse`/`afterAgentThought`, `workspaceOpen`.
 
 Context-injection capability per event (verified against docs + forum + the
-comment in `src/hooks.rs::hook_cursor_before_submit_prompt`):
+comment in `src/hooks/cursor.rs::hook_cursor_before_submit_prompt`):
 
 | Event | Injection field | Notes |
 | --- | --- | --- |
@@ -168,7 +168,7 @@ to `~/.cursor/plugins/local/tracedecay/`:
   `postToolUse`, `afterFileEdit`, `afterShellExecution`, `preCompact`,
   `sessionEnd`, `stop`, `workspaceOpen`, each shelling to
   `tracedecay hook-cursor-*` (dispatch: `src/hook_cmd.rs`, impls:
-  `src/hooks.rs`).
+  `src/hooks/`).
 - **`rules/tracedecay.mdc`** — always-applied rule; its **Recall** bullet
   steers models to `tracedecay_message_search` / `tracedecay_fact_store`
   search and the `recalling-project-memory` skill.
@@ -182,8 +182,8 @@ What the hooks currently do (all fail-open):
 
 - `sessionStart` (`hook_cursor_session_start`) — catch-up transcript ingest,
   then emits `additional_context` built by `build_cursor_session_context`
-  (`src/hooks.rs:1416`): **index status + skill list + tokens-saved counter.
-  No facts.** Sets `TRACEDECAY_PROJECT_ROOT` env.
+  (`src/hooks/steering.rs`): **index status + skill list + tokens-saved
+  counter. No facts.** Sets `TRACEDECAY_PROJECT_ROOT` env.
 - `beforeSubmitPrompt` — hot transcript ingest only; emits
   `{"continue": true}` (no context possible, see §2.3).
 - `postToolUse` — tool-routing hints via `additional_context`
@@ -302,23 +302,24 @@ Codex is the lowest-effort path because `UserPromptSubmit` carries the prompt
 text and honors `hookSpecificOutput.additionalContext`, and the hook binary is
 `tracedecay` with in-process store access (no MCP hop, fits the 5s timeout).
 
-- `SessionStart`: in `codex_session_context_for_event` (`src/hooks.rs:624`),
+- `SessionStart`: in `codex_session_context_for_event` (`src/hooks/codex.rs`),
   after workspace status, run `FactRetriever::search`/`list` for the top-K
   high-trust project facts (e.g. K=8, `min_trust` 0.6, category-diverse,
   newest-first tiebreak) and append a compact `## Project memory` block with
   fact ids ("rate with tracedecay_fact_feedback, correct with fact_store
   update"). Reuse the token-budget discipline the context builders already
   have.
 - `UserPromptSubmit`: in `codex_user_prompt_submit_context_for_event`
-  (`src/hooks.rs:1738`), embed the prompt (`prompt_like_text`) via the
+  (`src/hooks/codex.rs`), embed the prompt (`prompt_like_text`) via the
   existing HRR encoder and inject only facts above a similarity × trust
   threshold, deduped per session the same way tool hints are deduped
   (`deduped_codex_hint` pattern, `remember_hint_in_process`). Empty result →
   inject nothing (most prompts).
 - `SubagentStart`: optionally include the same session-start block so
   subagents inherit memory.
 
-Implementation pointers: `src/hooks.rs` (context builders above),
+Implementation pointers: `src/hooks/codex.rs`, `src/hooks/cursor.rs`,
+`src/hooks/steering.rs`, and shared helpers in `src/hooks/mod.rs`,
 `src/memory/retrieval.rs` (`FactRetriever::search/probe`), analytics via
 `record_hint_analytics` so injection quality is measurable. No plugin schema
 change; hook hashes change → users re-trust via `/hooks` (already documented
@@ -333,7 +334,8 @@ channels that exist:
 
 1. **`sessionStart.additional_context`** — extend
    `build_cursor_session_context` / `cursor_session_context_for_root`
-   (`src/hooks.rs:1416,610`) with the same top-K fact block as design A.
+   (`src/hooks/steering.rs`, `src/hooks/cursor.rs`) with the same top-K fact
+   block as design A.
    Cheap, but treat as best-effort given the open forum bugs about dropped
    `additional_context`.
 2. **Materialized always-applied memory rule** — generate
@@ -348,7 +350,7 @@ channels that exist:
 
 Implementation pointers: rule generation next to
 `cursor_plugin_manifest`/`write_embedded_plugin` (`src/agents/cursor.rs:404`),
-refresh in `hook_cursor_workspace_open` (`src/hooks.rs:666`); mark the file
+refresh in `hook_cursor_workspace_open` (`src/hooks/cursor.rs`); mark the file
 managed the same way the skill overlay marks generated skills
 (`managed_skill_format.rs`) so uninstall (`remove_cursor_plugin_install`) and
 doctor checks cover it.
@@ -451,7 +453,7 @@ alongside D and reusing the managed-file conventions from the skill overlay.
 
 ## 6. Recommended sequence
 
-1. **A + B1** (hook-based injection, both agents) — one PR in `src/hooks.rs`
+1. **A + B1** (hook-based injection, both agents) — one PR across `src/hooks/`
    + `src/memory/retrieval.rs` helpers; measurable via existing hook
    analytics.
 2. **B2 + C** (materialized Cursor memory rule + proactive storage wording) —

docs/HERMES-LOOPS-PARITY-AUDIT.md

@@ -3,7 +3,7 @@
 Status: comparison audit, July 2026. Hermes agent codebase examined at
 `/home/zack/projects/hermes-agent` (registered tracedecay project
 "hermes-agent"). TraceDecay side examined at HEAD of
-`feat/dashboard-ux-improvements`.
+the current TraceDecay worktree after dashboard automation work landed.
 
 This audit compares Hermes's self-improvement machinery (background review,
 memory writing, skill writing, curator, cron) against TraceDecay's automation

docs/SKILL-ADOPTION-RESEARCH.md

@@ -3,7 +3,7 @@
 *Research date: 2026-07-02. Read-only study of the local superpowers plugin
 (`~/.cursor/plugins/cache/cursor-public/superpowers/b7a8f76…/`), the installed
 TraceDecay plugins (`~/.cursor/plugins/local/tracedecay/`, `~/.codex/…`), the
-repo sources (`cursor-plugin/`, `codex-plugin/`, `src/hooks.rs`,
+repo sources (`cursor-plugin/`, `codex-plugin/`, `src/hooks/`,
 `src/mcp/tools/definitions.rs`), and TraceDecay's own analytics
 (`http://127.0.0.1:7341/api/plugins/analytics/*`,
 `~/.tracedecay/projects/proj_b4a8bbe4953823c4/hook_analytics.jsonl`).*
@@ -46,7 +46,8 @@ correlated usage**.
 So every session begins with the full bootstrap skill already in context — the
 model never has to *decide* to read it. Contrast: TraceDecay's Cursor
 session-start context is (by design, see the doc comment on
-`build_cursor_session_context` in `src/hooks.rs`) "intentionally lean":
+`build_cursor_session_context` in `src/hooks/steering.rs`) "intentionally
+lean":
 
 > `tracedecay index status: initialized.\nWorkflow skills: tracedecay:architecture-overview, …`
 > *(a comma-separated list of 25 names, no instructions)*
@@ -143,16 +144,16 @@ deliberate design choice preventing ad-hoc work.
 | Layer | Mechanism | Character |
 |---|---|---|
 | Always-applied rule | `cursor-plugin/rules/tracedecay.mdc` | ~15 bullet points of routing advice; "prefer/first/fallback" phrasing; no decision procedure, no counters to rationalization |
-| Session start (Cursor) | `build_cursor_session_context` in `src/hooks.rs` | Index status line + bare list of 25 skill names + tokens-saved counter. Doc comment says steering is deliberately left to the rule |
-| Session start (Codex) | `build_codex_session_context` in `src/hooks.rs` | One paragraph: "Prefer tracedecay MCP tools … over broad file reads"; CLI fallback note; index status |
-| Mid-session hints | `postToolUse` hook → `cursor_post_tool_use_decision` → `deduped_project_hint` (`src/hooks.rs`), dedupe in `src/hooks/tool_hints.rs` | Fires after Grep/Read/etc., but deduped to **once per (session, category) forever** (`ToolHintDedupe::should_emit` is a plain `HashSet::insert`) |
+| Session start (Cursor) | `build_cursor_session_context` in `src/hooks/steering.rs` | Index status line + bare list of 25 skill names + tokens-saved counter. Doc comment says steering is deliberately left to the rule |
+| Session start (Codex) | `build_codex_session_context_for_workspace` in `src/hooks/steering.rs` | One paragraph: "Prefer tracedecay MCP tools … over broad file reads"; CLI fallback note; index status |
+| Mid-session hints | `postToolUse` hook → `cursor_post_tool_use_decision` (`src/hooks/cursor.rs`) → `deduped_project_hint` (`src/hooks/mod.rs`), dedupe in `src/hooks/tool_hints.rs` | Fires after Grep/Read/etc., but deduped to **once per (session, category) forever** (`ToolHintDedupe::should_emit` is a plain `HashSet::insert`) |
 | Skills | `cursor-plugin/skills/` (40 dirs installed: 23 model-invocable + 15 `tracedecay-*` slash-command variants with `disable-model-invocation: true` + a `memorize-subject`/`memorizing-subject` near-duplicate pair); `codex-plugin/skills/` (25) | Descriptions are actually good "Use when…" trigger form; the problem is volume and overlap, not phrasing |
 | MCP tool descriptions | `src/mcp/tools/definitions.rs` (68+ tools) | Capability descriptions ("Search for symbols … by name or keyword"), not invocation triggers; only `tracedecay_outline` and `tracedecay_context` carry usage steering (the latter a *budget cap*, i.e. anti-usage steering) |
 
 Two structural notes:
 
 - The Cursor `beforeSubmitPrompt` hook **cannot inject context** (per the
-  comment at `src/hooks.rs:351`, only `user_message` is available on that
+  comment at `src/hooks/cursor.rs`, only `user_message` is available on that
   event), so per-prompt re-steering à la Codex's `UserPromptSubmit` is not
   available on Cursor — which makes sessionStart and postToolUse the only
   injection points, and both are currently minimal.
@@ -269,7 +270,7 @@ uses". `tracedecay_skill_list` was called 3 times ever;
    and default to the native tools they were RL-trained on. Superpowers shows
    that mandate framing + rationalization counters materially change this.
 2. **The session-start slot is spent on status, not behavior.** The lean
-   injection was a deliberate token economy (`src/hooks.rs:1413`), but it
+   injection was a deliberate token economy (`src/hooks/steering.rs`), but it
    delegates all steering to a rule that sits among *dozens* of other
    always-applied rules and skill listings, with no priority claim.
 3. **The mid-session correction loop is mostly inactive.** Once-per-session-per-category
@@ -295,7 +296,7 @@ uses". `tracedecay_skill_list` was called 3 times ever;
 ## 6. Recommendations (prioritized)
 
 ### P0 — Inject a behavioral contract at session start
-*Files: `src/hooks.rs` (`build_cursor_session_context`,
+*Files: `src/hooks/steering.rs` (`build_cursor_session_context`,
 `build_codex_session_context_for_workspace`, `CURSOR_PLUGIN_SKILLS`);
 new skill `cursor-plugin/skills/using-tracedecay/SKILL.md` (mirror in
 `codex-plugin/skills/`).*
@@ -326,7 +327,7 @@ Index status: {status}. Tokens saved this session: {n}.
 Keep it under ~40 lines; the token cost is what buys reliability.
 
 ### P0 — Resurrect the hint loop
-*Files: `src/hooks/tool_hints.rs` (`should_emit`), `src/hooks.rs`
+*Files: `src/hooks/tool_hints.rs` (`should_emit`), `src/hooks/mod.rs`
 (`deduped_project_hint`), `src/mcp/tool_analytics.rs` +
 `src/dashboard/analytics_api.rs` for telemetry.*
 
@@ -350,7 +351,7 @@ CLI-fallback and truncation-handle bullets (those are good).
 
 ### P1 — Consolidate the skill catalog to ~10 workflow-stage skills
 *Files: `cursor-plugin/skills/`, `codex-plugin/skills/`,
-`CURSOR_PLUGIN_SKILLS` in `src/hooks.rs`,
+`CURSOR_PLUGIN_SKILLS` in `src/hooks/steering.rs`,
 `tests/agent_suite/plugin_skill_contract_test.rs`.*
 
 Merge along workflow stages, mirroring superpowers' shape: **explore**