Validation

Tooling Direction

The canonical product tooling path is the Go foundry CLI. Current Node validators and foundry-doctor.js remain reference/fallback behavior until the equivalent Go commands reach parity.

Current Go CLI surfaces:

go run ./cmd/foundry doctor
go run ./cmd/foundry doctor --json
go run ./cmd/foundry doctor --site /absolute/path/to/site --json
go run ./cmd/foundry inspect --json
go run ./cmd/foundry inspect blocks --json
go run ./cmd/foundry inspect blueprints --json
go run ./cmd/foundry inspect scaffolds --json
go run ./cmd/foundry inspect discovery --json
go run ./cmd/foundry inspect motion --json
go run ./cmd/foundry inspect --site /absolute/path/to/site --json
go run ./cmd/foundry inspect --site /absolute/path/to/site /route/ --json
go run ./cmd/foundry new-page --brief /absolute/path/to/brief.md --site /absolute/path/to/site --dry-run --json
go run ./cmd/foundry new-page --blueprint creative-work-detail --prompt --dry-run --json
go run ./cmd/foundry new-page --blueprint creative-work-detail --slug sample-work --title "Sample Work" --description "Project summary" --work-intro "Opening text" --artist-name "Artist" --primary-cta-url /contact/ --dry-run --json
go run ./cmd/foundry new-page --blueprint creative-work-detail --site /absolute/path/to/site --slug sample-work --title "Sample Work" --description "Project summary" --work-intro "Opening text" --artist-name "Artist" --primary-cta-url /contact/ --json
go run ./cmd/foundry scaffold creative-route-floor --site /absolute/path/to/site --artist-name "Creative Studio" --artist-role "Photographer" --primary-email hello@example.com --dry-run --json
go run ./cmd/foundry scaffold local-service-route-floor --site /absolute/path/to/site --business-name "Local Business" --service-name "Primary Service" --city-name "Sample City" --region-name "Region" --primary-phone "(555) 555-0100" --dry-run --json
go run ./cmd/foundry validate runtime
go run ./cmd/foundry validate runtime --json
go run ./cmd/foundry validate motion
go run ./cmd/foundry validate motion --json
go run ./cmd/foundry validate quality
go run ./cmd/foundry validate quality --json
go run ./cmd/foundry validate scaffolds
go run ./cmd/foundry validate scaffolds --json

Critical Verification Path

Phase 4 now has Go doctor slices for core and site mode plus a framework inventory inspect slice. These commands own the public human/JSON surface while using Node reference validators for checks that have not yet reached native Go parity:

go run ./cmd/foundry doctor
go run ./cmd/foundry doctor --json
go run ./cmd/foundry doctor --site /absolute/path/to/site --json
go run ./cmd/foundry inspect --json
go run ./cmd/foundry inspect scaffolds --json
go run ./cmd/foundry inspect --site /absolute/path/to/site --json
go run ./cmd/foundry new-page --brief /absolute/path/to/brief.md --site /absolute/path/to/site --dry-run --json
go run ./cmd/foundry new-page --blueprint creative-work-detail --prompt --dry-run --json
go run ./cmd/foundry new-page --blueprint creative-work-detail --slug sample-work --title "Sample Work" --description "Project summary" --work-intro "Opening text" --artist-name "Artist" --primary-cta-url /contact/ --dry-run --json
go run ./cmd/foundry scaffold creative-route-floor --site /absolute/path/to/site --artist-name "Creative Studio" --artist-role "Photographer" --primary-email hello@example.com --dry-run --json
go run ./cmd/foundry scaffold local-service-route-floor --site /absolute/path/to/site --business-name "Local Business" --service-name "Primary Service" --city-name "Sample City" --region-name "Region" --primary-phone "(555) 555-0100" --dry-run --json
go run ./cmd/foundry validate runtime
go run ./cmd/foundry validate motion
go run ./cmd/foundry validate quality
go run ./cmd/foundry validate scaffolds

