@softspark/ai-toolkit 4.1.0 → 4.2.1

package/app/skills/seo-validate/reference/geo-guidelines.md

@@ -1,8 +1,10 @@
 # GEO — Generative Engine Optimization
 
-Reference for `seo-validate` Category 6. Structuring content so AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Bing Copilot, Claude) can extract, cite, and quote it accurately.
+Reference for `seo-validate` Category 6. Structuring content so AI answer engines (ChatGPT, Perplexity, Google AI Overviews, Bing Copilot, Claude, Google AI Mode) can extract, cite, and quote it accurately.
 
-GEO is emerging practice, not a ranking algorithm with known penalties. **All findings in Category 6 are severity `INFO`** — guidance, not enforcement.
+GEO patterns have measurable impact on AI citation probability. **Category 6 findings are `WARN` (chunk size, author quality, freshness) or `INFO` (hedging, frameworks, contrast, bio)** — guidance based on citation research, not penalty-causing.
+
+See [ai-pipeline.md](ai-pipeline.md) for Google's 4-stage pipeline and 7 ranking signals. See [content-citability.md](content-citability.md) for chunk anatomy, semantic triples, and hedging patterns.
 
 ## Core Principles
 
@@ -224,17 +226,124 @@ These don't render content for crawlers at all. **Category 7 (rendering) superse
 
 ---
 
+## Chunk Architecture
+
+Google's retrieval stage (Stage 2 of the pipeline — see [ai-pipeline.md](ai-pipeline.md)) splits content into chunks of ≤500 tokens (~375 words). AI does not read your article — it extracts one chunk and uses it as the answer. If the answer is distributed across multiple sections or buried after a long preamble, AI cannot assemble it.
+
+**The 375-word rule:** Each H2 section should stay within ~375 words. If a section runs longer, add an H3 — each H3 becomes its own independent chunk candidate.
+
+### Anatomy of a citable chunk
+
+```
+H2: [Question or keyword-rich heading]
+│
+├── Direct answer — 2–3 sentences. Fact first. No preamble.
+│
+├── Elaboration — data, context, nuance. 3–5 sentences.
+│
+├── Visual element — list, table, or code block.
+│
+└── TL;DR (optional) — 1-sentence summary for long sections.
+```
+
+### Before / after
+
+**Before (unchunkable):**
+```
+H2: Choosing the Right Mattress
+
+When you're looking for a new mattress, there are many factors to consider.
+The market offers a wide variety of options, and it can be overwhelming...
+[70 words of preamble]
+Eventually, firmness is one of the most important factors...
+```
+*AI extracts the preamble as the "answer" — zero information.*
+
+**After (chunk-optimised):**
+```
+H2: How to Choose Mattress Firmness by Body Weight
+
+Match firmness to your weight: under 70 kg → H1–H2; 70–90 kg → H3; over 90 kg → H4.
+Higher body weight needs firmer support to maintain spinal alignment.
+
+| Weight    | Firmness  |
+|-----------|-----------|
+| < 70 kg   | H1–H2     |
+| 70–90 kg  | H3        |
+| > 90 kg   | H4        |
+```
+*AI extracts the first two sentences. Table is precision bonus.*
+
+---
+
+## Semantic Triples vs Marketing Prose
+
+AI answer engines parse content as Subject → Predicate → Object triples. Marketing prose requires inference; triples require none — lower hallucination risk, higher citation frequency.
+
+| Style | Example | AI extractable? |
+|---|---|---|
+| Marketing prose | "Our exceptional collection will enchant you with its elegance." | No — zero extractable facts |
+| Semantic triples | "Firmness: H3. Dimensions: 160×200 cm. Ideal for: side sleepers, 70–90 kg. Not for: stomach sleepers." | Yes — 4 distinct facts |
+
+Each triple answers a different AI sub-query. Six triples on a product page = six citation opportunities.
+
+---
+
+## Opinionated Content
+
+AI skips hedged claims. "This may be a good choice for many people" cannot be used as an answer to "which mattress should I buy?" Google's Jetstream signal explicitly rewards declarative, opinionated content.
+
+**Hedging to eliminate → replacement:**
+
+| Hedging | Replacement |
+|---|---|
+| "may be a good choice" | "We recommend X for Y" |
+| "worth considering" | "Our top pick for Z is X" |
+| "for many people" | "for side sleepers weighing 70–90 kg" |
+| "it depends" | "It depends on your weight: under 70 kg → H2, over 90 kg → H4" |
+
+**Rule:** Every guide and product page must take a position. Recommendation + named persona + justification = citable.
+
+---
+
+## The 13-Week Freshness Rule
+
+50% of top AI-cited content was published or updated within the last 13 weeks (Blyskall, 40M AI Overviews results). After 13 weeks without a visible update, citation probability drops.
+
+**Both signals required:**
+1. `dateModified` in JSON-LD — machine-readable freshness signal.
+2. Visible "Updated: [date]" near the byline — AI engines parse visible text; users trust visible dates.
+
+JSON-LD alone is insufficient.
+
+**Refresh strategy:**
+
+| Action | Interval |
+|---|---|
+| Full content review + update | Every 12 weeks for top pillar pages |
+| Date + minor fact refresh | Every 13 weeks for cluster articles |
+| Add new FAQ or data point | On new data availability for product pages |
+
+---
+
 ## Checklist (Category 6 findings)
 
