agent-bober 0.17.1 → 0.19.0

package/skills/bober.security-solidity/SKILL.md

@@ -0,0 +1,306 @@
+---
+name: bober.security-solidity
+description: "Solidity/EVM smart-contract security signature library. Not a workflow skill -- a data file of discrete vulnerable/safe code signature blocks read by SecuritySignatureParser. Covers reentrancy (single-function, cross-function, read-only), spot-price oracle manipulation, missing access control, unprotected initializers, unchecked arithmetic, ERC-4626 inflation, unsafe ERC20, tx.origin auth, missing slippage/deadline, DoS via unbounded loops, and signature replay."
+---
+
+# bober.security-solidity — Solidity/EVM Security Signature Library
+
+This skill is a **signature-library** file, not a workflow skill. It is read (as raw
+markdown text) by `SecuritySignatureParser.parse()`
+(`src/orchestrator/security-knowledge/parser.ts`) and turned into typed
+`SecuritySignature[]` records used by the security-audit agent team. Do not confuse this
+with `bober.solidity`, which is the general Solidity development skill, or
+`bober.security-audit`, which is the audit *workflow* skill.
+
+## Signature Block Format
+
+Each signature is a level-3 heading (three `#` characters, a space, then the
+`signatureId`) followed by labelled fields and two fenced code examples. This file and
+`SecuritySignatureParser` are one executable spec — keep them in sync.
+
+Required fields per block:
+- The heading text itself is the `signatureId` (must be non-empty).
+- `- **Title:** <human-readable title>`
+- `- **CWE:** CWE-xx` (optional — omit the line entirely for `cwe: null`)
+- `- **Severity:** critical|high|medium|low|info`
+- `- **VulnClass:** <a VulnClass union member, verbatim — see security-audit-types.ts>`
+- `- **Invariant:** <the safety invariant this signature protects>`
+- `- **Keywords:** comma, separated, keywords`
+
+Then two labelled fenced code examples:
+- `**Unsafe:**` followed by a fenced `ts` block with the vulnerable example.
+- `**Safe:**` followed by a fenced `ts` block with the fixed example.
+
+A block missing `Title`, a valid `VulnClass`, a valid `Severity`, or a non-empty
+unsafe/safe example is dropped by the parser — never a fatal error.
+
+## Signatures
+
+### solidity.reentrancy-single-function
+- **Title:** Single-function reentrancy: external call before state update
+- **CWE:** SWC-107
+- **Severity:** critical
+- **VulnClass:** race-condition
+- **Invariant:** All state that a function depends on is finalized (checks-effects-interactions) before any external call that could re-enter the same function.
+- **Keywords:** reentrancy, call, checks-effects-interactions, nonReentrant
+
+**Unsafe:**
+```ts
+(bool ok, ) = msg.sender.call{value: balances[msg.sender]}("");
+require(ok);
+balances[msg.sender] = 0;
+```
+
+**Safe:**
+```ts
+uint256 amount = balances[msg.sender];
+balances[msg.sender] = 0;
+(bool ok, ) = msg.sender.call{value: amount}("");
+require(ok);
+```
+
+### solidity.reentrancy-readonly
+- **Title:** Read-only reentrancy via view function during callback
+- **CWE:** SWC-107
+- **Severity:** high
+- **VulnClass:** race-condition
+- **Invariant:** A view function's return value must never be trusted mid-callback while a caller's external hook (e.g. an ERC777/ERC721 receiver hook) can still mutate the same pool state.
+- **Keywords:** read-only reentrancy, view, getReserves, callback
+
+**Unsafe:**
+```ts
+function price() external view returns (uint256) {
+  (uint112 r0, uint112 r1, ) = pair.getReserves(); // stale mid-callback
+  return r1 * 1e18 / r0;
+}
+```
+
+**Safe:**
+```ts
+function price() external view returns (uint256) {
+  require(!pair.locked(), "reentrant read"); // reentrancy-guard-aware getter
+  (uint112 r0, uint112 r1, ) = pair.getReserves();
+  return r1 * 1e18 / r0;
+}
+```
+
+### solidity.spot-price-oracle-flashloan
+- **Title:** Spot AMM price used as oracle (flash-loan manipulable)
+- **Severity:** critical
+- **VulnClass:** money-integrity
+- **Invariant:** A price used for liquidation/collateral/settlement math is never a single-block spot reserve ratio — it comes from a manipulation-resistant source with a staleness bound.
+- **Keywords:** oracle, spot price, getReserves, TWAP, flash loan
+
+**Unsafe:**
+```ts
+(uint112 r0, uint112 r1, ) = pair.getReserves();
+uint256 price = r1 * 1e18 / r0; // manipulable within one flash-loaned tx
+```
+
+**Safe:**
+```ts
+uint256 price = chainlinkFeed.latestAnswer();
+require(block.timestamp - chainlinkFeed.updatedAt() < MAX_STALENESS, "stale price");
+```
+
+### solidity.missing-onlyowner
+- **Title:** Missing onlyOwner/role modifier on a privileged function
+- **CWE:** SWC-105
+- **Severity:** critical
+- **VulnClass:** authn-authz
+- **Invariant:** Every function that mutates protocol-critical state (fees, admin addresses, pausing, minting) is gated by an explicit ownership or role check.
+- **Keywords:** onlyOwner, AccessControl, modifier, privileged
+
+**Unsafe:**
+```ts
+function setFee(uint256 newFee) public {
+  fee = newFee; // callable by anyone
+}
+```
+
+**Safe:**
+```ts
+function setFee(uint256 newFee) public onlyRole(FEE_ADMIN_ROLE) {
+  fee = newFee;
+}
+```
+
+### solidity.unprotected-initializer
+- **Title:** Unprotected initializer / uninitialized proxy implementation (Parity-style)
+- **CWE:** CWE-665
+- **Severity:** critical
+- **VulnClass:** privilege-escalation
+- **Invariant:** An upgradeable contract's `initialize()` can only ever run once, and the logic-contract instance itself is never left in an initializable state.
+- **Keywords:** initializer, initialize, proxy, _disableInitializers
+
+**Unsafe:**
+```ts
+function initialize(address _owner) public {
+  owner = _owner; // callable repeatedly by anyone on the implementation contract
+}
+```
+
+**Safe:**
+```ts
+constructor() { _disableInitializers(); }
+
+function initialize(address _owner) public initializer {
+  owner = _owner;
+}
+```
+
+### solidity.unchecked-arithmetic
+- **Title:** unchecked{} block underflows a balance
+- **CWE:** SWC-101
+- **Severity:** critical
+- **VulnClass:** money-integrity
+- **Invariant:** A balance or supply subtraction never wraps — the subtrahend is bounds-checked before entering an unchecked block, or the block is dropped in favor of checked arithmetic.
+- **Keywords:** unchecked, overflow, underflow, arithmetic
+
+**Unsafe:**
+```ts
+unchecked {
+  balances[msg.sender] -= amount; // wraps to a huge balance if amount > balance
+}
+```
+
+**Safe:**
+```ts
+require(balances[msg.sender] >= amount, "insufficient balance");
+balances[msg.sender] -= amount;
+```
+
+### solidity.erc4626-inflation
+- **Title:** ERC-4626 first-depositor / share-inflation attack
+- **Severity:** critical
+- **VulnClass:** money-integrity
+- **Invariant:** Share-price math (assets-per-share) can never be driven to an attacker-favorable rounding extreme by a first depositor donating raw assets directly to the vault.
+- **Keywords:** ERC4626, first depositor, inflation, virtual shares, dead shares
+
+**Unsafe:**
+```ts
+function deposit(uint256 assets) external returns (uint256 shares) {
+  shares = totalSupply == 0 ? assets : assets * totalSupply / totalAssets();
+  _mint(msg.sender, shares); // attacker mints 1 share then donates assets to inflate price
+}
+```
+
+**Safe:**
+```ts
+function deposit(uint256 assets) external returns (uint256 shares) {
+  shares = assets * (totalSupply + 10 ** decimalsOffset) / (totalAssets() + 1); // virtual shares/assets offset
+  _mint(msg.sender, shares);
+}
+```
+
+### solidity.unsafe-erc20
+- **Title:** Unsafe ERC20 usage (no SafeERC20 / fee-on-transfer / rebasing)
+- **CWE:** SWC-104
+- **Severity:** high
+- **VulnClass:** money-integrity
+- **Invariant:** Every ERC20 transfer's return value is checked, and any accounting derived from a transfer uses the measured balance delta, not the nominal amount passed in.
+- **Keywords:** transfer, SafeERC20, fee-on-transfer, rebasing, return value
+
+**Unsafe:**
+```ts
+token.transfer(recipient, amount); // return value ignored; assumes amount fully received
+credited[recipient] += amount;
+```
+
+**Safe:**
+```ts
+uint256 before = token.balanceOf(address(this));
+token.safeTransfer(recipient, amount);
+uint256 received = before - token.balanceOf(address(this));
+credited[recipient] += received;
+```
+
+### solidity.txorigin-auth
+- **Title:** tx.origin used for authorization (phishable)
+- **CWE:** SWC-115
+- **Severity:** high
+- **VulnClass:** authn-authz
+- **Invariant:** Authorization checks compare against `msg.sender`, never `tx.origin`, so a malicious intermediate contract cannot impersonate the original caller.
+- **Keywords:** tx.origin, msg.sender, phishing
+
+**Unsafe:**
+```ts
+function withdraw() external {
+  require(tx.origin == owner); // phishable via a malicious contract the owner interacts with
+  payable(owner).transfer(address(this).balance);
+}
+```
+
+**Safe:**
+```ts
+function withdraw() external {
+  require(msg.sender == owner);
+  payable(owner).transfer(address(this).balance);
+}
+```
+
+### solidity.missing-slippage-deadline
+- **Title:** Swap missing amountOutMin / deadline (sandwich-attack surface)
+- **Severity:** high
+- **VulnClass:** money-integrity
+- **Invariant:** Every swap specifies a caller-supplied minimum output and a real expiry deadline, so a sandwiching attacker cannot extract unbounded slippage.
+- **Keywords:** amountOutMin, deadline, slippage, swap, sandwich
+
+**Unsafe:**
+```ts
+router.swapExactTokensForTokens(amountIn, 0, path, msg.sender, block.timestamp);
+```
+
+**Safe:**
+```ts
+router.swapExactTokensForTokens(amountIn, minAmountOut, path, msg.sender, userSuppliedDeadline);
+```
+
+### solidity.dos-unbounded-loop
+- **Title:** DoS via unbounded loop over a growable array
+- **CWE:** SWC-128
+- **Severity:** high
+- **VulnClass:** denial-of-service
+- **Invariant:** No externally-triggerable function iterates over a collection whose size is controlled by untrusted users within a single transaction's gas budget.
+- **Keywords:** unbounded loop, gas limit, pull-over-push, DoS
+
+**Unsafe:**
+```ts
+function distribute() external {
+  for (uint256 i = 0; i < holders.length; i++) { // holders.length grows unbounded
+    payable(holders[i]).transfer(shares[holders[i]]);
+  }
+}
+```
+
+**Safe:**
+```ts
+function claim() external { // pull-over-push, one holder per call, bounded gas
+  uint256 amount = shares[msg.sender];
+  shares[msg.sender] = 0;
+  payable(msg.sender).transfer(amount);
+}
+```
+
+### solidity.signature-replay
+- **Title:** Missing nonce/chainId/EIP-712 domain; ecrecover==0 malleability
+- **CWE:** SWC-117
+- **Severity:** critical
+- **VulnClass:** crypto-weakness
+- **Invariant:** A recovered signer address is checked against the zero address, and the signed payload binds a single-use nonce, the chain id, and an EIP-712 domain so a signature cannot be replayed across calls or chains.
+- **Keywords:** ecrecover, nonce, chainId, EIP-712, replay, malleability
+
+**Unsafe:**
+```ts
+address signer = ecrecover(hash, v, r, s); // no domain, no nonce, no zero-address check
+require(signer == expectedSigner);
+```
+
+**Safe:**
+```ts
+bytes32 digest = _hashTypedDataV4(structHash); // EIP-712 domain-bound, includes nonce + chainId
+address signer = ecrecover(digest, v, r, s);
+require(signer != address(0) && signer == expectedSigner);
+require(!usedNonces[nonce]);
+usedNonces[nonce] = true;
+```

