test: project-scope distribution — beads-config across mixed subrepos

[arcaven]

Context

sideshow init --scope project landed on main (b9394f7). This distributes pack artifacts to all subrepos listed in repos.yaml. The first real pack is beads-config — distributes bd hooks, rules, CLAUDE.md sections, symlinks, and gitignore entries.

What to test

An aae-orc checkout with mixed subrepo state:

• Some repos have existing .beads symlinks and .gitignore entries (manually created)
• switchboard has a full _bmad/ install (68 commands, _bmad-custom/, _bmad-output/)
• ThreeDoors has .claude/settings.json with a PreToolUse hook
• Most repos have hand-authored CLAUDE.md files
• Some repos (ai, ourbot, akey, director) may have minimal or no .claude/ setup

Steps

1. Update sideshow

cd sideshow
git pull
go build -o sideshow ./cmd/sideshow/
# or: brew upgrade sideshow (once tap CI completes)

2. Install the beads-config pack

cd /path/to/aae-orc
./sideshow/sideshow install beads-config --from _packs/beads-config --yes --no-permissions
./sideshow/sideshow list   # should show bmad + beads-config

3. Dry-run first

./sideshow/sideshow init --scope project --dry-run

Check:

• All present subrepos listed with per-artifact status
• Absent repos (director if not cloned) show "not cloned (skipped)"
• Existing .beads symlinks show - (skipped, already correct)
• Existing .gitignore entries show - (skipped, already present)
• No files actually created (verify with git status after)

4. Apply for real

./sideshow/sideshow init --scope project

Check per artifact type:

• Rules (.claude/rules/task-workflow.md): Created in each repo with <!-- managed by sideshow:beads-config:1.0.0 --> marker as first line
• Hooks (.claude/settings.json): Created or merged with SessionStart and PreCompact hooks in Claude Code's nested format (matcher + hooks array)
• CLAUDE.md injection: Section appended between <!-- sideshow:beads-tracker:begin --> and <!-- sideshow:beads-tracker:end --> markers. Existing content preserved.
• Symlinks (.beads): Skipped where already correct, created where missing
• Gitignore (.beads): Skipped where already present, appended where missing

5. Mixed-state edge cases

• ThreeDoors: settings.json should have BOTH its existing PreToolUse hook AND the new SessionStart/PreCompact hooks. Permissions section untouched.
• switchboard: Existing _bmad/, _bmad-custom/, _bmad-output/ dirs untouched. New beads artifacts added alongside.
• Repos with hand-authored CLAUDE.md: Original content intact, beads section appended at end with markers.

6. Idempotency

./sideshow/sideshow init --scope project   # run again

• All artifacts show skipped or no-op (no duplicate hooks, no duplicate CLAUDE.md sections, no duplicate gitignore lines)
• settings.json not bloated with repeated entries

7. Start a Claude session in a subrepo

cd forestage   # or any subrepo
# start a new Claude Code session

• bd prime fires on session start (from the hook)
• Agent can see the beads-tracker section in CLAUDE.md
• Agent can run bd ready, bd show, etc. (symlink works)

8. Registry verification

cat ~/.local/share/sideshow/registry.yaml

• projects: section exists with UUID matching .sideshow/project.yaml
• Installation root path recorded
• Per-repo artifact ledger populated

Failure reporting

If anything behaves unexpectedly, report:

1. Which step failed
2. The exact command output
3. The state of the affected file before and after (if applicable)
4. git diff in the affected subrepo

Files of interest

File	Purpose
_packs/beads-config/pack.yaml	Pack manifest with distribute section
.sideshow/project.yaml	Project identity (UUID)
repos.yaml	Subrepo registry
~/.local/share/sideshow/registry.yaml	Distribution ledger

[arcavenai]

Test blocked — missing prerequisites

Attempted to run the test plan. Step 1 passes (sideshow 0.1.0-alpha.20260412.024603.bd9bf88 is ahead of b9394f7). Steps 2+ cannot proceed:

1. _packs/beads-config does not exist

The test plan references:

./sideshow/sideshow install beads-config --from _packs/beads-config --yes --no-permissions

But _packs/beads-config/ does not exist anywhere in aae-orc (checked main @ cc5597d). There's no _packs/ directory at all. The pack manifest (pack.yaml) and its artifacts (rules, hooks, CLAUDE.md sections, symlink targets) need to be created before this test can run.

Question: Where should _packs/beads-config come from? Is it something sideshow should scaffold (sideshow pack init beads-config?), does it live in a different repo, or does it need to be authored manually?

2. .sideshow/project.yaml does not exist

Step 3 references .sideshow/project.yaml (project identity with UUID), but this file doesn't exist in aae-orc. The --scope project flag presumably needs this to identify the project and record distribution state.

Question: Does sideshow init --scope project create this file if missing, or is there a separate sideshow project init step that should precede the test plan?

3. No bmad coverage in this test

This test plan validates beads-config distribution only. bmad is mentioned only as pre-existing state that should survive untouched (step 5, switchboard edge case). There's no test for:

• sideshow init --scope project distributing bmad artifacts to subrepos
• bmad commands syncing across subrepos after project-scope init
• Whether bmad's existing per-repo _bmad/ installs conflict with sideshow's distribution model

If sideshow init --scope project is meant to distribute all installed packs (not just beads-config), the test plan should verify bmad distribution alongside beads-config. If it only distributes packs that declare a distribute section in their pack.yaml, then bmad's pack.yaml needs to be checked for that section — and if absent, a separate test should cover bmad distribution when/if it's added.

Current state

sideshow list:
  bmad 6.3.0 (installed, 0 commands synced)

aae-orc:
  _packs/          — does not exist
  .sideshow/       — does not exist

[arcavenai]

Additional: bmad source repos available for testing

In addition to the installed bmad 6.3.0 pack, two source repos are available locally:

• ~/work/bmad-master/ — bmad 6.3.0 install (the --from source used with sideshow install)
• ~/work/BMAD-METHOD/ — upstream source repo (bmad-code-org/BMAD-METHOD)

These are available if needed when designing the bmad project-scope distribution test plan (see our earlier comment requesting bmad test coverage alongside beads-config).