import InfoBox from '../components/InfoBox.astro';
import Figure from '../components/Figure.astro';

The devcontainer's [firewall](/posts/moving-into-the-devcontainer#the-firewall-has-a-lifecycle-too), its [shared MCP server wiring](/posts/healthy-before-active#an-installation-is-not-a-health-check) across three agent CLIs, its [developer-CLI update policy](/posts/developer-cli-auto-updates#one-manifest-for-every-developer-cli), its SSH signing setup, and its build ordering had all been shaped by real incidents over months, but none of that reasoning lived anywhere but scattered commit messages and a running list of day-to-day gotchas. A wayfinder map set out to convert five of those areas into permanent architecture decision records in a single session, plus a separate, genericized version meant to travel outside this project entirely.

Eleven tickets ran through six background agents in true parallel, each dispatched into its own freshly created git worktree branched straight off the main branch, so no two agents ever shared a working directory or a checked-out branch. One of the two research tickets defensively built a further nested worktree partway through its own task, having noticed the shared session worktree's checked-out branch had briefly changed underneath it, evidence of another concurrent session touching the same machine at the same time. That near-miss became a design constraint for the six-way dispatch that followed rather than a one-off scare to shrug off.

<Figure caption="Six agents dispatched into six parallel worktrees, each branched from main, converging into two destination branches: one for repository ADRs (to be merged), one for genericized skill and retrospective (external, not merged).">

```mermaid
gitGraph
  accTitle: Six agents working in parallel on dev-environment documentation
  accDescr: Six agents each branch from main into their own worktree. Their work converges into two destination branches: one for repository ADRs to be merged, another for external skill and retrospective not meant for this repository.
  commit id: "main"
  
  branch adr/firewall
  commit id: "Firewall allowlist"
  
  branch adr/mcp-wiring
  commit id: "MCP wiring guide"
  
  branch adr/cli-lifecycle
  commit id: "CLI lifecycle"
  
  branch adr/signing
  commit id: "SSH signing setup"
  
  branch adr/build-ordering
  commit id: "Build ordering"
  
  branch research/nested-worktree
  commit id: "Worktree nesting research"
  
  checkout main
  branch docs/adr-bundle
  
  checkout adr/firewall
  checkout docs/adr-bundle
  merge adr/firewall
  
  checkout adr/mcp-wiring
  checkout docs/adr-bundle
  merge adr/mcp-wiring
  
  checkout adr/cli-lifecycle
  checkout docs/adr-bundle
  merge adr/cli-lifecycle
  
  checkout adr/signing
  checkout docs/adr-bundle
  merge adr/signing
  
  checkout adr/build-ordering
  checkout docs/adr-bundle
  merge adr/build-ordering
  
  checkout research/nested-worktree
  checkout docs/adr-bundle
  merge research/nested-worktree
  
  checkout main
  branch external/skill-and-retrospective
  commit id: "Skill + retrospective"
  commit id: "(not merged to repo)"
```

</Figure>

The tickets' output split into two branches on purpose, decided before any writing started. Five ADR files, ordinary repository documentation, went onto a normal feature branch to be reviewed and merged like anything else. A second bundle, a genericized reusable setup skill for future projects and a full retrospective write-up explicitly outside this project's own posting pipeline, went onto a branch never meant to merge into this repository at all. Mixing permanent internal history with disposable public-facing drafts on the same branch would have made review of either one harder than reviewing them apart.

<InfoBox title="What incident-driven documentation looks like">
One ADR records a firewall allowlist that lives in two separate scripts by necessity: one runs once at container start, the other loops continuously to keep pace with a CDN's rotating IPs. A domain added to only one of the two was silently dropped by the other on its next cycle, twice, each time breaking the container's own git and package-manager traffic mid-session with no error at the point of failure. Both incidents were already fixed; the ADR's job was writing down why the fix looks the way it does, not proposing a new one.
</InfoBox>

Each agent scrubbed its own category for anything project-identifying before closing its own ticket, and a final consolidation pass still ran a systematic sweep afterward, project and organization names, links back into this repository, environment-variable names, secret-shaped strings, the same category of check any writing meant to leave this project has to clear before anyone reads it externally. The sweep, plus a full read-through of everything staged for outside use, came back clean.

The five ADRs merged as one ordinary pull request. The staged skill package and retrospective sit untouched on their own branch, waiting on someone to review and migrate them out by hand, a deliberately slower and more manual path than the one this documentation itself just went through.