psf-memo/docs/process-improvements.md

SwarmForge Process Improvements — 2026-09-16

Owner: specifier. Scope: process and tooling changes only; no product feature behavior. Base commit: f44de33 → end commit: 8153f6f (10 commits). Verification: per-changeset evidence below; each change was committed on its own so it can be reviewed or reverted independently.

This document is the durable "what and why" for the process pass requested after the thread-query-bounds feature. It complements, and does not replace, the Git history, which remains the authoritative log.

Changes

#	Change	Why	Commit	Key files
1	Architect always sends an end-of-chain git_handoff to the specifier	The architect's terminal handoff only reached coder/refactorer, so the specifier was never notified to merge and a human had to bridge the gap every feature	0bc73ec	swarmforge/roles/architect.prompt
2	Delete acceptance LevelDB dirs in close() and sweep tmp/acceptance per run	Each scenario leaked an isolated LevelDB dir; psf-memo-db/tmp/acceptance had reached 961 dirs / 293 MB and bloats mutation worker copies	eb308d2	psf-memo-db/acceptance/lib/handlers.js, psf-memo-db/acceptance/acceptance.js
3	Self-healing handoff daemon	Queued handoffs sat undelivered when handoffd was not running; recovery was manual	053e8e3	swarmforge/scripts/ensure_handoff_daemon.sh, swarm_handoff.sh, ready_for_next.sh
4	Single canonical APS checkout at tmp/aps	Up to four copies (tmp/aps, tmp/aps-spec, tmp/aps-fresh, client-local) and the docs/wrappers/runners disagreed; the runners never updated, so tools could be stale	66a791b	ensure-aps.sh, gherkin-parser, architect-startup.sh, all three acceptance/acceptance.js, docs/architect-startup.md
5	Incremental acceptance generation	Every run re-parsed and regenerated every feature even when only one changed	5bbe276	all three acceptance/acceptance.js and acceptance/lib/generate.js
6	Canonical verify.sh + machine-readable verification record	The same commands were transcribed in several places and the full suite was re-run by every role	0db351a	swarmforge/scripts/verify.mjs, verify.sh, swarmforge/roles/architect.prompt, swarmforge/roles/specifier.prompt
7	Mutation guards: mutate-file.sh, clean-builds.sh	The default differential run can silently under-select after a function-set change; stale build dirs make worker copies huge	752bf2c	swarmforge/scripts/mutate-file.sh, clean-builds.sh, docs/architect-startup.md
8	Block handoffs from a dirty working tree	Unrelated tracked changes could ride along with a handoff	0942b2e	swarmforge/scripts/swarm_handoff.bb
9	state.sh helper	Refreshing the briefing HEAD lines required manual git inspection	a5f8967	swarmforge/scripts/state.sh
10	Briefing refresh (APS, daemon, verify, gotchas #24/#25, §11)	Keep the standing specifier briefing aligned with the new tooling	a5f8967, 8153f6f	specifier-prompt.md

Verification evidence

• #2: tmp/acceptance measured at 961 dirs / 293 MB before, 4 KB after; acceptance 11/11 still pass.
• #3: daemon stopped, ensure_handoff_daemon.sh restarted it (pid observed), ready_for_next.sh works.
• #4: ensure-aps.sh clone and --update verified; gherkin-parser wrapper parsed a feature; duplicate checkouts removed.
• #5: a second acceptance run left the generated test mtime unchanged (generation skipped) while 11/11 passed.
• #6: verify.mjs db --record … emitted result: pass for unit/property/acceptance/lint with git_sha.
• #7: mutate-file.sh reported Selected 0 / Covered 10, auto-reran --mutate-all, result 10 killed / 0 survived.
• #8: a handoff attempt with a dirty tree was blocked (exit 3), listed the files, retained the draft, and queued nothing.
• #9: state.sh printed each role branch HEAD and main-checkout status.

How to use

• Refresh tools: swarmforge/scripts/ensure-aps.sh --update.
• Verify a component and record it: swarmforge/scripts/verify.sh <client|db|indexer> --record docs/reviews/<task>-verification.json --task <task>.
• Mutate a file safely: from the component dir, ../swarmforge/scripts/mutate-file.sh src/<file>.js --max-workers 8.
• Clean worker-copy bloat: swarmforge/scripts/clean-builds.sh.
• Refresh state: swarmforge/scripts/state.sh.
• Handoffs: swarm_handoff.sh now self-heals the daemon and refuses a dirty tree (SWARMFORGE_ALLOW_DIRTY=1 overrides).

Known remaining work

• Acceptance execution is ~9 minutes (546 s) for the 11 psf-memo-db suites, dominated by running generated test files sequentially; generation is now incremental. Parallelizing the generated test files (with isolated tmp/ per worker) is the next efficiency candidate and is not yet specified.
• APS gherkin-mutator exposes no project mutation-filter hook, so intrinsic upper-bound survivors (at most N) cannot be filtered out; documented in docs/architect-startup.md and specifier gotcha #23.

By specifier.