Repair scratch setup preflight for repo-local host processes

docs/implplan/SPRINT_20260311_010_Platform_scratch_setup_revalidation.md

@@ -0,0 +1,71 @@
+# Sprint 20260311_010 - Platform Scratch Setup Revalidation
+
+## Topic & Scope
+- Validate the documented Stella Ops scratch setup path against a fully wiped local Docker state.
+- Remove Stella-only containers, images, volumes, and networks, then rerun the repo setup path as a first-time operator would.
+- If bootstrap defects surface, triage root cause and fix them cleanly before declaring the setup path healthy.
+- Working directory: `.`.
+- Expected evidence: scoped Docker wipe, setup-script execution evidence, root-cause notes for any bootstrap failures, and a local commit if code/docs change.
+
+## Dependencies & Concurrency
+- Depends on no other agent actively using the local Stella Docker stack.
+- Safe parallelism: none during the wipe/rebuild itself because the environment reset is global.
+
+## Documentation Prerequisites
+- `AGENTS.md`
+- `docs/dev/DEV_ENVIRONMENT_SETUP.md`
+- `docs/INSTALL_GUIDE.md`
+- `docs/implplan/SPRINT_20260309_001_Platform_scratch_setup_bootstrap_restore.md`
+
+## Delivery Tracker
+
+### PLATFORM-SCRATCH-001 - Wipe Stella Docker state only
+Status: DONE
+Dependency: none
+Owners: QA, 3rd line support
+Task description:
+- Tear down the Stella compose stack and remove Stella-specific images, volumes, and networks without touching unrelated Docker assets on the machine.
+
+Completion criteria:
+- [x] Stella compose services are stopped.
+- [x] Stella-specific images, volumes, and networks are removed.
+
+### PLATFORM-SCRATCH-002 - Re-run documented setup from zero state
+Status: DONE
+Dependency: PLATFORM-SCRATCH-001
+Owners: QA
+Task description:
+- Run the repo setup path from the documented entrypoint and capture the first blocking failure or a successful end-to-end bootstrap.
+
+Completion criteria:
+- [x] The documented setup command is executed from wiped state.
+- [x] The first-run result is captured with concrete evidence.
+
+### PLATFORM-SCRATCH-003 - Repair any bootstrap regression cleanly
+Status: DONE
+Dependency: PLATFORM-SCRATCH-002
+Owners: Product Manager, Architect, Developer
+Task description:
+- If the scratch setup exposes a real bootstrap defect, fix the root cause in scripts/docs/code, then rerun the setup path until the documented flow converges again.
+
+Completion criteria:
+- [x] Any exposed setup regression has a root-cause fix.
+- [x] Docs/sprint notes reflect the repaired bootstrap path.
+- [x] The repair is committed locally if code/docs changed.
+
+## Execution Log
+| Date (UTC) | Update | Owner |
+| --- | --- | --- |
+| 2026-03-11 | Sprint created to revalidate the Stella scratch setup path after the latest runtime/action sweeps on the warm stack came back clean. | QA |
+| 2026-03-11 | Completed a Stella-only Docker wipe and reran `scripts/setup.ps1` from zero state. The first real blocker was not Docker or compose; three leaked repo-local `StellaOps.Graph.Api.exe` processes from earlier host debugging locked `src/Graph/StellaOps.Graph.Api/bin/Debug/net10.0/*` and caused the Graph solution build to fail inside the documented setup path. | QA |
+| 2026-03-11 | Root cause classified as a bootstrap-preflight gap, not a Graph runtime defect: the documented setup/build path did nothing to clear repo-local host-run Stella services before rebuilding all module solutions. Added repo-scoped host-process cleanup to the setup/build preflight and aligned the bash path with the same behavior. | Developer |
+| 2026-03-11 | Revalidated the repaired bootstrap path on the rebuilt local stack and continued the live route/action sweeps from that clean baseline; the setup contract now converges without manual PID cleanup. | QA |
+
+## Decisions & Risks
+- Decision: keep the wipe scoped to Stella-labeled compose resources and `stellaops/*` images so unrelated local Docker work is not disturbed.
+- Risk: scratch rebuilds are long-running by nature; if a bootstrap failure appears, capture the first blocker and fix it before attempting to optimize further.
+- Decision: scratch setup now stops only repo-local host-run Stella processes before the solution build, because lingering debug services invalidate the documented bootstrap contract but should not require the operator to hunt PIDs manually.
+- Risk: forcibly terminating repo-local host services during setup would be surprising if applied to arbitrary processes, so the cleanup is scoped to commands or executables rooted under this repository and containing `StellaOps.`.
+
+## Next Checkpoints
+- Archived by the follow-on local commit once the scoped setup repair is recorded.