Omd:Add Reference skill

omd:add-reference — Core v2 catalog cutover gate

Status: CORE_V2_CATALOG_WRITE_BLOCKED.

Scope, narrowed by owner decision 2026-09-16. This gate blocks writes that create a new legacy reference or a new Core catalog package. It does not block refreshing evidence on an existing reference — verification_v2, .verification.md, tokens.components state values, ## Proof — because that produces no Core package and adds no migration debt; the file stays legacy and stays in the same queue. Creating a reference, adding a brand, restoring a legacy YAML marker, emitting retired section output, placeholder sentinels, or hand-editing generated counts and mirrors all remain refused. Full rationale and the two expiry conditions: .claude/skills/omd-add-reference/SKILL.md.

This repository still reads the 440 historical reference files through the legacy frontmatter adapter. That makes them valid migration inputs, but it does not authorize a new legacy writer. Do not create, update, backfill, or sync a web/references/<id>/DESIGN.md from this skill.

When invoked:

1. Inspect only. Do not write a reference, token block, generated catalog, or public count.
2. Explain that project/user-facing DESIGN.md is already single-write Core v2, while reference authoring is paused until the catalog has a graph-backed metadata/evidence package and Core projection compiler.
3. If research is still useful, save nothing to the catalog. Return a concise proposed source list and the intended reference id in chat only.
4. Resume writes only after all of these exist and pass together:
   • Core v2 reference metadata/evidence sidecar schema;
   • registry, quality, AST, token, and verification readers for that schema;
   • deterministic graph → portable DESIGN.md projection;
   • legacy dual-read and Core single-write tests;
   • migration report with dropped_segments=0 and unknown facts absent.

Never work around this gate by restoring a legacy YAML marker, numbered 13/15/16 sections, placeholder sentinels, or a second authoritative Markdown dialect.

Write path: DESIGN.md v3 (2026-10-14)

The catalog is DESIGN.md v3 (spec/design-md-v3.md): every web/references/<id>/ holds a Google-frontmatter DESIGN.md and a reference.json sidecar. Any write this gate permits (an evidence refresh on an existing reference) goes through one path: read readReferenceSource(dir).markdown (the legacy-shaped source), edit it, and write it with scripts/design-md-v3/writer.mjs writeReference(dir, text), which converts, checks spec §10 conformance with 0 Google lint errors, and writes the file, the sidecar and the design-md/ mirror. web/scripts/assemble-reference.mjs emits v3 the same way. The OmD 0.1 text-patching tools (apply-state-values, apply-measured-palette, apply-primary-tasks, migrate-frontmatters, retire-template-motion) refuse v3 files until they are ported. Creating a new reference stays refused until the owner lifts this gate.