@softspark/ai-toolkit 4.2.1 → 4.2.3

package/CHANGELOG.md

@@ -7,6 +7,37 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v4.2.3 - SEO FAQ rich results deprecation (2026-05-12)
+
+Patch release. Updates `seo-specialist` guidance after Google deprecated FAQ rich results.
+
+### Changed
+
+- **SEO structured data guidance** - `seo-specialist` now treats `FAQPage` as deprecated for Google rich results and recommends keeping it only when explicitly targeting non-Google engines.
+- **Citability schema checklist** - Prioritizes `Article`, `HowTo`, `QAPage`, and `Person` schema guidance for Google-facing SEO/GEO work.
+
+### Verification
+
+- Source checked against [Google Search Central `FAQPage` structured data documentation](https://developers.google.com/search/docs/appearance/structured-data/faqpage).
+
+---
+
+## v4.2.2 - Legacy hook duplicate cleanup (2026-05-12)
+
+Patch release. Cleans up legacy untagged hook duplicates found during post-release verification of v4.2.1.
+
+### Fixed
+
+- **Legacy notification hook cleanup** - `scripts/merge-hooks.py` now removes old direct `osascript` notification hooks from pre-script installs while preserving user-owned notification hooks.
+- **External hook duplicate cleanup** - `scripts/inject_hook_cli.py` now removes legacy untagged entries matching the same event, matcher, and handler payload as the external hook being re-injected.
+
+### Verification
+
+- `bats tests/test_merge_hooks_statusline.bats tests/test_inject_hook.bats`: 42/42 passing.
+- Local `~/.claude/settings.json`: 0 behavior duplicates, 0 exact duplicates, 0 untagged hook groups after cleanup.
+
+---
+
 ## v4.2.1 - Claude Code hook enforcement and README cleanup (2026-05-12)
 
 Patch release. Tightens Claude Code runtime enforcement, fixes duplicated hook cleanup during install/update, and removes the README hero image for release.

package/README.md

@@ -6,16 +6,15 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Skills](https://img.shields.io/badge/skills-107-brightgreen)](app/skills/)
 [![Agents](https://img.shields.io/badge/agents-44-blue)](app/agents/)
-[![Tests](https://img.shields.io/badge/tests-1049%20passing-success)](tests/)
+[![Tests](https://img.shields.io/badge/tests-1051%20passing-success)](tests/)
 
-## What's New in v4.2.1
+## What's New in v4.2.3
 
-Patch release focused on making Claude Code rule enforcement harder to bypass and cleaning the release-facing README.
+Patch release updating SEO guidance after Google's FAQ rich result deprecation.
 
-- **Stop quality gate**: `quality-gate.sh` now runs on `Stop` as well as `TaskCompleted`, blocking final responses when lint/type checks fail.
-- **Reliable hook failures**: shell pipelines in the quality gate now preserve the failing tool exit code instead of hiding errors behind `head`.
-- **Cleaner installs**: hook merging now strips legacy untagged ai-toolkit duplicates while preserving user-owned hooks.
-- **README cleanup**: removed the hero image block for a lighter release README.
+- **SEO agent guidance**: `seo-specialist` now treats `FAQPage` as deprecated for Google rich results.
+- **Schema recommendations**: citability guidance now prioritizes `Article`, `HowTo`, `QAPage`, and `Person` for Google-facing surfaces.
+- **GEO audit checklist**: FAQ markup is now scoped to non-Google engines instead of recommended as a default.
 
 See [CHANGELOG.md](CHANGELOG.md) for full history.
 
@@ -148,7 +147,7 @@ ai-toolkit/
 │   └── ARCHITECTURE.md  # Full system design
 ├── kb/                  # Reference docs, procedures, plans
 ├── scripts/             # Validation, install, evaluation scripts
-├── tests/               # Bats test suite (1049 tests)
+├── tests/               # Bats test suite (1051 tests)
 └── CHANGELOG.md
 ```
 

package/app/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ai-toolkit",
   "description": "Professional-grade Claude Code toolkit with persona presets, skill security auditor, expanded lifecycle hooks, experimental opt-in plugin packs, benchmark harvesting, and multi-tool support.",
-  "version": "4.2.1",
+  "version": "4.2.3",
   "author": {
     "name": "SoftSpark",
     "url": "https://github.com/softspark"

package/app/agents/seo-specialist.md

@@ -39,7 +39,7 @@ Optimization for both classical search engines AND generative engines (ChatGPT,
 
 ### Structured Data
 - Schema.org markup
-- Rich snippets
+- Rich snippets (note: Google dropped FAQ rich results on May 7, 2026; Search Console API support removed August 2026)
 - Knowledge graph
 - Breadcrumbs
 
@@ -157,7 +157,7 @@ Goal: get cited by ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews
 5. **Named author + author bio with credentials.** Authority signal that survives synthesis.
 6. **Original quotes from named experts.** Quotation blocks are over-represented in LLM citations.
 7. **Comparison tables with explicit labels.** Tables are extracted whole; vague prose is summarised away.
-8. **Schema.org `Article`, `FAQPage`, `HowTo`, `QAPage`, `Person`.** Mandatory for entity disambiguation.
+8. **Schema.org `Article`, `HowTo`, `QAPage`, `Person`.** Mandatory for entity disambiguation. `FAQPage` schema: Google dropped FAQ rich results on **May 7, 2026** (Search Console API removed August 2026) — keep markup only if targeting other engines (Bing, etc.).
 9. **`llms.txt` at site root.** Curated index of canonical pages for LLM crawlers (Anthropic-proposed convention).
 10. **Stable URLs with semantic slugs.** LLMs cache citations — URL changes erase your authority overnight.
 11. **Cross-linking with descriptive anchors.** "this article" is dead anchor text; use the actual claim.
@@ -189,7 +189,7 @@ Goal: get cited by ChatGPT, Claude, Perplexity, Gemini, and Google AI Overviews
 - [ ] At least one comparison table OR numbered list per long-form page
 - [ ] Author block with real name (not "Admin"), role, and ≥30 words of bio
 - [ ] Schema.org `Article` with `author` (`Person` + `sameAs`), `datePublished`, `dateModified`
-- [ ] Schema.org `FAQPage` for any page with Q/A structure
+  - [ ] ~~Schema.org `FAQPage`~~ — Google dropped FAQ rich results on **May 7, 2026**; Search Console reporting ends June 2026, API removed August 2026. Remove or keep only if targeting non-Google engines.
 - [ ] `dateModified` updated AND visible "Updated: [date]" text present
 - [ ] `llms.txt` at site root with curated canonical URLs
 - [ ] Page contains at least 3 unique data points (numbers, dates, version strings)

package/manifest.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softspark/ai-toolkit",
-  "version": "4.2.1",
+  "version": "4.2.3",
   "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",

package/scripts/inject_hook_cli.py

@@ -120,20 +120,56 @@ def _entry_source(entry: dict) -> str | None:
     return None
 
 
-def strip_source(hooks: dict, source: str) -> dict:
+def _entry_signature(entry: dict) -> tuple:
+    """Return behavior-defining hook fields without source tags."""
+    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_source(hooks: dict, source: str, replacement_hooks: dict | None = None) -> dict:
     """Remove all entries whose ``_source`` matches *source*.
 
     Args:
         hooks: Existing hooks dict (event-name -> list of entries).
         source: Source tag to strip.
+        replacement_hooks: Optional hook entries being re-injected. When
+            provided, untagged legacy entries with the same event/matcher/
+            handler payload are stripped as belonging to the same source.
 
     Returns:
         New hooks dict with matching entries removed.  Empty event lists
         are omitted.
     """
+    legacy_signatures: dict[str, set[tuple]] = {}
+    if replacement_hooks:
+        for event, entries in replacement_hooks.items():
+            legacy_signatures[event] = {
+                _entry_signature(entry)
+                for entry in entries
+                if isinstance(entry, dict)
+            }
+
     result: dict = {}
     for event, entries in hooks.items():
-        filtered = [e for e in entries if _entry_source(e) != source]
+        signatures = legacy_signatures.get(event, set())
+        filtered = [
+            e for e in entries
+            if _entry_source(e) != source
+            and not (
+                isinstance(e, dict)
+                and _entry_source(e) is None
+                and _entry_signature(e) in signatures
+            )
+        ]
         if filtered:
             result[event] = filtered
     return result
@@ -174,7 +210,7 @@ def merge_hooks(new_hooks: dict, existing_hooks: dict, source: str) -> dict:
     Returns:
         Merged hooks dict.
     """
-    merged = strip_source(existing_hooks, source)
+    merged = strip_source(existing_hooks, source, new_hooks)
     for event, entries in new_hooks.items():
         if event not in merged:
             merged[event] = []

package/scripts/merge-hooks.py

@@ -27,6 +27,23 @@ import os
 import sys
 
 SOURCE_TAG = "ai-toolkit"
+LEGACY_TOOLKIT_HOOKS = {
+    "Notification": [
+        {
+            "matcher": "",
+            "hooks": [
+                {
+                    "type": "command",
+                    "command": (
+                        "osascript -e 'display notification "
+                        '"Claude Code needs your attention" with title "Claude Code"'
+                        "'"
+                    ),
+                }
+            ],
+        }
+    ],
+}
 
 
 def load_json(path: str) -> dict:
@@ -95,6 +112,12 @@ def strip_toolkit(hooks: dict, toolkit_hooks: dict | None = None) -> dict:
                 for entry in entries
                 if isinstance(entry, dict)
             }
+    for event, entries in LEGACY_TOOLKIT_HOOKS.items():
+        legacy_signatures.setdefault(event, set()).update(
+            _entry_signature(entry)
+            for entry in entries
+            if isinstance(entry, dict)
+        )
 
     result = {}
     for event, entries in hooks.items():