branchbox-devcontainer-guardrails

Use when modifying BranchBox devcontainer/bootstrap workflows, compose templates, feature env-stash behavior, or manual E2E harness/release docs. Apply issue #45 guardrails for 1Password PAT plus SSH signing on Docker Desktop macOS, and run the required validation matrix before PR or release prep.

BranchBox Devcontainer Guardrails

Follow this skill for changes in these areas:

  • core/src/bootstrap/**
  • core/src/workflows/feature.rs
  • core/src/modules/compose.rs
  • scripts/manual-*.sh and scripts/manual-*.md
  • docs/docs/getting-started/manual-*.md

Load references before implementing:

  • Read references/gotchas.md for known failure patterns and fixes.
  • Read references/validation-checklist.md for exact test commands and required scope.

Classify the change

  • Identify whether the change impacts auth/signing bootstrap, compose behavior, feature env/stash logic, or harness/docs.
  • Treat any change in these areas as release-sensitive and run the full validation checklist.

Implement with guardrails

  • Keep host secret retrieval in initializeCommand and container setup in postStartCommand.
  • Keep 1Password PAT/signing key flow file-based; do not rely on SSH-agent socket forwarding on Docker Desktop macOS.
  • Ensure mounted secret files exist before compose startup.
  • Preserve existing secret files on 1Password read failures (temp file + atomic move; never truncate-first).
  • Treat empty/whitespace secrets from op read as failed refreshes and keep existing files.
  • Create secret temp files with restricted permissions from creation (umask 077) before writing.
  • Enforce owner-only permissions (0600) for host-side token/signing files.
  • Keep secret mount files ignored by git and generated by init/bootstrap flows.
  • Do not interpolate raw token values into persisted shell snippets; prefer runtime env vars (GH_TOKEN) in credential helpers.
  • Keep compose templates worktree-safe (no fixed compose project/container names).
  • Keep compose command compatibility (docker compose with fallback to docker-compose).
  • Keep feature workflow robust when .env is absent and when untracked files exist.
  • Sanitize untrusted env-derived values before writing generated env files; keep policy-specific allow-lists (APP_URL, GIT_BRANCH, COMPOSE_PROJECT_NAME).
  • Compute compose identity once and reuse it for process env + generated files to avoid drift.
  • Keep harness service resolution tolerant of JSONC comments and multi-stack compose templates.
  • Extract duplicated harness helpers into scripts/lib/*.sh instead of copy/paste between scripts.

Validate before handoff

  • Run ./scripts/review-preflight.sh first to catch security/sanitizer/docs-sync regressions early.
  • Run devcontainer-side Rust checks and harness matrix from references/validation-checklist.md.
  • Run host-side checks when required (docs build, Swift checks, and 1Password E2E harness).
  • Run security/robustness preflight checks from references/validation-checklist.md (secret permissions, no token interpolation, env-write sanitization, compose fallback, JSONC-safe parsing).
  • Run a duplication check for harness helpers and keep shared docs as plain synchronized files (no symlink-only assumptions).
  • Treat failing validation as a blocker unless the failure is unrelated and documented with evidence.

Update docs in the same change

  • Update CHANGELOG.md when behavior changes.
  • Keep script docs and docs-site pages synchronized for the same harness.
  • Update AGENTS.md when new project-level expectations are introduced.