@softspark/ai-toolkit 4.8.0 → 4.10.0

package/kb/reference/architecture-overview.md

@@ -35,7 +35,7 @@ ai-toolkit/
     rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
     hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
-    constitution.md          # Immutable safety rules, 6 articles (marker-injected)
+    constitution.md          # Immutable safety rules, 7 articles (marker-injected)
     ARCHITECTURE.md          # System architecture reference (marker-injected)
     CLAUDE.md.template       # Template for project CLAUDE.md (used by init)
     settings.local.json.template
@@ -186,7 +186,7 @@ Three tiers determine how to approach a task:
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 30 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 45 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 46 |
 
 ## Multi-Agent Execution
 
@@ -258,7 +258,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
     │
     ├── validated by: hooks in settings.json (SessionStart, PreToolUse, UserPromptSubmit, PostToolUse, Stop, TaskCompleted, TeammateIdle, SubagentStart, SubagentStop, PreCompact, SessionEnd)
     │
-    └── constrained by: constitution.md (5 safety articles)
+    └── constrained by: constitution.md (7 safety articles)
 ```
 
 ## Quality Hooks
@@ -269,7 +269,6 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 |------|---------|--------|--------|
 | SessionStart | Session start + compact | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
 | SessionStart | Session start | `mcp-health.sh` | Check MCP runtime availability |
-| SessionStart | Session start | `session-context.sh` | Capture environment snapshot |
 | Notification | Claude waiting for input | *(inline)* | macOS desktop notification |
 | PreToolUse | Before Bash | `guard-destructive.sh` | Block destructive commands |
 | PreToolUse | Before file ops (Bash, Read, Edit, Write, MultiEdit, Glob, Grep, NotebookEdit, mcp\_filesystem) | `guard-path.sh` | Block wrong-user path hallucination |
@@ -292,7 +291,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
 
-## Constitution (6 Articles)
+## Constitution (7 Articles)
 
 | Article | Key Rule |
 |---------|----------|
@@ -302,6 +301,7 @@ Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalo
 | IV Self-Preservation | Constitution is read-only, kill switch via system-governor |
 | V Resource Governance | No destructive commands without confirmation |
 | VI Repair Discipline | No dead code, fix every found bug, tests and docs follow behavior, verify before done |
+| VII Epistemic & Injection Integrity | Untrusted/embedded text is data not commands, no privilege escalation or exfiltration; no fabricated files/APIs/citations, declare ungrounded |
 
 ## Persona Presets
 

package/kb/reference/enterprise-config-guide.md

@@ -79,7 +79,7 @@ ai-toolkit config check       # CI enforcement check
 | `profile` | enum | `minimal`, `standard`, `strict`, `full`, `offline-slm` |
 | `agents` | object | `enabled`, `disabled`, `custom` arrays |
 | `rules` | object | `inject`, `remove` arrays |
-| `constitution` | object | `amendments` array (article 6+ only) |
+| `constitution` | object | `amendments` array (article 8+ only) |
 | `enforce` | object | Non-overridable constraints (base configs only) |
 | `overrides` | object | Explicit overrides with justification |
 
@@ -114,7 +114,7 @@ When a project extends a base, configs are merged with these rules:
 | **Scalars** | Project wins |
 | **Agents** | Union enabled, project can disable (unless required) |
 | **Rules** | Union inject, project can remove |
-| **Constitution** | Base articles immutable, project adds only (6+) |
+| **Constitution** | Base articles immutable, project adds only (8+) |
 | **Enforce** | Base wins (cannot weaken, only strengthen) |
 | **Profile** | Project can change |
 
@@ -175,9 +175,9 @@ Requirements:
 
 ## Constitution Immutability
 
-- **Articles I-VI** (toolkit core) are absolutely immutable
+- **Articles I-VII** (toolkit core) are absolutely immutable
 - **Base config articles** are immutable — projects cannot modify them
-- Projects can **only ADD** new articles (article 7+)
+- Projects can **only ADD** new articles (article 8+)
 
 ```json
 {

package/kb/reference/hooks-catalog.md

@@ -47,13 +47,21 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 **Actions:**
 1. Injects MANDATORY reminder to follow CLAUDE.md rules
 2. Injects REMINDER about tests and documentation
-3. Loads session context from `.claude/session-context.md` (if exists)
+3. Loads session context from the per-repo session store (if exists)
 4. Loads active instincts from `.claude/instincts/*.md` (if any)
 
 By default the hook performs session-state reset, stale search-flag cleanup, and
 update notification side effects without printing informational stdout. Set
-`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
-for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
+`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context for
+debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
+
+> **Session storage:** auto-generated session artifacts (context, handoff note,
+> checkpoints, decisions) are stored **outside the project repo** under
+> `~/.softspark/ai-toolkit/sessions/<repo-key>/`, where `<repo-key>` is the git
+> work-tree root path (fallback: cwd) with `/` replaced by `-` (mirrors Claude
+> Code's own `~/.claude/projects/` convention). This keeps generated files from
+> piling up in every project's `.claude/` directory. Path resolution lives in the
+> shared helper `app/hooks/_session-paths.sh`.
 
 ### Notification — `notify-waiting.sh`
 
@@ -192,10 +200,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
 
-**Action:** Writes enriched session context to `.claude/session-context.md` for cross-session persistence. Captures:
+**Action:** Writes enriched session context to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/session-context.md`) for cross-session persistence. Captures:
 - Session ID and last assistant message (first 5 lines)
 - Git branch, uncommitted change count, and diff stat (last 5 lines)
-- Agent-written checkpoints from `.claude/session-context.md.checkpoints` (if present — written by proactive checkpointing per Constitution Art. I §5)
+- Agent-written checkpoints from `session-context.md.checkpoints` in the same store (if present — written by proactive checkpointing per Constitution Art. I §5)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -263,9 +271,9 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 **Actions (prioritized — higher priority items survive tighter token budgets):**
 1. **Mandatory reload reminder** — always emitted, instructs Claude to re-read CLAUDE.md and active tasks
 2. **Active instincts** — lists each instinct with confidence score and pattern name from `.claude/instincts/*.md`
-3. **Session context** — preserves task state from `.claude/session-context.md` (if exists)
+3. **Session context** — preserves task state from the per-repo session store (if exists)
 4. **Git working state** — branch name, uncommitted change count, last commit (if inside a git repo)
-5. **Key decisions** — last 10 lines from `.claude/decisions.md` (if exists)
+5. **Key decisions** — last 10 lines from `decisions.md` in the per-repo session store (if exists)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -278,7 +286,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
 | Fires | When a Claude session ends |
 
-**Action:** Writes `.claude/session-end.md` with a lightweight handoff note for the next session and reminds the next session to review preserved context.
+**Action:** Writes `session-end.md` to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/`) with a lightweight handoff note for the next session and reminds the next session to review preserved context.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -351,17 +359,6 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 **Action:** Non-blocking (always exits 0). Inspects Bash commands containing `git commit`. Extracts the commit message from the `-m` flag and checks it against Conventional Commits format (`type: description`, where type is one of feat/fix/docs/refactor/test/chore/ci/perf/style/revert). Emits an advisory warning if the message does not match — the commit is not blocked, only nudged. Commands without `git commit` or without a `-m` message (e.g. interactive commits) are ignored.
 
-### SessionStart — `session-context.sh`
-
-| Field | Value |
-|-------|-------|
-| Event | `SessionStart` |
-| Matcher | *(all)* |
-| Script | `~/.softspark/ai-toolkit/hooks/session-context.sh` |
-| Fires | Session start |
-
-**Action:** Captures an environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
-
 ---
 
 ## New Hooks (Constitution Art. VI Enforcement)
@@ -520,8 +517,8 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
     ├── _locate-toolkit.sh        # NEW: shared $TOOLKIT_DIR locator
     ├── _hook-io.sh               # NEW: shared multi-editor payload/output adapter
     ├── _search-capability.sh     # NEW: capability-aware search-first enforcement
+    ├── _session-paths.sh         # NEW: per-repo session storage path resolver
     ├── session-start.sh
-    ├── session-context.sh
     ├── guard-destructive.sh
     ├── guard-path.sh
     ├── guard-config.sh
@@ -549,7 +546,7 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 
 ~/.claude/settings.json
 └── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
-    ├── SessionStart       → session-start.sh, mcp-health.sh, session-context.sh
+    ├── SessionStart       → session-start.sh, mcp-health.sh
     ├── Notification       → notify-waiting.sh
     ├── PreToolUse         → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh, revert-guard.sh
     ├── UserPromptSubmit   → user-prompt-submit.sh, track-usage.sh
@@ -590,7 +587,7 @@ Windsurf rebranded to Devin Desktop (2026-06-02); the Cascade agent — and its
 Devin CLI uses a **Claude-compatible** hook format (docs.devin.ai/cli/extensibility/hooks). Key facts driving the generator:
 
 - **Standalone file shape:** in `.devin/hooks.v1.json` the entire file IS the hooks object — no top-level `"hooks"` wrapper key (unlike `.claude/settings.json`).
-- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SessionStart`. `post_setup_worktree` has no Devin equivalent (`session-context.sh` moves to `SessionStart`); `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
+- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`. `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
 - **Matchers:** regex against the Devin **tool name** (`read`, `edit`, `exec`, `grep`, `glob`, `mcp__<server>__<tool>`) — NOT Claude's `Bash`/`Edit`, so the shared guards reliably fire.
 - **Block contract:** the guard scripts emit `{"decision":"block","reason":...}` on stdout (plain mode) AND exit 2 — Devin honors both. Hooks run **without** `AI_TOOLKIT_HOOK_FORMAT=json` because Devin expects the flat `{"decision","reason"}` shape, not Claude's `hookSpecificOutput` envelope.
 - **Stdin payload:** flat `{ "hook_event_name", "tool_name", "tool_input" }` — already handled by `_hook-io.sh` via its `.tool_name` / `.tool_input.*` branches, so no normalizer change was needed.

package/kb/reference/opencode-compatibility.md

@@ -79,7 +79,7 @@ Each command file carries the prompt in its markdown body (built from the SKILL.
 
 | opencode event             | Bash hook(s)                                                       |
 |----------------------------|--------------------------------------------------------------------|
-| `session.created`          | `session-start.sh` + `session-context.sh` + `mcp-health.sh`        |
+| `session.created`          | `session-start.sh` + `mcp-health.sh`                               |
 | `session.compacted`        | `pre-compact.sh` + `pre-compact-save.sh` (PreCompact equivalent)   |
 | `session.deleted`          | `session-end.sh` + `save-session.sh`                               |
 | `message.updated`          | `user-prompt-submit.sh` + `track-usage.sh`                         |

package/kb/reference/skills-catalog.md

@@ -161,7 +161,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **content-moderation-patterns** | `skills/content-moderation-patterns/` | Two-stage moderation: pre-filter + LLM classifier; categories; thresholds |
 | **model-routing-patterns** | `skills/model-routing-patterns/` | Haiku/Sonnet/Opus routing; escalation; sub-agent delegation; fallback |
 
-## Knowledge Skills - Process (5)
+## Knowledge Skills - Process (6)
 
 | Skill | Directory | Domain |
 |-------|-----------|--------|
@@ -169,6 +169,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **architecture-decision** | `skills/architecture-decision/` | Architecture notes, trade-off analysis, alternatives |
 | **performance-profiling** | `skills/performance-profiling/` | Profiling, bottleneck analysis, optimization |
 | **research-mastery** | `skills/research-mastery/` | Multi-source research, synthesis, fact-checking |
+| **deep-research** | `skills/deep-research/` | Web/multi-source research methodology, retrieval budget, adversarial verification, citation discipline |
 | **verification-before-completion** | `skills/verification-before-completion/` | Iron Law: evidence-before-claims, no completion without fresh verification |
 
 ## Quality Guardrails

package/kb/reference/supported-tools-registry.md

@@ -170,7 +170,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Config paths | `AGENTS.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `.codex/config.toml` (project layers, root→cwd, closest wins, trusted projects only), `~/.codex/config.toml` |
 | Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | Rules delivery | Universal coding rules are inlined into `AGENTS.md` (Codex reads instructions only from AGENTS.md, not `.agents/rules/`); language rules ship as `<lang>-rules` skills under `.agents/skills/`. |
-| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire all 10 to shared toolkit hook scripts, mirroring the Claude Code mapping in `app/hooks.json`. |
+| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire 9 of these to shared toolkit hook scripts, mirroring the Claude Code mapping in `app/hooks.json`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
 | Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |

package/kb/reference/unique-features.md

@@ -27,7 +27,6 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 |-------|--------|--------|
 | SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts + reset session-edit state |
 | SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
-| SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
 | Notification | `notify-waiting.sh` | Cross-platform desktop notification |
 | PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |

package/llms-full.txt

@@ -21,6 +21,7 @@
 - [Plan: Output & Token Discipline](kb/history/completed/output-token-discipline-plan-20260504.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
+- [Plan: Drop Cascade hooks after 2026-07-01 sunset](kb/planning/drop-cascade-hooks-after-sunset.md)
 - [PRD: MCP Context Trim v4.0](kb/planning/mcp-context-trim-v4-prd.md)
 - [SOP: Ecosystem Sync](kb/procedures/ecosystem-sync-sop.md)
 - [SOP: Claude Toolkit Maintenance](kb/procedures/maintenance-sop.md)
@@ -92,6 +93,7 @@
 - **dart-rules**: Dart/Flutter coding rules: style, patterns, security, testing. Triggers: .dart, pubspec.yaml, Flutter, Riverpod, Bloc, widget, StatelessWidget, StatefulWidget.
 - **database-patterns**: DB schema design and query tuning: normalization, indexing, N+1, transactions, EXPLAIN. Triggers: schema, index, slow query, N+1, PostgreSQL, MySQL, EXPLAIN, deadlock, query plan.
 - **debug**: Systematic debugging via logs, health checks, hypothesis-driven investigation. Triggers: debug, error, trace root cause, fix bug, reproduce symptom, investigation.
+- **deep-research**: Multi-source web research methodology: retrieve-vs-answer gate, complexity-scaled search budget, query craft, primary-source preference, source-conflict skepticism, adversarial verification, attribution-without-reproduction. Triggers: deep research, multi-source, web research, synthesize sources, cross-reference, fact synthesis, source verification.
 - **deploy**: Deploys with pre-flight checks and health verification. Triggers: deploy, deployment, ship, release, push to prod.
 - **design-an-interface**: Generates and compares parallel interface designs (Ousterhout 'Design It Twice'). Triggers: design API, interface options, compare modules, design it twice.
 - **design-engineering**: UI craftsmanship: animation rules, easing, micro-interactions, state polish. Triggers: animation, transition, ease-out, motion, micro-interaction, hover, loading state, UI polish.
@@ -155,7 +157,7 @@
 - **ruby-rules**: Ruby coding rules: style, patterns, security, testing. Triggers: .rb, Gemfile, .gemspec, Rails, ActiveRecord, Sidekiq, RSpec, Sorbet, rubocop.
 - **rust-patterns**: Rust: ownership, lifetimes, async (Tokio), Result/anyhow/thiserror, traits, unsafe. Triggers: Rust, borrow checker, lifetime, Tokio, cargo, trait, impl, Result, unsafe, clippy.
 - **rust-rules**: Rust coding rules: style, patterns, security, testing. Triggers: .rs, Cargo.toml, Cargo.lock, Tokio, Axum, Serde, clippy, cargo test.
-- **security-patterns**: App security: OWASP, authN/authZ, input validation, secrets, TLS, CSRF/XSS/SQLi, JWT, CSP. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, TLS, CSP, CORS.
+- **security-patterns**: App security: OWASP, authN/authZ, input validation, secrets, TLS, CSRF/XSS/SQLi, JWT, CSP, LLM prompt injection. Triggers: security, OWASP, auth, JWT, CSRF, XSS, SQL injection, secrets, TLS, CSP, CORS, prompt injection, LLM output trust, tool permissions.
 - **seo-validate**: SEO validator: meta/OG, Schema.org, hreflang, Core Web Vitals, crawlability. Triggers: SEO, meta tags, Schema.org, hreflang, LCP, INP, CLS, Core Web Vitals, sitemap, crawlability.
 - **skill-audit**: Scans skills/agents for security risks: dangerous patterns, secrets, excessive perms. Triggers: skill audit, security scan, agent audit, dangerous pattern.
 - **skill-creator**: Creates new skills from templates via guided workflow. Triggers: new skill, create skill, skill scaffold, skill template.
@@ -3974,6 +3976,102 @@ Examples:
 
 ---
 
+## kb/planning/drop-cascade-hooks-after-sunset.md
+
+---
+title: "Plan: Drop Cascade hooks after 2026-07-01 sunset"
+category: planning
+service: ai-toolkit
+tags:
+  - windsurf
+  - devin
+  - cascade
+  - hooks
+  - deprecation
+  - cleanup
+doc_type: plan
+status: scheduled
+created: "2026-06-10"
+last_updated: "2026-06-10"
+completion: "0%"
+trigger_date: "2026-07-01"
+description: "Scheduled cleanup: remove the deprecated Windsurf Cascade hooks generator (.windsurf/hooks.json) in the first ai-toolkit release after the 2026-07-01 Cascade sunset. The Devin CLI replacement (.devin/hooks.v1.json) shipped in v4.8.0; this plan removes the dead Cascade half once it can no longer run."
+---
+
+# Plan: Drop Cascade hooks after 2026-07-01 sunset
+
+## Why this exists
+
+Windsurf rebranded to Devin Desktop on 2026-06-02. The Cascade agent — and its
+`.windsurf/hooks.json` hook surface (`agent_action_name`/`tool_info` format) — is
+available **only through 2026-07-01**. Devin Local / Devin CLI do **not** read
+`.windsurf/hooks.json` as a fallback.
+
+v4.8.0 already shipped the replacement: `generate_devin_hooks.py` emits
+`.devin/hooks.v1.json` in the Claude-compatible format Devin CLI uses. During the
+transition **both** generators run at `profile=full` so pre-sunset Cascade users
+keep working. After 2026-07-01 the Cascade half is dead code and must be removed
+(Constitution Art. VI.1 — no dead code).
+
+## Trigger
+
+First ai-toolkit release **on or after 2026-07-01**. Do NOT do this earlier —
+removing it before the sunset breaks Cascade users who are still on the old agent.
+
+## Scope — remove the Cascade hooks surface
+
+1. **Delete the generator:** `scripts/generate_windsurf_hooks.py`.
+2. **Unwire the install step:** in `scripts/install_steps/ai_tools.py`, remove the
+   `_try_generator("generate_windsurf_hooks", cwd)` call (keep
+   `generate_devin_hooks`). Update the `profile=full` dry-run message to drop
+   `.windsurf/hooks.json (Cascade, deprecated)`.
+3. **Tests:** remove the windsurf-`.windsurf/hooks.json` cases from
+   `tests/test_hooks_per_editor.bats` (output path, valid JSON, source tag,
+   `$HOME` prefix, idempotence, user-preservation, `pre_write_code` coverage) and
+   the `profile=full` assertion in `tests/test_install_profiles.bats`
+   (`windsurf + full emits .windsurf/hooks.json`). Keep all `.devin/hooks.v1.json`
+   tests. Adjust the README test-count badge to the new total.
+4. **Registry:** in `scripts/ecosystem_tools.json` (windsurf entry), remove
+   `scripts/generate_windsurf_hooks.py` from `our_generators`; keep
+   `.windsurf/hooks.json` out of `config_paths` (it was never listed). Trim the
+   `status_note` hooks-migration paragraph to past tense ("Cascade hooks removed
+   in vX.Y.Z").
+5. **Docs:** in `kb/reference/supported-tools-registry.md` drop the
+   `generate_windsurf_hooks.py` row and the "drop after 2026-07-01" note; in
+   `kb/reference/hooks-catalog.md` remove the Cascade row from the
+   Per-Editor Native Hooks table and the deprecation wording, leaving the Devin CLI
+   section as the windsurf-family hook surface.
+6. **validate.py:** the `_HOOK_STEM_ALIAS = {"devin": "windsurf"}` mapping STAYS —
+   it is what keeps the `devin` hook generator counted as windsurf hooks in the
+   README-honesty check after the Cascade generator is gone.
+7. **CHANGELOG / version:** minor bump, `Removed` entry, regen artifacts, full
+   release-preparation SOP gate.
+
+## Verification
+
+- `python3 scripts/validate.py --strict` — 0/0 (editor-hooks-honesty must still
+  report windsurf as hook-enabled via the `devin` generator alias).
+- `python3 scripts/ecosystem_doctor.py --offline --check` — exit 0.
+- `npm test` — 0 `not ok`; confirm no test still references
+  `generate_windsurf_hooks.py` or `.windsurf/hooks.json`.
+- `grep -rn "generate_windsurf_hooks\|windsurf/hooks.json" scripts/ tests/ kb/ README.md`
+  returns nothing (Art. VI.1 orphan check).
+
+## Do NOT touch
+
+- `generate_devin_hooks.py` and `.devin/hooks.v1.json` — the live replacement.
+- The `.devin/`/`.windsurf/` rules + skills dual-emit (that fallback persists as
+  long as Devin Desktop reads legacy `.windsurf/` paths; this plan is hooks-only).
+
+## Related
+
+- `kb/reference/hooks-catalog.md` — Per-Editor Native Hooks + Devin CLI section
+- `kb/reference/supported-tools-registry.md` — windsurf entry, hooks-migration row
+- `kb/procedures/ecosystem-sync-sop.md` — class-D deprecation workflow
+- `scripts/ecosystem_tools.json` — windsurf `status_note`
+
+---
+
 ## kb/planning/mcp-context-trim-v4-prd.md
 
 ---
@@ -6169,7 +6267,7 @@ ai-toolkit/
     rules/                   # Rules auto-injected into ~/.claude/CLAUDE.md
     hooks/                   # Hook scripts (copied to ~/.softspark/ai-toolkit/hooks/)
     hooks.json               # Hook definitions (merged into ~/.claude/settings.json)
-    constitution.md          # Immutable safety rules, 6 articles (marker-injected)
+    constitution.md          # Immutable safety rules, 7 articles (marker-injected)
     ARCHITECTURE.md          # System architecture reference (marker-injected)
     CLAUDE.md.template       # Template for project CLAUDE.md (used by init)
     settings.local.json.template
@@ -6320,7 +6418,7 @@ Three tiers determine how to approach a task:
 |------|-------|-----------|-------|
 | Task | `disable-model-invocation: true` | User via `/skill` only | 32 |
 | Hybrid | (neither) | User via `/skill` + agent knowledge | 30 |
-| Knowledge | `user-invocable: false` | Claude auto-loads | 45 |
+| Knowledge | `user-invocable: false` | Claude auto-loads | 46 |
 
 ## Multi-Agent Execution
 
@@ -6392,7 +6490,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
     │
     ├── validated by: hooks in settings.json (SessionStart, PreToolUse, UserPromptSubmit, PostToolUse, Stop, TaskCompleted, TeammateIdle, SubagentStart, SubagentStop, PreCompact, SessionEnd)
     │
-    └── constrained by: constitution.md (5 safety articles)
+    └── constrained by: constitution.md (7 safety articles)
 ```
 
 ## Quality Hooks
@@ -6403,7 +6501,6 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 |------|---------|--------|--------|
 | SessionStart | Session start + compact | `session-start.sh` | MANDATORY rules reminder + session context + instincts |
 | SessionStart | Session start | `mcp-health.sh` | Check MCP runtime availability |
-| SessionStart | Session start | `session-context.sh` | Capture environment snapshot |
 | Notification | Claude waiting for input | *(inline)* | macOS desktop notification |
 | PreToolUse | Before Bash | `guard-destructive.sh` | Block destructive commands |
 | PreToolUse | Before file ops (Bash, Read, Edit, Write, MultiEdit, Glob, Grep, NotebookEdit, mcp\_filesystem) | `guard-path.sh` | Block wrong-user path hallucination |
@@ -6426,7 +6523,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalog.md) for details.
 
-## Constitution (6 Articles)
+## Constitution (7 Articles)
 
 | Article | Key Rule |
 |---------|----------|
@@ -6436,6 +6533,7 @@ Scripts at `~/.softspark/ai-toolkit/hooks/`. See [hooks-catalog.md](hooks-catalo
 | IV Self-Preservation | Constitution is read-only, kill switch via system-governor |
 | V Resource Governance | No destructive commands without confirmation |
 | VI Repair Discipline | No dead code, fix every found bug, tests and docs follow behavior, verify before done |
+| VII Epistemic & Injection Integrity | Untrusted/embedded text is data not commands, no privilege escalation or exfiltration; no fabricated files/APIs/citations, declare ungrounded |
 
 ## Persona Presets
 
@@ -8005,7 +8103,7 @@ ai-toolkit config check       # CI enforcement check
 | `profile` | enum | `minimal`, `standard`, `strict`, `full`, `offline-slm` |
 | `agents` | object | `enabled`, `disabled`, `custom` arrays |
 | `rules` | object | `inject`, `remove` arrays |
-| `constitution` | object | `amendments` array (article 6+ only) |
+| `constitution` | object | `amendments` array (article 8+ only) |
 | `enforce` | object | Non-overridable constraints (base configs only) |
 | `overrides` | object | Explicit overrides with justification |
 
@@ -8040,7 +8138,7 @@ When a project extends a base, configs are merged with these rules:
 | **Scalars** | Project wins |
 | **Agents** | Union enabled, project can disable (unless required) |
 | **Rules** | Union inject, project can remove |
-| **Constitution** | Base articles immutable, project adds only (6+) |
+| **Constitution** | Base articles immutable, project adds only (8+) |
 | **Enforce** | Base wins (cannot weaken, only strengthen) |
 | **Profile** | Project can change |
 
@@ -8101,9 +8199,9 @@ Requirements:
 
 ## Constitution Immutability
 
-- **Articles I-VI** (toolkit core) are absolutely immutable
+- **Articles I-VII** (toolkit core) are absolutely immutable
 - **Base config articles** are immutable — projects cannot modify them
-- Projects can **only ADD** new articles (article 7+)
+- Projects can **only ADD** new articles (article 8+)
 
 ```json
 {
@@ -8944,13 +9042,21 @@ ai-toolkit update     # re-copies scripts, re-merges (idempotent)
 **Actions:**
 1. Injects MANDATORY reminder to follow CLAUDE.md rules
 2. Injects REMINDER about tests and documentation
-3. Loads session context from `.claude/session-context.md` (if exists)
+3. Loads session context from the per-repo session store (if exists)
 4. Loads active instincts from `.claude/instincts/*.md` (if any)
 
 By default the hook performs session-state reset, stale search-flag cleanup, and
 update notification side effects without printing informational stdout. Set
-`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context
-for debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
+`AI_TOOLKIT_HOOK_VERBOSE=1` to print the startup reminders and loaded context for
+debugging; `AI_TOOLKIT_HOOK_QUIET=1` keeps it silent explicitly.
+
+> **Session storage:** auto-generated session artifacts (context, handoff note,
+> checkpoints, decisions) are stored **outside the project repo** under
+> `~/.softspark/ai-toolkit/sessions/<repo-key>/`, where `<repo-key>` is the git
+> work-tree root path (fallback: cwd) with `/` replaced by `-` (mirrors Claude
+> Code's own `~/.claude/projects/` convention). This keeps generated files from
+> piling up in every project's `.claude/` directory. Path resolution lives in the
+> shared helper `app/hooks/_session-paths.sh`.
 
 ### Notification — `notify-waiting.sh`
 
@@ -9089,10 +9195,10 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/save-session.sh` |
 | Fires | After every Claude response |
 
-**Action:** Writes enriched session context to `.claude/session-context.md` for cross-session persistence. Captures:
+**Action:** Writes enriched session context to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/session-context.md`) for cross-session persistence. Captures:
 - Session ID and last assistant message (first 5 lines)
 - Git branch, uncommitted change count, and diff stat (last 5 lines)
-- Agent-written checkpoints from `.claude/session-context.md.checkpoints` (if present — written by proactive checkpointing per Constitution Art. I §5)
+- Agent-written checkpoints from `session-context.md.checkpoints` in the same store (if present — written by proactive checkpointing per Constitution Art. I §5)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9160,9 +9266,9 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 **Actions (prioritized — higher priority items survive tighter token budgets):**
 1. **Mandatory reload reminder** — always emitted, instructs Claude to re-read CLAUDE.md and active tasks
 2. **Active instincts** — lists each instinct with confidence score and pattern name from `.claude/instincts/*.md`
-3. **Session context** — preserves task state from `.claude/session-context.md` (if exists)
+3. **Session context** — preserves task state from the per-repo session store (if exists)
 4. **Git working state** — branch name, uncommitted change count, last commit (if inside a git repo)
-5. **Key decisions** — last 10 lines from `.claude/decisions.md` (if exists)
+5. **Key decisions** — last 10 lines from `decisions.md` in the per-repo session store (if exists)
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9175,7 +9281,7 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 | Script | `~/.softspark/ai-toolkit/hooks/session-end.sh` |
 | Fires | When a Claude session ends |
 
-**Action:** Writes `.claude/session-end.md` with a lightweight handoff note for the next session and reminds the next session to review preserved context.
+**Action:** Writes `session-end.md` to the per-repo session store (`~/.softspark/ai-toolkit/sessions/<repo-key>/`) with a lightweight handoff note for the next session and reminds the next session to review preserved context.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
@@ -9248,17 +9354,6 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 **Action:** Non-blocking (always exits 0). Inspects Bash commands containing `git commit`. Extracts the commit message from the `-m` flag and checks it against Conventional Commits format (`type: description`, where type is one of feat/fix/docs/refactor/test/chore/ci/perf/style/revert). Emits an advisory warning if the message does not match — the commit is not blocked, only nudged. Commands without `git commit` or without a `-m` message (e.g. interactive commits) are ignored.
 
-### SessionStart — `session-context.sh`
-
-| Field | Value |
-|-------|-------|
-| Event | `SessionStart` |
-| Matcher | *(all)* |
-| Script | `~/.softspark/ai-toolkit/hooks/session-context.sh` |
-| Fires | Session start |
-
-**Action:** Captures an environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json`. Records working directory, git branch, git status summary, Node.js version, Python version, and timestamp. Used by other hooks and tools to access session metadata without re-running discovery commands. Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
-
 ---
 
 ## New Hooks (Constitution Art. VI Enforcement)
@@ -9417,8 +9512,8 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
     ├── _locate-toolkit.sh        # NEW: shared $TOOLKIT_DIR locator
     ├── _hook-io.sh               # NEW: shared multi-editor payload/output adapter
     ├── _search-capability.sh     # NEW: capability-aware search-first enforcement
+    ├── _session-paths.sh         # NEW: per-repo session storage path resolver
     ├── session-start.sh
-    ├── session-context.sh
     ├── guard-destructive.sh
     ├── guard-path.sh
     ├── guard-config.sh
@@ -9446,7 +9541,7 @@ commands explicitly silent, and Codex-generated hooks plus Claude's bundled
 
 ~/.claude/settings.json
 └── hooks:          # Hook definitions referencing ~/.softspark/ai-toolkit/hooks/
-    ├── SessionStart       → session-start.sh, mcp-health.sh, session-context.sh
+    ├── SessionStart       → session-start.sh, mcp-health.sh
     ├── Notification       → notify-waiting.sh
     ├── PreToolUse         → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh, revert-guard.sh
     ├── UserPromptSubmit   → user-prompt-submit.sh, track-usage.sh
@@ -9487,7 +9582,7 @@ Windsurf rebranded to Devin Desktop (2026-06-02); the Cascade agent — and its
 Devin CLI uses a **Claude-compatible** hook format (docs.devin.ai/cli/extensibility/hooks). Key facts driving the generator:
 
 - **Standalone file shape:** in `.devin/hooks.v1.json` the entire file IS the hooks object — no top-level `"hooks"` wrapper key (unlike `.claude/settings.json`).
-- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`, `SessionStart`. `post_setup_worktree` has no Devin equivalent (`session-context.sh` moves to `SessionStart`); `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
+- **Events:** Claude-style PascalCase — `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `Stop`. `post_cascade_response` maps to `Stop` (which carries no response text on stdin).
 - **Matchers:** regex against the Devin **tool name** (`read`, `edit`, `exec`, `grep`, `glob`, `mcp__<server>__<tool>`) — NOT Claude's `Bash`/`Edit`, so the shared guards reliably fire.
 - **Block contract:** the guard scripts emit `{"decision":"block","reason":...}` on stdout (plain mode) AND exit 2 — Devin honors both. Hooks run **without** `AI_TOOLKIT_HOOK_FORMAT=json` because Devin expects the flat `{"decision","reason"}` shape, not Claude's `hookSpecificOutput` envelope.
 - **Stdin payload:** flat `{ "hook_event_name", "tool_name", "tool_input" }` — already handled by `_hook-io.sh` via its `.tool_name` / `.tool_input.*` branches, so no normalizer change was needed.
@@ -10958,7 +11053,7 @@ Each command file carries the prompt in its markdown body (built from the SKILL.
 
 | opencode event             | Bash hook(s)                                                       |
 |----------------------------|--------------------------------------------------------------------|
-| `session.created`          | `session-start.sh` + `session-context.sh` + `mcp-health.sh`        |
+| `session.created`          | `session-start.sh` + `mcp-health.sh`                               |
 | `session.compacted`        | `pre-compact.sh` + `pre-compact-save.sh` (PreCompact equivalent)   |
 | `session.deleted`          | `session-end.sh` + `save-session.sh`                               |
 | `message.updated`          | `user-prompt-submit.sh` + `track-usage.sh`                         |
@@ -11493,7 +11588,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **content-moderation-patterns** | `skills/content-moderation-patterns/` | Two-stage moderation: pre-filter + LLM classifier; categories; thresholds |
 | **model-routing-patterns** | `skills/model-routing-patterns/` | Haiku/Sonnet/Opus routing; escalation; sub-agent delegation; fallback |
 
-## Knowledge Skills - Process (5)
+## Knowledge Skills - Process (6)
 
 | Skill | Directory | Domain |
 |-------|-----------|--------|
@@ -11501,6 +11596,7 @@ Hybrid skills combine slash-command invocation with domain knowledge that agents
 | **architecture-decision** | `skills/architecture-decision/` | Architecture notes, trade-off analysis, alternatives |
 | **performance-profiling** | `skills/performance-profiling/` | Profiling, bottleneck analysis, optimization |
 | **research-mastery** | `skills/research-mastery/` | Multi-source research, synthesis, fact-checking |
+| **deep-research** | `skills/deep-research/` | Web/multi-source research methodology, retrieval budget, adversarial verification, citation discipline |
 | **verification-before-completion** | `skills/verification-before-completion/` | Iron Law: evidence-before-claims, no completion without fresh verification |
 
 ## Quality Guardrails
@@ -11962,7 +12058,7 @@ The canonical data lives in **`scripts/ecosystem_tools.json`** and is consumed b
 | Config paths | `AGENTS.md`, `.agents/skills/*/SKILL.md`, `.codex/hooks.json`, `.codex/config.toml` (project layers, root→cwd, closest wins, trusted projects only), `~/.codex/config.toml` |
 | Our generators | `scripts/generate_codex.py`, `scripts/generate_codex_hooks.py`, `scripts/generate_codex_skills.py` (opt-in via `--codex-skills`) |
 | Rules delivery | Universal coding rules are inlined into `AGENTS.md` (Codex reads instructions only from AGENTS.md, not `.agents/rules/`); language rules ship as `<lang>-rules` skills under `.agents/skills/`. |
-| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire all 10 to shared toolkit hook scripts, mirroring the Claude Code mapping in `app/hooks.json`. |
+| Tracked hook events | Upstream canonical (codex-rs `HookEventName` enum): `PreToolUse`, `PostToolUse`, `PermissionRequest`, `PreCompact`, `PostCompact`, `SessionStart`, `UserPromptSubmit`, `SubagentStart`, `SubagentStop`, `Stop` (10 events). We wire 9 of these to shared toolkit hook scripts, mirroring the Claude Code mapping in `app/hooks.json`. `PostCompact` is not wired (its only hook was the removed environment-snapshot probe). |
 | Tracked handler types | `command` (emitted by default); `prompt` and `agent` available upstream but authored by hand |
 | Other capabilities | `AGENTS.md`, `config.toml`, `mcp_servers`, sandbox policies, `.agents/skills/*/SKILL.md` (native Codex skill discovery path) |
 | Version probe | `codex --version` |
@@ -12144,7 +12240,6 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 |-------|--------|--------|
 | SessionStart | `session-start.sh` | MANDATORY rules reminder + session context + instincts + reset session-edit state |
 | SessionStart | `mcp-health.sh` | Check MCP server command availability (non-blocking warning) |
-| SessionStart | `session-context.sh` | Capture environment snapshot to `~/.softspark/ai-toolkit/sessions/current-context.json` |
 | Notification | `notify-waiting.sh` | Cross-platform desktop notification |
 | PreToolUse | `guard-destructive.sh` | Block `rm -rf`, `DROP TABLE`, etc. |
 | PreToolUse | `guard-path.sh` | Block wrong-user path hallucination |

package/llms.txt

@@ -21,6 +21,7 @@
 - [Plan: Output & Token Discipline](kb/history/completed/output-token-discipline-plan-20260504.md)
 - [How-To Guides](kb/howto/README.md)
 - [Plan: Cloud Security Pack — Multi-Cloud Audit](kb/planning/cloud-security-pack-plan.md)
+- [Plan: Drop Cascade hooks after 2026-07-01 sunset](kb/planning/drop-cascade-hooks-after-sunset.md)
 - [PRD: MCP Context Trim v4.0](kb/planning/mcp-context-trim-v4-prd.md)
 - [SOP: Ecosystem Sync](kb/procedures/ecosystem-sync-sop.md)
 - [SOP: Claude Toolkit Maintenance](kb/procedures/maintenance-sop.md)

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.8.0",
+  "version": "4.10.0",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.8.0",
-  "description": "AI coding toolkit: 107 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
+  "version": "4.10.0",
+  "description": "AI coding toolkit: 108 skills, 44 agents, 12-editor write-through (Claude, Cursor, Windsurf, Copilot, Gemini, Cline, Roo, Aider, Augment, Antigravity, Codex, opencode), machine-enforced safety constitution, SARIF audit, signed npm provenance.",
   "keywords": [
     "claude",
     "claude-code",
@@ -50,12 +50,12 @@
     "ecosystem:doctor": "python3 scripts/ecosystem_doctor.py --format text",
     "ecosystem:doctor:offline": "python3 scripts/ecosystem_doctor.py --offline --format text",
     "ecosystem:doctor:update": "python3 scripts/ecosystem_doctor.py --update",
-    "generate:agents": "python3 scripts/generate_agents_md.py > AGENTS.md",
+    "generate:agents": "AI_TOOLKIT_NO_CUSTOM_RULES=1 python3 scripts/generate_agents_md.py > AGENTS.md",
     "generate:cursor": "python3 scripts/generate_cursor_rules.py > .cursorrules",
     "generate:llms": "python3 scripts/generate_llms_txt.py > llms.txt && python3 scripts/generate_llms_txt.py --full > llms-full.txt",
     "generate:windsurf": "python3 scripts/generate_windsurf.py > .windsurfrules",
-    "generate:copilot": "python3 scripts/generate_copilot.py > .github/copilot-instructions.md",
-    "generate:gemini": "python3 scripts/generate_gemini.py > GEMINI.md",
+    "generate:copilot": "AI_TOOLKIT_NO_CUSTOM_RULES=1 python3 scripts/generate_copilot.py > .github/copilot-instructions.md",
+    "generate:gemini": "AI_TOOLKIT_NO_CUSTOM_RULES=1 python3 scripts/generate_gemini.py > GEMINI.md",
     "generate:cline": "python3 scripts/generate_cline_rules.py .",
     "generate:roo": "python3 scripts/generate_roo_modes.py > .roomodes",
     "generate:aider": "python3 scripts/generate_aider_conf.py > .aider.conf.yml",