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-inventory-crosswalk. Scroll down for Before / After examples and Evidence and remediation steps.

Purpose

Kitchen Sink builds a showcase tree (showcase/*.html, showcase/assets/*.js) that demonstrates every governed visual surface. Those files emit hash="XYZ" and data-ks-hash="XYZ" markers on catalog roots. DET.INVENTORY.CROSSWALK is a repo-wide deterministic check (metrics phase) that crosswalks all showcase-emitted hashes against docs/design/catalog/visual-registry.generated.json and flags stray tokens whose values are not exactly three ASCII letters.

Primary evidence lives in docs/design/catalog/visual-inventory.generated.json → catalogCrosswalk, refreshed by node tools/design-catalog/inventory-ks-visuals.mjs --repo . --out docs/design/catalog/visual-inventory.generated.json. The check module design-rules/deterministic/generated/det-inventory-crosswalk.check.js reads that block (or rescans showcase/ when the block is absent) and surfaces findings capped at MAX_INVENTORY_CROSSWALK_FINDINGS (12) per audit pass.

Plan: Register a surface in visual-registry.yaml before adding its hash to showcase output. Do: Run python3 generator/build-showcase.py after component changes; regenerate inventory JSON so catalogCrosswalk.showcase_hashes_not_in_registry stays empty. Check: node tools/design-catalog/check-visual-catalog.mjs --repo . --refresh-inventory and analyze-website-ux.mjs metrics for inventoryCrosswalkReport. Adjust: Register missing hashes, remove experimental markers, or fix invalid token shapes before chasing per-page DET.HASH.REGISTRY_ROW failures on consumer sites.

Unlike per-page rules, this rule evaluates the entire showcase inventory, not a single crawled URL. Passing DET.HASH.MARKERS on one page does not guarantee the repo crosswalk is clean if another showcase file still emits an unregistered hash.

Passing signals

• visual-inventory.generated.json includes a catalogCrosswalk block without error, listing showcase_dir (typically showcase) and an empty showcase_hashes_not_in_registry array.
• Every hash collected from showcase HTML/JS by collectEmittedHashes() exists in visual-registry.generated.json with a valid three-letter token (for example Hbk, Ksr, Ksf, Vln, Ldg on preview pages).
• collectShowcaseStrayTokens() returns empty hash and dataKsHash arrays — no values like ABCD, 12, or placeholder slugs on hash= / data-ks-hash= attributes.
• Showcase JS under showcase/assets/ uses the same three-letter convention in hash:"XYZ" and "data-ks-hash":"XYZ" literals when present.
• buildInventoryCrosswalkReport(repoRoot) returns { skipped: false, issues: [] }.
• After python3 generator/build-showcase.py, preview shells such as showcase/preview-handbook.html and showcase/preview-landing.html emit only registry-known layout and chrome hashes.
• Consumer submodule sites inherit a showcase tree whose crosswalk was verified at KS source — drift appears when local edits add markers without updating the registry.

Failing signals

• unregistered-emitted (warn): Showcase HTML emits hash="Zzz" / data-ks-hash="Zzz" but Zzz has no row in visual-registry.generated.json — common after a prototype component ships before allocate-visual-hash.mjs / registry YAML update.
• stray-token (minor): Invalid marker shape in showcase — for example hash="ABCD" (four letters), hash="12", or data-ks-hash="todo" — detected by collectShowcaseStrayTokens().
• crosswalk-missing (minor): visual-inventory.generated.json exists but lacks catalogCrosswalk; regenerate inventory before interpreting crosswalk results.
• crosswalk-error (minor): catalogCrosswalk.error is set — inventory generation failed; fix upstream catalog tooling first.
• inventory-parse-error / no-inventory: Missing or unreadable inventory JSON — run inventory-ks-visuals.mjs from repo root.
• Findings truncate at 12 issues with a trailing "additional inventory crosswalk issues omitted" message when many showcase files drift at once.
• Passing DET.HASH.REGISTRY_ROW on a single built page does not clear this rule if another showcase file still emits an orphan hash.

Before example

After example

Evidence and remediation

Workflow (PDCA):

1. Plan — When adding a visual root to components/ or showcase previews, allocate or reuse a registry hash first (allocate-visual-hash.mjs / edit visual-registry.yaml).
2. Do — Emit markers via ks_hash_attrs(), layout_shell_attrs(), or chrome_region_attrs() in Python generators; rebuild showcase with python3 generator/build-showcase.py.
3. Check — Refresh inventory JSON and run the UX auditor on the KS repo (metrics phase reads inventoryCrosswalkReport). Confirm showcase_hashes_not_in_registry is empty and no stray tokens appear in showcase/.
4. Adjust — Register orphan hashes, delete experimental markers, or normalize invalid token shapes; regenerate inventory before consumer submodule bumps.

Harness verification: python3 generator/build_rule_defect_fixtures.py (overlay with unregistered Zzz), then auditor-tests/invoke-det-ruleset-harness.sh --only-rule DET.INVENTORY.CROSSWALK.

Related rules

• DET.HASH.MARKERS — per-page marker pairing and three-letter shape on crawled HTML.
• DET.HASH.REGISTRY_ROW — per-page registry membership and data-ks-type alignment.
• DET.CONTRACT.PATH — registered hashes must reference on-disk design contract files where required.
• DET.DIAGRAM.ASSET_REGISTRY — diagram SVG assets referenced by registry rows exist on disk.
• DET.PY.KS_HASH_ATTRS — Python generators must use ks_hash_attrs() instead of manual hash literals.