feat: scaffold FPSMaxxing Rust workspace with typed contracts, CI, and OSS docs

[undeemed]

Intent

Create a public OSS-ready GitHub repository named fpsmaxxing under undeemed. Scaffold a Rust 2024 monorepo for an AI- and Claude-driven, measurement-gated PC performance optimizer with strict privilege separation, typed capabilities, verification, rollback, and no real hardware writes in the scaffold. Use Apache-2.0, include organized implementation and architecture plans in canonical Markdown plus a static HTML visualization, contributor and security documentation, CI, natural GitHub discoverability without keyword stuffing, Cargo workspace plus xtask, one isolated .NET LibreHardwareMonitor bridge, and provider-first source and target artifacts.

What Changed

• Bootstrapped a Rust 2024 Cargo workspace for the FPSMaxxing performance gateway: five app binaries (broker, cli, gateway, experiment-runner, watchdog), contracts and provider-sdk crates, a mock-provider sidecar that exercises the snapshot -> apply -> verify -> rollback lifecycle, and an xtask check runner. The scaffold performs no real hardware writes.
• Added typed capability and sidecar JSON schemas plus contracts tests that generate schemas from the Rust types and diff them against the checked-in files, alongside default risk/conflict policy TOML files.
• Added CI (fmt, clippy, tests, cargo-deny, JSON schema metaschema validation, with .gitattributes forcing LF checkout so rustfmt passes on Windows) and the OSS project surface: Apache-2.0 license, README, CONTRIBUTING, SECURITY, GOVERNANCE, code of conduct, issue/PR templates, dependabot, ADRs, threat model, and the implementation plan in Markdown plus a static HTML visualization.

Risk Assessment

✅ Low: Round-1 findings are all correctly addressed with tests that strengthen contract/schema sync, and the only residuals are a leftover branding string in a docs artifact and an unpinned CI helper version.

Testing

Ran the full workspace test suite (8 contracts schema-sync tests + mock provider apply/verify/rollback, all passing), exercised all seven scaffold binaries end-to-end capturing a CLI transcript that shows privilege-separated stubs and hardware writes disabled, verified the cargo xtask alias, validated the JSON schemas against their metaschema as CI does, and captured a full-page screenshot of the HTML implementation plan confirming it renders cleanly.

Evidence: CLI transcript: all scaffold binaries incl. mock provider lifecycle and cli doctor

$ cargo run -q -p fpsmaxxing-cli -- doctor FPSMaxxing scaffold diagnostics contracts: ready provider SDK: ready hardware writes: disabled status: architecture scaffold only $ cargo run -q -p fpsmaxxing-broker fpsmaxxing-broker: scaffold ready; no privileged actions are enabled $ cargo run -q -p fpsmaxxing-gateway fpsmaxxing-gateway: scaffold ready; MCP transport is not implemented yet $ cargo run -q -p fpsmaxxing-mock-provider mock # full snapshot→apply→verify→rollback lifecycle asserted in main

$ cargo run -q -p fpsmaxxing-cli
fpsmaxxing-cli

usage: fpsmaxxing-cli doctor

$ cargo run -q -p fpsmaxxing-cli -- doctor
FPSMaxxing scaffold diagnostics
  contracts: ready
  provider SDK: ready
  hardware writes: disabled
  status: architecture scaffold only

$ cargo run -q -p fpsmaxxing-broker
fpsmaxxing-broker: scaffold ready; no privileged actions are enabled

$ cargo run -q -p fpsmaxxing-gateway
fpsmaxxing-gateway: scaffold ready; MCP transport is not implemented yet

$ cargo run -q -p fpsmaxxing-experiment-runner
fpsmaxxing-experiment-runner: scaffold ready; no benchmark configured

$ cargo run -q -p fpsmaxxing-watchdog
fpsmaxxing-watchdog: scaffold ready; no leases are active

$ cargo run -q -p fpsmaxxing-mock-provider
mock

$ cargo run -q -p xtask
usage: cargo xtask <check|test>

- Evidence: Full-page render of docs/IMPLEMENTATION_PLAN.html (static HTML visualization) (local file: /var/folders/dn/rb9kwwms3yq_c7ym5vgtp1740000gn/T/no-mistakes-evidence/01KXCWFER8ERGXNKB3G11ZZFEW/implementation-plan-full.png)

