branchbox-devcontainer-guardrails

name	branchbox-devcontainer-guardrails
description	Use when modifying BranchBox devcontainer/bootstrap workflows, compose templates, feature env-stash behavior, or manual E2E harness/release docs. Apply issue
metadata	{"author":"branchbox"}

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.

---

Source: branchbox/branchbox — distributed by TomeVault.