Tooling language ADR

Status: accepted and completed by the Core v1.0.1 Go/Hugo-only boundary Date: 2026-04-30 Scope: Foundry-maintained validators, doctor commands, release tooling, and future CLI

Decision

Foundry’s canonical product tooling path is the Go foundry CLI. Core contains no executable Node validators, package manifests, package-manager locks, Node workflow setup, or Node-backed migration, upgrade, browser, documentation, or release lane. Historical receipts may name the measurement tool that produced them; that does not make the tool a current Core dependency.

Python remains acceptable for distribution and release orchestration while those workflows are still evolving, but Python should not become the long-term canonical language for Core validation logic.

Rationale

Foundry is a Hugo framework. Hugo is written in Go, Hugo modules are part of the runtime model, and Foundry’s users run one portable tool without installing or debugging a package-manager runtime.

The product direction is:

• one cross-platform foundry CLI
• a portable binary for Linux, macOS, and Windows
• validators that understand Foundry’s Hugo/module shape
• consistent output for humans, CI, and AI agents
• fewer platform surprises around symlinks, shell behavior, child process spawning, and runtime installation

Language Policy

Cross-Platform Requirements

All canonical Foundry tools must run on:

• Linux
• macOS
• Windows

Rules:

• no required symlinks
• no required Bash-only behavior
• no required PowerShell-only behavior
• no hardcoded /tmp, /Users/..., or Windows drive paths
• use repo-relative or config-driven paths
• prefer language-native filesystem and process APIs
• use explicit path handling that supports spaces and Windows separators
• produce deterministic output suitable for CI and AI agents
• expose direct commands for each validator, not only an aggregate doctor command

Migration Strategy

The migration is complete. The Go foundry CLI owns the public product surface, focused validators, routine checks, release checks, browser fixture lane, source migration, and upgrade rehearsal. foundry validate tooling prevents the retired package-tooling layer from returning.

Pilot candidates and status:

• validate-runtime-contracts: implemented as Go validator
• validate-motion-manifest: implemented as Go validator
• scaffold/page contract validation: implemented as Go validator
• validate-quality-gates: implemented as Go validator
• validate-block-contract: implemented as Go validator
• block governance, content kits, Creative Lane, compatibility fixtures, feature flags, shell contracts, section families, site blocks, site shadows, and shell overrides: implemented as Go validators
• compatibility fixture browser smoke: implemented in Go with optional Safari WebDriver execution and non-failing skip when the browser is unavailable

Avoid starting with the most complex discovery/site migration work. First prove the validator shape.

Tool Fitness Gate

Before a tool is migrated, rewritten, promoted into the Go CLI, or treated as a required release gate, it must pass a tool fitness review.

Every tool must answer:

1. What job does this tool do?
2. What real product, compatibility, migration, or drift risk does it catch?
3. Is the risk still worth catching?
4. Is this the simplest tool shape that catches that risk?
5. Is the tool flexible across Core, high-consideration service proof site, creative proof site, and future marketing sites?
6. Does it provide useful output for humans, CI, and AI agents?
7. Does it support Linux, macOS, and Windows?
8. Should the future home be Go, explicit Distribution orchestration, or retirement?
9. What acceptance test proves the tool is doing the job?
10. What would let us delete or consolidate it later?

Use audit/tooling-fitness-matrix.csv as the working inventory.

Tool outcomes:

• keep-reference: valuable current behavior; keep as reference.
• go-pilot: strong candidate for first Go rewrite.
• go-later: migrate after command contract stabilizes.
• fold-into-cli: useful behavior, but should become a subcommand or mode.
• optional-generator: useful authoring/build helper, not a release gate.
• consolidate: overlaps another tool and should merge eventually.
• retire: no longer catches a meaningful risk.

No tool should be rewritten just because it is old. No tool should remain required just because it already exists.

Execution Loop Requirement

Tooling work should be done in small loops:

