entity-seo.md:148 says "sameAs pointing to dead profiles — validate each URL
resolves", and STEP 7 asks "does the target resolve and match?". Nothing
implemented it: zero curl against a sameAs anywhere in the repo. A dead
sameAs is worse than a missing one — it asserts an identity link that fails
on follow, in the exact graph AI engines walk to confirm who you are.
The naive version of this check is a false-positive generator, which is
presumably why it stayed unimplemented. Verified live rather than assumed:
999 linkedin.com/company/anthropic <- blocks non-browsers
200 wikidata.org/wiki/Q108162414
200 x.com/anthropicai
404 <known-dead URL> <- correctly detected
So the check classifies by code, not by liveness guess: 404/410 = dead
(finding with direction), 401/403/429/999 = bot-blocked (inconclusive, NO
finding, never "dead"), 000/5xx = inconclusive. No G2/G6 item may remove a
sameAs on anything but 404/410 — same shape as the NAP direction rule: an
unreliable signal read confidently is worse than no signal.
Note: the spec draft asserted "X/Twitter and Instagram commonly 403" from
plausibility. The live test returned 200 for x.com and contradicted it —
corrected to classify by observed code, never by platform folklore. Third
unverified-plausible claim caught this session (I1, I6, here); the pattern
is exactly what these fixes exist to stop.
Verified: pipeline exercised end-to-end against real endpoints; make test
35 GREEN / 0 RED.
Audited each statistic in agents/resources/ against primary sources after
the VSI fiction (I2) showed WebSearch launders SEO-blog consensus.
The failure mode is not invention — it is plausible recombination, which is
what a model half-remembering a search result produces:
- "Adding statistics increases AI visibility by up to 40% (Aggarwal et al.)"
— paper real (KDD 2024), number real, SCOPE WRONG: 40% is the aggregate
over the whole method set, domain-dependent. No per-technique figure
exists.
- "Pages not updated quarterly are 3x more likely to lose AI citations
(LLMRefs)" — LLMrefs' actual 3x says brand mentions correlate ~3x more
strongly with AI visibility than backlinks. DIFFERENT SUBJECT. No source
supports a quarterly decay multiplier.
- "QAPage cited 58% more often than Article" — uncited. Nearest real number:
AccuraCast 2025, `Person` schema at 58.9% PREVALENCE among cited sources —
wrong type, and its FAQPage figure (1.8%) points the opposite way to the
claim it propped up. This one drove Tier 1 ranking.
- "62% of searches involve voice" — uncited; 62% circulates as smart-speaker
ADOPTION. Same family as the "50% by 2020" myth ComScore denied (origin: a
2014 Andrew Ng interview).
Corrected my own framing too: I claimed three times these stats "drive axis
weights". They do not — the weight tables carry no citations. They drive
Tier/priority recommendations and, worse, geo-analyzer's "Cite sources" rule
pushed them into CLIENT reports as research-backed.
Fixes: recommendations kept on mechanism, fabricated numbers removed with
the incident documented inline so they are not re-added. Unverified stats
(48% AI Overviews, 2.5B queries/day, Gartner -25%) labelled [UNVERIFIED]
rather than asserted or deleted — I did not check them.
Structural, not just exhortation: resources/README.md now mandates
`<claim> — <source, year, venue|vendor> — measured: <what the source ACTUALLY
measured> — <link>`. `measured:` is the field that catches this — all four
errors survive a source name; none survives stating the real measurement
next to the claim. WebSearch demoted from verification to crawler/tool-name
lookup only.
Verified: make test 35 GREEN / 0 RED.
Headers were scored three ways: seo-analyzer priced them into the Technical
axis at both depths (:619 FULL, :635 LOCAL), depth-matrix.md:29 said drop
them, and /harden re-audits them 0-100 against three external validators.
The dedup rule and the agent spec contradicted each other; the agent won by
default, so the same finding moved two scores in two reports.
Arbitrated (user): /harden keeps them, /seo drops them. That confirms the
rule that already existed — seo-analyzer was the violator.
Constraint: /harden REUSES seo-analyzer, so the capability cannot be
deleted, only scoped. Reading is not scoring:
- Technical axis definitions no longer name security headers.
- STEP 4 still curls them — needed for X-Robots-Tag, canonical/redirect
coherence, and the §14 observed-list — but they earn no points under /seo.
- Dispatched from /harden: unchanged, headers ARE the job (verified: its
scope spec untouched, 16 header references intact).
Carve-out: X-Robots-Tag stays in /seo under indexability. It is an indexing
directive wearing a header's clothes — `noindex` there deindexes as surely
as a meta robots tag. That is what depth-matrix.md:29 means by "unless it
directly affects indexability"; the security headers do not.
Drop is not silence: mandatory §14 line on FULL naming what was observed
live plus a "run /harden <url>" pointer. A user who never runs /harden must
not read a clean Technical score as clean headers — same principle as the
mandatory COVERAGE line (I5).
Verified: make test 35 GREEN / 0 RED.
Both agents sample (seo-analyzer.md:403 "sample 5-15 key pages",
geo-analyzer.md:460 "Sample 5-10 key pages") and neither states it. The
report says "audit". On a 500-page site a 12-page sample is 2.4%, and the
reader cannot know that unless it is printed. /client-handover gates on
these scores.
The denominator was already within reach: STEP 4 fetches sitemap.xml. Count
its URLs and the coverage ratio is free — same data C1 will use for
sitemap-driven crawl later.
- Mandatory COVERAGE line in both scoring blocks: N of M sitemap URLs (P%),
or "total UNKNOWN" when no sitemap. Never omitted, never rounded up.
- seo: <25% coverage repeats in §0 as a major alert. Sample by risk (one
page per template + GSC position 4-10 quick wins), name skipped templates
— an un-sampled template is an un-audited template.
- geo: scoped honestly rather than blanket — COVERAGE bounds the per-page
axes (Content Shape, page-level Schema.org) but NOT the site-wide ones
(AI Crawlers Policy, llms.txt are single files, fully read). One ratio
should not discredit axes it does not govern.
Verified: make test 35 GREEN / 0 RED.
seo-analyzer.md:278 listed "VSI (Visual Stability Index) — new 2026 signal,
Google Core Web Vitals 2.0" as a threshold, stated as fact, no hedge, in
client-facing audits. It does not exist.
Verified against two primary sources:
- developer.chrome.com/docs/crux/api — complete metric list carries no
visual_stability_index. Blogs claimed "Google is actively collecting VSI
through CrUX": flatly false.
- web.dev/articles/vitals — three stable CWV (LCP, INP, CLS). No VSI, no
"Core Web Vitals 2.0". Thresholds change with prior notice on an annual
cadence.
Ten SEO blogs cross-cited each other into an apparent consensus. WebSearch
returns that consensus, which is why the resources README rule "agents MUST
cross-check via WebSearch on FULL" did not catch it — that mitigation
launders blog misinformation into apparent verification.
Fix removes the metric and states the sourcing rule where a future rumour
would land: primary sources only (web.dev / Chromium blog / CrUX API list,
the last being decisive — a metric CrUX cannot return is one we cannot
score). Incident documented inline so it is not re-added.
Verified: make test 35 GREEN / 0 RED.
Surfaced by pointing /harden at zenquality.fr from the claude-config CWD.
A1 — no CWD/target coherence guard (systemic: /seo, /geo, /harden all
lack it; grep confirms). A URL is supplied, the agent greps whatever CWD
it landed in, nobody checks they are the same site. Demonstrated live:
from claude-config, /harden would curl zenquality.fr while grepping
claude-config, then score "Config hardening" on a codebase that is not the
site. The live half looks right, the code half is fiction, and the report
reads as authoritative.
Fixed in both agents' STEP 2 rather than the 3 dispatchers: the agent does
the grepping, so the guard binds whoever calls — same principle as I3.
/harden inherits it free.
A2 — seo-analyzer had zero origin-vs-edge awareness while geo-analyzer
has the full CDN/WAF-override check (geo-analyzer.md:246-261). seo-analyzer
does the infra detection AND is reused by /harden for its whole
config-hardening axis (20/100). On zenquality — Apache origin behind a
Scaleway nginx front — repo .htaccess + `server: nginx` invites the wrong
call "nginx serves this, .htaccess is dead". I made that exact inference
myself before reading the file. Rule added at STEP 2 infra detection:
`server:` names the edge, not the origin; live-but-not-in-repo = "set
upstream", never "missing".
Verified: live probe of zenquality.fr (read-only, nothing written to the
client repo); make test 35 GREEN / 0 RED.
Axis was defined "backlinks, mentions, authority" (10% local / 15%
national of the FULL score) but only mentions have a data source
(STEP 6 web_search "<name>" -site:<domain>). Backlinks and authority
have no index, no API — the agent had to invent 2/3 of the number, and
that number reaches a client via /client-handover.
- Axis label names what is measured + points at §14.
- Off-page axis note: score mentions ONLY; never price in unmeasured
sub-components; a low mention count is NOT evidence of a weak backlink
profile. Mandatory verbatim §14 line naming the gap + the nearest free
source (Common Crawl) so the omission is legible, not silent.
- LOCAL N/A label: was `N/A — requires FULL audit`, a promise FULL cannot
keep for backlinks. Now states FULL covers brand mentions only.
Weights deliberately unchanged: re-deriving now and again when a backlink
source lands would churn historical scores twice. Revisit when the axis
widens back (Common Crawl, phase 5).
Note: initial plan was to mark the axis N/A in FULL and redistribute the
weight. Reading the real spec (seo-analyzer.md:622 + STEP 6) showed that
over-corrects — it discards the mentions data, which IS gathered. Narrowed
the definition instead; composes with the Common Crawl work later.
Verified: make test 35 GREEN / 0 RED.
geo-analyzer owns JSON-LD NAP (ownership matrix, seo/SKILL.md:261) and can
rewrite it via G2 — AUTO tier, no confirmation (geo-analyzer.md:660). The
LRN-032 protection lived ONLY in the /seo dispatcher prompt
(seo/SKILL.md:339-343), so standalone /geo reconciled NAP with no canonical
and no anti-seed guard — the exact zenquality trap, writing into client
structured data.
Root cause: a safety invariant that depended on the caller. Fixed at the
layer that owns the data.
- Data integrity: NAP direction rule, caller-independent, binds G2/G6.
Covers CREATE (LocalBusiness from scratch) not just rewrite — geo builds
missing schemas, seo-analyzer's wording only covered rewrite.
- STEP 6 checklist: pointer at the line that triggers the action.
Absent canonical is already the safe default (no directional fix), so no
NAP collection step is needed in /geo — that would duplicate seo/SKILL.md
STEP 0 and risk drift.
Verified: make test 25+5+5 GREEN / 0 RED (incl. G3 strict-YAML frontmatter).
STEP 1-8 preserved byte-for-byte; STEP 9-16 replaced by a doc-gen orchestration
that resolves all interaction (questions, NAP, precheck, overwrite, client-name),
assembles the PACKAGE, and dispatches handover-doc-writer. Dropped the inert
model: opus pin (inherits the big session model via inline-load).
code-cleaner is now a pure fix executor (was audit+gate+execute). Reroute the two
read-only-audit consumers (onboard STEP 6, tour Phase B) to a big-model agent
(general-purpose/analyzer) — an audit must stay on the big model, never the sonnet
executor. Refactor now runs on sonnet inside the executor (inline-load pin was inert).
Reroute hotfix's deeper-bug escalation to the /bugfix skill (bugfixer is now a
pure executor, not loadable standalone). loops-light locks repointed to the
bugfix orchestrator + bugfixer-executor shape.
- STEP 0 collects user-confirmed CANONICAL NAP (LRN-032 zenquality:
duplicated-seed trap — source majority is not truth)
- Both dispatch prompts carry the canonical NAP + no-majority rule;
seo-analyzer spec forbids directional NAP fix without confirmation
- STEP 2 now emits .claude/audits/HUMAN-ACTIONS.md (checklist from §11)
and NAP-KIT.md (local business) in BOTH modes — audit-only runs leave
the user immediately actionable; /client-handover §4 consumes NAP-KIT
commit-changer committed code autonomously with no branch precondition
(gitflow-conformity §2a, verified MEDIUM CONFIRMED) — on develop/main it
attempted a direct code commit, backstopped only by the pre-commit hook.
Adds Phase 0: the same `gitflow-aiguillage.md` mechanism hotfixer/bugfixer/
feater already use (TYPE=chore) — branches to chore/* on a protected base,
no-op on a working branch — plus a report-only fallback (no develop / no
lib -> ask human, don't auto-branch). Commit-plan gate + scoped staging
untouched. SKILL.md pre-flight notes the aiguillage.
Dry-run (throwaway repos, REAL lib + REAL pre-commit hook) — both paths:
CASE 1 on develop: aiguillage -> chore/commit-pending, code commit
SUCCEEDS, hook never blocks; contrast: same commit direct on develop
is BLOCKED -> aiguillage is what avoids it. PASS
CASE 2 no develop: fallback -> no auto-branch, changes uncommitted,
no chore/* created, ask human. PASS
STEP 5 previously ran `git push origin "$CURRENT_BRANCH"` autonomously
after the fix loops (gitflow-conformity §2b, verified HIGH). Now:
- gitflow precondition: no develop / no lib -> skip commit+push, note in
summary (report-only fallback).
- push gated behind an explicit-GO AskUserQuestion (A push / B defer)
BEFORE the push; red-flag STOP on push without GO / finish / merge.
Core untouched: SEO/GEO/HARDEN/VALIDATE loops, scoring, doc + PDF branding.
Dry-run (throwaway repos) — both sides of each fallback:
CASE 1 report-only (no develop): DEVELOP_OK=no -> NO commit/push. PASS
CASE 2 gate answer A: -> RUN git push origin feature/handover. PASS
CASE 3 gate answer B: -> SKIP, push deferred; HEAD unchanged. PASS
RC fix (soak day 1): `make update` step 7.5 failed on a 300s clone timeout
of alchaincyf/find-skills. The skill (search the skills.sh registry from
Claude) was never used; the discovery case stays reachable manually via
`npx -y skills find <query>`. Removed from install-plugins.sh (install list
+ summary + comment), update-all.sh (refresh list), link.sh
(NPX_EXTERNAL_SKILLS), lib/toggle-external.sh (MANAGED_TOOLS + case arms),
plugin-advisor.md, .gitignore; local skills/find-skills symlink deleted.
Memory-registry and test-fixture mentions kept — append-only history.
toggle-external `list` verified post-removal; suites 8/8.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
geo-analyzer asserted 'PERMISSIVE default per user CLAUDE.md' in 2 sites (L224,
L867-869) but CLAUDE.md carries no PERMISSIVE/RESTRICTIVE crawler policy. Reframed
as the agent's own policy grounded in GEO's purpose (an AI-visibility audit defaults
to allowing AI crawlers); default unchanged. Completes job3 C6/C7/C8 scrub (which
missed geo) — job9's later rewrite also left it. User-approved wording. Review A5.
Both line-3 descriptions contained an unquoted ': ' (and '|') that fails
python3 yaml.safe_load ('mapping values are not allowed here'). seo-analyzer's
line was last rewritten by job9/a5a7b54 AFTER job2's F7 strict-YAML rule
(git blame); security-auditor's dates to job6. Single-quote wrap, no internal
apostrophes. Gate: yaml.safe_load over ALL agents/*.md now clean. Review A4.
Completes job9/5a3de92 (which only cleaned commit-changer). These 3 execution
agents still emitted the banned trailer into their commit-message templates;
the settings.attribution backstop does not filter agent-authored message bodies.
Extended sweep of agents/ lib/ hooks/ templates/ for Co-Authored-By|Claude-Session|
--trailer now returns zero. Review finding A1 (BLOQUANT), J4-16 follow-up.
- README + plugins.lock.json graphifyy note: pipx/PyPI install only, never
npm/npx — a different publisher (rhanka/graphify) squats the same
'graphifyy' name on npm as a version-shadowing shim with its own
conflicting 'graphify' bin (F-X1).
- agents/security-auditor.md: one-line caveat that p/* semgrep packs are
fetched from the registry at runtime — the CLI version pin does not
freeze ruleset content, so a new BLOCK can appear on unchanged code.
MCP magic (F-X3): version pin declined by user call (stays @latest in
lib/toggle-external.sh). ${VAR} env expansion confirmed unsupported at
~/.claude.json user scope (Claude Code docs — expansion is .mcp.json
project-scope only), so the BDR-026 reference-not-plaintext pattern
doesn't transfer here; existing mitigations (canonical ~/.claude/.env,
gitignore, audit env-field filtering) remain the practical ceiling.
~/.claude.json regenerated out-of-repo via toggle-external.sh disable+
enable magic to pick up the already-rotated MAGIC_API_KEY (no repo diff,
no commit for that file — traced in the job6 final report).
Upgrade confirmed format-incompatible before use (job6 gate, BATCH-2):
gsd-pi 3.0.0 no longer writes .gsd/ROADMAP.md (verified by generating a
real test milestone in a scratch project) — state moved to .gsd/STATE.md,
.gsd/gsd.db (authoritative DB), and one .gsd/milestones/<ID>/<ID>-ROADMAP.md
per milestone, all in a different markdown shape. Every grep/awk in
status-reporter.md PHASE 3 would silently print 0/blank against the old
path instead of erroring.
Rewired PHASE 3 to read `gsd headless query` (stable JSON snapshot, no LLM
call) instead of scraping markdown — smoke-tested against both the absent
case (this repo, no .gsd/) and a real gsd-managed scratch project.
plugins.lock.json pin bumped deliberately to 3.0.0 (update-all.sh honors
the pin; this is the required manual bump).
Complementary to frontend-design (kept: build-time aesthetic direction).
impeccable adds what the chain lacked: 45 deterministic anti-slop rules
(npx impeccable detect, exit 0/2, --json) — the design counterpart of the
semgrep gate — plus 23 design verbs under one /impeccable skill and
persistent per-project design context.
- plugins.lock.json: CLI pinned 3.2.0 (rules update = audit output change
on unchanged code, LRN-077 class); skill dist = its own release track
- install-plugins.sh Step 8d: staged npx install (tmpdir) -> moved to
skills-external/impeccable (machine-owned, gitignored, ctx7 pattern);
never writes through the ~/.claude/skills symlink into the tracked tree
- update-all.sh: pin-honored refresh, Node<24 or failure -> dist kept
- Node >= 24 required (host at 22): steps skip gracefully, activation
deferred to a deliberate Node bump
- link.sh EXTERNAL_SKILLS, profiles (design/web/web-full/full),
plugin-advisor, CLAUDE.md design routing, design-gate, README, CHANGELOG
- NOT in design GATE-BLOCK yet: promotion after first dogfood
lib/verify-secure-loop.md: shared main-loop include. GATE 1 fresh verifier
(blind, contract from disk) → CONFORME straight to GATE 2, ECARTS loop max
3; GATE 2 fresh security-auditor (MODE gate) → PASS to commit, BLOCK loop
max 3 with re-verify-request-FIRST order invariant. Mute agent never a PASS.
feater.md: STEP 0.7 CONTRACT (proportional, silent on a clear feature) +
STEP 3 VERIFY+SECURE via the include. Nominal = one verifier + one security
dispatch; the loop only costs when it loops.
bugfixer.md: STEP 3.5 CONTRACT fed by the DIAGNOSIS (bug report verbatim +
reproduced-then-gone + regression test criteria) + STEP 5 fresh gates via
the include. Renumbered STEP 5 sub-steps (gates before the commit gate).
hotfixer.md: STEP 1.7 CONTRACT (silent autofill, zero questions) + STEP 3
security gate whose FAILURE REVERTS (git restore to pre-flight SHA + escalate
to /bugfix), never loops — the 1-attempt model preserved. No fresh verifier
at hotfix weight (the smoke-check verifies the trivial contract). Adds the
Agent tool to hotfixer.md + hotfix/SKILL.md for the security dispatch.
lib/tests/loops-light.test.sh: 27 structure locks green, shellcheck clean.
Behavioral pipeline dogfood on a fixture (feat adding a feature WITH a SQLi):
GATE1 CONFORME (feature present, SQLi not a conformity gap — orthogonal
gates) → GATE2 BLOCK(1) (checklist caught the %-interp SQLi semgrep's taint
rules missed) → [fix to parameterized] → re-verify CONFORME (order invariant,
feature intact) → re-scan PASS. Loop converges to green.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
agents/security-auditor.md: fresh read-only-on-code SAST gate. Pinned
rulesets p/security-audit + p/secrets + p/owasp-top-ten (owasp REQUIRED —
measured: the 2-ruleset baseline misses SQLi + path-traversal entirely on
realistic Flask code), never --config auto, never auto login (BDR-048).
Severity map: secrets ERROR → CRITICAL, other ERROR → HIGH (block),
WARNING/INFO → reported. gate mode (diff, no Write) vs audit mode (Write
only to REPORT, rule-locked). DEGRADED (semgrep absent) still runs the
checklist and still blocks — never a vacuous pass (LRN-048). Anti-gaming:
a new un-gated nosemgrep suppression is BLOCKING. PROOF mandatory, mute
auditor never a PASS, blind (no iteration history), blocks HIGH/CRITICAL
only (LRN-047).
Grafts: onboard STEP 6 L3a dispatches it in audit mode (report
.onboard-audit/semgrep.md) in BOTH gstack branches — complement to cso
(cso is a gstack submodule, unmodifiable); synthesis picks it up via the
existing .onboard-audit/ sweep. audit-delta security axis runs the SAST
pass first, folds findings into the existing gate/fix/re-verify flow.
lib/tests/security-auditor.test.sh: 28 structure locks green, shellcheck
clean. Behavioral dogfood (fresh agents on a planted fixture):
BLOCK(9) on the vuln commit (2 secrets→CRITICAL, semgrep+checklist
complementarity — checklist caught the 6 semgrep missed off-context);
BLOCK(1) on a new nosemgrep suppression (understood semgrep's 0 was the
mask); DEGRADED → BLOCK(7) on grep-detectable secrets with semgrep hidden.
FP measured on real repos (faunosteo, game): owasp adds only hygiene
findings, contained by diff-scoping.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
lib/contract-interview.md: mandatory upstream passage for all orchestrators.
Verbatim REQUEST (immutable), proportional questions (complete request =
zero, max 3 one batch), testable criteria + file scope, written to disk
immediately (.claude/tasks/contracts/<date>-<slug>-<HHMM>.md — a context-only
contract dies at compaction). Lifecycle: enrichment only at human gates
([gated] marker, scope micro-gate), supersedes for re-scope, aborted runs
deleted or committed status:aborted — never left dirty. Hand-off = path,
not restatement.
agents/verifier.md: fresh read-only verifier. Reads the contract from disk,
renders VERIFY — VERDICT: CONFORME | ECARTS(n) | ERROR. Blind: never
receives iteration history. PROOF line mandatory (LRN-048), UNVERIFIABLE
never MET, mute verifier never a PASS (retry once fresh, 2nd structural
failure = human escalation). Orchestrator protocol documented in-file
(max 3 iterations, re-verify request before security).
lib/tests/contract-verifier.test.sh: 31 deterministic structure locks on
the load-bearing doctrine clauses — green, shellcheck clean.
Behavioral dogfood (2 fresh subagents on a planted fixture): gap case →
ECARTS(2) exactly as planted (NOT-MET located + out-of-scope flagged);
conform case with injected fake iteration history → CONFORME, noise
ignored, real python spot-check as evidence. Both outputs parse-clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XpphkdTosUzokBDNG7PToS
Bastien Chanot