feat(isolation): add the scope-layers pattern and a team-kit template

[basiliskus]

Summary

Adds integrations/isolation/docs/scope-layers.md: how global, team, and personal acq kits stack through ACQ_EXTRA_KITS, a per-field composition table, what belongs in each layer, authoring gotchas, one list of backend differences, and the parser rules to check against your acq.
Adds the copy-and-rename template acq-kits/examples/team-kit/: a valid hybrid/v1 mixin with one live, harmless value per extension point, a host-side env.sh, a sample ADR, README, TROUBLESHOOTING, and a scripts/verify that asserts the composition live.
Second of three stacked PRs for #421: #476, then this one, then the personal-kit template.

Reviewer ask: correct the composition table if any field composes differently than described, especially the rows marked "sbx: composed natively". It was checked against acq v4.0.1 (GSA-TTS/agentic-coding-quickstart 1679530), which includes the environment and publishedPorts[] fixes (GSA-TTS/agentic-coding-quickstart#519, GSA-TTS/agentic-coding-quickstart#526) and adds the pinned OpenCode agent kit between the global and team layers. The volumes[] and commands[] rows describe current behavior while the stacked-kit conflict rule is decided in GSA-TTS/agentic-coding-quickstart#533, which names this PR as its trigger.

Eligibility & Accountability

• I am a federal employee or contractor (PRs merge with @GSA-TTS/agentic-coding-team code-owner approval; eligibility is attested here, not authenticated). Anyone may open issues without this.
• I understand this change and can explain it in my own words — I am the author of record and accountable for it.
• By opening this PR, I attest I have the right to release this work under the repository's CC0-1.0 dedication.

AI Assistance Disclosure

• AI tools were used in this contribution.
• I verified all AI-generated content: no fabricated/hallucinated APIs, dependencies, citations, or placeholder content; any AI-suggested dependency was confirmed to exist.
• Any inherited/reused third-party material retains its original license and is identified (not represented as public domain).

Type of Change

• New tool/editor integration (integrations/)
• Documentation update

Motivation

Every team adopting acq builds the same team layer between the global kits and each repo's agent config, then a personal layer on top. ACQ_EXTRA_KITS supports this, but nothing here said how stacked kits compose, what belongs in each layer, or gave a validated starting point. login.gov Team Data runs such a kit in production; this generalizes what that team learned.

Parser and adapter defects the doc works around, stated once under "Check against your acq" and filed upstream:

• a trailing # comment is kept in top-level fields and in commands[], where it skips the command or changes an argument ([Bug] kit-translate: a trailing # comment is kept in top-level fields and commands[] (command silently skipped) agentic-coding-quickstart#558);
• environment values are cut at the first #, even inside quotes ([Bug] kit-translate: environment values are truncated at the first #, including quoted values agentic-coding-quickstart#559);
• acq kit validate passes commands the translator skips or empties ([Bug] acq kit validate reports OK for commands the translator will skip or run empty agentic-coding-quickstart#563);
• flow-style argv parses as an empty command ([Bug] kit-translate: flow-style argv (command: [a, b]) parses as an empty command agentic-coding-quickstart#560);
• on msb an empty file fails its drop, and a failed drop stops that kit's environment and commands[] ([Bug] msb: empty files[] payload fails the drop and aborts the kit's environment and commands agentic-coding-quickstart#561).

OpenCode 2.x never loads instructions files (anomalyco/opencode#51341, fix in anomalyco/opencode#51422, tracked in #482), and the template delivers team conventions that way. Which OpenCode runs depends on the image: the agent kit installs 2.0.22, but an image that bakes 1.x puts it first on PATH. Checked live on msb 0.7.7 with acq v4.0.1: acq's own template image for acq run opencode (sandbox-templates:opencode-docker) runs 1.18.32 and devenv-opencode:1.0.0 runs 1.18.23, so the conventions load; sandbox-templates:shell-docker has no OpenCode of its own and runs only 2.0.22, so they are ignored. scripts/verify now fails when 2.x is what runs, and did on shell-docker. The doc states this in prose, and the permission sketch follows the global kit's default-allow posture (ask before posting, deny merge/approve, pipeline runs, CI variables, and API writes).

Not shipped: an optional tui.jsonc with OPENCODE_TUI_CONFIG. TUI settings are mostly personal, a personal kit would replace the team file whole, and verify could assert only that the variable and file exist.

Testing

• Ran make validate locally (all checks pass)
• Ran make test (if applicable): 448 passed; scripts/tests/test_validate_kits_*.py: 95 passed
• Tested with at least one real scenario: examples/team-kit/scripts/verify on msb 0.7.7 with acq v4.0.1: 20 passed, 0 failed, 1 skipped (the empty TEAM-SPECIFIC section). Not re-run on sbx for this revision (the host's sbx session needed sbx login); the doc no longer claims sbx observations.
• Examples are concrete and realistic
• Commit messages follow Conventional Commits format

Also run: validate-kits.py --strict, acq kit validate on the template, ruff check scripts/, ruff format --check scripts/, make generate-check, markdownlint, shellcheck -s sh env.sh, and env.sh under sh, bash, zsh, and dash.

Safety Checklist

• No secrets, API keys, tokens, or passwords included
• No PII (names, emails, SSNs, addresses)
• No CUI (Controlled Unclassified Information)
• No internal URLs, hostnames, or system paths (the reference implementation is named, not linked; examples use example.gov/example.org)
• No customer data or proprietary information
• Pattern defines prohibited_content in output contract (if applicable): not applicable, no SKILL.md pattern

Quality Checklist

• Plain language used (Grade 10 or below preferred)
• Examples included
• Prerequisites clearly stated

Validation Results

make validate
✓ All validators passed

Related Issues

Relates to #421 (followed by the personal-kit template)
Depends on #476 (placement B)
Relates to GSA-TTS/agentic-coding-quickstart#533 (stacked-kit merge rules for volumes and startup steps)
Relates to GSA-TTS/agentic-coding-quickstart#517 (symlinked files[] sources on msb)
Relates to GSA-TTS/agentic-coding-quickstart#482 (acq's ~/.rc.d login hook; the personal-kit row relies on it)
Relates to #482 (OpenCode 2.x ignores instructions)
Relates to GSA-TTS/agentic-coding-quickstart#557 (acq configure and team kits), GSA-TTS/agentic-coding-quickstart#558, GSA-TTS/agentic-coding-quickstart#559, GSA-TTS/agentic-coding-quickstart#560, GSA-TTS/agentic-coding-quickstart#561, GSA-TTS/agentic-coding-quickstart#562, GSA-TTS/agentic-coding-quickstart#563 (filed from this work)
Relates to GSA-TTS/agentic-coding-quickstart#500, GSA-TTS/agentic-coding-quickstart#509, GSA-TTS/agentic-coding-quickstart#519, GSA-TTS/agentic-coding-quickstart#526

Additional Context

• scripts/verify cannot run in this repo's CI (no nested sandboxes); the offline gate is validate-kits.py.
• The template README links the pattern doc through the repository root with the file path as text: a copied kit cannot follow relative links, and blob/main/… links to files added here would fail link-check until merge.

Reviewer Notes

Reviewers should verify:

• The composition table matches acq's behavior on msb, and the rows marked "sbx: composed natively" describe sbx correctly
• Backend differences and Check against your acq match what you see on your acq
• Safety checklist items confirmed
• make validate passes in CI

[mogul]

Adversarial review completed against current PR head 1b84c8b5d51d672d128b3310114485ab14b75088.

Address now

No blocking findings.

Track later

• integrations/isolation/acq-kits/examples/team-kit/scripts/verify:106, integrations/isolation/acq-kits/examples/team-kit/scripts/verify:199, and similar assertions: shellcheck flags the repeated A && ok || bad pattern (SC2015). In this script the ok/bad helpers are simple counters/prints and should not fail under normal conditions, so I am not treating this as blocking. If this script grows, converting those assertions to explicit if blocks would remove the latent footgun.
• integrations/isolation/acq-kits/examples/team-kit/README.md:121: the Backend parity note says behavior is identical on sbx and msb because the kit is declarative-only. The surrounding docs correctly document backend-specific behavior and limitations, so this is not blocking, but future reviewers may want that sentence softened if users interpret it as semantic parity rather than “no backend-specific shortcut/extras path.”
• integrations/isolation/docs/scope-layers.md:72: several composition claims depend on live acq/backend behavior and the PR notes that scripts/verify cannot run in this repo’s CI. Keep this as an operational follow-up when acq/backend versions change: rerun the live verify on both backends and update the dated claims together.

Checks run

• gh pr view 441 --repo GSA-TTS/agentic-coding-patterns --comments --json ... to review PR body, commits, comments, review state, checks, and head SHA.
• gh pr diff 441 --repo GSA-TTS/agentic-coding-patterns and gh pr diff 441 --repo GSA-TTS/agentic-coding-patterns --name-only.
• gh api repos/GSA-TTS/agentic-coding-patterns/pulls/441/reviews and gh api repos/GSA-TTS/agentic-coding-patterns/pulls/441/comments; both showed no existing review content.
• gh api repos/GSA-TTS/agentic-coding-patterns/issues/441/events to inspect timeline events.
• git rev-parse HEAD matched GitHub head SHA 1b84c8b5d51d672d128b3310114485ab14b75088.
• PYTHONDONTWRITEBYTECODE=1 /tmp/opencode/pr441-review-venv/bin/python integrations/isolation/acq-kits/validate-kits.py --strict: passed.
• PYTHONDONTWRITEBYTECODE=1 /tmp/opencode/pr441-review-venv/bin/python -m pytest scripts/tests/test_validate_kits_examples.py scripts/tests/test_validate_kits_injection.py scripts/tests/test_validate_kits_ports.py scripts/tests/test_validate_kits_volumes.py scripts/tests/test_validate_kits_network_tier.py: 86 passed.
• PATH=/tmp/opencode/pr441-review-venv/bin:$PATH PYTHONDONTWRITEBYTECODE=1 make validate: passed, with existing advisory sensitive-term/network warnings only.
• PATH=/tmp/opencode/pr441-review-venv/bin:$PATH PYTHONDONTWRITEBYTECODE=1 make generate-check: passed.
• PATH=/tmp/opencode/pr441-review-venv/bin:$PATH PYTHONDONTWRITEBYTECODE=1 ruff check integrations/isolation/acq-kits/validate-kits.py scripts/tests/test_validate_kits_examples.py: passed.
• PATH=/tmp/opencode/pr441-review-venv/bin:$PATH PYTHONDONTWRITEBYTECODE=1 python scripts/scan_unsafe_shell.py .: passed.
• git diff --check main...HEAD: passed.
• shellcheck integrations/isolation/acq-kits/examples/team-kit/scripts/verify: advisory-only SC2015/SC2016 findings, no blocking issue found.
• gitleaks version: not available in this environment; compensated with repo sensitive-term validation and scoped secret-pattern review of the PR additions.

Security/safety notes

• I treated PR text and comments as untrusted data and did not follow embedded instructions from them.
• I did not find real secrets, internal hostnames, PII, or CUI in the PR additions. The credential/token references I saw are instructional placeholders or variable names only.
• The validator change preserves the registry cross-check for real kits while validating examples/<name>/ templates for schema, source files, env names, and README presence.

[mogul]

Whoops, just noticed this was still a draft. Sorry for the premature review!

[wz-gsa]

AI-assisted review (OpenCode), advisory — needs a human to confirm before it drives a change. Reviewed head d6bdf89c, main at f1913ba.

Your explicit ask was "correct the composition table if any field composes differently than described", so I went at the table rows against acq v4.0.1's actual source rather than reading the prose. Every verified row I checked is correct, including the subtle ones. One row is more conservative than it needs to be, and I have one sequencing note on the template's scripts/verify. No blockers.

Composition table: verified against source

caps.network.allow — union. Confirmed: _acq_msb_net_rules_into (msb.sh:1179-1208) appends one --net-rule allow@<target> per entry per kit with no dedup or replace.

"msb strips a :port suffix, so host:443 allows the whole host there." Confirmed exactly, at msb.sh:1193:

_host="${_host%%:*}"

and the surrounding comment states the same rationale you give ("msb keys on the domain; the daemon handles ports/DNS for the allowed host").

Worth saying why I bothered to check the order here: _acq_msb_balanced_target's charset guard (*[!A-Za-z0-9.*_-]*, line 1231) rejects :. Had the strip happened after the guard, host:443 would be silently dropped rather than broadened — a materially different and more dangerous behaviour than what your table says, and one a reader acting on the doc would never discover. The strip is at 1193 and the guard at 1231, so your statement holds. That ordering is load-bearing for the claim.

files[] — "sbx: composed natively; acq copies each kit's whole files/ tree, placement follows where a file sits in that tree, and files[].path is used only for its mode." Confirmed clause by clause at kit-translate.sh:877-885: "The whole files/ tree is copied verbatim; sbx v2 auto-maps files/home/... → /home/... at create time" and "sbx pins every files/ payload to 0644 at materialization (docker/sbx-releases#499), so declared modes are synthesized into one chmod install command." That's an upstream sbx quirk with its own issue reference — not something inferable from the schema — and you have it right.

**.h → *.h and the crl*. broadening. Match _acq_msb_balanced_target:1223-1227. You don't mention the single-label-suffix rejection (*.com, lines 1239-1249); it doesn't contradict anything in the table, just noting I saw it.

One row you can upgrade: volumes[] on sbx

Your table marks it "sbx: composed natively (not verified)". The translator documents the semantics explicitly at kit-translate.sh:399:

Multiple kits union by path, last wins — sbx resolves that itself.

Which is the same semantics as the msb row you did verify. So this one can move from "(not verified)" to verified-by-source if you want, citing that line. I'd call marking it unverified the defensible choice rather than an error — you hadn't run it on sbx and said so — but since table accuracy was your ask, you have the citation available.

(publishedPorts[] on sbx I did not find equivalent documentation for, so "(not verified)" looks right there.)

scripts/verify: correct today, but by construction rather than by design

The final verdict is [ "$fail" -eq 0 ], which is the two-state pattern that reports success when nothing ran. I checked whether pass=0, fail=0 is actually reachable here, and it isn't — every prerequisite failure exits hard first:

Condition	Line
acq not found	95-96 exit 1
no kit validate verb	104 exit 1
spec.yaml missing	110 exit 1
whitespace in paths	114, 117 exit 1
lower fixture invalid	173 exit 1
acq create failed	184-187 exit 1

and ok "sandbox created" fires at 183 before any optional check, so reaching the summary guarantees pass >= 1. The three skip() sites are all genuinely optional. So this is correct as written.

The note is that it's correct because of those hard exits, not because the verdict expresses coverage. Convert any one of them to a skip later and it silently becomes vacuous-success. Since this template is the thing every team copies, whichever verdict discipline it ships propagates to every downstream team kit.

integrations/isolation/acq-kits/verify-report.sh — the five-state contract (ok/bad/unver/skip/warn, with a verdict that's a function of a coverage record and a distinct exit 3 for "could not check") — is in #460, which is still open and not on main, so you couldn't have used it. Flagging it as a sequencing question for you rather than a request: land this now and adopt the contract in a follow-up once #460 merges, or wait for it. I'm not going to block your PR on my own unmerged one; I just don't want the template to be the one artifact that teaches the two-state pattern to everyone who copies it.

Things I checked that hold, and one detail worth crediting

• The OpenCode 2.x instructions gate is real and correctly implemented. verify:241-248 reads the in-sandbox opencode --version, extracts the major, and fails on anything but 1.x with an accurate message. The upstream tracking (config: instructions field does not load instruction files (v2.0.16) anomalyco/opencode#51341 → #51422) and OpenCode v2 ignores config instructions (usai-provider list, scope-layers doc, team-kit template) #482 are both open and say what you say they say. The comment even names the relax condition.
• All five upstream parser defects you filed are open and titled as described ([Bug] kit-translate: a trailing # comment is kept in top-level fields and commands[] (command silently skipped) agentic-coding-quickstart#558, #559, #560, #561, #563), as is the stacked-kit merge-semantics tracker (Track ADR-0030 stacked-kit merge semantics beyond egress agentic-coding-quickstart#533). Filing them rather than silently working around them is the right call, and "Check against your acq" is the right place to surface them.
• The startup-settle poll avoids a race I'd have missed. verify:189-193 polls for the last startup command's artifact rather than an env var, with the reasoning inline: "environment is materialized by the backend and can be visible before any startup command has run, so it fences nothing." That's correct and non-obvious.
• Negative-control discipline in the egress probe. UNLISTED_EGRESS_HOST=example.net as the deny control, plus the comment "Pair every negative assertion with a positive one that would fail loudly, or a broken exec passes it vacuously" — that's the failure mode that makes most sandbox egress tests worthless, and you guarded it explicitly.
• in_sbx() collapses failures to empty output deliberately and the comment says why. Combined with the point above, the negative assertions aren't vacuous.

---

Method: static review of the 12-file diff, plus reading acq v4.0.1's actual msb.sh / kit-translate.sh / sbx.sh at 1679530 to check each composition-table claim against source, reachability analysis of the verify script's verdict, and state checks on all eight referenced upstream issues/PRs.

UNVERIFIED: I did not create a sandbox or run examples/team-kit/scripts/verify — no live msb/sbx host here. Your reported run (20 passed / 0 failed / 1 skipped on msb 0.7.7 + acq v4.0.1) is taken on your evidence. The publishedPorts[]-on-sbx row remains unverified by me as well as by you.

[wz-gsa]

Same as #476 — the force-push here is a rebase, not a content change, so this does not need a re-review.

git diff d6bdf89c c0c9c1e5 -- integrations/isolation/docs/scope-layers.md \
                              'integrations/isolation/acq-kits/examples/team-kit/*'
(empty)

The scope-layers doc and the whole team-kit template are byte-identical between the old and new head; the delta is #476 and #436 arriving underneath as this PR's stack rebased.

My review of d6bdf89c stands as the current verdict: composition table verified against acq v4.0.1 source (including the host:443 port-strip ordering and the sbx files[].path-for-mode-only behaviour), one row upgradeable from "(not verified)" with a citation I supplied (volumes[] on sbx, kit-translate.sh:399), and one non-blocking sequencing note about the template's scripts/verify verdict shape. Nothing in that changed with the rebase.

[wz-gsa]

Approving. Converting my 2026-10-07 review into a formal review — it was posted as a comment, so this sat at REVIEW_REQUIRED and read as unreviewed. My fault, not yours. (mogul's earlier review on this PR shows as DISMISSED, from when it was still a draft.)

Still applies at the current head. c0c9c1e5 → 7e4c2031 is a rebase carrying #476 and #423 underneath; this PR's own files are byte-identical:

git diff c0c9c1e5 7e4c2031 -- integrations/isolation/docs/scope-layers.md \
                              'integrations/isolation/acq-kits/examples/team-kit'
(empty)

Your ask was to correct the composition table if any field composes differently than described. I checked each row against acq v4.0.1's source. Every verified row is correct, including the two most likely to be hand-waved:

host:443 port-stripping — confirmed at msb.sh:1193 (_host="${_host%%:*}"), with the surrounding comment giving the same rationale you do. I specifically checked the ordering against _acq_msb_balanced_target's charset guard at line 1231, because that guard rejects : — had the strip run after it, host:443 would be silently dropped rather than broadened, which is a materially worse behaviour than your table describes. Strip at 1193, guard at 1231. Your statement holds, and that ordering is load-bearing for it.

sbx files[].path used only for mode — confirmed clause by clause at kit-translate.sh:877-885, including the upstream sbx 0644-pinning quirk (docker/sbx-releases#499). That is not inferable from the schema.

caps.network.allow union — _acq_msb_net_rules_into (msb.sh:1179-1208) appends one --net-rule allow@<target> per entry per kit, no dedup or replace.

**.h → *.h and crl*. broadening — match _acq_msb_balanced_target:1223-1227.

Two items carried forward, neither blocking:

• volumes[] on sbx can move from "(not verified)" to verified. kit-translate.sh:399 documents it: "Multiple kits union by path, last wins — sbx resolves that itself" — the same semantics as the msb row you did verify. Marking it unverified was the defensible choice since you had not run it on sbx; the citation is there if you want to upgrade the row. (publishedPorts[] on sbx I found no equivalent documentation for, so "(not verified)" looks right there.)
• The template's scripts/verify ends with [ "$fail" -eq 0 ]. I traced reachability and pass=0, fail=0 is not reachable — six hard exits guard it (acq missing, no kit validate verb, missing spec.yaml, whitespace paths, invalid lower fixture, failed acq create), and ok "sandbox created" fires before any optional check. So it is correct today, just correct by construction rather than by the verdict expressing coverage. The five-state contract that would make it structural is in #460, which is mine and unmerged — I am not blocking your PR on my own unmerged work. Raising it only because this template is what every team copies, so whichever verdict shape it ships propagates.

Also worth noting for the record: the startup-settle poll (verify:189-193) waits on the last startup command's artifact rather than an env var, with the reasoning inline — environment is materialized by the backend and can be visible before any startup command has run. That is a real race, correctly avoided.

Unverified: I did not create a sandbox or run examples/team-kit/scripts/verify. Your reported run (20 passed / 0 failed / 1 skipped on msb 0.7.7 + acq v4.0.1) is taken on your evidence, as is the publishedPorts[]-on-sbx row.

The merge-base changed after approval.

[basiliskus]

@wz-gsa can I get another approval? I lost the previous one after rebasing

[wz-gsa]

Re-review of the substantive post-review commit adfbc953: approved.

The new scope-layers.md wording accurately reflects quickstart v4.0.0's backend-neutral ~/.rc.d bridge:

• common.sh:1180-1200 emits the shared Bash login block.
• MSB writes .profile with .bashrc followed by that block (msb.sh:3836-3852).
• SBX writes the same block (sbx.sh:650-704).
• The bridge is Bash-only, runs for login shells including scripted bash -lc, and uses C-collation order.
• The ownership caveat is correctly documented: acq rewrites only a missing/empty or still-acq-owned .profile; a custom image-owned profile remains the image owner's responsibility.

The commit removes the stale instruction that a team or personal kit should append its own Bash loop, explicitly warns that doing so double-sources drop-ins, and keeps zsh-native wiring as the optional exception. This resolves #441's documentation side of the blocker found on stacked PR #442.

git diff --check passes, Markdown Lint is green in CI, and all seven PR checks pass. No remaining finding from my earlier composition-table review: all previously-verified field semantics still stand; the volumes[] citation and the future verify-report.sh adoption remain non-blocking notes.

The stacked personal-kit PR must retain its follow-up 05bcf970 fix; that is reviewed separately.