[FINAL] Cross-Cutting Standards, Reproducibility & Product Polish — Closing the Gaps

[mohityadav8]

[FINAL] Cross-Cutting Standards, Reproducibility & Product Polish — Closing the Gaps

Owner: Shared — M. Yadav, Y. Jangra, B. Kataria (assign individual checkboxes as they come up in planning)
Scope: Everything left over after Issues #1 (Node A), #2 (Node B), #3 (Node C), and #4 (Governance/Meta) — code-quality tooling, heterogeneous hardware reproducibility, lowering the barrier to adoption, secrets management, release engineering, feedback loops, and long-term portability. This is the last issue — after this, the full 6-month project is covered end to end.
Duration: Runs parallel to all phases, weighted toward Phase I (standards set early) and Phase VI (release engineering)
Labels: meta, devex, epic, polish, catch-all

---

🎯 Why This Issue Exists

Issues #1–#4 cover building the product and coordinating the team. What's missing is everything that determines whether the code is actually pleasant and safe to work in day-to-day, whether it runs correctly across three genuinely different laptops (not just three instances of the same machine), whether someone outside the team can actually try it, and what happens technically once v0.1.0 needs a v0.1.1. None of that has an owner yet.

---

🟦 1. Code Quality, Style & DevEx Standards

Nobody in Issues #1–#3 owns the shared tooling that makes the other three people's code consistent with each other.

• 1.1 Set up pre-commit hooks repo-wide — ruff format, ruff check, mypy, and a Prettier/ESLint pass for the TS/dashboard code, all run automatically before commit
  • Acceptance: a fresh clone + pre-commit install blocks a badly-formatted commit locally, not just in CI
• 1.2 Agree on a strict mypy policy — which packages must pass --strict (recommend: orchestrator, shared) vs. which can be looser during early prototyping
  • Acceptance: documented per-package in pyproject.toml, not left ambiguous
• 1.3 Define a shared logging standard — one logging format/library (e.g. structlog) used identically across orchestrator, inference, sandbox so combined logs are actually readable together
  • Acceptance: a log line from Node A and a log line from Node C use the same timestamp format, log level names, and structured-field convention
• 1.4 Define a shared error taxonomy — common exception base classes (HydraConfigError, HydraNetworkError, HydraSandboxError, etc.) used across all three packages instead of each node inventing its own
  • Acceptance: documented in /packages/shared/errors.py; each node's Phase I–VI error handling (already in Issues [Node A] Supervisor, State Machine & Reaper Protocol — Full 6-Month Track (M. Yadav) #1–[Node C] Sandbox, Infrastructure & Launch — Full 6-Month Track (B. Kataria) #3) is expected to import from here rather than raise bare exceptions
• 1.5 Write a STYLE.md — naming conventions (files, functions, gRPC message fields), import ordering, docstring format
  • Acceptance: short enough that all three actually read it; referenced from CONTRIBUTING.md
• 1.6 Set up a shared .editorconfig — consistent indentation/line-endings across three different personal machine setups
  • Acceptance: verified a file edited on each of the 3 laptops produces an identical diff for unrelated whitespace

---

🟥 2. Hardware & Environment Reproducibility (Heterogeneous Machines)

Three different laptops (RTX 3050 6GB, two RTX 4060 8GB) means "works on my machine" is a real risk nobody's individual issue addresses holistically.

• 2.1 Document exact GPU driver + CUDA/ROCm toolkit versions required on all three machines, and verify they match
  • Acceptance: a HARDWARE.md lists driver version, CUDA version, and OS/kernel version actually running on each of the 3 machines
• 2.2 Build a GPU compatibility matrix — what's confirmed working (RTX 3050/4060), what's untested (AMD, older NVIDIA, Apple Silicon), what's explicitly unsupported for now
  • Acceptance: table published in README or /docs/model-selection.md, sets honest expectations for outside adopters
• 2.3 Verify WSL2 vs. native Linux parity — if any teammate runs Windows/WSL2, confirm Docker networking and GPU passthrough behave identically to native Linux
  • Acceptance: the exact same integration test suite passes on both environments, differences (if any) documented explicitly
• 2.4 Pin Python/Node runtime versions exactly — not just library versions, the interpreter/runtime itself (e.g. via .python-version, .nvmrc)
  • Acceptance: uv sync and npm install produce byte-identical lockfiles across all three machines
• 2.5 Write a machine-onboarding checklist — the exact sequence a teammate follows when setting up a new laptop (e.g. after a hardware replacement) to rejoin the cluster
  • Acceptance: tested at least once for real, not just written speculatively

---

🟩 3. Lowering the Barrier to Adoption

The README's target interface assumes 3 laptops on a LAN — that's a meaningfully high barrier for anyone wanting to just try HydraNet. Nobody currently owns making evaluation easier.

• 3.1 Build a single-machine "trial mode" — all three roles (supervisor, inference, sandbox) running as local processes on one laptop, no networking required, reduced feature set acceptable
  • Acceptance: a hydra fix --local (or similar) flag runs the Phase I loop with zero cluster setup
• 3.2 Write a docker-compose.yml for trial mode — spin up Postgres/pgvector + a single-node agent loop with one command for evaluation
  • Acceptance: docker compose up + one CLI command produces a working demo on a fresh machine within 10 minutes
• 3.3 Document minimum viable hardware for trial mode — what's the smallest GPU (or CPU-only, accepting slower inference) someone can use just to see it work
  • Acceptance: explicit "minimum" vs. "recommended" (3-node) hardware tiers published
• 3.4 Record a "5-minute quicklook" video — distinct from the Phase VI full demo — aimed at someone deciding whether to invest 30 minutes in the full setup
  • Acceptance: video is short, unscripted-feeling, shows trial mode not the full cluster

