How this rule is fixed

Pilot deterministic fixer: repo_overlay · harness mode repo_overlay · verify expect_rule_clean.

• Harness: fixture includes a repo overlay tree; remediate_repo_overlay() writes catalog/repo files, then applies After HTML when present.
• Production: repo_overlay Node adapter patches the website repository (contracts, registry JSON, CSS, Python stubs).

Detection module: docs/design/ux-audit/deterministic-design-rules.md#det-contract-placeholders. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink design contracts (docs/design/catalog/**/{HASH}-*.md) are the implementation spec for registry-backed visuals. When a contract still reads like a copied template—lorem ipsum, [placeholder], example-visual, XYZ headings, or stub bullets (- TBD, - TODO, - FIXME)—implementers and agents must guess anatomy, responsive rules, and verification gates. That produces drift between showcase HTML, consumer sites, and audit evidence.

This deterministic rule repo-scans every registry row with contract_status: own or family-covered (skipping contract-template.md). It reuses analyzeContractPlaceholders from tools/design-catalog/lib/contract-placeholders.mjs:

• Always errors (any mode): lorem ipsum, example-visual, # XYZ template headings, [placeholder], and <insert markers.
• Stub bullets: TBD / TODO / FIXME list items are warnings by default; they become errors when strictContractPlaceholders is enabled (--strict-contract-placeholders on check-visual-catalog.mjs or ctx.strictContractPlaceholders in UX audits).

Findings cap at 12 per pass (MAX_CONTRACT_PLACEHOLDER_FINDINGS); run the catalog linter locally for the full list.

Plan: After allocating a hash or importing a contract from contract-template.md, list every section still marked stub. Do: Replace stubs with element-specific Expected look, Anatomy, States, and Deterministic checks tied to real selectors. Check: node tools/design-catalog/check-visual-catalog.mjs --strict-contract-placeholders reports zero placeholder errors. Adjust: If the same stub repeats across a family, move shared prose into the family contract and delete child-level TBD bullets.

Passing signals

• Contract Markdown has no lorem ipsum, example-visual, # XYZ … heading, [placeholder], or <insert … template markers.
• No - TBD, - TODO, or - FIXME stub bullets remain when strict placeholder mode is on (CI / remediation loops should enable strict before claiming catalog readiness).
• Expected look and Anatomy name concrete KS surfaces—.ks-doc-breadcrumb, forge-card breathe-link, main#main + hash="Idx"—so HTML builders do not invent Bootstrap stand-ins.
• scanContractPlaceholders / metrics.contractPlaceholderReport returns zero issues for the repo (or only non-strict warnings you have explicitly accepted with a remediation plan).
• Changelog entries document when stub contracts were replaced with authored guidance (for example Kbc on 2026-05-18).

Failing signals

• Placeholder markers (always): placeholder language (lorem ipsum), template marker (example-visual), template heading still uses XYZ, or explicit placeholder insert marker on a registry-linked contract path.
• Stub bullets (strict): contract still uses stub bullets (TBD, TODO, …) when strict: true; auditor message Design contract still uses unresolved stub bullets: ….
• Severity: minor for placeholder markers and stub bullets in default UX audit mode; stub bullets surface as warn when mapped from catalog warnings in some pipelines.
• Evidence: hash=Kbc contract=docs/design/catalog/chrome/Kbc-doc-breadcrumb.md (or comma-separated hashes when one file backs multiple registry rows).
• Truncation: Additional contract placeholder issues omitted (N more) when the repo has more than 12 failures—remediation points to --verbose-contract-placeholders.
• Skipped scan: skipped: true, reason: 'no-registry' when visual-registry.generated.json is missing—fix inventory generation before trusting placeholder cleanliness.

Before example

After example

Evidence and remediation

Commands (repo root):

node tools/design-catalog/check-visual-catalog.mjs --repo . --strict-contract-placeholders
node tools/design-catalog/inventory-ks-visuals.mjs

After contract edits that change expected HTML, run python3 generator/build-showcase.py and re-check showcase inventory markers (DET.HASH.MARKERS). Pair with DET.CATALOG.CONTRACT_SPECIFICITY when stubs were removed but sections still read generic.

Related rules

• DET.CONTRACT.PATH — registry-linked contracts must resolve to on-disk .md files.
• DET.CATALOG.CONTRACT_SPECIFICITY — contracts need element-specific Expected look, Anatomy, Forbidden patterns, and Deterministic checks—not boilerplate slabs.
• DET.HASH.MARKERS — built HTML must emit hash / data-ks-hash (and related data-ks-*) on visual roots.
• AI.CONTRACT.IMPLEMENTATION_USEFULNESS — AI review for whether a non-stub contract is actually implementable end-to-end.