Sandcastle's default maxIterations: 1 cut every agent off after its
first response, so files written inside the sandbox never made it
into a captured commit. The decomposer wrote 9 epic + story files,
hit the limit, and sandcastle returned 0 commits — the host saw
nothing.
decompose.mjs: maxIterations 10 (small authoring task — read
context, write files, commit). Override via env
SANDCASTLE_DECOMPOSE_ITERATIONS.
dispatch.mjs:
- Implementer: maxIterations 30 (full TDD slice — read context,
red test, green impl, run all five gates, commit). Override via
SANDCASTLE_IMPLEMENTER_ITERATIONS.
- Reviewer: maxIterations 10 (read diff + task spec, decide).
Override via SANDCASTLE_REVIEWER_ITERATIONS.
Each call site documents WHY the value was picked + names the env
override inline so tuning is discoverable from the code.
Two stale-comment fixes surfaced after the dispatch handoff fix:
cli.mjs: the top-of-file JSDoc listed only 3 of 8 subcommands
(rebuild-state, status, next) and missed ready / blocked /
dispatch / decompose / prd-ship. Rewrote the header to describe
all 8 subcommands + their flags + the explicit-runCli routing
pattern that replaces the older side-effect-on-import approach
(established when the dispatch handoff broke and got fixed in
bb643b8).
prd-ship.mjs: the JSDoc claimed allowed transitions were
"<approved|in-review|draft> -> shipped", but the code refuses
draft (throws "still draft — flip to approved (human review)
before shipping"). Corrected the doc to "<approved|in-review>
-> shipped" + clarified that draft -> approved is the human step
deliberately kept outside the command's scope.
No behaviour change — comments only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
cli.mjs's `dispatch` branch called `import("./dispatch.mjs")` and
relied on dispatch.mjs's top-level CLI block running as a side
effect of the import. The earlier guard added to dispatch.mjs (to
stop the CLI firing when sibling work scripts import
`resolveClaudeAuth`) also stopped this legit handoff — so
`pnpm work dispatch` silently exited with no output.
Fix: explicit CLI entry function, called by name. Same pattern
already in use for prd-ship + decompose.
dispatch.mjs:
- Wraps the args parsing + print/execute branch in `export async
function runCli(args)`
- The invokedDirectly guard now wraps `runCli(process.argv.slice(2))`
so direct-invocation (`node scripts/work/dispatch.mjs ...`) still
works
cli.mjs:
- Imports runCli as runDispatch
- The `cmd === "dispatch"` branch calls runDispatch(args) directly
with a .catch attached (instead of import("./dispatch.mjs"))
Verified: `pnpm work dispatch` now correctly prints the dispatch
plan for the first ready task (`binder-wrap-helper /
01-wire-use-case-helper`'s first bullet); decompose tests stay 9/9.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The dispatch.mjs + decompose.mjs error handlers grew an image-not-
found hint in cd0a332 but the macOS keychain hint that the earlier
commit's message claimed wasn't actually applied (the Edit tool
required re-reading those files post-commit).
This commit applies the keychain hint to both error handlers: when
the sandcastle error matches /Not logged in|Please run \/login/ AND
process.platform === "darwin", the dispatcher prints the
`security find-generic-password ... > ~/.claude/.credentials.json`
one-liner + chmod 600 + the API-key fallback inline above the
generic "See runbook" line.
Now future agents hitting this on macOS see the fix at the failure
site, not just in docs.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the gap the user hit running `pnpm work decompose --execute`:
sandcastle errored with `Image 'sandcastle:template-vertical' not
found locally. Build it first with 'sandcastle docker build-image'`,
but neither the README nor the runbook documented this step.
README.md: new "Sandcastle setup (one-time)" section after Quick
reference. Three commands (docker info, build-image, auth) — the
minimum needed to make dispatch work. Links to the runbook for the
full lifecycle.
docs/guides/runbook.md: Prerequisites in "Using Sandcastle" grow
from 4 to 5 items. New step 2 walks through `sandcastle docker
build-image`, quotes the exact "Image not found locally" error so
agents searching for the string land on the fix, and shows the
remove-image + rebuild flow for Dockerfile edits.
.sandcastle/README.md: new "Build the sandbox image (one-time)"
section parallel to the env section, cross-linking to the runbook.
scripts/work/decompose.mjs + scripts/work/dispatch.mjs: when the
sandcastle error message matches the "Image '.+' not found locally"
pattern, the dispatcher now prints the build-image command inline
above the generic "See runbook" line. The error stack itself remains
unchanged.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the gap surfaced by the user: `pnpm work` usage referenced
`decompose` (via docs + the to-prd skill) but the subcommand was
never built. Mirrors `pnpm work dispatch`'s shape.
scripts/work/decompose.mjs (new):
- validatePrdForDecompose(prdPath) — refuses draft (must go
through human review first), in-review (review incomplete),
shipped (epic already exists); accepts only approved
- printDecomposePlan(prdId, prdPath, frontmatter) — print-mode
output showing the PRD's eligibility + sandcastle invocation
plan + auth modes
- executeDecompose(prdId, prdPath, prdText) — invokes sandcastle
with .sandcastle/decomposer.prompt.md, passing PRD_FILE_CONTENT
promptArg. The decomposer agent writes the epic + per-story
files to disk on a sandcastle branch the human can review
- runCli(args, { workRoot }) — entry point used by cli.mjs
- Direct invocation also supported (mirrors dispatch.mjs's
invokedDirectly guard, NEW pattern after this commit)
scripts/work/decompose.test.mjs (new, 9 tests, all green):
- validatePrdForDecompose: accepts approved; rejects draft,
in-review, shipped, unknown status, missing file
- runCli: writes error + returns 1 on missing PRD; writes error
+ returns 1 on draft PRD; prints plan + returns 0 on approved
scripts/work/cli.mjs:
- Adds `decompose` subcommand to usage + dispatch
- Usage formatting realigned for the 3-line subcommand block
scripts/work/dispatch.mjs:
- **Fix** the bug surfaced by the user: dispatch.mjs's CLI ran
as a top-level side effect whenever any of its exports was
imported. decompose.mjs imports resolveClaudeAuth from it, so
importing decompose.mjs printed "No ready task to dispatch."
Added an `import.meta.url === \`file://${process.argv[1]}\``
guard so the CLI only runs when invoked directly. This unblocks
cross-import without side effects.
Smoke-tested end-to-end:
- `pnpm work decompose` (no id) prints usage + exits 2
- `pnpm work decompose 2026-05-13-binder-wrap-helper` prints the
decompose plan with status: approved (eligible)
- 9/9 unit tests green
- dispatch.mjs's existing direct-invocation path unchanged
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the PRD-lifecycle gap surfaced by the user: when sandcastle
finishes an epic's last task, the seed PRD should auto-flip from
approved -> shipped. Builds the mechanism, wires it into the work
CLI + state index + reviewer prompt + docs.
scripts/work/prd-ship.mjs (new):
- parseFrontmatter / serializeFrontmatter — minimal YAML-ish parser
sufficient for PRD frontmatter (scalar + list shapes)
- flipPrdStatus — pure function: takes PRD text, returns new text
with status=shipped + shipped=<date> + optional shipping-commits.
Refuses to flip draft, idempotent fail-soft on already-shipped,
rejects unexpected statuses
- deriveShippingCommits — best-effort git log of the linked epic
folder for the --auto-commits flag
- findPrdPath — id -> path lookup under docs/work/prds/
- runCli — wiring for `pnpm work prd-ship <id> [--commits|--auto-commits]`
scripts/work/prd-ship.test.mjs (new, 17 tests):
- Frontmatter parser handles scalars + lists + missing frontmatter
- flipPrdStatus covers all transitions + refusals + body/key preservation
- findPrdPath + serializeFrontmatter coverage
scripts/work/state-builder.mjs:
- Epic entries gain a `prd` field
- New computeNeedsPrdShip surfaces epics done with PRD status not yet
shipped: state.needs_prd_ship[] with action commands
scripts/work/cli.mjs:
- New subcommand `pnpm work prd-ship <id>`
.sandcastle/reviewer.prompt.md:
- "Epic close-out: PRD status flip" section instructing reviewer to
check _state.json.needs_prd_ship and run the suggested action
- JSON output extends with prd_shipped: "<id>" | null
docs/work/README.md:
- "PRD lifecycle" section documenting the 4 statuses + auto-flip
Future PRDs follow the lifecycle automatically: decomposer refuses
draft, human flips to approved, sandcastle ships the epic, reviewer
runs prd-ship on the final task, PRD lands as shipped with its
commit trail.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