Use --dry-run --json for preflight and diagnostics. foundry new-page accepts direct fields, --brief <path> using Markdown/YAML/JSON input, or --prompt/--interactive for missing required fields. Prompt mode defaults to dry-run; add --write --site <path> when prompted values should create files. Write mode creates the rendered page under --site, refuses existing files by default, and only overwrites when --force is provided.

foundry scaffold creative-route-floor preflights all seven Creative v1 route pages before writing any files, so an existing route-floor file fails the whole scaffold unless --force is provided.

foundry scaffold local-service-route-floor preflights all nine Local Service v1 route pages before writing any files, so an existing route-floor file fails the whole scaffold unless --force is provided.

foundry validate scaffolds is the Go-native scaffold/page contract gate. It checks content kit starter renders, page type and composition references, allowed/required block compatibility, blueprint output templates and paths, and the Creative and Local Service route-floor dry-run smoke paths.

foundry validate motion is the Go-native Motion Kit contract gate. It checks the motion manifest header, required profiles/capabilities/display patterns, normalized authoring fields, safety rules, source-file hooks, reduced-motion support, and block/profile/capability references. It also enforces the governed Motion Kit budgets: profile limit keys, capability allowances against those limits, parallax and pinned-parallax speed ranges, required safety-rule contracts, and primitive normalized-field ownership.

foundry validate quality is the Go-native quality-gates contract. It checks the same first enforceable a11y, SEO, and performance floor as the Node reference validator: shared template image attributes, button types, SEO/head hook presence, fixture viewport/main landmark coverage, image decoding, and image loading/fetchpriority hints. With --rendered-root, it also validates an already-rendered HTML tree for content-page head/landmark contracts, rendered image/button attributes, and unresolved template markers. The compatibility fixture harness runs that rendered mode after each Hugo fixture build.

The Go doctor supports:

• core validation summary
• site bootstrap checks
• site block usage validation
• allowlist-aware drift audits
• Hugo render smoke
• --include-drift-audits
• --skip-core
• --skip-hugo
• --strict-warnings
• --browser-smoke
• --require-browser

The Node aggregate remains the reference implementation for browser smoke while the Go command owns the product CLI surface and delegates that lane:

node scripts/foundry-doctor.js

That runs the core validation stack:

• validate-block-contract.js
• validate-block-governance.js
• validate-content-kits.js
• validate-creative-lane.js
• validate-quality-gates.js
• validate-compatibility-fixtures.js
• validate-section-family-manifest.js
• validate-motion-manifest.js
• validate-feature-flags.js
• validate-shell-contract.js
• validate-runtime-contracts.js

foundry validate quality is the Go CLI surface for the first enforceable framework-level quality gate. validate-quality-gates.js remains the Node source-template reference behavior. The compatibility fixture harness renders the six baseline sites and calls foundry validate quality --rendered-root so generated HTML keeps the same objective accessibility, SEO, performance, and anti-template-leak floor. See Quality Gates.

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

go run ./cmd/foundry doctor --browser-smoke --json
node scripts/foundry-doctor.js --browser-smoke

The Go command delegates the browser lane to the Node reference fixture validator. That validator uses Safari WebDriver on macOS plus a lightweight mock Pagefind index to check the highest-risk interactive fixture flows.

The generated Creative route-floor fixture also uses this browser lane as a visual/computed-style gate. It checks all seven Creative routes at desktop and mobile viewports for page preset/profile tokens, motion-profile durations, shell/search/accessibility fallback styling, hero CTA/media rhythm, chapter navigation presence, story-reel presence, route-floor token surfaces (page-list, timeline, contact-split, rich-text, cta, and table-of-contents), Creative block preset surfaces, non-empty journal feed content, work-detail caption/credit surfaces, and horizontal overflow.

The Go scaffold/page validator also checks Creative content-model contracts: work metadata, journal-entry metadata, exhibition event metadata, fixture content, and profile/inquiry data. Use this when page manifests, blueprints, content kits, or Creative starter templates change:

