stack/docs/scratchpads/rm-01-reproducible-checkout.md

RM-01 — Reproducible checkout

• Task/ref: RM-01 (docs/remediation/TASKS.md, internal mission tracking)
• Objective: make checkout/install/typecheck hooks fail on code rather than environmental residue, for root CI and non-root seats.
• Scope: pnpm store configuration, transactional Husky installation, dependency/generated-state preflight, checkout regression tests, developer documentation.
• Constraints: isolated worktree; no skip-switch fixes; no writes under /root or /tmp; workers do not edit docs/remediation/TASKS.md; author does not review or merge.
• Acceptance: AC1–AC8 from the orchestrator dispatch/addendum.
• Plan:
  1. Add RED-first tests for missing dependencies, stale/foreign .next, and interrupted hook installation.
  2. Implement environment-overridable HOME-based pnpm store defaults, deterministic preflight, and transactional hook installation.
  3. Run focused tests, install/build/baseline gates, and explicit AC negative controls.
  4. Obtain independent review, push after queue guard, open PR, and send evidence to mos-remediation.
• Budget: orchestrator estimate 6K/60K; no explicit hard token cap. Keep scope to RM-01 and avoid unrelated cleanup.
• Risks: 97%-full shared /tmp; native dependency install size; root-owned fixtures may require Docker for realistic verification.

Progress / evidence

• Worktree created at /home/hermes/agent-work/rm-01 from origin/main 06e0d403.
• /tmp baseline: 28G used, 889M available (97%); worktree and planned store are on /home.
• Root causes confirmed from source: committed .npmrc pins /root; prepare invokes Husky directly; web typecheck includes generated .next types without validating ownership/freshness.

Checkpoint evidence (c45e5e19)

• AC1 IN PROGRESS: non-root pnpm install --frozen-lockfile --store-dir "$HOME/.local/share/pnpm/store" exited 0; pnpm exec turbo run typecheck --force exited 0 (45/45 uncached). Clean CI-container run not performed.
• AC2 DONE: with node_modules absent, pnpm preflight exited 42 with MOSAIC_PREFLIGHT_MISSING_DEPS and run pnpm install; after install it exited 0.
• AC3 DONE: appending export const x: number = "s" to packages/types/src/index.ts made pnpm -w typecheck exit 2 with TS2322; reverting made it exit 0.
• AC4 IN PROGRESS: local pnpm -w build exited 0 and git status --porcelain showed no generated residue beyond the intended RM-01 source changes. Fresh-clone proof not performed.
• AC5 DONE: non-root install exited 0; pnpm store path resolved /home/hermes/.local/share/pnpm/store/v10; no /root write was attempted.
• AC6 IN PROGRESS: focused failure/rollback tests passed, but final review found a concurrent-install race. Two installers can both observe .husky/_ absent; after one installs successfully, the losing install's catch path can quarantine the winner's active hooks and restore stale Git config (scripts/install-hooks.mjs, activation/catch transaction). A RED regression is committed after the checkpoint.
• AC7 DONE: install/store/worktree were on /home; full pnpm -w build exited 0; /tmp usage changed by 4096 bytes during the build (23,805,173,760 → 23,805,177,856 bytes), not materially.
• AC8 DONE for the implemented path: store resolves under $HOME; test/quarantine/build state resolves under the worktree; no implemented component requires a writable path outside $HOME or the worktree.

Handoff

1. Keep the newly committed RED tests red until implementing: (a) source-fingerprint marker support for valid incremental .next output, and (b) ownership-safe concurrent hook activation.
2. The latest automated review rejected oldest-generated-file mtime as a false positive for valid incremental Next output. Use a source-content fingerprint marker written only after successful next build; do not continue tuning mtimes.
3. For Husky, generation in an isolated temporary Git repo avoids mutating real core.hooksPath during staging. Preserve that design. Fix the losing concurrent process so it never removes a peer's completed hook set or restores stale config.
4. Codex review runs in a read-only sandbox, so its attempts to run the fixture-writing Node tests report opaque test-file failures. The same tests run normally in the worktree.
5. Full pnpm test is not green on this host: it exits 97 at the pre-existing Bash BASH_LINENO convention guard (#1003), after the changed checkout tests and package tests pass. Do not weaken that gate.