+- [ ] Each H2 section is ≤375 words; sections exceeding this have an H3 sub-heading.
+- [ ] First paragraph under each heading is ≤60 words before a concrete fact or recommendation.
+- [ ] No hedging language ("may be", "worth considering", "for many") in recommendation contexts.
+- [ ] At least one decision framework ("if X → choose Y") per guide or category page.
+- [ ] At least one explicit contrast ("X vs Y", "unlike X") per comparison page.
+- [ ] At least one negative definition ("not recommended for…") per product or category page.
+- [ ] Author block: real name (not "Admin"), ≥30-word bio, `Person` schema with `sameAs`.
+- [ ] `dateModified` in JSON-LD AND visible "Updated: [date]" text present.
 - [ ] FAQ-style content uses `FAQPage` schema.
 - [ ] Summary content uses `speakable` schema.
-- [ ] Paragraphs >400 words are broken up with sub-headings.
 - [ ] Citations use `<cite>` and author bylines.
 - [ ] Quoted content uses `<blockquote>`/`<q>` with `cite` attr.
 - [ ] How-to content uses `<ol>` + `HowTo` schema.
 - [ ] Comparative data uses `<table>` with proper headers.
 - [ ] Glossary content uses `<dl>`/`<dt>`/`<dd>`.
-- [ ] Semantic HTML (`<article>`, `<section>`, `<main>`, `<nav>`, `<aside>`) is used over `<div>`.
+- [ ] Semantic HTML (`<article>`, `<section>`, `<main>`) used over `<div>`.
 - [ ] Critical content is NOT hidden behind tabs/accordions (except native `<details>`).
 
 ---

package/benchmarks/ecosystem-doctor-snapshot.json

