feat(telemetry-sweep): F-013 — per-skill references via PR #6 mechanism

[MountainUnicorn]

Summary

Closes Swarm F's M3-deferred per-skill telemetry reference sweep (F-013) using Path A — the references: frontmatter mechanism that PR #6 unblocked when it merged at 3522a8f on 2026-04-26.

Every core/skills/*/SKILL.md now declares rules/telemetry.md in its references: array. The contract documented in core/rules/telemetry.md is now discoverable from any individual SKILL.md, and a coverage test gates against future skills shipping without the reference.

• 17 skills got a fresh references: ["rules/telemetry.md"] entry (agents-md, away, back, brand, changelog, implementer, init, learnings, milestone, optimize, plan, promote, reviewer, roadmap, spec, test-writer, version)
• 10 skills had rules/telemetry.md appended to existing references lists (cycle, verify, deploy, docs, retro, tdd-cycle, infographic, dashboard, brand-update, ux) — preserving existing entries and order
• This is the deferred sweep from Swarm F (v0.9.0 telemetry-jsonl PR) that was held back during M3 because every Wave-2/Wave-3 swarm was modifying SKILL.md files; with M3 merged, the file-set is quiet.

No body changes. No behavior changes. No schema additions. plugins/add/ regenerated via scripts/compile.py. dist/codex/ skill output is unchanged because Codex projection strips both allowed-tools and references: — same behavior the codex adapter already had.

Path A confirmed (PR #6 mechanism)

Path B (body-prose @reference line) was the documented fallback. We're past that gate — Path A is live.

AC Checklist

• AC-001a — Every core/skills/*/SKILL.md declares rules/telemetry.md in references: (Path A)
• AC-002a — scripts/validate-frontmatter.py accepts the key (PR perf: Refactor rules and knowledge for on-demand loading and context window reduction #6 schema)
• AC-003a — references: is a list; existing entries preserved; ordering preserved
• AC-010 — All 27 skills carry the declaration
• AC-011 — No implicit-emission shortcut: every skill is explicit (sub-agent skills reviewer/test-writer/implementer/verify each carry their own reference)
• AC-012 — Spec § 7 audit checklist enumerates all 27 skills with status
• AC-013 — No skips; all swept
• AC-015 — No skill behavior change (single-line frontmatter edit per file)
• AC-020 — Coverage test exists at tests/telemetry-sweep/test-skill-reference-coverage.sh
• AC-021 — Test fails when a skill ships without the reference (RED bar verified pre-sweep)
• AC-022 — Test runs in <2s (pure bash + python YAML parse)
• AC-023 — python3 scripts/compile.py --check clean
• AC-024 — python3 scripts/validate-frontmatter.py clean

Test plan

• bash tests/telemetry-sweep/test-skill-reference-coverage.sh — 31 pass, 0 fail (4 fixture self-tests + 27 skill assertions)
• python3 scripts/validate-frontmatter.py — all frontmatter valid
• python3 scripts/compile.py --check — compile output matches committed artifacts
• bash tests/hooks/test-filter-learnings.sh — 4 passed
• bash tests/test-deletion-guardrail/test-test-deletion-guardrail.sh — 16 passed
• bash tests/codex-install/test-install-paths.sh — 7 passed
• bash tests/cache-discipline/test-cache-discipline.sh — 7 passed
• bash tests/secrets-handling/test-secrets-handling.sh — 12 passed
• bash tests/agents-md-sync/test-agents-md-sync.sh — 8 passed
• bash tests/telemetry-jsonl/test-telemetry-jsonl.sh — 12 passed
• bash tests/security/test-prompt-injection-defense.sh — 11 passed
• bash tests/rule-parity/test-rule-parity.sh — 5 passed

Commits

1. test(telemetry-sweep): coverage fixture for per-skill references — RED bar with self-testing fixtures
2. feat(skills): F-013 — declare references: rules/telemetry.md across all 27 skills — GREEN sweep + regenerated plugins/add/
3. docs(spec): telemetry-skill-reference-sweep audit checklist filled — § 7 audit + CHANGELOG [Unreleased]

Closes F-013 from plugin-family-release-hardening review.

🤖 Generated with Claude Code