go run ./cmd/foundry validate scaffolds

foundry inspect scaffolds --json is the matching discovery surface. The Creative scaffold profile exposes content_models with generation policy, required fields, recommended fields, recommended nested media/credit/event structures, and explicit foundry new-page commands for detail pages. The scaffold/page validator validates those discovered contracts against registered manifests, starter templates, generated new-page renders, and governed fixture content so discovery cannot drift ahead of implementation.

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

go run ./cmd/foundry doctor --browser-smoke --require-browser --json
node scripts/foundry-doctor.js --browser-smoke --require-browser

The compatibility fixture step materializes 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
• generated Creative route-floor 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 generated Creative route-floor fixture also asserts on the scaffolded source files so normalized Motion Kit fields and route-floor content contracts stay present before Hugo rendering, then uses the browser lane to catch visual drift that string assertions cannot see, including token-scoped panel, list, timeline, contact, rich-text, CTA, and chapter-navigation surfaces. It also asserts the Creative-safe preset names used by the route floor so starter source cannot silently drift back to generic neutral variants. The Creative fixture includes governed sample content for journal entries, work metadata, media captions/credits, exhibition metadata, and profile/inquiry data so source and render assertions prove the content model, not just route shells.

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:

go run ./cmd/foundry doctor --site /absolute/path/to/site --json
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:

go run ./cmd/foundry doctor \
  --site /absolute/path/to/site \
  --include-drift-audits \
  --json

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.

For planning cycles that affect productization, discovery, or proof-site upstreaming, also confirm the decision path in Foundry Productization Plan and the ownership model in Builder Guidance And Discovery.

Any Core Contract Change

• Run go run ./cmd/foundry inspect --json
• Run go run ./cmd/foundry validate runtime
• Run go run ./cmd/foundry validate motion
• Run go run ./cmd/foundry validate quality
• Run go run ./cmd/foundry validate scaffolds
• Run node scripts/validate-quality-gates.js
• 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
• Run go run ./cmd/foundry inspect blocks --json
• 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 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
• Run go run ./cmd/foundry validate scaffolds
• Run go run ./cmd/foundry inspect scaffolds --json
• Run go run ./cmd/foundry inspect blueprints --json when the change affects blueprint inventory
• Run go run ./cmd/foundry inspect --site /absolute/path/to/site --json when the change affects downstream page ownership, routes, or block usage
• Render or scaffold at least one affected starter path
• Run doctor against a consuming site if the change is already adopted downstream

Motion, Parallax, Or Authored-Feel Change

• Run core doctor
• Run go run ./cmd/foundry validate motion
• Run node scripts/validate-motion-manifest.js
• Run go run ./cmd/foundry inspect motion --json
• Confirm field names are documented in data/foundry/block-options.yaml and block docs
• Confirm any display-pattern change has canonical blocks, supported capabilities, reduced-motion behavior, an ownership boundary, and anti-drift notes in data/foundry/motion-manifest.json
• Confirm reduced-motion behavior is preserved
• Review Foundry Motion Kit Plan for profile, parallax, and blueprint expectations
• Run doctor against a representative consumer when the change affects service, Creative, or property storytelling surfaces
• Use --include-drift-audits for downstream review when copied local motion runtime, block shadows, or framework shadows are suspected; use --strict-warnings once a migration path has been reviewed

CI Safety Bar

GitHub Actions now runs three validation jobs:

• Go contract validator matrix on Ubuntu, macOS, and Windows:

go test ./...
go run ./cmd/foundry validate runtime
go run ./cmd/foundry validate motion
go run ./cmd/foundry validate quality
go run ./cmd/foundry validate scaffolds

• Ubuntu Node reference core validation:

node scripts/foundry-doctor.js

• macOS browser parity:

go run ./cmd/foundry doctor --browser-smoke --require-browser --json
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