The previous layout placed epic folders directly under docs/work/
alongside prds/ and _system/. Tightening: epics now live in their
own docs/work/epics/ subfolder, peer to prds/ and _system/. Same
shape as the existing prds/ bucket.
Final docs/work/ layout:
README.md
prds/<slug>.prd.md
_system/_state.json
epics/<slug>/_epic.md + <story-folder>/_story.md
Renames (git mv preserves history):
- docs/work/binder-wrap-helper/
-> docs/work/epics/binder-wrap-helper/
- docs/work/library-evaluation-policy/
-> docs/work/epics/library-evaluation-policy/
- docs/work/ci-security-and-supply-chain/
-> docs/work/epics/ci-security-and-supply-chain/
Tooling updates:
- state-builder.mjs walks workRoot/epics/ directly; SKIP_FOLDERS
obsoleted (no more sibling folders to filter out).
- dispatch.mjs's findNextTask, tickStoryBulletInEpic, and
flipEpicDoneIfAllStoriesDone all join with "epics" segment.
- prd-ship.mjs's deriveShippingCommits walks workRoot/epics/ and
git-logs docs/work/epics/<epic>/.
- decomposer.prompt.md emits epics under docs/work/epics/<epic-id>/.
- handoff + grill-with-docs glossary references updated.
- Glossary entry for Epic updated.
Reserved future shape: when a task-tracker integration (ClickUp,
Linear) ships, the epics/ subfolder hosts <task-id>-<slug>/
folders. Today it just hosts bare slugs.
Convention shift: epic folders + PRD filenames + frontmatter id
fields are now bare slugs. The created: timestamp (Phase 2) carries
the date; folder names don't repeat it. A future <task-id>-<slug>
shape (e.g. ClickUp) lands cleanly when that integration ships.
Renames (git mv preserves history):
- docs/work/2026-05-13-binder-wrap-helper/
-> docs/work/binder-wrap-helper/
- docs/work/2026-05-14-library-evaluation-policy/
-> docs/work/library-evaluation-policy/
- docs/work/2026-05-14-ci-security-and-supply-chain/
-> docs/work/ci-security-and-supply-chain/
- docs/work/prds/2026-05-13-binder-wrap-helper.prd.md
-> docs/work/prds/binder-wrap-helper.prd.md
- docs/work/prds/2026-05-13-coverage-architecture.prd.md
-> docs/work/prds/coverage-architecture.prd.md
- docs/work/prds/2026-05-14-library-evaluation-policy.prd.md
-> docs/work/prds/library-evaluation-policy.prd.md
- docs/work/prds/2026-05-14-ci-security-and-supply-chain.prd.md
-> docs/work/prds/ci-security-and-supply-chain.prd.md
Frontmatter updates inside the renamed files: epic id, epic prd,
story epic, PRD id, PRD builds-on all drop date prefixes.
System folder + state file move:
- New docs/work/_system/ holds framework-managed state.
- docs/work/_state.json -> docs/work/_system/_state.json.
- state-builder.mjs adds _system to SKIP_FOLDERS.
- cli.mjs + state-sync-guard.mjs + .husky/pre-commit point at the
new path.
template-reset-v1 epic deleted entirely (one-off cleanup epic from
the pre-date-convention era; status was already done).
Generator-template updates (so new artifacts ship in the right
shape):
- .sandcastle/decomposer.prompt.md emits bare-slug folder names +
ISO created: timestamp.
- .claude/skills/to-prd/SKILL.md template uses bare-slug filename +
bare-slug id field + ISO created: timestamp.
Doc reference updates: glossary, runbook, agent-first-workflow-
and-conformance, reviewer prompt, ADR-020, ADR-022, ADR-023 all
point at the new paths/slugs.
Sandcastle re-invokes agents up to maxIterations even when the work is
already done — the decomposer was looping 4x re-writing the same epic
on every dispatch. Two halves to the fix:
- Pass completionSignal: "<promise>COMPLETE</promise>" explicitly on
all three run() calls (decompose, implementer, reviewer). Makes the
contract visible alongside maxIterations instead of relying on
sandcastle's default.
- Append a "Signal completion (required)" section to each prompt
telling the agent to emit the literal marker as its final line when
the work is genuinely done, plus a "do NOT emit if..." list to
discourage premature signaling.
The user surfaced that the binder-wrap-helper epic's stories
decomposed into horizontal sub-steps (read 3 files → write helper
→ write test → export → typecheck → coverage), not vertical
slices. Per the glossary's slice = task = PR = commit rule, every
checkbox should land as one green commit.
.sandcastle/decomposer.prompt.md:
- New "The slice rule (non-negotiable)" section near the top
defining the three constraints every task must satisfy: one
green commit; exercises a layer; independently meaningful.
- New "Tasks that are FORBIDDEN" list naming the anti-patterns
the previous output exhibited (read a file as a task; write
test without impl; standalone gate runs; standalone export;
sub-step decomposition of a single slice).
- New "Tasks that are CORRECT" list with examples drawn from
this codebase (gen invocation, full use-case slice, per-feature
binder migration, audit emission, bindAll wiring).
- New paragraph on "Manifest-first ordering INSIDE a task" —
the 4-step ordering (manifest → contracts → red test → green
impl) is what the implementer does within one task, not a
multi-checkbox decomposition.
- Constraints section gains two new bullets:
* Prefer FEWER but FATTER tasks (one per vertical slice)
over MANY thinner sub-steps
* Self-check: imagine the commit each checkbox produces;
do all gates pass on that commit alone?
.sandcastle/reviewer.prompt.md:
- New check #8 "Slice discipline" rejecting:
* Multi-commit diffs where any intermediate commit has red
gates
* Sub-step shape that should have been separate tasks
* Incomplete slices (use case w/o DI binding, manifest
publish w/o publish site, controller w/o router wiring)
.gitignore: adds `.pnpm-store/` so a misconfigured pnpm install
that places the store inside the project doesn't stage thousands
of cache files.
The existing binder-wrap-helper stories were decomposed under the
old (unconstrained) prompt and need re-decomposing under the new
rule. That's a separate action — this commit fixes the prompts;
the existing epic stays as-is until you re-decompose.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
