uupl-smart-contract/.superpowers/sdd/2026-08-17-uups-bank-demo/progress.md

SDD ledger — plan: /home/golem/dev/sandbox/codius-test-uupl-smart-contract/.worktrees/uups-bank-demo/docs/superpowers/plans/2026-08-17-uups-bank-demo.md

Setup: isolated worktree /home/golem/dev/sandbox/codius-test-uupl-smart-contract/.worktrees/uups-bank-demo on branch feature/uups-bank-demo. Baseline: clean documentation-only repository; no package manifest or runnable test suite exists before Task 1. Task 1: fix round 1/5 (1 addressed, 1 open — plan-file scope conflict awaiting user ruling; commits eece34c..a6f9533) Task 1: ruling — keep the plan correction; the task-specific verified-compatibility clause governs the general listed-files constraint. Task 1: complete (commits 14980e6..a6f9533, review findings resolved) Task 2: minor (deferred): standardize MockUSDC public NatSpec to the exact global educational warning. Task 2: fix round 1/5 (1 addressed, 0 open — literal RED/GREEN command evidence reproduced; no new commit) Task 2: controller check — reported pre-production missing-source failure and isolated reproduction substantiate TDD chronology; no real gap found. Task 2: complete (commits a6f9533..1f4175b, review clean; 1 minor deferred) Task 3: awaiting user ruling — pinned upgrades-core rejects OpenZeppelin 5.6.1 ReentrancyGuard's inherited constructor despite its @custom:stateless marker. Task 3: ruling — user approved the single unsafe-allow-reachable constructor annotation; all other upgrade validation remains enabled. Task 3: approved reachable annotation proved ineffective — upgrades-core 1.46.0 applies it only to opcode traversal, not inherited constructor errors; awaiting second ruling. Task 3: ruling — user selected OpenZeppelin ReentrancyGuardTransient; retain the original sole constructor annotation and add no validator bypass. Task 3: controller check — report confirms literal RED/GREEN, 19/19 full-suite, and exact storage output; focused source scan confirms no validator bypass, while chain allowlisting remains a later script-task requirement. Task 3: complete (commits 1f4175b..0664eb4, review clean) Task 4: controller check — prior fixture confirms proxy binding; foundry config confirms Cancun/fixed seed/validation settings; report records literal offline RED/GREEN commands. Task 4: complete (commits 0664eb4..2a21766, review clean) Task 5: minor (deferred): make actorAt reject indices above three instead of silently returning actor3. Task 5: fix round 1/5 (1 addressed, 0 open — genuine handler-absent RED and fresh selector-summary GREEN reproduced; no new commit) Task 5: complete (commits 2a21766..6dcbb03, review clean; 1 minor deferred) Task 6: PAUSED by user for host reboot at committed HEAD 6dcbb03; active worker interrupted. Uncommitted work is limited to script/lib/DemoScript.sol, script/DeployV1.s.sol, script/SeedV1Demo.s.sol, script/CheckState.s.sol, and test/ScriptPreflight.t.sol. Resume Task 6 from focused preflight GREEN/debug; no Anvil process was running. Task 6: reboot recovery — focused forge test --match-path test/ScriptPreflight.t.sol -vvv --force is GREEN (14/14); preserved work is internally coherent and ready for the remaining Node finalizer/selector, Make targets, and live smoke.

Preflight compatibility scan (restored after reboot)

The approved design spec is authoritative. “Shared interface” below means a direct producer/consumer dependency or a file touched by both tasks, not a merely transitive use of the pinned toolchain.