package/skills/bober.seo/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: bober.seo
+description: >-
+  Orchestration skill for the Bober SEO/GEO suite — routes to the 8 workflows
+  (technical-audit, rank-track, content-decay, topical-map, ai-visibility,
+  parasite-watch, internal-linking, schema-audit) run via `bober seo <workflow>
+  [target]`. Offline by default; live data is behind two default-false egress
+  axes (seo.egress.search-console, seo.egress.serp-provider). Use when you want
+  an SEO audit, rank/decay analysis, topical map, AI-visibility check, schema
+  audit, internal-linking pass, or parasite-SEO watch.
+argument-hint: "<workflow> [target]"
+---
+
+# bober.seo — SEO/GEO Suite Orchestrator
+
+You are the **orchestrator** for an SEO/GEO run. You do NOT analyze data yourself —
+you route to the `bober seo <workflow> [target]` CLI (scriptable/CI-friendly, exit-code
+driven) or spawn the `bober-seo-strategist` subagent (conversational, findings woven
+into this session), optionally followed by the `bober-seo-verifier` subagent, then
+present the result. The whole suite is **offline by construction**: the default data
+source reads local exports under `.bober/seo/imports/`; live Google Search Console or
+DataForSEO data only flows when the matching egress axis is explicitly opted in.
+
+## The 8 workflows
+
+| Workflow | What it analyzes |
+|---|---|
+| `technical-audit` | Crawlability, indexing state, robots/sitemap, technical health (URL inspection + search-analytics data) |
+| `rank-track` | Ranking position movement and SERP presence for tracked keywords |
+| `content-decay` | Pages/queries losing clicks or position over time — candidates for a refresh |
+| `topical-map` | Topical coverage and site-focus/site-radius gaps against a target topic |
+| `ai-visibility` | Brand/citation presence in AI answers (AI Overviews, ChatGPT, Perplexity, etc.) |
+| `parasite-watch` | Third-party-host placement risk — **detect-only**, never recommends the tactic itself (see Guardrails) |
+| `internal-linking` | Internal link structure, orphan pages, anchor-text distribution |
+| `schema-audit` | Structured-data / entity markup coverage and validity |
+
+Name these 8 verbatim when discussing the suite — this is the canonical list
+(`src/seo/command.ts:27-36`); do not invent a 9th workflow or rename one.
+
+## How to run
+
+**CLI (scriptable / CI-friendly):**
+
+```bash
+bober seo <workflow> [target]
+# or: agent-bober seo <workflow> [target]
+```
+
+- `[target]` is a URL, domain, or local path; when omitted the runner falls back to
+  `config.seo.defaultTarget` if set.
+- Prints one summary line: `SEO report <id>: verdict=…, findings=…, droppedUncited=…`.
+- **Exit codes:** `0` = pass, `2` = blocked (citation-gate threshold tripped) or
+  fail-closed (an unknown workflow, or the run threw). `1` is reserved for Commander's
+  own usage errors, never an audit outcome.
+- An unrecognized `<workflow>` prints the valid list and exits `2` immediately — no
+  partial run.
+
+**Conversational (spawn the subagent):** use when the user wants findings discussed,
+iterated on, or woven into this conversation rather than piped through CI.
+
+## When to spawn which agent
+
+- **`bober-seo-strategist`** (`agents/bober-seo-strategist.md`, read-only: Read/Grep/Glob
+  only) — the analysis role. Feed it the workflow, target, a retrieved playbook context
+  (`SeoSignature` blocks selected from `skills/bober.seo-*/SKILL.md` for the declared
+  workflow), and a gathered SEO data bundle. It returns evidence-cited findings; it
+  cannot write, edit, or call a live API itself.
+- **`bober-seo-verifier`** (`agents/bober-seo-verifier.md`, no tools, fresh contract-free
+  context) — the adversarial false-positive control. Spawn it **after** the strategist,
+  only when `config.seo.verifier.enabled` is `true`, feeding it ONLY the strategist's
+  findings (never the sprint contract or any "already reviewed" framing). It can only
+  confirm, downgrade, or drop a finding — never promote or add one.
+- Route the CLI path instead of spawning either agent when the user wants a scriptable,
+  exit-code-driven result (CI, a script, a quick pass/fail check).
+
+## Offline vs. live data
+
+**Offline by default.** The default `LocalExportSource` reads one file per capability
+from `.bober/seo/imports/`: `search-analytics`, `url-inspection`, `serp`, `keywords`,
+`backlinks`, each as `<capability>.csv` or `<capability>.json`. A missing file for a
+capability degrades to `disabled` for that capability alone — it never blocks the rest
+of the run, and it requires no API key.
+
+**Live data is opt-in, per source, and default-false** — two independent egress axes
+(`SeoEgressGuard`, `src/seo/egress.ts`):
+
+| Axis | Config key | Gates |
+|---|---|---|
+| Google Search Console | `seo.egress.search-console` | Live search-analytics / URL-inspection API calls |
+| DataForSEO | `seo.egress.serp-provider` | Live SERP / keyword / backlink API calls |
+
+Both default `false`; the whole `seo.egress` object is optional and omitting it keeps
+every workflow fully offline. Opting into one axis does **not** opt into the other.
+Live credentials come from environment variables, not config: `GSC_OAUTH_TOKEN` for
+`search-console`, `DATAFORSEO_LOGIN` / `DATAFORSEO_PASSWORD` for `serp-provider`.
+
+## Config knobs
+
+- `seo.budget.maxUsd` — per-run USD spend ceiling for PAYG DataForSEO calls (absent =
+  uncapped).
+- `seo.verifier.enabled` — turns on the adversarial `bober-seo-verifier` pass (default
+  `false`).
+- `seo.defaultTarget` — used when the CLI's `[target]` argument is omitted.
+- `seo.blockThreshold` — `never | any-uncited | critical-uncited` (default
+  `critical-uncited`) — the citation gate's exit-code-2 threshold.
+
+## Guardrails to restate
+
+- **Never-encode tactics are dropped at parse, never surfaced.** Any playbook block
+  tagged `PolicyClass: never-encode` (e.g. parasite-SEO placement on a third-party host)
+  is dropped by `SeoPlaybookParser` before it ever reaches an analysis prompt — this is
+  why `parasite-watch` is detect-only: it can flag exposure, never recommend the tactic.
+- **`humanApprovalRequired` findings need a human.** Any recommendation touching policy
+  compliance (paid links, cloaking, structured-data misuse) or spend (ad budget, paid
+  placements, metered live-API calls) is flagged for manual review before acting on it.
+- **Citation discipline.** Every finding the strategist emits must carry a primary-source
+  `citationUrl`; an uncited finding is dropped by the deterministic `SeoCitationGate`
+  before it reaches a report or the hub — the LLM's judgment never bypasses this gate.
+
+For the full reference (CLI exit codes, config schema, import file format, per-workflow
+detail), see [`docs/seo.md`](../../docs/seo.md).
+
+## Report
+
+After a run (CLI or subagent), summarize for the user: the workflow + target, the
+verdict (`pass`/`blocked`), the finding count and how many were dropped for missing
+citations (`droppedUncited`), and — for any `humanApprovalRequired` finding — call it out
+explicitly rather than folding it into the general list. The CLI path persists the
+report to `.bober/seo/reports/<reportId>.json` (`SeoReportStore`) and best-effort emits
+critical/notable findings into the priority hub — point the user there. When you spawn
+the subagent(s) directly instead of the CLI, you own persisting the returned JSON
+yourself if the user wants it kept; the subagents have no Write tool.

