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

Purpose

Kitchen Sink ties every active visual-registry row to a design contract — a Markdown file under docs/design/catalog/**/{HASH}-*.md that records anatomy, states, accessibility, forbidden patterns, and screenshot acceptance. When contract_status is own or family-covered, the registry must list a non-empty contract / contract_path that resolves to a real file in the repo. Without that link, showcase HTML can still render with correct hash / data-ks-hash markers while implementers and auditors have no authoritative spec.

This deterministic rule scans docs/design/catalog/visual-registry.generated.json during the metrics phase (scanContractPaths). It flags empty-path (required status but no path) and missing-file (path set but file absent). Rows with other statuses (for example not-applicable) are out of scope when policy does not require a contract file.

Plan: After adding or renaming a hash, allocate or update the registry row and contract file together. Do: Set contract: to the canonical path (for example docs/design/catalog/layouts/Hbk-layout-handbook.md) and commit the Markdown contract in the same change. Check: node tools/design-catalog/check-visual-catalog.mjs --repo . and confirm contractPathReport.issues is empty. Adjust: Either restore the contract file, fix the registry path, or change contract_status with a justified family rule when a separate contract is not required.

Passing signals

• Every active registry entry with contract_status: own has contract (or contract_path) set to an existing file such as docs/design/catalog/layouts/Hbk-layout-handbook.md.
• Family-covered rows reference the family contract on disk (for example a shared Ksc style-family contract) — path is non-empty and fs.existsSync succeeds from repo root.
• contractPathFromRegistryEntry returns the same path the catalog linter and check-visual-catalog.mjs use (entry.contract ?? entry.contract_path).
• scanContractPaths returns { skipped: false, issues: [] } after regenerating the registry JSON from visual-registry.yaml.
• Showcase and consumer builds emit layout chrome (Hbk, Ksr, Ksf, Kbc) that matches the contract named in the registry row for that hash.
• contract_status: not-applicable rows are not required to carry a contract path unless policy changes — no false positives for intentionally uncovered primitives.

Failing signals

• empty-path: status: active and contract_status: own (or family-covered) but contract is null, "", or whitespace — message cites contract_status and hash.
• missing-file: Registry lists docs/design/catalog/layouts/Hbk-layout-handbook-OLD.md (or a typo directory) after a rename; HTML and hashes unchanged but the contract file was deleted or never added.
• Contract moved under docs/design/catalog/chrome/ without updating visual-registry.yaml / regenerating JSON.
• New hash allocated in Python (layout_shell_attrs, chrome_region_attrs) while the registry row still has contract_status: own and an empty contract field.
• Auditor caps at MAX_CONTRACT_PATH_FINDINGS (12) per pass with a trailing “additional issues omitted” finding when many rows break at once.
• contractPathReport.skipped: true with reason: no-registry — fix registry generation before interpreting pass/fail on consumer sites.

Before example

After example

Evidence and remediation

Evidence: Metrics phase stores contractPathReport with rowCount, issues[] (kind: empty-path | missing-file, hash, contractStatus, optional contract rel path). Findings use area visual-catalog, severity minor, and evidence such as hash=Hbk contract_status=own contract=docs/design/catalog/layouts/Hbk-layout-handbook-OLD.md. Attach the registry row snippet from visual-registry.yaml and git status showing whether the contract file exists.

Remediate (in order):

1. Restore or create the contract — add docs/design/catalog/**/{HASH}-*.md with identity, anatomy, and verification sections; match the hash slug convention used elsewhere in the catalog.
2. Fix the registry path — set contract: (and regenerate visual-registry.generated.json) to the real file; run node tools/design-catalog/check-visual-catalog.mjs --repo . --registry docs/design/catalog/visual-registry.yaml --showcase showcase.
3. Empty path — if the row should not own a contract, set contract_status to not-applicable only with a documented family rule; do not leave own with a blank contract.
4. Family-covered — point at the family contract file that explicitly covers child hashes (AI.CONTRACT.FAMILY_COVERAGE_JUSTIFIED when variance is high).
5. Re-audit — run analyze-website-ux.mjs on the KS repo or consumer site; confirm no DET.CONTRACT.PATH findings before relying on AI.CONTRACT.IMPLEMENTATION_USEFULNESS or DET.CATALOG.CONTRACT_SPECIFICITY.

Related rules

• DET.CONTRACT.PLACEHOLDERS — contract body must not leave unresolved TBD / TODO / FIXME in strict mode.
• DET.CATALOG.CONTRACT_SPECIFICITY — contract content must be element-specific, not generic boilerplate.
• DET.HASH.REGISTRY_ROW — emitted hashes must exist in the registry with expected type.
• DET.HASH.MARKERS — visual roots carry hash and data-ks-hash; orthogonal to path resolution.
• DET.INVENTORY.CROSSWALK — showcase-emitted hashes ⊆ registry inventory.
• DET.SCREENSHOT.STATUS — when screenshot_status: captured, PNG paths must exist (separate catalog gate).
• AI.CONTRACT.IMPLEMENTATION_USEFULNESS — judges whether an on-disk contract is actionable for implementers.
• AI.CONTRACT.FAMILY_COVERAGE_JUSTIFIED — family contracts must truly cover child surfaces.