refactor: scoped state writes preserve untouched entries

[dhruva-reddy]

ELI5

Problem. Even when you ran a scoped push — say
npm run push -- <env> assistants/foo.md to update one assistant —
the engine rewrote the entire state file. Any pre-existing drift
in unrelated state entries (UUIDs from earlier sessions, untracked
local files, etc.) swept into the focused commit. Reviewers couldn't
tell from the state-file diff "what did this push actually change?"
and the state file became a pile of side effects accumulated across
sessions instead of a precise record of intent.

What this fix does. During a push, the engine tracks which
resourceIds it actually mutated (a per-section Set<string>). At
end-of-run, for scoped pushes only, it loads the on-disk state
fresh, replaces only the touched entries with the in-memory version,
and leaves everything else alone. Full pushes (no scope) still write
wholesale (existing behavior). Credentials are always replaced
because bootstrap pull populates them every push regardless.

This depends on Stack F's ResourceState because we need per-entry
metadata to distinguish "stale" from "just-not-touched."

Outcome you'll notice. A one-file npm run push produces a
one-file diff in the state file — same scope as the resource change.
Reviewers can read the state diff and tell "this push updated
assistant foo, here's its new hash" cleanly. Pre-existing drift
elsewhere in state stays where it is until you explicitly address it.

---

When push is scoped to specific paths, only update state entries for
the resources actually touched. A surgical push of two files used to
rewrite the entire state file, sweeping in pre-existing drift from
earlier pushes (improvements.md #15) and producing noisy diffs that
hide the actual scope of the change.

Files:

• src/state-merge.ts (NEW): mergeScoped(disk, inMemory, touched).
  For each section, replace only touched.X resourceIds with the in-memory
  version; leave the rest of disk's section as-is. Credentials are
  always replaced wholesale (bootstrap pull populates them on every
  push). Pure data, no I/O — safe to test directly.
• src/push.ts: TouchedSets tracker. Each upsertState call site
  records the resourceId. End-of-run, partial pushes call
  mergeScoped(loadState(), state, touched) before saveState; full
  pushes save wholesale (existing behavior).
• tests/state-merge.test.ts: replace-only-touched, leave-untouched,
  drift in untouched stays, credentials always replaced.

Closes improvements.md #15.

🤖 Generated with Claude Code

[dhruva-reddy]

Warning

This pull request is not mergeable via GitHub because a downstack PR is open. Once all requirements are satisfied, merge this PR as a stack on Graphite.
Learn more

• refactor: scoped state writes preserve untouched entries #22 👈 (View in Graphite)
• feat: snapshot-on-push + npm run rollback #21
• feat: drift detection on push (--overwrite to bypass) #20
• refactor: state schema with per-resource content hashes #19
• feat: simulation suite runner (npm run sim) #18
• feat: validate command with five fail-fast schema/lockstep/shape checks #17
• feat: push --dry-run preview mode #16
• refactor: deterministic state-file key ordering #15
• docs: adopt upstream improvements.md log + voice-providers cheat-sheet #14
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.