package/skills/bober.seo-ai-visibility/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: bober.seo-ai-visibility
+description: "Per-workflow SEO signature library for the ai-visibility workflow. A data file of discrete, cited SEO/GEO tactics read by SeoPlaybookParser (src/seo/parser.ts), not a workflow skill. Encodes VERIFIED 2025-2026 AI-visibility correlations (Ahrefs 75k-brand study, Semrush ghost-citations study, Profound platform-citation study) with per-platform GEO divergence marked perishable."
+---
+
+# bober.seo-ai-visibility — AI-Visibility (GEO) Signature Library
+
+This skill is a **signature-library** file for the `ai-visibility` workflow, not a
+workflow skill in its own right. It is read (as raw markdown text) by
+`SeoPlaybookParser.parse()` (`src/seo/parser.ts`) and turned into typed
+`SeoSignature[]` records consumed by the SEO agent team's retriever
+(`SeoPlaybookRetriever`). It follows the identical block format defined and
+documented in `skills/bober.seo-generic/SKILL.md` ("Signature Block Format") --
+the two files are one executable spec; a block missing `Title` or
+`PrimarySourceUrl`, or tagged `PolicyClass: never-encode`, is DROPPED by the
+parser at load time.
+
+The signatures below encode VERIFIED generative-engine-optimization (GEO)
+correlations from three independent 2025-2026 studies -- Ahrefs' 75,000-brand
+correlation analysis, Semrush's ghost-citations study, and Profound's
+680-million-citation platform analysis -- plus one deliberate `never-encode`
+boundary block for AI-recommendation poisoning. Per-platform citation-mix
+figures are explicitly marked **PERISHABLE** below: platform algorithms and
+source-weighting change fast, so treat those specific percentages as
+dated-as-of-measurement, not durable constants. See
+`.bober/research/research-20260715-ultimate-seo-agents-skills-research.md`
+§1/§7 for the underlying evidence and the two REFUTED claims that must never
+be encoded here (ChatGPT-Wikipedia dominance, Reddit-leading-AI-Overviews).
+
+## Signatures
+
+### ai-visibility-youtube-presence-audit
+- **Title:** Audit and grow YouTube presence -- the strongest single AI-visibility correlate
+- **Workflows:** ai-visibility
+- **Tactic:** Include YouTube brand presence (owned-channel content, creator partnerships, video PR, transcript/caption quality) as a first-class line item in every AI-visibility audit, not an afterthought to written-content SEO. Report current YouTube mention volume as a baseline metric alongside branded web mentions.
+- **Invariant:** Across ChatGPT, Google AI Mode, and AI Overviews, YouTube mentions show the single highest correlation (~0.737 Spearman) with brand visibility in AI answers, in a 75,000-brand Ahrefs correlation study -- stronger than any other measured signal, including backlinks.
+- **PrimarySourceUrl:** https://ahrefs.com/blog/ai-brand-visibility-correlations/
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** verified
+- **Keywords:** youtube, ai-visibility, geo, correlation, audit
+
+### ai-visibility-branded-mention-audit
+- **Title:** Audit branded web-mention volume (linked or unlinked) -- the strongest non-video AI-visibility signal
+- **Workflows:** ai-visibility
+- **Tactic:** Track and report branded web-mention volume across the open web as a distinct AI-visibility metric, counting unlinked mentions equally with linked ones; do not discount coverage that omits a hyperlink when assessing AI-visibility health.
+- **Invariant:** Branded web mentions (linked or unlinked) correlate at 0.66-0.71 with brand visibility in AI answers -- the strongest non-YouTube signal, and dramatically stronger than classic backlink volume (~0.218), in the same 75,000-brand Ahrefs study.
+- **PrimarySourceUrl:** https://ahrefs.com/blog/ai-brand-visibility-correlations/
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** verified
+- **Keywords:** brand-mention, ai-visibility, geo, correlation, backlinks-weak
+
+### ai-visibility-ghost-citation-mention-split
+- **Title:** Track citation rate and mention rate as two distinct AI-visibility metrics
+- **Workflows:** ai-visibility
+- **Tactic:** Report AI-citation rate and AI-mention rate as separate audit metrics for every tracked brand/page; do not conflate "the page is linked as a source" with "the brand is named in the answer text" -- they measure different things and a gap between them is itself a finding.
+- **Invariant:** 61.7% of AI citations are "ghost citations" -- the source page is linked but the brand is never named in the AI-generated answer -- across 3,981 domain appearances / 115 prompts / 4 platforms / 14 countries in the Semrush/Kevin Indig ghost-citations study.
+- **PrimarySourceUrl:** https://www.semrush.com/blog/the-ghost-citations-study/
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** verified
+- **Keywords:** ghost-citation, citation-rate, mention-rate, ai-visibility
+
+### ai-visibility-per-platform-geo-divergence
+- **Title:** [PERISHABLE, dated 2026] Audit per-platform citation/mention mix separately -- platforms diverge sharply and the mix will shift over time
+- **Workflows:** ai-visibility
+- **Tactic:** Do not optimize AI-visibility as a single undifferentiated target; audit and report citation-vs-mention behavior per platform (ChatGPT, Gemini, Perplexity, AI Overviews), because a page can be heavily mentioned on one platform and heavily cited-but-unnamed on another. Re-measure this split on a recurring cadence -- the specific percentages below are a point-in-time snapshot, not a stable baseline.
+- **Invariant:** [PERISHABLE] The Semrush ghost-citations study documents sharp per-platform divergence in citation-vs-mention behavior (e.g. platforms differ materially in how often a cited source page is also named as the brand in the answer text); this mix is measured as of the 2025-2026 study window and should be treated as dated, not durable, given known platform-algorithm churn.
+- **PrimarySourceUrl:** https://www.semrush.com/blog/the-ghost-citations-study/
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** per-platform, geo-divergence, perishable, citation-mix, dated-2026
+
+### ai-visibility-comparative-query-mention-lift
+- **Title:** Build comparison ("vs") content to capture the comparative-query mention lift
+- **Workflows:** ai-visibility, topical-map
+- **Tactic:** Prioritise comparative/"X vs Y" content in the AI-visibility content plan -- comparison-framed queries earn a measurably higher brand-mention rate than single-entity queries, so this is a specific, evidence-backed content type to invest in, not a generic content-marketing suggestion.
+- **Invariant:** Comparative queries generate 2.4x more brand mentions than single-entity queries (43.3% vs 18% mention rate) in the Semrush ghost-citations study's query-type breakdown.
+- **PrimarySourceUrl:** https://www.semrush.com/blog/the-ghost-citations-study/
+- **PolicyClass:** human-approve
+- **EvidenceGrade:** single-source
+- **Keywords:** comparative-query, mention-lift, content-plan, ai-visibility
+
+### ai-visibility-aio-citation-rank-decouple
+- **Title:** Audit AI Overview citation coverage separately from organic rank -- most cited pages no longer rank top-10
+- **Workflows:** ai-visibility, rank-track
+- **Tactic:** Do not treat organic top-10 ranking as a prerequisite for AIO citation in the audit methodology; run a dedicated AIO-citation crawl/check independent of rank-tracking, since a majority of currently-cited pages rank outside the top 10.
+- **Invariant:** Only 38% of AIO-cited pages ranked in the organic top-10 as of Jan 2026 (down from ~76% in Jul 2025); 31.2% of cited pages ranked 11-100 and 31.0% ranked beyond top-100, per an Ahrefs analysis of 863K SERPs / 4M AIO URLs.
+- **PrimarySourceUrl:** https://ahrefs.com/blog/ai-overview-citations-top-10/
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** verified
+- **Keywords:** aio, citations, rank-decouple, ai-visibility
+
+### ai-visibility-perplexity-community-weighted
+- **Title:** [PERISHABLE, dated 2026] For Perplexity-specific work, weight community presence over publisher-style placement
+- **Workflows:** ai-visibility
+- **Tactic:** When auditing or building Perplexity-specific AI-visibility, prioritise genuine community presence and discussion (Reddit and similar forums) as one input among several platform-mix signals, alongside publisher-style content; re-check this platform mix periodically since platform citation-source weighting is known to shift.
+- **Invariant:** [PERISHABLE] In a 680-million-citation Profound study, Perplexity showed the most community-weighted citation mix of the platforms measured, with community-forum sources forming a materially larger share of Perplexity's citations than of other platforms' citation mixes; this mix is a point-in-time measurement, not a durable constant.
+- **PrimarySourceUrl:** https://www.tryprofound.com/blog/ai-platform-citation-patterns
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** perplexity, community, platform-specific, perishable, dated-2026
+
+### ai-recommendation-poisoning-boundary
+- **Title:** AI-recommendation poisoning via prompt injection -- NEVER encode as a tactic
+- **Workflows:** ai-visibility
+- **Tactic:** NEVER encode as actionable. Injecting hidden prompts into page content, browser-extension "Summarize with AI" surfaces, or other AI-consumed channels to manipulate an AI assistant's recommendation or citation behavior toward a brand is prompt injection / AI-recommendation poisoning, a security and trust violation, not a legitimate GEO tactic. Documented here only to mark the automation boundary; the parser DROPS this block so it can never reach an analyzer prompt.
+- **Invariant:** AI-recommendation poisoning (prompt-injection attacks against AI-summarization and AI-assistant surfaces) is a documented 2025-2026 attack class against AI-consumed content; it must never be surfaced as an option, even human-approval-gated -- it is a manipulation technique, not a judgment call.
+- **PrimarySourceUrl:** https://developers.google.com/search/docs/essentials/spam-policies
+- **PolicyClass:** never-encode
+- **EvidenceGrade:** primary-unverified
+- **Keywords:** ai-recommendation-poisoning, prompt-injection, never-encode, policy-violation

