Validation

Tooling Direction

The canonical product tooling path is the Go foundry CLI. Current Node validators and foundry-doctor.js remain compatibility backstops for legacy scripts and CI comparison, but the release-facing doctor, build, release-check, and validator lanes are Go-owned.

See CLI Reference for every command, flag group, safety mode, task report chain, and Node maintenance equivalent.

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 build --json
go run ./cmd/foundry build --site /absolute/path/to/site --json
go run ./cmd/foundry release-check --json
go run ./cmd/foundry release-check --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 theme-tokens --json
go run ./cmd/foundry inspect crawler-policy --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 authoring-contract --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 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/ --write --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 crawler-policy
go run ./cmd/foundry validate crawler-policy --json
go run ./cmd/foundry validate discoverability --rendered-root public
go run ./cmd/foundry validate discoverability --rendered-root public --strict --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
go run ./cmd/foundry validate tasks
go run ./cmd/foundry validate tasks --json
go run ./cmd/foundry validate block-contracts
go run ./cmd/foundry validate block-governance
go run ./cmd/foundry validate content-kits
go run ./cmd/foundry validate creative-lane
go run ./cmd/foundry validate compatibility-fixtures
go run ./cmd/foundry validate feature-flags
go run ./cmd/foundry validate shell
go run ./cmd/foundry validate section-families
go run ./cmd/foundry task improve-page --dry-run --site fixtures/compatibility/utility-service-theme-proof --path content/_index.md --json
go run ./cmd/foundry task validate-improve-page-report --report <saved-improve-page-report.json> --json

Critical Verification Path

The Go CLI owns the public human/JSON surface for Core validation, inspection, page generation, scaffold preflight, report contracts, and narrow add-only task apply behavior:

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 build --json
go run ./cmd/foundry release-check --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 authoring-contract --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 crawler-policy
go run ./cmd/foundry validate motion
go run ./cmd/foundry validate quality
go run ./cmd/foundry validate scaffolds
go run ./cmd/foundry validate tasks
go run ./cmd/foundry validate block-contracts
go run ./cmd/foundry validate block-governance
go run ./cmd/foundry validate content-kits
go run ./cmd/foundry validate creative-lane
go run ./cmd/foundry validate compatibility-fixtures
go run ./cmd/foundry validate feature-flags
go run ./cmd/foundry validate shell
go run ./cmd/foundry validate section-families

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 crawler-policy is the Go-native crawler-purpose and robots-policy gate. It checks the versioned schema and registry, required profiles and vendor tokens, crawler purpose and robots applicability, official source URLs, review dates, profile references, user-fetch safety boundaries, and the shared robots renderer/docs source contract.

foundry validate discoverability is the rendered-page discovery and agent-readiness contract. It checks canonical and index controls, JSON-LD validity and agreement with visible content, internal-link targets, visible review/freshness evidence, accessible link/button names, and form names and labels. Its stable JSON includes page-level facts and source-locatable finding codes. Warnings remain advisory by default and become errors with --strict. The compatibility fixture harness runs it after every rendered quality gate.

foundry authoring-contract derives and validates the portable V1 block, typed-field, blueprint, global, site-identity, and preview-mapping report. It is read-only. Go tests protect the public JSON shape and golden fixture; release validation also generates a contract from the Core checkout so template, manifest, schema, and CLI integration cannot drift independently.

Every typed field must include a generated, section-scoped preview selector. The focused authoring-contract tests also scan each golden block renderer and fail when an advertised field has no matching data-foundry-field-path anchor. See Portable Authoring Contract.

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.

foundry validate tasks is the Go-native task/report contract gate. It checks data/foundry/task-contract-manifest.json for required safety modes, current implemented task kinds, source files, write policies, idempotency expectations, and forbidden overwrite/delete/provider/sync behavior. Run it whenever task docs, task manifests, import/apply behavior, or improve-page report fields change.

foundry validate block-contracts, block-governance, content-kits, creative-lane, compatibility-fixtures, feature-flags, shell, and section-families are also Go-native release gates. compatibility-fixtures materializes representative downstream sites, runs site doctor checks, renders the fixture HTML, applies rendered quality and discoverability gates, and can run browser smoke with --browser-smoke.

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

