[Cedric Vidal (cedricvidal)]

Summary

Docker Desktop and Podman Machine can store images, writable layers, build cache, and named volumes inside a VM or separate runtime filesystem. That storage can be exhausted independently of apparent host free space, causing a large clean Scope build to fail deep into package installation or compilation even when the host still reports ample capacity.

This final stack layer is intentionally documentation and AI-agent guidance only. It adds inspection-first contributor guidance in CONTRIBUTING.md and concise enforcement rules in AGENTS.md: inspect and report runtime/VM capacity before a large clean rebuild; identify only Scope/worktree-specific resources; require explicit user approval before targeted cleanup; warn that named volumes may contain MongoDB, Azurite, authentication, gateway-build, or worker-workspace data; and prohibit automatic broad pruning, wildcard deletion, or removal of unrelated resources. It does not add runtime enforcement, automatic cleanup, build-progress UX, Docker-context validation, or other application behavior.

This is the sixth and final dependent layer of native stack #1610. It targets cedricvidal-fix/remove-portal-git-lookup at synchronized base ccacccc37c46cfca29094cb0f5e4a197bc657d2b; current head is ce5840588da7bee556dfa73054fcc2b7ce0499b2.

Demos

N/A — documentation and AI-agent instructions only.

Before

N/A

After

N/A

Testing

• PASS pnpm headers:check — all 969 in-scope files have the required license header.
• PASS git diff --check origin/cedricvidal-fix/remove-portal-git-lookup...HEAD on the final synchronized base.
• PASS focused documentation safety checks — the CONTRIBUTING.md#prepare-container-storage-for-a-clean-rebuild heading exists, the AGENTS.md link resolves to it, approval/named-volume warnings remain present, and the layer diff relative to the final base is documentation-only: AGENTS.md (+9) and CONTRIBUTING.md (+84).
• PASS read-only Docker-compatible inspections on Docker 29.5.0 targeting the Podman context: docker context show, docker info --format 'DockerRootDir={{.DockerRootDir}}', docker system df, and docker system df -v.
• PASS native Podman 5.8.2 inspections: podman machine list, podman system df, podman system df -v, and podman machine ssh "$machine_name" df -h / /var /var/lib/containers.
• PASS Compose-resource inspection syntax and filters: Compose project label filters were exercised against existing Compose-managed containers/volumes, and docker compose images --help verified the documented image command. The first documentation validation occurred before this worktree had generated .env, so that worktree-specific sequence was syntax/filter-validated rather than executed end to end; subsequent cumulative acceptance generated the worktree project name.
• PASS exact-resource cleanup syntax verified from installed Docker and Podman CLI help: container, image (--no-prune), and volume removal by explicit ID/name. No destructive cleanup command was run.
• PASS synchronized stack regression suite: pnpm exec vitest run scripts/docker-compose.test.ts scripts/register-agent.test.ts scripts/verify-dev-stack.test.ts apps/portal/src/lib/build-metadata.test.ts --reporter=default — 4 files, 36 tests passed after the corrected readiness lifecycle was merged.
• PASS final-base CI — Pull Request Labeler, both gitleaks checks, and CLA completed successfully. Expected Daily Test Improver jobs are skipped.
• PASS merged Compose/static cumulative checks from the top branch: gateway CPU limit resolves to null, memory to 2 GiB, health start period to 600 seconds; registration uses pinned mikefarah/yq:4.54.1 with no runtime registration apk add; package bootstrap fell back from Corepack to pinned pnpm 10.29.1 through the package registry and succeeded; optional native dependency output contained no cpu-features, ssh2, ERR_PNPM, or optional-build failure; Portal regression asserts no runtime execSync or git rev-parse lookup.
• LIMITATION final warmed-cache acceptance ran from exact local/remote head 1fed733328dccc0bdc9aad59d695571066b2e4fc using GITHUB_TOKEN="$(gh auth token)" pnpm docker:dev:copilot. Preflight showed the Podman VM had 101 GiB free. The command was allowed to make build progress for 30 additional minutes without pruning or --no-cache; the corrected readiness lifecycle did not emit the earlier premature not-created failure. Podman built/tagged the Portal image and progressed through parallel Judge, report-generator, scheduler, post-processor, and model-scanner TypeScript build stages. At the bound, the final active stage was pnpm --filter shared build && pnpm --filter telemetry build && pnpm --filter model-scanning build && pnpm --filter model-scanner-copilot build, with model-scanner-copilot running tsc. No worktree Compose container or named volume had yet been created, so published Portal/API/gateway probes, registration runtime logs, Copilot queue/Mongo readiness, and a pending → processing → done run could not be completed; no run/request ID exists. The acceptance process was stopped, useful images/cache were preserved, unrelated resources were untouched, and a final VM df probe timed out under residual runtime load.

Documentation and compatibility

Updated CONTRIBUTING.md with detailed safe preparation guidance and AGENTS.md with concise AI-agent rules linking to that section. The change is documentation-only and introduces no runtime, API, CLI, dependency, migration, deployment, or compatibility change. No upgrade step is required.

Checklist

• If Portal features changed, keep CLI capabilities in sync. — N/A (no Portal feature change)
• If Portal components changed, update their Storybook stories. — N/A (no Portal component change)
• If database changes require a migration, include up() / down() and keep it CosmosDB-compatible. — N/A (no database change)
• If dependencies changed, update the lockfile and regenerate NOTICE / NOTICE-REVIEW.txt with pnpm notice as needed. — N/A (no dependency change)
• Video showing the behavior before the suggested change — N/A (documentation-only)
• Video showing the behavior after the suggested change — N/A (documentation-only)

[github-actions]

Test Results (Node.js 22)

test: Run #503

Tests 📝	Passed ✅	Failed ❌	Skipped ⏭️	Pending ⏳	Other ❓	Flaky 🍂	Duration ⏱️
3253	3253	0	0	0	0	0	1m19s

🎉 All tests passed!

Github Test Reporter