docs(skills): SHAPE-GOTCHAS §7 signal_type + build-* deep-link cross-cutting anchors

[bokelley]

Summary

Two follow-ups from PR #1515 expert review.

1. SHAPE-GOTCHAS §7 — signal_type decision table (skills/SHAPE-GOTCHAS.md)

dx-expert and docs-expert both flagged that the signal_type: 'custom' clarification appeared twice in build-signals-agent/SKILL.md (~30 lines apart) and was a known footgun better captured as a SHAPE-GOTCHAS entry than skill-prose repetition. Added entry §7 with a decision table covering the three enum values (marketplace / owned / custom per schemas/cache/3.0.5/enums/signal-catalog-type.json), spec definitions, and the most common adopter mistake: first-party data agents (Kroger 84.51°, Walmart Connect, publisher behavioral data) mis-classifying their segments as custom when they have a standing data asset behind them. The test is provenance, not lifecycle — if you can point at a customer table / pixel / panel, it's owned. custom is reserved for per-call agent-native segments without standing provenance.

Replaced both inline clarifications in signals SKILL with pointers to §7.

2. Build- skills deep-link cross-cutting.md anchors* (8 skills)

docs-expert deferred from #1515: build-* skills had bare [../cross-cutting.md](../cross-cutting.md) references with no per-rule deep-links, so adopters fetching the file pulled the whole 73-line file even when only one rule was relevant. Each build-*-agent skill's "Cross-cutting rules" section now lists the high-traffic rules for that skill domain with anchor deep-links to the specific cross-cutting.md rule. Adopters land on a 5-line block instead of the full file.

Per-skill deep-link tables:

Skill	Top deep-links
seller	idempotency_key, resolve-then-authorize, authentication, account-resolution, webhooks
creative	idempotency_key, authentication, webhooks
signals	idempotency_key, authentication, resolve-then-authorize, webhooks
governance	idempotency_key, resolve-then-authorize, account-resolution
brand-rights	idempotency_key, authentication, webhooks
generative-seller	idempotency_key, webhooks
retail-media	idempotency_key, webhooks
si	idempotency_key, authentication, ctx_metadata
holdco	account-resolution, resolve-then-authorize, ctx_metadata

Bare cross-cutting.md link kept as the "read it once cold" pointer.

Test plan

• npm run compliance:fork-matrix — 23/23 in ~13s
• npm run typecheck clean
• npm run format:check clean

🤖 Generated with Claude Code

[bokelley]

Expert review summary (one round, two reviewers)

Verdict: ship. No convergent blockers, no concerns.

• code-reviewer: all clean. SHAPE-GOTCHAS §7 anchor matches GFM slug, schema citation resolves, all 9 build-* SKILL deep-link anchors round-trip against the canonical Quick-reference table at the top of cross-cutting.md. Optional follow-up: cross-cutting.md and §7 cite schemas/cache/3.0.5/... while the repo pinned 3.0.6 today (chore(deps): bump AdCP to 3.0.6 + close end-to-end gaps for guaranteed worked example #1510); pre-existing inconsistency, not introduced.
• docs-expert: both deferred items fixed. SHAPE-GOTCHAS §7 stands alone. Voice consistent across the 9 skills. Persona-rule fit sensible (seller surfaces account-resolution + webhooks, SI surfaces ctx_metadata, holdco surfaces resolve-then-authorize + ctx_metadata, etc.). One single-reviewer wording polish addressed in commit 23f8b06c: dropped seller skill's unique trailing "Read the file once cold..." line for symmetry.

Final state

• fork-matrix: 23/23 in ~13s
• typecheck + format clean
• Single-reviewer 3.0.5 → 3.0.6 citation drift left as separate follow-up (pre-existing, would touch cross-cutting.md too)

[bokelley]

Acknowledged — two-reviewer pass clean, no blockers. 3.0.5 → 3.0.6 citation drift noted as pre-existing; separate follow-up tracks it. Ready for merge when you are.

---

Generated by Claude Code

[bokelley]

Noted — standing by for human merge approval.

---

Generated by Claude Code