Merge pull request 'architect: supervisor project-wide oversight' (#32) from architect/supervisor-project-wide-oversight into main

sprints/supervisor-project-wide-oversight.md

@@ -0,0 +1,42 @@
+# Sprint: supervisor project-wide oversight
+
+## Vision issues
+- #540 — supervisor should have project-wide oversight, not just self-monitoring
+
+## What this enables
+After this sprint, the supervisor can:
+1. Discover all Docker Compose stacks on the deployment box — not just the disinto factory
+2. Attribute resource pressure to specific stacks — "harb-anvil-1 grew 12 GB" instead of "disk at 98%"
+3. Surface cross-stack symptoms (restarting containers, unhealthy services, volume bloat) without per-project knowledge
+4. Coordinate remediation through vault items naming the stack owner, rather than blindly pruning
+
+This turns the supervisor from a single-project health monitor into a deployment-box health monitor — critical because factory deployments coexist with the projects they supervise.
+
+## What exists today
+- preflight.sh (227 lines) — already collects RAM, disk, load, docker ps, CI, PRs, issues, locks, phase files, worktrees, vault items. Easy to extend.
+- run-supervisor.toml — priority framework (P0-P4) with auto-fix vs. vault-item escalation. New cross-stack rules slot into existing tiers.
+- Edge container — has docker socket access, docker CLI installed. Can run docker compose ls, docker stats, docker system df.
+- projects/*.toml — per-project config with [services].containers field. Could be extended for sibling stack ownership.
+- AD-006 — external actions go through vault. Supervisor reports foreign stack symptoms but does not auto-remediate.
+- docker system prune -f — already runs as P1 auto-fix. Currently affects all images symmetrically (the problem this sprint solves).
+
+## Complexity
+- Files touched: 3-4 (preflight.sh, run-supervisor.toml, projects/*.toml schema, new knowledge/sibling-stacks.md)
+- Subsystems: supervisor only — no changes to other agents
+- Estimated sub-issues: 5-6
+- Gluecode vs greenfield: 80/20 (extending existing preflight sections and priority rules vs. stack ownership model)
+
+## Risks
+1. Docker socket blast radius — mitigated by read-only discovery commands; write actions stay vault-gated for foreign stacks.
+2. docker system prune collateral — scoping prune to disinto-managed images requires label-based filtering (com.disinto.managed=true), factory images need labeling first.
+3. Performance of docker stats — mitigated by --no-stream --format for a single snapshot.
+4. Stack ownership ambiguity — no standard way to identify who owns a foreign compose project. Design fork needed.
+
+## Cost — new infra to maintain
+- No new services, cron jobs, or containers. Extends the existing supervisor.
+- New knowledge file: knowledge/sibling-stacks.md (low maintenance).
+- Optional TOML schema extension: [siblings] section in project config.
+- Image labeling convention: com.disinto.managed=true on factory Dockerfiles and compose.
+
+## Recommendation
+Worth it. Addresses a real incident (harb-dev-box 98% disk), mostly gluecode extending proven patterns, adds no new services, directly supports Foundation milestone. The one-box-many-stacks model is the common case for resource-constrained dev environments.