fix(bin): install worktree dependencies in ship briefs before tooling#691
Open
Boxyboxy wants to merge 4 commits into
Open
fix(bin): install worktree dependencies in ship briefs before tooling#691Boxyboxy wants to merge 4 commits into
Boxyboxy wants to merge 4 commits into
Conversation
5 tasks
… architecture guide
Boxyboxy
force-pushed
the
fm/brief-deps-boot-q4
branch
from
July 19, 2026 00:43
ecdd6bb to
bf15ce2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
Ensure every rendered ship brief created by fm-brief.sh tells crewmates, immediately after branch creation and before tooling or tests, to install dependencies in the freshly cut worktree because gitignored .venv and node_modules environments are absent. The dependency bootstrap instruction must be unconditional shared SHIP heredoc text across no-mistakes, direct-PR, and local-only modes; the no-mistakes doctor instruction must become step 3; and the script header must document this setup behavior. Extend the existing colocated fm-brief behavior test to assert the full rendered dependency step in all three ship modes and the step-3 no-mistakes doctor line. Do not assert anything about scout briefs either way because scout dependency bootstrap is intentionally out of scope, not prohibited. Keep the change based on main, shellcheck-clean through bin/fm-lint.sh, and do not modify generated files.
What Changed
bin/fm-brief.shnow renders an unconditional dependency-install step in every ship brief (no-mistakes, direct-PR, and local-only), placed right after branch creation and before tooling, so crewmates restore gitignored environments like.venvandnode_modulesin a freshly cut worktree; the no-mistakes doctor instruction moves to step 3, and the script header documents the new setup behavior.# Ruleswhen no doctor step is present, and extendedtests/fm-brief.test.shto assert the full dependency step across all three ship modes plus the step-3 doctor line (scout briefs are intentionally left unasserted).docs/architecture.md.Risk Assessment
✅ Low: A small, well-bounded change to one generated-brief template plus a colocated fixed-string test whose expectation byte-matches the emitted line in all three ship modes, with the prior round's blank-line fix applied exactly as directed and all remaining round-1 concerns explicitly ignored by the user.
Testing
Ran the extended colocated fm-brief behavior test (all 15 cases pass; full suite passed as baseline), then generated real briefs end-to-end in all three ship modes plus a scout brief and captured them as artifacts: every ship brief renders the unconditional dependency-install step 2 immediately after branch creation, the no-mistakes doctor step is step 3 with no stray blank line in the other modes, --help documents the behavior, and scout briefs are untouched. No screenshot evidence applies because the end-user surface is the generated markdown brief itself, captured verbatim.
Evidence: Generated no-mistakes ship brief (dependency step 2, doctor step 3)
Evidence: Generated direct-PR ship brief (dependency step 2)
Evidence: Generated local-only ship brief (dependency step 2)
Evidence: Generated scout brief (no dependency step, as intended)
Evidence: Rendered setup-section excerpts across all modes
## brief-no-mistakes 1. First action: create your branch:git checkout -b fm/evid-nomistakes2. Install this worktree's dependencies before any tooling or tests: it was freshly cut and has no .venv/node_modules, so language servers and test runs are degraded until you do. Detect the stack and run the project's setup - Python (pyproject.toml/requirements*.txt): create a .venv and install (preferuv sync, elsepip install -r requirements*.txtplus any requirements-dev.txt); Node/TypeScript (package.json):npm ci(or the project's package manager). Prefer any setup command the README/AGENTS.md documents. Skip only if there's no dependency manifest. 3. Runno-mistakes doctor; if it reports the repo is not initialized here, runno-mistakes init. (direct-PR and local-only render the identical step 2 with no doctor step and no stray blank line; scout briefs carry no dependency step)Evidence: fm-brief test transcript (15/15 ok)
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
🔧 **Review** - 4 issues found → auto-fixed ✅
bin/fm-brief.sh:344- The generated dependency step tells crewmates to runpip install -r requirements*.txt. When a project has more than one matching file (e.g. requirements.txt and requirements-dev.txt), the shell expands the glob topip install -r requirements.txt requirements-dev.txt; pip reads only the first as a requirements file and treats the second as a package name, so the install fails. The instruction already says "plus any requirements-dev.txt" separately, so the glob is both wrong and redundant - usepip install -r requirements.txtinstead.bin/fm-brief.sh:345-$SETUP2is empty for direct-PR and local-only modes, so those briefs now render two consecutive blank lines between the new step 2 and the# Rulesheading (the bare$SETUP2line plus the intentional separator). Previously$SETUP2was appended to the end of the branch-creation line, so an empty value produced no stray line. Cosmetic in the rendered brief only; can be tidied by keeping the doctor line appended to step 2's line or by trimming trailing blanks.bin/fm-brief.sh:344- The dependency bootstrap is only in the ship heredoc; scout briefs (the branch exiting at line 269) get no equivalent instruction, even though scouts are the default classification for bug reproduction and diagnosis - work that needs a usable test environment in an equally fresh worktree. Understood to be an intentional scope boundary for this change, but the reproduction case makes it a real gap worth an explicit follow-up decision.tests/fm-brief.test.sh:362- The secondmate charter assertion was changed from "persistent domain supervisor" to "persistent second mate managed by the main firstmate". The old string does not appear anywhere in bin/fm-brief.sh at the base commit either, so this test was already failing on main and the change is a repair of pre-existing breakage rather than a consequence of this feature. Noting it so the unrelated scope is visible in review; the fix itself matches bin/fm-brief.sh:132 exactly.🔧 Fix: drop stray blank line in direct-PR and local-only briefs
✅ Re-checked - no issues remain.
✅ **Test** - passed
✅ No issues found.
command -v tmux >/dev/null || { echo "tmux is required for e2e tests" >&2; exit 1; }; tmux -V; rc=0; for t in tests/*.test.sh; do echo "== $t =="; bash "$t" || rc=1; done; exit "$rc"Baseline: fulltests/*.test.shsuite via the configured test command (ran successfully before this validation)bash tests/fm-brief.test.sh— all 15 cases pass, including the newdependency setup renders for every ship modecase and the step-3 doctor assertionManual e2e: generated real briefs withFM_HOME=<fixture> bin/fm-brief.sh <id> <proj>for no-mistakes, direct-PR, and local-only projects plus a--scoutbrief, then inspected the rendered setup sectionsByte-level check (sed -n l) that direct-PR/local-only briefs render step 2 followed by exactly one blank line before# Rules(no stray blank line)bin/fm-brief.sh --help | grep 'dependency installation'— header documents the new setup behaviorgit merge-base --is-ancestor bc1a21b HEAD— branch is based on the main tipConfirmed scout brief contains no dependency-install step (intentionally out of scope)✅ **Document** - passed
✅ No issues found.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.