docs(review): adversarial review of fleet-index design

[Techn0Ninja27]

Hostile design review of docs/superpowers/specs/2026-07-22-fleet-index-design.md (341 lines @ c991cd4) against the 8 named traps. Report only — no design file touched.

10 defects: 2 CRITICAL, 5 HIGH, 2 MED, 1 LOW. Verdict: restructure into 3 milestones; do not ship as one; do not reject the idea.

Trap	Verdict	Sev
1. §2 impossibility claim	DEFECT — conclusion survives, mechanism is false	MED
2. Index-in-git under parallel workers	DEFECT ×2	CRITICAL + HIGH
3. Break-even arithmetic	DEFECT — always-on map.md is net-negative here	HIGH
4. Adoption	DEFECT — fleet q is blocked, not merely unadopted	CRITICAL
5. Staleness split	DEFECT — no lock specified; §9 undoes §8	HIGH
6. Verified code claims	DEFECT — 6 of 8 wrong	HIGH
7. Receipt collision	DEFECT — 2 executable receipts, both unfixable as written	HIGH
8. Other	3 further defects + 1 unspecified rule	MED/MED/LOW

The two CRITICALs

symbols.tsv's sort key conflicts at N = 2. §5.2 sorts by name, which scatters each file's symbols through the whole table, so a per-file change edits hunks everywhere. Reproduced with this repo's real 2090-symbol table: two branches, fully disjoint source files → CONFLICT (content) in symbols.tsv. A path-sorted control with the identical edits auto-merges clean. This retires the disjoint-file-parallelism rule at knowledge/lessons.md:24 and the 7-wide result at :103.

fleet q cannot execute for the default worker. bin/fleet.py:8478 sets spawn's default --mode to dontask, and worker-settings.template.json ships no permissions key at all. §6.2 asserts Bash(fleet q:*) is safe to allowlist but never adds it anywhere. Same failure class as the headless permission hang documented at bin/fleet.py:7390-7395, which is why --add-dir exists.

Also worth the manager's attention

• The design's worked example is wrong. compose_prompt 887→917 (end 946→972), dispatch_bg 6621→7357 (end 6702→7573), _PREAMBLE_TEMPLATE 879→909, mailbox_dir end 71→70, file length 7832→8706, and both signatures. Those values are §5.2/§5.3's sample symbols.tsv rows — the demonstration of "exact derived facts, never summaries treated as truth" is a hand-written summary treated as truth.
• §2's mechanism is backwards. bin/fleet.py:7381,7385,7407: the composed prompt is written to a task file and the argv prompt is Read <path> and follow it exactly. Name/task/journal are never in the prefix — they arrive as a tool result. The conclusion holds; the reason does not, and the wrong reason is what sends map.md into the one channel guaranteed never to be shared.
• Two fenced blocks parse as executable receipts (§6.2 lines 161 and 168) and fail today unpinned and pinned. Line 170's expected output is the placeholder <actual source of those 60 lines> — unmatchable forever. docs/specs/*.md is a non-recursive glob, so the doc currently sits outside the harness entirely; moving it in fires test_every_spec_is_classified (reproduced in the review).

Suggested split

1. M1 — indexer + .fleet-index/ gitignored + --context digest injection only. No map, no fleet q, no committed artifact, no concurrency question, no permissions migration.
2. M2 — fleet q, gated on worker-settings.template.json gaining Bash(fleet q:*) and the fleet init migration that implies.
3. M3 — map.md, opt-in per spawn, with the break-even measurement §12.1 currently cannot produce.

Committing the index is a separate decision needing a path-sorted table, an atomic-replace writer, and an answer for git worktree remove.

Every claim in the review carries a re-runnable witness (path:line or pasted command output). Worker journal: state/journals/idx-adv2.md.

🤖 Generated with Claude Code