Tasks	Producer / consumer or shared file	Finding / ruling
1 / 6	Makefile, Foundry/npm pins, upgrades CLI	Compatible: Task 6 extends the exact pinned foundation and offline validator contract.
1 / 7	Makefile, web configuration and package scripts	Compatible: Task 7 adds bridge targets without changing exact dependency pins.
1 / 8	web/src/test/setup.ts, web scripts	Compatible: Task 8 consumes the configured jsdom/Vitest/React setup.
1 / 9	Makefile, tools/doctor.sh	Compatible: Task 9 replaces the temporary doctor and completes the gate.
1 / 11	Makefile, generated artifact policy	Compatible: V2 extends the existing gate and ignored generated module.
1 / 12	.env.example, Makefile	Compatible: public Base configuration is added later without secrets or floating dependencies.
2 / 3	MockUSDC asset interface	Compatible: V1 stores and reads the fixed six-decimal ERC-20.
2 / 4	MockUSDC and ERC-20 behavior	Compatible: custody tests build on standard mint/transfer/approve behavior.
2 / 5	Mintable test liquidity	Compatible: handler receives token ownership only in invariant setup.
2 / 6	Deployment/seeding asset	Compatible: scripts deploy and seed the same mock token.
2 / 7	Token ABI and reserve reads	Compatible: ABI sync exports balanceOf; browser reads proxy token reserves.
3 / 4	src/BankV1.sol	Compatible: Task 4 adds mutations without changing frozen field order or admin behavior.
3 / 5	BankTestBase, V1 proxy	Compatible: invariants target the validated proxy fixture.
3 / 6	V1 deploy/init/view interfaces	Compatible: scripts consume only established proxy-facing APIs.
3 / 7	V1 ABI and state views	Compatible: browser model remains V1-only through demo-start.
3 / 10	V1 storage/layout and UUPS authorization	Compatible subject to the recorded user ruling selecting ReentrancyGuardTransient; V2 must inherit the resulting actual layout and add no storage.
4 / 5	Deposit/withdraw accounting	Compatible: ghost counters independently model exact successful deltas and surplus donations.
4 / 6	Deposit/withdraw and Act 1 values	Compatible: scripted sequence yields the exact tested accounting state.
4 / 10	V1 behavior retained through V2	Compatible: upgrade regression explicitly re-exercises V1 mutations.
5 / 11	test/BankInvariant.t.sol, handler interface	Compatible: Task 11 adds transfers without altering liability/reserve ghosts.
6 / 7	Confirmed/active manifest contract	Compatible: ABI sync is chain-independent; publishing alone consumes validated active.json.
6 / 8	Dashboard deployment identity and Act 1 snapshot	Compatible: UI consumes only validated manifest/state, never a signer.
6 / 9	Makefile, scripts, manifests, process lifecycle	Compatible: orchestration composes Task 6’s direct targets and preserves Base state during local reset.
6 / 11	Upgrade/check scripts, finalizer, manifest identity	Compatible: upgrade mutates only implementation/version and stages before confirmed writes.
6 / 12	Base script paths, finalizer/selector, manifest schema	Ruling: Task 6 provides chain recognition and generic public manifest validation; Task 12 owns the fully runnable Base actor/RPC/keystore path. Cost if wrong: Task 6 may need a narrow compatibility adjustment when Task 12 adds Base actors.
7 / 8	Dashboard types, manifest parser, bank client	Compatible: Task 8 renders the typed, V1-only read model.
7 / 9	ABI sync/publish targets and offline verification	Compatible: make verify requires ABI freshness but no live manifest.
7 / 11	dashboard.ts, bankClient, artifact sync	Compatible: V2 ABI/activity is deliberately absent at demo-start and added only after Task 10.
7 / 12	manifest publisher/selector and Base explorer/RPC metadata	Compatible: browser receives only public credential-free RPC data.
8 / 9	V1 console and local orchestration	Compatible: Task 9 launches Vite directly and verifies read-only Act 1 display.
8 / 11	activity timeline and App tests	Compatible: Task 11 adds one transfer variant while retaining read-only UI constraints.
8 / 12	generic explorer links and Base manifest	Compatible: links derive only from validated confirmed public metadata.
9 / 10	demo-start checkpoint	Compatible: Task 10 begins after the verified V1 tag and does not rewrite it.
9 / 11	Makefile, scan/process gates, prepared V1 state	Compatible: Task 11 verifies before broadcast and runs from the V1 checkpoint.
9 / 12	Makefile, README/runbook, Base-preserving reset	Compatible: the encore remains optional and offline config tests alone join verify.
9 / 13	README/guides, full smoke and tags	Compatible: Task 13 completes claims only from newly observed output.
10 / 11	BankV2, upgrade validation, V2 transfer ABI	Compatible: scripts/UI consume the tested storage-free extension.
10 / 12	V2 upgrade/transfer on Base	Compatible: Task 12 reuses the same V2 implementation with explicit actors/signing.
10 / 13	upgrade proof and V2 learning material	Compatible: documentation is conditioned on final verification evidence.
11 / 12	upgrade/transfer/check scripts, finalizer, Makefile	Compatible: Base branches extend local exact paths without weakening local guards.
11 / 13	Act 2/3 state and event evidence	Compatible: docs consume exact verified proxy/implementation/balance results.
12 / 13	README/runbook and optional encore	Compatible: no public-network execution is required for local completion.
1 self	Exact versions, install, RED/GREEN web scaffold, initial gate	Internally consistent; prior compatibility exceptions are committed and recorded.
2 self	Token tests then minimal token	Internally consistent; deferred NatSpec wording is non-load-bearing and final scan/docs can normalize it.
3 self	Admin tests, initializer, storage, validator	Ruling already recorded: use ReentrancyGuardTransient because pinned validator rejects the inherited ordinary constructor. Cost if wrong: transient-storage behavior would need replacement and revalidation.
4 self	Adversarial tests and exact custody mutations	Internally consistent; rollback and CEI expectations match implementations.
5 self	Three bounded handler actions and three invariants	Internally consistent; deferred actorAt bounds check is non-load-bearing because callers use actorCount.
6 self	Preflight, staging, finalization, exact local smoke	Internally consistent after ruling Base’s fully configured path belongs to Task 12; confirmed files remain untouched until receipt/code validation.
7 self	Separate ABI sync and manifest publishing	Internally consistent: static verification can run without RPC/manifest while live publishing remains explicit.
8 self	Hook states, console regions, read-only prohibition	Internally consistent; all unknown/failure values remain nonzero-fabricating.
9 self	Process ownership, reset scope, V1 docs/tag	Internally consistent; attached processes and second-terminal smoke are compatible with bounded lifecycle checks.
10 self	Storage-free V2, unit/fuzz/upgrade failures	Internally consistent with the actual V1 layout and no unsafe validation bypass.
11 self	V2 invariants, staging/finalizer, scripts, UI	Internally consistent: already-V2 is a non-broadcast no-op, satisfying the spec’s refusal to send a transaction.
12 self	Explicit optional Base encore	Internally consistent: only offline fake-value config tests enter the mandatory gate; real network use requires explicit user choice.
13 self	Final docs, static gate, three-act smoke, cleanup/tag	Internally consistent; documentation claims are gated on fresh observed evidence.