solo-orchestrator: Instructions file for Claude Code

CLAUDE.md — agent orientation for the solo-orchestrator repo

Read this first. It is the map for working effectively in THIS repository. Counts are date-stamped (they drift); prefer the grep/command recipes — run them to get current truth. Verified 2026-07-23.

WHAT THIS REPO IS

This is the framework repo that GENERATES downstream projects — it is not itself a scaffolded project. init.sh scaffolds a new project elsewhere; the files a downstream agent reads at kickoff live in the GENERATED project, not here.

• The README "Quick Start" no longer carries a kickoff prompt of its own (BL-202 residual 2). It points at bash scripts/resume.sh — the single state-aware first-message generator, whose three branches are the intake prompt, PROJECT_INTAKE.md § 13 verbatim, and the classic resume prompt — plus, checked before them, the assessment prompt for an adopted project not yet assessed (# BL-242-RESUME-ASSESSMENT, which prints a file adoption wrote). That script and everything its output names (CLAUDE.md, PROJECT_INTAKE.md, docs/reference/…, .claude/phase-state.json) exist in generated projects only; the README says so in as many words, because it is read by people who have not run init yet. Do not re-add a verbatim paste block here — the hand-maintained copy is what drifted, and tests/test-bl202-readme-kickoff-consolidation.sh now fails if one comes back (literal signatures and a structural bare-fence net, five mutation proofs).
• init.sh ships the guide downstream to docs/reference/: see the cp "$SCRIPT_DIR/docs/builders-guide.md" docs/reference/ line (grep builders-guide in init.sh). In THIS repo the guide is docs/builders-guide.md (top level), and there is no PROJECT_INTAKE.md and no .claude/phase-state.json.
• docs/INDEX.md is the documentation map — a one-screen index of docs/** and Reports/**. Start there to find a doc.

ENVIRONMENT TRAPS

• No timeout / gtimeout on this macOS host. Wrapping a command in them yields a spurious rc=127 (command-not-found), not a real timeout. Do not use them.
• The repo path contains a space (Claude Projects/…). Quote every path in every command, always.
• bash is 3.2 (/bin/bash, GNU bash 3.2.57). In product code: no ${var,,} lowercasing, no associative arrays (declare -A), no nullglob. Use temp files / indexed arrays instead.
• sed with a | delimiter and a shell-code replacement bites, and it bites SILENTLY. Shell replacements are |-dense (||), so s|old|new| where new contains || either errors (bad flag in substitute command) or — worse — terminates the expression early and leaves the file unchanged while sed reports success. It has bitten three times (twice inside a mutation harness, once ad-hoc), and 25 files carry s|-delimited sed. Two rules: pick a delimiter absent from the replacement, and assert the edit actually applied (a changed-line count), because "sed ran" is not "sed edited". A related one-liner: & in a sed replacement means the whole match — an unescaped && splices the original line back in, and that mutant passes bash -n. See ## BL-224: for the sibling case where a lint's own regex over-matched for the same reason.
• The same & trap lives in bash's own ${var/pat/rep}, and it is VERSION-SPLIT between this host and CI. Since bash 5.2 an unescaped & in the replacement of a pattern substitution means THE WHOLE MATCH, exactly as in sed; bash 3.2 has no such rule. 5.2 is the boundary, not 5.1 — measured, u='one TWO three'; "${u//TWO/&}" gives one & three on 3.2.57, 5.0.18 and 5.1.16 and one TWO three on 5.2.37, and the shopt that governs it (patsub_replacement, on by default) does not exist before 5.2. This Mac runs 3.2 and the runners run 5.2, so a replacement carrying && — which every shell guard does — produces the intended text locally and splices the match back in on CI. It is silent in the worst way: the line still changes, the changed-line count is still right, and bash -n is still clean, so a mutation harness reports a healthy mutant that no longer mutates. That is a red rest shard on PR #380, found only because the mutant stopped killing its case. Two rules, the same two as for sed: do not use ${var/pat/rep} when the replacement can contain & — split on the pattern instead (lhs="${s%%"$pat"*}"; rhs="${s#*"$pat"}"), which has no & rule in any version — and assert the replacement LANDED, by its own literal text, not by a line count. soif_sed_repl_esc in helpers-core.sh is unaffected, but do not try to read that off the spelling — two drafts of this bullet reasoned about it and both were wrong. Measure it. Double-quoted, t='R&D tools', u='one TWO three':

  replacement, as written   what it is        bash 3.2      bash 5.2
  ${t//&/\\&}   <- REAL      two backslashes   R\&D tools    R\&D tools
  ${t//&/\&}                  one backslash     R\&D tools    R&D tools
  ${u//TWO/\\&}              two backslashes   one \& three  one \TWO three
  ${u//TWO/&}                 bare &            one & three   one TWO three
  

  On 5.2, \\ collapses at quote removal to a LITERAL backslash that does not escape, so \\& is backslash-plus-whole match; a single \& is an escaped & and yields a literal & with the backslash consumed; a bare & is the whole match. On 3.2 all three are literal. So the real source line — t="${t//&/\\&}", two backslashes — is byte-identical across versions ONLY because its pattern is the single character &, which makes "the whole match" happen to be &. Change that pattern and the versions diverge in silence. tests/test-bl255-sed-replacement-escape.sh pins those bytes in the unit lane, and that is what would catch it — but only there. Mutate the helper's \\& to \& and that suite stays GREEN on this Mac and goes red only on the runner, which is this same trap one level up: a local run of the suite that guards the trap does not see the trap. Reproduce the runner's bash on this host:

  docker run --rm -v "$PWD:/repo:ro" ubuntu:24.04 bash -c 'apt-get update -qq \
    && apt-get install -y -qq jq git && useradd -m t && cp -r /repo /home/t/r \
    && chown -R t /home/t/r && su t -c "cd /home/t/r && bash tests/<file>.sh"'
  

  Run as a NON-root user or every chmod 555 fixture silently stays writable.
• A local that DECLARES without ASSIGNING is a second version split, and it is NOT the same boundary as the one above — it is bash 4.0, not 5.2. local t followed by a read of $t under set -u is an empty string on bash 3.2 and an unbound variable that exits the shell on 4.0 and every version after. Measured, same probe, bash:<v> images plus this Mac — f() { local t; [ -n "$t" ] && echo hit; echo AFTER; }:

  bash 3.2.57 (this Mac AND the container)   empty, prints AFTER, rc 0
  bash 4.0.44 / 4.1.17 / 4.2.53 / 4.4.23     t: unbound variable, rc 1
  bash 5.0.18 / 5.1.16 / 5.2.37 / 5.3.20     t: unbound variable, rc 1
  

  Do not merge this into the ${var/pat/rep} bullet. That one flips at 5.2 and 5.1 is on the safe side; this one flips at 4.0 and every bash a runner has shipped this decade is on the failing side. The 2026-09-18 commit that fixed the first instance (81316ea) named 3.2-vs-5.2 because those were the two hosts in front of it — true, and it reads as a 5.x rule, which it is not. Measure the boundary before you quote one.