opensquid 0.5.395

package/packs/builtin/seo-aeo-expert/skills/ground-truth-gate/skill.yaml

@@ -0,0 +1,66 @@
+# ground-truth-gate — claim-bearing schema requires a ground-truth source.
+# Born from the 2026-06-10 dogfood incident: a syntactically perfect
+# OfferCatalog advertised a nonexistent product for weeks. Validators check
+# shape, not truth ([[schema-claims-need-ground-truth]]). This guard fires
+# when priced/offer-bearing structured data is written in a project that has
+# no business ground-truth doc (docs/BUSINESS.md) to trace claims against.
+name: ground-truth-gate
+load: preload
+triggers:
+  - kind: tool_call
+rules:
+  - id: claim-bearing-schema-no-ground-truth
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: claim_w
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - '"@type"\s*:\s*"Offer"'
+            - '"price"\s*:'
+            - 'priceSpecification'
+            - '"offers"\s*:'
+            - 'priceCurrency'
+      - call: text_pattern_match
+        as: claim_e
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - '"@type"\s*:\s*"Offer"'
+            - '"price"\s*:'
+            - 'priceSpecification'
+            - '"offers"\s*:'
+            - 'priceCurrency'
+      - call: path_exists
+        as: gt
+        if: 'claim_w.matched.length > 0 || claim_e.matched.length > 0'
+        args:
+          dir: docs
+          pattern: 'BUSINESS.md'
+      - call: verdict
+        if: '(claim_w.matched.length > 0 || claim_e.matched.length > 0) && gt.exists == false'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/ground-truth: priced/offer-bearing structured data
+            is being written but this project has NO business ground-truth
+            doc (docs/BUSINESS.md). Schema validators check SHAPE, not TRUTH
+            — wrong prices and nonexistent products pass every validator and
+            get repeated verbatim by AI engines. Establish the real catalog
+            first (live API/DB the UI renders from, or owner confirmation),
+            record it in docs/BUSINESS.md, then trace every claim to it.
+            [[schema-claims-need-ground-truth]]
+prose: |
+  The truth gate, complementing schema-validation-gate (shape) and the FSM
+  (process). Deterministic: pattern-match for claim-bearing fields +
+  path_exists for the ground-truth doc. When the doc exists, the gate is
+  silent — lesson 19 carries the tracing discipline; this guard only
+  catches the worst case (claims authored with no truth source at all).

package/packs/builtin/seo-aeo-expert/skills/meta-quality-gate/skill.yaml

