Validation

Critical Verification Path

Phase 4 defines one default safety path for this repo:

node scripts/foundry-doctor.js

That runs the core validation stack:

• validate-block-contract.js
• validate-block-governance.js
• validate-content-kits.js
• validate-compatibility-fixtures.js
• validate-feature-flags.js
• validate-shell-contract.js
• validate-runtime-contracts.js

For a local browser pass over the compatibility fixtures, run:

node scripts/foundry-doctor.js --browser-smoke

That delegates to validate-compatibility-fixtures.js --browser-smoke, which uses Safari WebDriver on macOS plus a lightweight mock Pagefind index to check the highest-risk interactive fixture flows.

When the browser environment must be present rather than skipped, require it explicitly:

node scripts/foundry-doctor.js --browser-smoke --require-browser

The compatibility fixture step materializes five representative downstream consumers inside /tmp, runs Foundry Doctor in site mode against each one, and then performs rendered-output assertions against the built HTML for each baseline:

• current-site baseline
• older-site baseline
• search-heavy site
• article-heavy site
• property-retreat site

Those assertions deliberately check for shared runtime markers such as shell chrome, search UI mounts, language alternates, article-shell markup, property-media tab/lightbox scaffolding, and the absence of templating leaks like ZgotmplZ.

The browser lane requires:

• macOS with Safari available
• Enable Remote Automation turned on in Safari’s Develop menu, or safaridriver --enable run once by the local user
• a local environment allowed to talk to localhost, since Safari WebDriver and the fixture file server both run locally

When a change also affects a consuming site, run doctor against that site too:

node scripts/foundry-doctor.js --site /absolute/path/to/site

That adds:

• site block-usage validation
• go.mod bootstrap check for a valid local site bootstrap mode:
  • locked-materialized site mode via ./.foundry/modules/...
  • live sibling-repo framework-dev mode
• hugo --renderToMemory smoke build

For proof consumers or sites with reviewed local framework shadows, include the drift audits:

node scripts/foundry-doctor.js \
  --site /absolute/path/to/site \
  --include-drift-audits

If the site already has allowlists in .planning/, doctor picks them up automatically. Use --strict-warnings when Hugo warnings should fail the run.

Regression Review Checklist

Use this checklist before treating framework work as complete.

Any Core Contract Change

• Run node scripts/foundry-doctor.js
• Confirm the changed docs still describe the current contract surface
• If manifests or starter templates changed, confirm content-kit render smoke is still green

Block, Template, Or Schema Change

• Run core doctor
• If the change adds, removes, renames, or reclassifies a block, confirm the family assignment and any justified proof-gap entries in data/foundry/block-family-manifest.json and data/foundry/block-governance.json
• Run doctor against at least one representative consuming site
• Confirm field names match across:
  • block template expectations
  • schema/docs
  • starter content-kit templates

Flow System, Theme Interaction, Or CSS Token Change

• Run core doctor
• Run doctor against a Shield-based consumer site
• Review [SITE-BOOTSTRAP.md](https://github.com/jerrybroughton/likestyle-foundry-core/blob/v0.1.20/docs/</Users/gb/Library/Mobile Documents/comappleCloudDocs/Documents/CodexProjects/likestyle-foundry-core/docs/SITE-BOOTSTRAP.md>) rules for:
  • dark-section text contrast
  • alternating-row overrides
  • CSS load order
  • stats counter constraints

Shell Contract Or Shared Chrome Change

• Run core doctor
• Run doctor with --include-drift-audits against the proof consumer or any downstream repo with reviewed shell overrides
• Confirm allowlists still match reality before accepting new shadows

Pack, Page Type, Composition, Content Kit, Or Scaffold Change

• Run core doctor
• Render or scaffold at least one affected starter path
• Run doctor against a consuming site if the change is already adopted downstream

CI Safety Bar

GitHub Actions now runs two validation jobs:

• Ubuntu core validation:

node scripts/foundry-doctor.js

• macOS browser parity:

node scripts/foundry-doctor.js --browser-smoke --require-browser

That keeps the local safety path and the CI gate aligned while making browser availability a real requirement in the macOS lane instead of a skip.

Because doctor now renders real Hugo fixture sites and the browser lane uses Safari WebDriver, CI also needs:

• Go 1.22 or later for Hugo module resolution
• Hugo Extended 0.160.1 or later
• a macOS runner with Safari available
• safaridriver --enable before the browser parity step