Tooling language ADR

Status: accepted direction; Go CLI product path established; first Go pilot implemented 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.

Existing Node validators remain reference/fallback behavior because they already exist, pass direct validation locally, and are close to the current JSON/YAML/docs surfaces. They should not be treated as throwaway legacy. They are the behavior contract that Go tooling must match or intentionally supersede with documented migration notes.

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 should eventually be able to run one portable tool without installing or debugging a Node or Python 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

Do not rewrite every validator immediately.

Recommended sequence:

1. Keep current Node validators stable and documented as reference/fallback behavior.
2. Treat the Go foundry CLI as the canonical public product surface.
3. Keep new public/productized CLI work Go-first, including inspect, doctor, new-page, motion validation, route-floor validation, and upgrade flows.
4. Build small Go validators in bounded slices. The first pilot is foundry validate runtime.
5. Compare Go output against the Node reference behavior.
6. Use generic high-consideration service and creative proof profiles as priority proof consumers.
7. Promote Go validators only when parity, fixtures, docs, and migration notes are complete.

Pilot candidates and status:

• validate-runtime-contracts: implemented as additive Go pilot
• validate-motion-manifest: implemented as additive Go validator
• scaffold/page contract validation: implemented as additive Go validator
• validate-quality-gates: implemented as additive Go validator
• validate-block-contract
• Windows-safe compatibility fixture materialization

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, Node reference, Python 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 doctor --json: Go-owned core doctor command surface. Current core checks use Node reference validators where native Go parity does not exist; runtime, motion, quality-gates, and scaffold/page validation run natively in Go.
• foundry doctor --site <path> --json: Go-owned site doctor command surface with native bootstrap and Hugo smoke checks plus Node reference site/drift validators.
• foundry doctor --browser-smoke --json: Go-owned browser-smoke command surface that delegates to the Node reference fixture browser lane.
• 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 replace all Node validators in one broad rewrite.
• Do not pause Core quality work until Go tooling is fully complete.
• Do not make Python the default language for Core validators.
• Do not treat current Node validators as disposable; they are reference behavior.
• Do not add new productized CLI features as Node-only canonical surfaces.

Acceptance Criteria For Go Validator Work

• runs on Linux, macOS, and Windows
• matches existing Node validator behavior or explicitly documents intentional differences
• has fixture coverage
• has docs and migration notes
• does not break high-consideration service proof site
• has a rollback path to the Node validator
• supports CI-friendly output