@@ -0,0 +1,137 @@
+# meta-quality-gate — cheap deterministic on-write lints for the metadata
+# fields that get silently truncated or rewritten. Google rewrites ~60% of
+# titles, more when they overflow; descriptions truncate ~160 chars; images
+# without alt are invisible to extraction. All warn-level (false-positive
+# tolerant by design — regex lints, not a parser).
+name: meta-quality-gate
+load: preload
+triggers:
+  - kind: tool_call
+rules:
+  - id: meta-title-length
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: webfile
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.file_path
+          patterns:
+            - '\.(tsx|jsx|html)$'
+            - '\.mdx?$'
+      - call: text_pattern_match
+        as: long_w
+        if: 'webfile.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - '<title>[^<]{61,}'
+            - 'title:\s*["''][^"'']{61,}["'']'
+      - call: text_pattern_match
+        as: long_e
+        if: 'webfile.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - '<title>[^<]{61,}'
+            - 'title:\s*["''][^"'']{61,}["'']'
+      - call: verdict
+        if: 'webfile.matched.length > 0 && (long_w.matched.length > 0 || long_e.matched.length > 0)'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/meta: title over ~60 chars RENDERED — it will
+            truncate in SERPs, and Google rewrites ~60% of titles (overflow
+            invites it). REMEMBER the template budget: if a layout title
+            template appends a brand suffix ("%s | Brand" ≈ +15 chars), the
+            bare title must stay ~45 chars — a 46-60-char bare title passes
+            this regex but overflows rendered (live miss, 2026-06-10).
+            Front-load the differentiator.
+
+  - id: meta-description-length
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: webfile
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.file_path
+          patterns:
+            - '\.(tsx|jsx|html)$'
+            - '\.mdx?$'
+      - call: text_pattern_match
+        as: long_w
+        if: 'webfile.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - 'description:\s*["''][^"'']{161,}["'']'
+            - 'name="description"[^>]{0,80}content="[^"]{161,}'
+      - call: text_pattern_match
+        as: long_e
+        if: 'webfile.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - 'description:\s*["''][^"'']{161,}["'']'
+            - 'name="description"[^>]{0,80}content="[^"]{161,}'
+      - call: verdict
+        if: 'webfile.matched.length > 0 && (long_w.matched.length > 0 || long_e.matched.length > 0)'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/meta: meta description over ~160 chars truncates.
+            Lead with the answer — AI Overviews and snippets extract from the
+            first sentence.
+
+  - id: meta-img-alt
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: webfile
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.file_path
+          patterns:
+            - '\.(tsx|jsx|html)$'
+            - '\.mdx?$'
+      - call: text_pattern_match
+        as: noalt_w
+        if: 'webfile.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - '<img(?![^>]{0,300}\balt=)[^>]{0,300}>'
+      - call: text_pattern_match
+        as: noalt_e
+        if: 'webfile.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - '<img(?![^>]{0,300}\balt=)[^>]{0,300}>'
+      - call: verdict
+        if: 'webfile.matched.length > 0 && (noalt_w.matched.length > 0 || noalt_e.matched.length > 0)'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/meta: `<img>` without alt text — invisible to
+            extraction and an accessibility miss. Decorative images get
+            alt=""; content images get a descriptive alt.
+prose: |
+  Regex lints, deliberately recall-over-precision at warn level. A parserized
+  version (real HTML/JSX AST) is out of scope — these catch the common 90%.

package/packs/builtin/seo-aeo-expert/skills/page-removal-guard/skill.yaml

@@ -0,0 +1,30 @@
+# page-removal-guard — no 404s without redirects. Deleting a routable page
+# orphans its inbound links, internal links, and sitemap entry; AI engines
+# keep citing the dead URL for weeks. warn (deletion can be correct — 410 for
+# retired long-tail is policy per the seo-technical skill).
+name: page-removal-guard
+load: preload
+triggers:
+  - kind: tool_call
+rules:
+  - id: page-removal
+    process:
+      - call: match_command
+        args:
+          pattern: '\b(rm|git\s+rm)\b[^|;&\n]*/(app|pages|content)/[^ \n]+\.(tsx|jsx|ts|js|md|mdx|astro|html)'
+          target: tool_args.command
+        as: removing
+      - call: verdict
+        if: 'removing'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/page-removal: deleting a routable page/content
+            file. Before shipping: (1) add a 301 in next.config redirects /
+            vercel.json (or intentionally 410 for retired long-tail), (2)
+            update the sitemap, (3) grep internal links to the dead route.
+            Soft-404s and orphaned citations decay AI + organic visibility —
+            decision tree in the seo-technical skill.
+prose: |
+  Bash-side deletion guard. Write-tool route deletions (full-file overwrite of
+  a routes config) are P1 scope; rm/git rm is how routes actually die.

package/packs/builtin/seo-aeo-expert/skills/pre-push-seo-checklist/skill.yaml

@@ -0,0 +1,61 @@
+# pre-push-seo-checklist — the ship gate, FSM-backed (spec §4.3/§5.9).
+#   push while fixing/validating → unvalidated SEO work in flight → warn
+#     (dogfood week; promotes to block_tool in drift_response after FP review)
+#   push from validated → surface the one-screen checklist + advance `pushed`
+#   push from idle (no SEO cycle this session) → untouched
+# `\bgit\s+push\b` matches anywhere — compound commands (`cd x && git push`)
+# can't evade (the coding-flow FU.1 lesson).
+name: pre-push-seo-checklist
+load: preload
+triggers:
+  - kind: tool_call
+rules:
+  - id: push-while-unvalidated
+    process:
+      - call: match_command
+        args:
+          pattern: '\bgit\s+push\b'
+          target: tool_args.command
+        as: pushing
+      - call: read_fsm_state
+        if: 'pushing'
+        as: st
+      - call: verdict
+        if: 'pushing && (st == "fixing" || st == "validating")'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/push-gate: SEO fix cycle is OPEN (state: {{st}}) —
+            JSON-LD or SEO-relevant files were touched this session and no
+            schema validation has run. Run the validator (ajv / Rich Results
+            Test) before pushing; a validation command advances the cycle to
+            `validated` automatically. [[freehand-schema-forbidden]]
+
+  - id: push-checklist
+    process:
+      - call: match_command
+        args:
+          pattern: '\bgit\s+push\b'
+          target: tool_args.command
+        as: pushing
+      - call: read_fsm_state
+        if: 'pushing'
+        as: st
+      - call: advance_fsm
+        if: 'pushing && st == "validated"'
+        args:
+          event: pushed
+      - call: verdict
+        if: 'pushing && st == "validated"'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/push-checklist: validation passed — final sweep
+            before ship: sitemap updated for new/removed routes · 301s for
+            removed pages · build output is SSR/SSG (no page-level "use
+            client" regressions) · robots/bot policy unchanged-or-intended ·
+            canonical tags on new pages. Cycle marked `shipped`.
+prose: |
+  The EXECUTE gate of the SEO ops FSM, symmetric with coding-flow's commit
+  gate. P0 ships it at warn (spec §10.6 dogfood week); promotion to
+  block_tool is a one-line drift_response change, no skill edit.

package/packs/builtin/seo-aeo-expert/skills/schema-validation-gate/skill.yaml

@@ -0,0 +1,163 @@
+# schema-validation-gate — no unvalidated JSON-LD ships. Three jobs:
+#   1. schema-touched   — a JSON-LD edit ENTERS the FSM fix cycle (fix_start);
+#                         one informative warn when entering from idle
+#   2. schema-lint-*    — deterministic regex lints for the two highest-yield
+#                         Merchant/rich-result errors
+#   3. validation-run   — running a schema validator fires validation_passed
+#                         (P0 evidence proxy; P1 upgrades to exit-code proof)
+# Evidence: [[freehand-schema-forbidden]] + [[schema-actual-role]].
+name: schema-validation-gate
+load: preload
+triggers:
+  - kind: tool_call
+rules:
+  - id: schema-touched
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: jsonld_w
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - 'application/ld\+json'
+            - '"@context"[^\n]{0,60}schema\.org'
+      - call: text_pattern_match
+        as: jsonld_e
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - 'application/ld\+json'
+            - '"@context"[^\n]{0,60}schema\.org'
+      - call: read_fsm_state
+        if: 'jsonld_w.matched.length > 0 || jsonld_e.matched.length > 0'
+        as: st
+      - call: advance_fsm
+        if: 'jsonld_w.matched.length > 0 || jsonld_e.matched.length > 0'
+        args:
+          event: fix_start
+      - call: verdict
+        if: '(jsonld_w.matched.length > 0 || jsonld_e.matched.length > 0) && st == "idle"'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/schema: JSON-LD touched — entering the
+            validate-before-push cycle. LLMs are unreliable at freehand
+            schema; run a validator (ajv / Rich Results Test) before `git
+            push` or the push gate will flag it. [[freehand-schema-forbidden]]
+
+  - id: schema-lint-product
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: product_w
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - '"@type"\s*:\s*"Product"'
+      - call: text_pattern_match
+        as: price_w
+        if: 'product_w.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - 'priceValidUntil'
+      - call: text_pattern_match
+        as: product_e
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - '"@type"\s*:\s*"Product"'
+      - call: text_pattern_match
+        as: price_e
+        if: 'product_e.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - 'priceValidUntil'
+      - call: verdict
+        if: '(product_w.matched.length > 0 && price_w.matched.length == 0) || (product_e.matched.length > 0 && price_e.matched.length == 0)'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/schema-lint: Product JSON-LD without
+            `priceValidUntil` — triggers a Rich Results warning, and Merchant
+            listing eligibility also wants MerchantReturnPolicy +
+            OfferShippingDetails (2024+ requirement). See the seo-ecommerce
+            skill for the full Offer template.
+
+  - id: schema-lint-rating
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: rating_w
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - 'ratingValue'
+      - call: text_pattern_match
+        as: count_w
+        if: 'rating_w.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - '(reviewCount|ratingCount)'
+      - call: text_pattern_match
+        as: rating_e
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - 'ratingValue'
+      - call: text_pattern_match
+        as: count_e
+        if: 'rating_e.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - '(reviewCount|ratingCount)'
+      - call: verdict
+        if: '(rating_w.matched.length > 0 && count_w.matched.length == 0) || (rating_e.matched.length > 0 && count_e.matched.length == 0)'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/schema-lint: `ratingValue` without `reviewCount`
+            or `ratingCount` — invalid AggregateRating; the rich result will
+            be dropped. Also: self-fabricated review ratings are an FTC
+            violation (Oct-2024 final rule) and demoted by Google.
+
+  - id: validation-run
+    process:
+      - call: match_command
+        args:
+          pattern: '(ajv\b|rich-results|structured[- ]data|schema[^\n]{0,40}valid|valid[^\n]{0,40}schema)'
+          target: tool_args.command
+        as: valrun
+      - call: advance_fsm
+        if: 'valrun'
+        args:
+          event: validation_passed
+prose: |
+  The schema gate pairs with the FSM: touching JSON-LD opens the cycle,
+  running a validator closes it, and pre-push-seo-checklist reads the state.
+  P0 treats "validator was run" as the evidence proxy; P1 moves to
+  exit-code/cached_audit proof via the `validating` station.

package/packs/builtin/seo-aeo-expert/skills/ssr-regression-guard/skill.yaml

@@ -0,0 +1,58 @@
+# ssr-regression-guard — content must exist without JavaScript. Zero major AI
+# crawlers execute JS (500M+ GPTBot fetches, zero JS execution; Vercel study,
+# still true 2026). Client-rendering page content makes it invisible to
+# ChatGPT/Claude/Perplexity — and ChatGPT rides Bing's limited rendering too.
+# Evidence: [[no-js-execution]].
+name: ssr-regression-guard
+load: preload
+triggers:
+  - kind: tool_call
+rules:
+  - id: ssr-regression
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: pagefile
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.file_path
+          patterns:
+            - 'app/.*page\.(tsx|jsx)$'
+            - 'app/.*layout\.(tsx|jsx)$'
+            - '(^|/)pages/.*\.(tsx|jsx)$'
+      - call: text_pattern_match
+        as: hit_w
+        if: 'pagefile.matched.length > 0'
+        args:
+          text_field: args.content
+          patterns:
+            - '["'']use client["'']'
+            - 'useEffect\([\s\S]{0,500}?fetch\('
+      - call: text_pattern_match
+        as: hit_e
+        if: 'pagefile.matched.length > 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - '["'']use client["'']'
+            - 'useEffect\([\s\S]{0,500}?fetch\('
+      - call: verdict
+        if: 'pagefile.matched.length > 0 && (hit_w.matched.length > 0 || hit_e.matched.length > 0)'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/ssr: `"use client"` or client-side fetch on a
+            PAGE-level file — no major AI crawler executes JavaScript, so
+            client-rendered content is invisible to ChatGPT, Claude, and
+            Perplexity (Googlebot is the only full renderer). Keep indexable
+            content in server components / SSG; push `"use client"` to the
+            interactive leaf. [[no-js-execution]]
+prose: |
+  Atomic-design corollary: pages and layouts stay server-rendered; client
+  interactivity belongs in leaf organisms. This guard fires on the page/layout
+  boundary only, so leaf components are untouched.

package/packs/builtin/seo-aeo-expert/skills/stale-tactic-guard/skill.yaml

@@ -0,0 +1,72 @@
+# stale-tactic-guard — structurally refuse 2026-disproven SEO tactics in
+# shipped content/code. warn-level: surfaces the evidence, human decides.
+# Exempt: research/docs/lessons/tests/fixtures (writing ABOUT a dead tactic is
+# legitimate — this pack's own lessons discuss llms.txt). Evidence:
+# [[deprecated-tactics-2026]] + [[llms-txt-dead]].
+name: stale-tactic-guard
+load: preload
+triggers:
+  - kind: tool_call
+rules:
+  - id: stale-tactic
+    process:
+      - call: text_pattern_match
+        as: is_write
+        args:
+          text_field: tool
+          patterns:
+            - '^(Write|Edit|NotebookEdit)$'
+      - call: text_pattern_match
+        as: exempt
+        if: 'is_write.matched.length > 0'
+        args:
+          text_field: args.file_path
+          patterns:
+            - '(^|/)research/'
+            - '(^|/)docs/'
+            - '(^|/)lessons/'
+            - '(^|/)fixtures/'
+            - '\.test\.(ts|js|tsx|jsx)$'
+            - 'CHANGELOG\.md$'
+            - '\.opensquid/'
+      - call: text_pattern_match
+        as: stale_w
+        if: 'is_write.matched.length > 0 && exempt.matched.length == 0'
+        args:
+          text_field: args.content
+          patterns:
+            - 'llms\.txt[^\n]{0,100}(rank|citation|visib|boost)'
+            - '(rank|citation|visib|boost)[^\n]{0,100}llms\.txt'
+            - 'keyword[ -]density'
+            - 'meta[ -]keywords'
+            - '\bLSI keyword'
+            - '"@type"\s*:\s*"(FAQPage|HowTo)"'
+      - call: text_pattern_match
+        as: stale_e
+        if: 'is_write.matched.length > 0 && exempt.matched.length == 0'
+        args:
+          text_field: args.new_string
+          patterns:
+            - 'llms\.txt[^\n]{0,100}(rank|citation|visib|boost)'
+            - '(rank|citation|visib|boost)[^\n]{0,100}llms\.txt'
+            - 'keyword[ -]density'
+            - 'meta[ -]keywords'
+            - '\bLSI keyword'
+            - '"@type"\s*:\s*"(FAQPage|HowTo)"'
+      - call: verdict
+        if: 'is_write.matched.length > 0 && exempt.matched.length == 0 && (stale_w.matched.length > 0 || stale_e.matched.length > 0)'
+        args:
+          level: warn
+          message: >-
+            seo-aeo-expert/stale-tactic: a 2026-deprecated SEO tactic is being
+            shipped. llms.txt has ZERO measured citation correlation (SE
+            Ranking 300k-domain study; Google calls it "purely speculative" —
+            harmless for agent docs, dead as a ranking lever). FAQ/HowTo rich
+            results were removed (2023; FAQ fully dead 2026-05) — FAQPage
+            markup only plausibly aids Bing/Copilot comprehension. Keyword
+            density / meta keywords / LSI are folklore; the Princeton GEO
+            study measured keyword stuffing as neutral-to-NEGATIVE for AI
+            citations. See [[deprecated-tactics-2026]].
+prose: |
+  The evidence gate for tactics. The field is drowning in folklore; this
+  pack's credibility position is refusing disproven advice at write time.