@@ -1,5 +1,5 @@
 {
-  "last_run": "2026-05-06T08:17:20Z",
+  "last_run": "2026-05-12T10:01:38Z",
   "schema_version": 1,
   "tools": {
     "aider": {
@@ -24,10 +24,10 @@
       }
     },
     "augment": {
-      "docs_hash": "ac138d99235e1f3e",
+      "docs_hash": "b746d5dbbc5a2936",
       "headings": [
         "Agent",
-        "Code Completions",
+        "Chat",
         "Documentation Index",
         "Introduction",
         "\u200bAuggie CLI",
@@ -57,7 +57,7 @@
       }
     },
     "claude-code": {
-      "docs_hash": "789113e1bc4cd34c",
+      "docs_hash": "9e0292a9f92392e0",
       "headings": [
         "Claude Code overview",
         "Documentation Index",
@@ -85,7 +85,7 @@
         "SessionEnd": false,
         "SessionStart": false,
         "Setup": true,
-        "Stop": false,
+        "Stop": true,
         "StopFailure": false,
         "SubagentStart": false,
         "SubagentStop": false,
@@ -103,10 +103,10 @@
         "slash command": true,
         "sub-agent": true
       },
-      "version": "2.1.131 (Claude Code)"
+      "version": "2.1.139 (Claude Code)"
     },
     "cline": {
-      "docs_hash": "b4009dc8e6d40af9",
+      "docs_hash": "b59e8836b3217cdb",
       "headings": [
         "Cline CLI",
         "Cline Documentation",
@@ -137,7 +137,7 @@
       }
     },
     "codex-cli": {
-      "docs_hash": "c6b51936294d38e7",
+      "docs_hash": "3f963da56d00add9",
       "headings": [
         "About",
         "Contributing",
@@ -156,7 +156,7 @@
         "Packages 0",
         "Provide feedback",
         "Quickstart",
-        "Releases 765",
+        "Releases 784",
         "Repository files navigation",
         "Resources",
         "Saved searches",
@@ -186,10 +186,10 @@
         "mcp_servers": false,
         "sandbox": true
       },
-      "version": "codex-cli 0.128.0"
+      "version": "codex-cli 0.130.0"
     },
     "cursor": {
-      "docs_hash": "8ed1f5cf7441b6c0",
+      "docs_hash": "705adfd617433088",
       "headings": [],
       "markers": {
         ".cursor/rules": false,
@@ -205,7 +205,7 @@
       }
     },
     "gemini-cli": {
-      "docs_hash": "21a2f14121ff27fa",
+      "docs_hash": "93694630a3d04327",
       "headings": [
         "Breadcrumbs",
         "Directory actions",
@@ -244,7 +244,7 @@
       }
     },
     "github-copilot": {
-      "docs_hash": "99a5ab7bd5f7556f",
+      "docs_hash": "d9b9fcdfe3b67469",
       "headings": [
         "About Copilot auto model selection",
         "About Copilot integrations",
@@ -292,7 +292,7 @@
       }
     },
     "opencode": {
-      "docs_hash": "fe845a4bffb6371b",
+      "docs_hash": "c1c8ba8f6b2e7ddf",
       "headings": [
         "Add features",
         "Ask questions",
@@ -353,7 +353,7 @@
       }
     },
     "windsurf": {
-      "docs_hash": "9b2879646f041aea",
+      "docs_hash": "66295add1d0f0645",
       "headings": [
         "Advanced",
         "App Deploys",

package/kb/reference/architecture-overview.md

@@ -3,9 +3,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.4.4"
+version: "1.4.5"
 created: "2026-03-23"
-last_updated: "2026-04-15"
+last_updated: "2026-05-12"
 description: "Architecture of ai-toolkit: directory layout, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -264,7 +264,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 ## Quality Hooks
 
-21 entries across 12 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
+22 entries across 12 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
 
 | Hook | Trigger | Script | Action |
 |------|---------|--------|--------|
@@ -282,6 +282,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 | PostToolUse | After any tool | `governance-capture.sh` | Log security-sensitive operations |
 | Stop | After response | `quality-check.sh` | Multi-language lint |
 | Stop | After response | `save-session.sh` | Persist session context |
+| Stop | Before final stop | `quality-gate.sh` | Block final response on lint/type errors |
 | TaskCompleted | Agent Teams: task done | `quality-gate.sh` | Block completion on errors |
 | TeammateIdle | Agent Teams: idle | *(inline)* | Completeness reminder |
 | SubagentStart | Subagent spawn | `subagent-start.sh` | Scope reminder for subagents |

package/kb/reference/hooks-catalog.md

@@ -3,9 +3,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.0"
+version: "1.5.1"
 created: "2026-03-27"
-last_updated: "2026-04-24"
+last_updated: "2026-05-12"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -13,7 +13,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
+ai-toolkit provides 22 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
 ## Supported Surface
 
@@ -164,6 +164,19 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
+### Stop (quality gate) — `quality-gate.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `Stop` |
+| Matcher | *(all)* |
+| Script | `~/.softspark/ai-toolkit/hooks/quality-gate.sh` |
+| Fires | Before Claude is allowed to finish a response |
+
+**Action:** Runs lint/typecheck. **Blocks stopping (exit 2)** if errors found, so Claude must continue and fix the issues. Missing local tooling is reported as skipped rather than blocking the session.
+
+Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
 ### TaskCompleted — `quality-gate.sh`
 
 | Field | Value |
@@ -362,7 +375,7 @@ Set in `.claude/settings.local.json`:
     ├── PreToolUse       → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh
     ├── UserPromptSubmit → user-prompt-submit.sh, track-usage.sh
     ├── PostToolUse      → post-tool-use.sh, governance-capture.sh
-    ├── Stop             → quality-check.sh, save-session.sh
+    ├── Stop             → quality-check.sh, save-session.sh, quality-gate.sh
     ├── TaskCompleted    → quality-gate.sh
     ├── TeammateIdle     → echo (inline)
     ├── SubagentStart    → subagent-start.sh

package/kb/reference/unique-features.md

@@ -4,7 +4,7 @@ category: reference
 service: ai-toolkit
 tags: [features, differentiators, constitution, hooks, security, tdd, memory]
 created: "2026-04-13"
-last_updated: "2026-04-13"
+last_updated: "2026-05-12"
 description: "Detailed description of ai-toolkit's unique features: constitution enforcement, hooks system, security scanning, effort budgeting, quality gates, and more."
 ---
 
@@ -12,7 +12,7 @@ description: "Detailed description of ai-toolkit's unique features: constitution
 
 ## 1. Machine-Enforced Constitution
 
-Unlike other toolkits that put safety rules in documentation only, ai-toolkit enforces a 5-article constitution via `PreToolUse` hooks. The hook actually **blocks** execution of:
+Unlike other toolkits that put safety rules in documentation only, ai-toolkit enforces a 6-article constitution via hooks. The hooks actually **block** execution of:
 - Mass deletion (`rm -rf`, `DROP TABLE`)
 - Blind overwrites of uncommitted work
 - Any action that could cause irreversible data loss
@@ -21,7 +21,7 @@ Unlike other toolkits that put safety rules in documentation only, ai-toolkit en
 
 Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are copied to `~/.softspark/ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.
 
-**12 lifecycle events / 21 global hook entries:**
+**12 lifecycle events / 22 global hook entries:**
 
 | Event | Script | Action |
 |-------|--------|--------|
@@ -39,6 +39,7 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 | PostToolUse | `governance-capture.sh` | Log security-sensitive operations to JSONL |
 | Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
 | Stop | `save-session.sh` | Persist session context for cross-session continuity |
+| Stop | `quality-gate.sh` | Block final response on lint/type errors |
 | TaskCompleted | `quality-gate.sh` | Block task completion on lint/type errors |
 | SubagentStart | `subagent-start.sh` | Narrow-scope reminder for spawned subagents |
 | SubagentStop | `subagent-stop.sh` | Completion checklist for subagent handoff |

package/llms-full.txt

@@ -215,7 +215,7 @@
 - **search-specialist**: Information retrieval and search optimization specialist. Trigger words: search, query, semantic search, information retrieval, relevance, ranking, search optimization
 - **security-architect**: Proactive security design expert. Use for Threat Modeling, architecture security reviews, and designing secure systems (AuthN/AuthZ, Crypto).
 - **security-auditor**: Security expert. Use for OWASP Top 10, CVE analysis, security audits, penetration testing, vulnerability assessment, hardening. Triggers: security, owasp, cve, vulnerability, audit, hardening, penetration, pentest, injection test, api security.
-- **seo-specialist**: Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews
+- **seo-specialist**: Search engine + generative engine optimization specialist. Trigger words: SEO, GEO, AEO, search engine, meta tags, structured data, Core Web Vitals, sitemap, robots.txt, schema.org, llms.txt, ChatGPT visibility, Claude citation, Perplexity ranking, AI Overviews, topical authority, chunk architecture, semantic triples, query fan out
 - **system-governor**: The Guardian of the Constitution. Validates all evolutionary changes and enforces immutable rules. Has VETO power.
 - **tech-lead**: Technical authority for code quality, architecture patterns, and stack decisions. Use for code reviews, technological disputes, and standards enforcement.
 - **technical-researcher**: Deep technical investigation and multi-source research synthesis specialist. Trigger words: technical research, feasibility study, root cause analysis, API investigation, compatibility research, comparison matrix, synthesize, aggregate, report, executive summary, gap analysis, findings, multi-source, cross-reference
@@ -6091,9 +6091,9 @@ title: "AI Toolkit - Architecture Overview"
 category: reference
 service: ai-toolkit
 tags: [architecture, overview, design, structure]
-version: "1.4.4"
+version: "1.4.5"
 created: "2026-03-23"
-last_updated: "2026-04-15"
+last_updated: "2026-05-12"
 description: "Architecture of ai-toolkit: directory layout, global install model, editor-aware MCP install, Codex translation layer, skill tiers, and integration with projects."
 ---
 
@@ -6352,7 +6352,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 
 ## Quality Hooks
 
-21 entries across 12 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
+22 entries across 12 lifecycle events. See [hooks-catalog.md](hooks-catalog.md) for full details.
 
 | Hook | Trigger | Script | Action |
 |------|---------|--------|--------|
@@ -6370,6 +6370,7 @@ Agents (code-reviewer, debugger, devops-implementer, ...)
 | PostToolUse | After any tool | `governance-capture.sh` | Log security-sensitive operations |
 | Stop | After response | `quality-check.sh` | Multi-language lint |
 | Stop | After response | `save-session.sh` | Persist session context |
+| Stop | Before final stop | `quality-gate.sh` | Block final response on lint/type errors |
 | TaskCompleted | Agent Teams: task done | `quality-gate.sh` | Block completion on errors |
 | TeammateIdle | Agent Teams: idle | *(inline)* | Completeness reminder |
 | SubagentStart | Subagent spawn | `subagent-start.sh` | Scope reminder for subagents |
@@ -8757,9 +8758,9 @@ title: "Hooks Catalog"
 category: reference
 service: ai-toolkit
 tags: [hooks, quality, safety, enforcement, settings.json]
-version: "1.5.0"
+version: "1.5.1"
 created: "2026-03-27"
-last_updated: "2026-04-24"
+last_updated: "2026-05-12"
 description: "Complete reference of all ai-toolkit hooks: events, scripts, installation, and runtime behavior."
 ---
 
@@ -8767,7 +8768,7 @@ description: "Complete reference of all ai-toolkit hooks: events, scripts, insta
 
 ## Overview
 
-ai-toolkit provides 21 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
+ai-toolkit provides 22 global hook entries across 12 lifecycle events that enforce quality, safety, and workflow rules across all Claude Code sessions. Hooks are merged into `~/.claude/settings.json` on install, with logic in standalone scripts at `~/.softspark/ai-toolkit/hooks/`.
 
 ## Supported Surface
 
@@ -8918,6 +8919,19 @@ Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
 Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
 
+### Stop (quality gate) — `quality-gate.sh`
+
+| Field | Value |
+|-------|-------|
+| Event | `Stop` |
+| Matcher | *(all)* |
+| Script | `~/.softspark/ai-toolkit/hooks/quality-gate.sh` |
+| Fires | Before Claude is allowed to finish a response |
+
+**Action:** Runs lint/typecheck. **Blocks stopping (exit 2)** if errors found, so Claude must continue and fix the issues. Missing local tooling is reported as skipped rather than blocking the session.
+
+Skipped when `TOOLKIT_HOOK_PROFILE=minimal`.
+
 ### TaskCompleted — `quality-gate.sh`
 
 | Field | Value |
@@ -9116,7 +9130,7 @@ Set in `.claude/settings.local.json`:
     ├── PreToolUse       → guard-destructive.sh, guard-path.sh, guard-config.sh, commit-quality.sh
     ├── UserPromptSubmit → user-prompt-submit.sh, track-usage.sh
     ├── PostToolUse      → post-tool-use.sh, governance-capture.sh
-    ├── Stop             → quality-check.sh, save-session.sh
+    ├── Stop             → quality-check.sh, save-session.sh, quality-gate.sh
     ├── TaskCompleted    → quality-gate.sh
     ├── TeammateIdle     → echo (inline)
     ├── SubagentStart    → subagent-start.sh
@@ -11749,7 +11763,7 @@ category: reference
 service: ai-toolkit
 tags: [features, differentiators, constitution, hooks, security, tdd, memory]
 created: "2026-04-13"
-last_updated: "2026-04-13"
+last_updated: "2026-05-12"
 description: "Detailed description of ai-toolkit's unique features: constitution enforcement, hooks system, security scanning, effort budgeting, quality gates, and more."
 ---
 
@@ -11757,7 +11771,7 @@ description: "Detailed description of ai-toolkit's unique features: constitution
 
 ## 1. Machine-Enforced Constitution
 
-Unlike other toolkits that put safety rules in documentation only, ai-toolkit enforces a 5-article constitution via `PreToolUse` hooks. The hook actually **blocks** execution of:
+Unlike other toolkits that put safety rules in documentation only, ai-toolkit enforces a 6-article constitution via hooks. The hooks actually **block** execution of:
 - Mass deletion (`rm -rf`, `DROP TABLE`)
 - Blind overwrites of uncommitted work
 - Any action that could cause irreversible data loss
@@ -11766,7 +11780,7 @@ Unlike other toolkits that put safety rules in documentation only, ai-toolkit en
 
 Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are copied to `~/.softspark/ai-toolkit/hooks/` on install and referenced from `~/.claude/settings.json`. Easy to read, debug, and extend.
 
-**12 lifecycle events / 21 global hook entries:**
+**12 lifecycle events / 22 global hook entries:**
 
 | Event | Script | Action |
 |-------|--------|--------|
@@ -11784,6 +11798,7 @@ Hook logic lives in `app/hooks/*.sh` — not inline JSON one-liners. Scripts are
 | PostToolUse | `governance-capture.sh` | Log security-sensitive operations to JSONL |
 | Stop | `quality-check.sh` | Multi-language lint (ruff/tsc/phpstan/dart/go) |
 | Stop | `save-session.sh` | Persist session context for cross-session continuity |
+| Stop | `quality-gate.sh` | Block final response on lint/type errors |
 | TaskCompleted | `quality-gate.sh` | Block task completion on lint/type errors |
 | SubagentStart | `subagent-start.sh` | Narrow-scope reminder for spawned subagents |
 | SubagentStop | `subagent-stop.sh` | Completion checklist for subagent handoff |

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "4.1.0",
+  "version": "4.2.1",
   "components": {
     "agents": {
       "description": "44 specialized agents (orchestrator, backend, frontend, security, devops, etc.)",
@@ -16,7 +16,7 @@
       "tags": ["core", "skills", "commands"]
     },
     "hooks": {
-      "description": "21 global hook entries across 12 lifecycle events + 5 skill-scoped lifecycle hooks",
+      "description": "22 global hook entries across 12 lifecycle events + 5 skill-scoped lifecycle hooks",
       "path": "app/hooks.json + app/hooks/*.sh",
       "target": "~/.claude/settings.json (merge) + ~/.softspark/ai-toolkit/hooks/ (copy)",
       "type": "merge+copy",
@@ -30,7 +30,7 @@
       "tags": ["plugins", "packs", "experimental"]
     },
     "constitution": {
-      "description": "5-article machine-enforced safety constitution",
+      "description": "6-article machine-enforced safety constitution",
       "path": "app/constitution.md",
       "target": ".claude/constitution.md",
       "type": "symlink",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.1.0",
+  "version": "4.2.1",
   "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.",
   "keywords": [
     "claude",
@@ -41,7 +41,7 @@
     "ai-toolkit": "bin/ai-toolkit.js"
   },
   "scripts": {
-    "prepublishOnly": "npm run generate:all && python3 scripts/validate.py && npm test",
+    "prepublishOnly": "npm run generate:all && python3 scripts/validate.py --strict && npm test",
     "test": "bats tests/ --jobs 4 --no-parallelize-within-files",
     "validate": "python3 scripts/validate.py",
     "evaluate": "python3 scripts/evaluate_skills.py",

package/scripts/merge-hooks.py

@@ -65,11 +65,49 @@ def _is_toolkit_entry(entry: dict) -> bool:
     return False
 
 
-def strip_toolkit(hooks: dict) -> dict:
-    """Remove all entries tagged with _source == SOURCE_TAG."""
+def _entry_signature(entry: dict) -> tuple:
+    """Return the behavior-defining parts of a hook entry.
+
+    Older ai-toolkit installs wrote hook entries without ``_source``. Matching
+    on the event, matcher, and handler payload lets current installs remove
+    those legacy duplicates while preserving unrelated user hooks.
+    """
+    handlers = []
+    for hook in entry.get("hooks", []):
+        if not isinstance(hook, dict):
+            handlers.append(hook)
+            continue
+        handlers.append(tuple(sorted(
+            (key, value)
+            for key, value in hook.items()
+            if key != "_source"
+        )))
+    return (entry.get("matcher", ""), tuple(handlers))
+
+
+def strip_toolkit(hooks: dict, toolkit_hooks: dict | None = None) -> dict:
+    """Remove entries tagged with ai-toolkit or matching legacy toolkit hooks."""
+    legacy_signatures: dict[str, set[tuple]] = {}
+    if toolkit_hooks:
+        for event, entries in toolkit_hooks.items():
+            legacy_signatures[event] = {
+                _entry_signature(entry)
+                for entry in entries
+                if isinstance(entry, dict)
+            }
+
     result = {}
     for event, entries in hooks.items():
-        filtered = [e for e in entries if not _is_toolkit_entry(e)]
+        signatures = legacy_signatures.get(event, set())
+        filtered = [
+            e
+            for e in entries
+            if not _is_toolkit_entry(e)
+            and not (
+                isinstance(e, dict)
+                and _entry_signature(e) in signatures
+            )
+        ]
         if filtered:
             result[event] = filtered
     return result
@@ -85,7 +123,7 @@ def merge(toolkit_hooks: dict, target_hooks: dict) -> dict:
     Returns:
         Merged hooks dictionary with old toolkit entries replaced by new ones.
     """
-    merged = strip_toolkit(target_hooks)
+    merged = strip_toolkit(target_hooks, toolkit_hooks)
     for event, entries in toolkit_hooks.items():
         if event not in merged:
             merged[event] = []

package/scripts/url_fetch.py

@@ -9,6 +9,9 @@ Stdlib-only — no external dependencies.
 from __future__ import annotations
 
 import ssl
+import json
+import os
+from pathlib import Path
 import urllib.error
 import urllib.request
 
@@ -34,6 +37,13 @@ def fetch_url(url: str) -> bytes:
             f"Only HTTPS URLs are supported (got: {url.split('://')[0]}://)"
         )
 
+    fixture_map = os.environ.get("AI_TOOLKIT_TEST_URL_FIXTURE_MAP")
+    if fixture_map and os.environ.get("AI_TOOLKIT_TEST_MODE") == "1":
+        fixtures = json.loads(fixture_map)
+        fixture_path = fixtures.get(url)
+        if fixture_path:
+            return Path(fixture_path).read_bytes()
+
     ctx = ssl.create_default_context()
     with urllib.request.urlopen(url, timeout=_FETCH_TIMEOUT, context=ctx) as resp:
         data = resp.read(_FETCH_MAX_BYTES)