Pipeline

Updates from git push no-mistakes

✅ **intent** - passed

✅ No issues found.

✅ **Rebase** - passed

✅ No issues found.

⚠️ **Review** - 2 infos

• ⚠️ docs/IMPLEMENTATION_PLAN.html:6 - HTML implementation plan is branded "Performance Gateway" and never mentions "FPSMaxxing" (0 occurrences), while docs/README.md presents it as the visual companion to the canonical FPSMaxxing plan. Appears to be a leftover working title; rebrand the HTML (title, hero, nav) to match the repository name or readers will not connect the two documents.
• ⚠️ .github/pull_request_template.md:22 - PR template validation checklist omits cargo deny check, but AGENTS.md documents it as part of the required validation suite and CI enforces it via cargo-deny-action. Add a - [ ] cargo deny check line so contributors run the same gate locally.
• ℹ️ .github/workflows/ci.yml:20 - Third-party GitHub Actions are pinned by mutable tag (actions/checkout@v4, Swatinem/rust-cache@v2, EmbarkStudios/cargo-deny-action@v2). For a project with an explicit security posture, pin to full commit SHAs; dependabot's github-actions ecosystem already updates SHA pins automatically.
• ℹ️ README.md:5 - README.md line 5 and docs/IMPLEMENTATION_PLAN.html (estimate-basis note) use em dashes, violating the author's standing rule to use plain dashes only. Replace with plain "-".
• ℹ️ crates/contracts/src/lib.rs:5 - The schemars JsonSchema derive is currently unused: schemas/*.json are hand-written and the contracts tests hand-compare enum wire strings and field sets. Either use schemars in the tests to generate schemas from the types and diff against the checked-in files (stronger sync, less manual assertion code) or drop the schemars dependency until it is needed.
• ℹ️ crates/contracts/src/lib.rs:76 - ChangeRequest.lease_seconds is a plain u64 that permits 0, but the design says every mutation carries a TTL lease. Consider NonZeroU64 (mirroring protocol_version's NonZeroU32) or document what a zero lease means before real providers consume the contract.
• ℹ️ AGENTS.md:35 - AGENTS.md claims CI runs "JSON schema validation", but the CI schemas job only checks the files parse as JSON (json.loads); structural validation lives in the contracts tests. Either soften the wording or validate the schemas against the 2020-12 metaschema in the job.

🔧 Fix: rebrand HTML plan, pin CI actions, enforce non-zero leases
2 infos still open:

• ℹ️ docs/IMPLEMENTATION_PLAN.html:352 - Rebrand from round 1 is incomplete: the repo-layout tree data in the page script still names the repository root "performance-gateway/" (the only remaining occurrence), so the rendered layout diagram shows the old working title instead of fpsmaxxing. Rename the tree root label to "fpsmaxxing/".
• ℹ️ .github/workflows/ci.yml:48 - pipx run check-jsonschema resolves the latest PyPI release at CI time, which is inconsistent with the commit's SHA-pinning of actions and lets an upstream release break or alter the schemas gate; pin the version (e.g. pipx run check-jsonschema==<version>) so dependabot-style bumps are deliberate.

✅ **Test** - passed

✅ No issues found.

• cargo test --workspace --locked (9 tests: 8 contracts schema-sync/wire-format tests incl. generated_schemas_match_checked_in_schemas, plus mock provider apply_verify_and_rollback)
• Ran every binary end-to-end and captured a CLI transcript: fpsmaxxing-cli + fpsmaxxing-cli doctor (reports hardware writes disabled), fpsmaxxing-broker, fpsmaxxing-gateway, fpsmaxxing-experiment-runner, fpsmaxxing-watchdog, fpsmaxxing-mock-provider (runs snapshot→apply→verify→rollback lifecycle)
• cargo xtask and cargo xtask check via the .cargo/config.toml alias
• uvx check-jsonschema --check-metaschema schemas/*.json (mirrors the CI schemas job) → ok
• Rendered docs/IMPLEMENTATION_PLAN.html in headless Chromium (CDP) and captured a full-page 1440px screenshot to verify the static visualization renders without layout breakage

✅ **Document** - passed

✅ No issues found.

✅ **Lint** - passed

✅ No issues found.

✅ **Push** - passed

✅ No issues found.