Establish local-first validation framework and conflict-resistant pre-push enforcement

[justinrayshort]

Summary

Establish a repo-owned local-first validation framework so contributors run the same checks locally that GitHub enforces remotely, with blocking pre-push validation, shared scope selection, and reduced merge-conflict pressure from generated UI artifacts.

Problem Statement

The repository has strong validation primitives in xtask, but local and remote validation are still fragmented. Contributors must remember multiple commands, required remote checks are not fully predicted by one local gate, security validation is not yet normalized for local use, and GitHub workflow YAML still contains path and validation logic that is not owned by repository tooling. In parallel, generated UI outputs remain committed in a high-conflict area.

Proposed Solution

Implement a new cargo xtask validate command family as the single validation surface for local and GitHub execution, normalize the security baseline into a repo-owned policy, install blocking pre-push hooks, move workflow-only checks into xtask, stop committing generated UI CSS outputs, and make GitHub Actions call the same repo-owned validation entrypoints used locally.

Architectural References

• AGENTS.md
• ARCHITECTURE.md
• docs/architecture/layer-boundaries.md
• DEVELOPMENT_MODEL.md
• docs/process/github-workflow-migration.md
• docs/process/platform-regression-guardrails.md
• docs/process/pr-conflict-reduction-playbook.md

Owning Subsystem

Repository validation, xtask, GitHub governance workflows, and UI generated-asset pipeline.

Integration Boundaries

Allowed cross-plane touchpoints:

• xtask/
• .github/
• .cargo/
• ui/crates/system_ui/
• ui/crates/site/
• docs/
• plans/

Explicit non-goals:

• No domain-runtime redesign outside validation and generated-asset flow.
• No container-first local development model.
• No bypass of protected-branch or review policy.

Impacted Domains

• repository delivery workflow
• local developer validation
• GitHub CI/CD enforcement
• UI generated styling assets

Affected Consistency Class

Class B

Affected Risk Tier

high

Primary Architectural Plane

cross-layer

Scope In

• Add repo-owned cargo xtask validate commands for doctor/bootstrap/scoped validation/CI/hook installation.
• Normalize security validation into a local/remote repo-owned suite.
• Refactor GitHub workflows to use xtask validation entrypoints instead of ad hoc path logic.
• Install blocking pre-push validation and branch-freshness enforcement.
• Remove committed generated UI CSS/token outputs from Git and generate them through repo-owned flows.
• Update contributor docs, PR template, and execution artifacts for the new workflow.

Scope Out

• Broad application feature work unrelated to validation.
• Runtime contract redesign unrelated to generated asset handling.
• Replacing native local workflows with devcontainers or containerized-only execution.

Acceptance Criteria

• cargo xtask validate provides doctor, bootstrap, changed, suite, ci, and install-hooks entrypoints.
• Local scoped validation and GitHub CI derive suite selection from the same repo-owned logic.
• Security validation runs locally and remotely from repo-owned commands with explicit policy for temporary exceptions.
• Blocking pre-push hooks reject pushes when required local validation fails.
• Validation enforces branch freshness for documented conflict hot spots before push.
• Generated UI CSS outputs stop being committed and are produced deterministically from repo-owned generation.
• Required GitHub workflows invoke repo-owned validation entrypoints instead of duplicating shell-only validation logic.
• Contributor docs and templates describe the new local-first flow and bypass disclosure.

Validation Requirements

• cargo test -p xtask
• cargo xtask validate doctor
• cargo xtask validate suite security
• cargo xtask validate changed --base <ref>
• cargo verify-repo
• cargo verify-ui
• cargo xtask ui-hardening

Validation Artifacts

• Passing xtask test output
• Passing local validation reports under target/validation
• Passing repo and UI verification output
• Updated workflow parity tests

Rollback Considerations

This change spans repo workflow, local hooks, and generated asset handling. Rollback must restore prior aliases, workflow entrypoints, and tracked generated CSS outputs together to avoid leaving the repo in a partially enforced state.

Rollback Path

Revert the validation-framework commits, re-track the generated CSS outputs if needed, and restore the previous workflow commands and local contributor instructions.

Technical Notes

• Local enforcement should be blocking at pre-push time.
• Execution remains native-first.
• Merge queue should be treated as required on main in governance/docs updates.
• Temporary security exceptions must carry owner, linked issue, and expiry metadata.