package/skills/bober.seo-content-decay/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: bober.seo-content-decay
+description: "Per-workflow SEO signature library for the content-decay workflow. A data file of discrete, cited SEO tactics read by SeoPlaybookParser (src/seo/parser.ts), not a workflow skill. Encodes the leak's NavBoost click-decay mechanism, the rolling 13-month refresh window, and the HCU-era content-decay baseline (522 sites, 64% traffic-lost) for the content-decay workflow."
+---
+
+# bober.seo-content-decay — Content Decay Signature Library
+
+This skill is a **signature-library** file for the `content-decay` workflow, not a
+workflow skill in its own right. It is read (as raw markdown text) by
+`SeoPlaybookParser.parse()` (`src/seo/parser.ts`) and turned into typed
+`SeoSignature[]` records consumed by the SEO agent team's retriever
+(`SeoPlaybookRetriever`). It follows the identical block format defined and
+documented in `skills/bober.seo-generic/SKILL.md` ("Signature Block Format") --
+the two files are one executable spec; a block missing `Title` or
+`PrimarySourceUrl`, or tagged `PolicyClass: never-encode`, is DROPPED by the
+parser at load time -- see
+`.bober/research/research-20260715-ultimate-seo-agents-skills-research.md`
+for the underlying evidence.
+
+The signatures below encode the leaked Google Content Warehouse API's
+NavBoost click-decay mechanism (decay as a failure to keep driving a page's
+expected click share over a rolling 13-month window) and Detailed's
+522-content-site post-HCU study, which found 64% of content-first sites lost
+traffic with a median loss of -471K visits / -17.8%. Most signatures here are
+**read-only detection/monitoring** (auto-safe); the one signature that would
+execute a large-scale rewrite or page consolidation that changes the live
+site is `human-approve` -- consistent with research §6's automation boundary.
+
+## Signatures
+
+### navboost-decay-expected-clicks
+- **Title:** Content decay is partly a NavBoost failure to keep driving a page's expected click share
+- **Workflows:** content-decay
+- **Tactic:** Detect decay by comparing a page's current click share against the click share its rank would predict, not by watching raw rank alone; flag pages whose click-share is sliding relative to their rank as decaying even before the rank itself drops.
+- **Invariant:** The leaked Google Content Warehouse API documents NavBoost as a click-based re-ranking system tracking goodClicks, badClicks, lastLongestClicks, and unsquashedClicks over a rolling 13-month window; a page's ranking position and its actual click performance can diverge, and a sustained failure to drive the clicks NavBoost expects for that position is a mechanical decay signal.
+- **PrimarySourceUrl:** https://ipullrank.com/google-algo-leak
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** navboost, decay, expected-clicks, click-share
+
+### navboost-13month-refresh-window
+- **Title:** Set refresh cadence inside NavBoost's rolling 13-month click window, not annually
+- **Workflows:** content-decay
+- **Tactic:** Schedule content-refresh review cycles to land within the 13-month click-history window NavBoost scores over, rather than on a slower annual cadence that lets a page's click history fully roll past its refresh.
+- **Invariant:** The leak documents NavBoost as scoring goodClicks/badClicks/lastLongestClicks/unsquashedClicks on a rolling 13-month window at the URL, subdomain, and root-domain level; a refresh cadence slower than that window lets decayed click history persist uncorrected for a full scoring cycle.
+- **PrimarySourceUrl:** https://ipullrank.com/google-algo-leak
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** navboost, 13-month-window, refresh-cadence, click-history
+
+### content-decay-hcu-baseline
+- **Title:** Post-HCU decay is the norm, not the exception -- run a standing decay-detection pass on every site
+- **Workflows:** content-decay
+- **Tactic:** Treat decay detection as a standing, recurring audit line item for every content-first site rather than a one-off diagnostic run only when traffic visibly craters; the base rate of decay is high enough that absence of a detection pass is itself a risk.
+- **Invariant:** A study of 522 content-first sites post-Helpful Content Update found 64% lost organic traffic, with a median loss of -471K visits (-17.8%) among the sites that declined, per Detailed's Q3 analysis (Glen Allsopp).
+- **PrimarySourceUrl:** https://detailed.com/q3/
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** hcu, decay-baseline, 64-percent, detailed-q3
+
+### goodclicks-badclicks-early-warning
+- **Title:** Audit good/bad-click proxies as a leading indicator of decay before rank drops
+- **Workflows:** content-decay
+- **Tactic:** Pull bounce-back behavior and dwell/engagement proxies for at-risk pages as a leading-indicator audit line item; a rising badClicks-to-goodClicks proxy ratio is a decay early warning worth flagging before the page's rank actually falls.
+- **Invariant:** The leak documents goodClicks and badClicks as tracked NavBoost inputs distinguishing navDemotion (on-site UX causes) from serpDemotion (SERP-behavior causes); a shift in that ratio precedes and helps cause the rank movement decay is ultimately measured by.
+- **PrimarySourceUrl:** https://ipullrank.com/google-algo-leak
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** goodclicks, badclicks, early-warning, navdemotion
+
+### refresh-cadence-monitoring
+- **Title:** Re-measure decaying pages on a recurring cadence, not a one-shot report
+- **Workflows:** content-decay
+- **Tactic:** Build decay monitoring as a recurring, read-only re-measurement pass over previously-flagged pages rather than a single diagnostic snapshot; re-check decay status on each cadence run so a page's trajectory (worsening, stabilizing, recovering) is visible over time.
+- **Invariant:** Both the 64%-decayed HCU baseline and the underlying NavBoost rolling-window mechanism argue that decay is an ongoing, shifting condition rather than a fixed state -- a single audit snapshot cannot capture trajectory, only recurring monitoring can.
+- **PrimarySourceUrl:** https://detailed.com/q3/
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** refresh-cadence, monitoring, recurring-audit, trajectory
+
+### content-refresh-genuine-effort
+- **Title:** Refresh decaying pages with genuine substantiation, not scaled regeneration
+- **Workflows:** content-decay
+- **Tactic:** When recommending a refresh for a decaying page, recommend adding genuine original substantiation (new data, analysis, first-hand detail) rather than a scaled/templated rewrite pass; a low-effort regeneration risks tripping the same low-effort signal that contributes to decay in the first place.
+- **Invariant:** Mike King's technical analysis of the leak documents contentEffort as an LLM-based effort-estimation signal Google runs on article pages; refreshing a decaying page with low-effort scaled output risks reinforcing, not reversing, the mechanical signal associated with decline.
+- **PrimarySourceUrl:** https://ipullrank.com/google-algo-leak
+- **PolicyClass:** auto-safe
+- **EvidenceGrade:** single-source
+- **Keywords:** content-refresh, genuine-effort, contenteffort, scaled-regeneration
+
+### large-scale-rewrite-consolidation-approval
+- **Title:** Mass rewrite or consolidation of decayed pages changes the live site -- requires human sign-off
+- **Workflows:** content-decay
+- **Tactic:** When decay analysis surfaces a large batch of decayed pages warranting mass rewrite or consolidation/merging into fewer stronger URLs, propose the plan as a report but do not execute the rewrite, redirect, or merge without explicit human approval, since it is a structural change to the live site.
+- **Invariant:** The 522-site/64%-decayed HCU baseline shows decay clusters at scale across many pages at once; executing a large-scale rewrite or consolidation response to that scale of finding involves redirects and content replacement that a human must own the execution decision for, mirroring the internal-linking workflow's authority-consolidation-merge boundary.
+- **PrimarySourceUrl:** https://detailed.com/q3/
+- **PolicyClass:** human-approve
+- **EvidenceGrade:** single-source
+- **Keywords:** large-scale-rewrite, consolidation, human-approve, live-site-change