---

🟨 4. Secrets, Tokens & Config Management

The pre-shared token and TLS setup are built in Phase IV (Issues #1/#3), but nobody owns the ongoing lifecycle of that secret.

• 4.1 Define a token rotation policy — how often the pre-shared cluster token rotates, and the procedure for rotating it without breaking an in-flight run
  • Acceptance: documented procedure, tested once by actually rotating the token on a live (test) cluster
• 4.2 Audit .gitignore for secret leakage risk — hydra.config.json (contains the token), any .env files, TLS private keys — confirmed never committable
  • Acceptance: a deliberate test commit of a dummy secret is confirmed blocked by .gitignore + a pre-commit secret scanner (e.g. detect-secrets)
• 4.3 Add a secret-scanning pre-commit hook / CI check — catches an accidentally-committed token or key before it reaches main
  • Acceptance: CI fails a PR containing a fake test secret, proving the check works
• 4.4 Document what happens if a laptop with the cluster token is lost or stolen — revocation procedure
  • Acceptance: short incident-response note in SECURITY.md

---

🟪 5. Release Engineering & Versioning

Issue #3 covers the one-time v0.1.0 tag. Nobody owns what happens for v0.1.1, v0.2.0, and beyond.

• 5.1 Adopt semantic versioning explicitly — document what counts as a breaking change (e.g. any .proto change) vs. minor vs. patch
  • Acceptance: VERSIONING.md or a section in CONTRIBUTING.md states the rule plainly
• 5.2 Set up automated changelog generation — driven by the Conventional Commits convention from Issue [META] Project Coordination, Governance & Cross-Team Integration #4 (3.5)
  • Acceptance: CHANGELOG.md auto-updates (or is trivially generatable) from commit history for each release
• 5.3 Write a release checklist template — repeatable steps for every future release, not just the one-time v0.1.0 launch checklist in Issue [Node C] Sandbox, Infrastructure & Launch — Full 6-Month Track (B. Kataria) #3
  • Acceptance: template used to test-drive a hypothetical v0.1.1 patch release before it's actually needed
• 5.4 Define a deprecation policy — if a .proto field, CLI flag, or config key needs to change later, how much notice/backward-compat is given
  • Acceptance: documented, even if the answer for a young project is intentionally simple ("breaking changes allowed pre-1.0, flagged in release notes")

---

🟧 6. Feedback Loop & Beta Testing

Issue #3's launch posts go straight to public (HN/Reddit). Nobody owns getting real outside feedback before that public moment.

• 6.1 Recruit 2–3 outside beta testers before the Phase VI public launch — ideally people with their own hardware, not team members
  • Acceptance: at least 2 outside people have run hydra fix on their own machine and given written feedback before launch day
• 6.2 Build a lightweight feedback intake — a short form or a pinned Discussion asking "what broke, what confused you, what would make you use this again"
  • Acceptance: at least 3 pieces of concrete feedback collected and triaged before launch
• 6.3 Fix or explicitly document (don't ignore) beta-tester-found issues before launch
  • Acceptance: every beta-reported issue has a linked GitHub issue with a resolution or an explicit "known limitation" note
• 6.4 Plan a post-launch feedback checkpoint — 2 weeks after v0.1.0, review what real public users are reporting vs. what beta testers found
  • Acceptance: short written comparison, informs the Issue [META] Project Coordination, Governance & Cross-Team Integration #4 roadmap (ROADMAP.md)

---

🟦 7. Long-Term Portability & Extensibility

The README explicitly scopes out tensor-parallel GPU pooling and non-NVIDIA support "for now" — but nobody has a placeholder for revisiting that later.

• 7.1 Document why AMD/Apple Silicon support is out of scope for v0.1.0 — and what would need to change to support it (ROCm equivalents, MLX for Apple Silicon)
  • Acceptance: an honest "not yet, here's why, here's what it'd take" section in /docs/architecture.md, not silence
• 7.2 Document a theoretical cloud-burst fallback — if someone only has 1 laptop and wants Node B/C in the cloud temporarily, what would that integration look like
  • Acceptance: a design sketch only (not built) — placeholder for a future phase, explicitly marked speculative
• 7.3 Sketch a plugin architecture note for language targets beyond Python/TypeScript — the README states "Python first, TypeScript phase 2" — write down what "phase 3" (Go, Rust, Java, etc.) would require structurally
  • Acceptance: short forward-looking doc, not an implementation commitment
• 7.4 Note NATS/Qdrant/Weaviate as documented future swap options — the README's "why we chose these tools" table already flags these as reconsideration points; make sure that's captured as an actual tracked follow-up, not just README prose
  • Acceptance: each flagged reconsideration point gets a corresponding low-priority tracked issue for later

---

✅ Full Project Coverage Map

Issue	Owns
#1 — Node A (M. Yadav)	State machine, Reaper Protocol, convergence scoring, cluster networking, WebSocket backend
#2 — Node B (Y. Jangra)	Model serving, prompt engineering, AST parsing, retrieval logic, dashboard frontend, SWE-bench benchmark
#3 — Node C (B. Kataria)	Docker sandbox, checkpoint/rollback, hybrid retrieval assembly, dashboard state, CI, launch
#4 — Meta/Governance	Team cadence, cross-node contract sign-off, repo hygiene, legal/licensing, ongoing public comms, risk register, post-launch plan
#5 — This issue	Shared tooling standards, heterogeneous-hardware reproducibility, low-barrier trial mode, secrets lifecycle, release engineering, beta feedback loop, long-term portability

Nothing from the README's Phase tables, tech stack, or "what this is/isn't" sections is left unassigned across these 5 issues.