foundry build and foundry release-check are doctor-backed golden-path wrappers that reuse the same stable JSON shape. foundry build is the common Core/site readiness lane. foundry release-check defaults to strict Hugo warning handling and enables site drift audits when a site is provided.

The Node aggregate remains a compatibility backstop for the legacy script surface:

node scripts/foundry-doctor.js

The Go doctor/release-check path is canonical for release decisions. The legacy Node aggregate still runs the older script 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
• validate-improve-page-report-contract.js

foundry validate quality is the Go CLI surface for the first enforceable framework-level quality gate. The compatibility fixture harness renders the committed fixture set 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

The Go compatibility fixture harness uses Safari WebDriver on macOS plus a lightweight mock Pagefind index to check the highest-risk interactive fixture flows. If Safari WebDriver is unavailable, the lane reports a non-failing skip unless --require-browser is provided.

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

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 fixture:

• current-site-baseline
• older-site-baseline
• search-heavy-site
• article-heavy-site
• property-retreat-site
• creative-route-floor-site
• cinematic-campaign-theme-proof
• utility-service-theme-proof
• form-heavy-theme-proof
• managed-form-availability-proof
• quiet-editorial-theme-proof
• immersive-product-story-theme-proof
• gallery-property-destination-theme-proof

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, reference-theme proof surfaces, 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

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

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 crawler-policy
• Run go run ./cmd/foundry validate motion
• Run go run ./cmd/foundry validate quality
• Run go run ./cmd/foundry validate discoverability --rendered-root <public> after producing a rendered tree; compatibility fixtures cover this for Core
• Run go run ./cmd/foundry validate scaffolds
• Run go run ./cmd/foundry validate tasks when task/report contracts or docs changed
• Run go run ./cmd/foundry validate block-contracts
• Run go run ./cmd/foundry validate block-governance
• Run go run ./cmd/foundry validate content-kits
• Run go run ./cmd/foundry validate compatibility-fixtures
• Run go run ./cmd/foundry validate feature-flags
• Run go run ./cmd/foundry validate shell
• Run go run ./cmd/foundry validate section-families
• 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 typed editor fields or preview anchors changed, run go run ./cmd/foundry authoring-contract --site . --core-version dev --site-key foundry-core-dev --commit-sha dev --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

Task Or Report Contract Change

• Run go run ./cmd/foundry validate tasks
• Run go run ./cmd/foundry validate tasks --json when the JSON summary is part of the review evidence
• Run the affected foundry task ... --dry-run --json command against a compatibility fixture when the change affects report output
• For improve-page, run go run ./cmd/foundry task improve-page --dry-run --site fixtures/compatibility/utility-service-theme-proof --path content/_index.md --json
• For saved improve-page payload compatibility, run go run ./cmd/foundry task validate-improve-page-report --report <saved-improve-page-report.json> --json
• Confirm Core still refuses approval persistence, final copy generation, provider fetches, hidden service state, overwrite, delete, sync, rollback, and managed publish behavior

Motion, Parallax, Or Authored-Feel Change

• Run core doctor
• Run go run ./cmd/foundry validate motion
• 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 crawler-policy
go run ./cmd/foundry authoring-contract --site . --core-version ci --site-key foundry-core-ci --commit-sha ci
go run ./cmd/foundry validate motion
go run ./cmd/foundry validate quality
go run ./cmd/foundry validate scaffolds
go run ./cmd/foundry validate tasks
go run ./cmd/foundry validate block-contracts
go run ./cmd/foundry validate block-governance
go run ./cmd/foundry validate content-kits
go run ./cmd/foundry validate creative-lane
go run ./cmd/foundry validate compatibility-fixtures
go run ./cmd/foundry validate feature-flags
go run ./cmd/foundry validate shell
go run ./cmd/foundry validate section-families

The compatibility-fixture command in this CI sequence performs the rendered discoverability audit for every fixture after Hugo builds it.

• Ubuntu core validation and legacy backstop:

go run ./cmd/foundry doctor --json
go run ./cmd/foundry release-check --json
node scripts/foundry-doctor.js

• macOS browser parity:

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

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