1. Review one tool or tightly related tool group.
2. Identify the job, risk, value, and flexibility gaps.
3. Decide whether it is a release gate, helper, optional generator, consolidation candidate, Go pilot, or retirement candidate.
4. Write the decision to audit/tooling-fitness-matrix.csv.
5. Stop and report before changing implementation.

Do not combine a tool fitness decision and a rewrite in the same loop. The rewrite only starts after the tool has a clear job and acceptance test.

Implemented Go CLI Slices

• foundry validate runtime: native Go runtime-contract validator with human and JSON output.
• foundry validate motion: native Go Motion Kit contract validator for profiles, capabilities, display patterns, normalized fields, source hooks, and safety rules.
• foundry validate scaffolds: native Go scaffold/page contract validator for content kits, page types, compositions, blueprints, and route-floor smoke paths.
• foundry validate quality: native Go quality-gates validator for the first objective a11y, SEO, performance, and rendered-output floor across shared template images, buttons, SEO/head contracts, and already-rendered fixture HTML trees supplied with --rendered-root.
• foundry validate block-contracts, block-governance, content-kits, creative-lane, compatibility-fixtures, feature-flags, shell, section-families, site-blocks, site-shadows, and shell-overrides: native Go validators for the promoted Core and downstream-site release lanes.
• foundry doctor --json: Go-owned core doctor command surface backed by the promoted Go validators.
• foundry doctor --site <path> --json: Go-owned site doctor command surface with native bootstrap, site block, drift audit, shell override, and Hugo smoke checks.
• foundry doctor --browser-smoke --json: Go-owned browser-smoke command surface backed by the Go compatibility fixture harness and Safari WebDriver.
• foundry inspect --json: Go-owned framework inventory command for manifests, block partial source paths, blueprint YAML, runtime contract counts, and deterministic JSON output.
• foundry inspect discovery --json: Go-owned discovery inspection target for the public section-family chooser manifest.
• foundry inspect motion --json: Go-owned Motion Kit inspection target for profiles, capabilities, normalized authoring fields, safety rules, and source files.
• foundry inspect --site <path> --json: Go-owned site/page inventory command for content paths, routes, language variants, block usage, blueprint candidates, and source dependency mapping.

Future CLI Shape

Target commands:

foundry doctor
foundry doctor --site <path> --json
foundry doctor --browser-smoke --json
foundry validate core
foundry validate blocks
foundry validate shell
foundry validate fixtures
foundry validate motion
foundry validate quality
foundry validate site
foundry inspect --json
foundry inspect blocks --json
foundry inspect blueprints --json
foundry inspect discovery --json
foundry inspect motion --json
foundry inspect site --site <path> --json
foundry inspect /route/ --site <path> --json
foundry new-page --blueprint <key> --dry-run --json
foundry materialize
foundry report

The CLI should support JSON output for automation and human-readable output for local use.

Proof Consumers

Priority impacted consumers for tooling and migration proof:

1. high-consideration-service-proof-site
2. creative-proof-site
3. property proof site

high-consideration service proof site is available in the current local workspace at:

C:\Users\likestyle\Documents\Codex\high-consideration-service\high-consideration-service-proof-site

The creative-proof-site and property proof site repos are not present in the current local Windows workspace as of this ADR, but both are present and validated on the remote server:

• /srv/foundry/repos/creative-proof-site
• /srv/foundry/repos/property proof site

Non-Goals

• Do not weaken WCAG, Web Vitals, browser, visual, or migration evidence merely to remove a tool.
• Do not make Python the default language for Core validators.
• Do not add productized Core features outside the Go/Hugo toolchain contract.

Acceptance Criteria For Go Validator Work

• runs on Linux, macOS, and Windows
• matches the documented contract and retained fixtures
• has fixture coverage
• has docs and migration notes
• does not break high-consideration service proof site
• has an explicit compatibility and rollback path
• supports CI-friendly output