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.
- New scripts/work/bump-updated-timestamps.mjs stamps the `updated:`
frontmatter field to the current ISO 8601 UTC timestamp on every
staged docs/work/**/*.md file. Idempotent; adds the field after
`created:` if missing.
- .husky/pre-commit invokes the bump script as step 2 (before
rebuild-state) so _state.json sees the fresh timestamp.
- Backfill all existing work docs (4 PRDs + 3 epics + 21 stories):
* created: promoted from \`YYYY-MM-DD\` -> ISO timestamp using
git log --diff-filter=A on each file (first-commit date for
stories that had no \`created:\` line, midnight UTC for PRDs
and epics that had date-only created).
* updated: added from \`git log -1 --format=%aI\` on each file
(last-commit timestamp); will be re-stamped to "now" by the
pre-commit hook on this commit.
Stories that had no \`created:\` line now get one.
Decomposer produced 9 stories under docs/work/2026-05-14-ci-
security-and-supply-chain/, ordered to land the schema foundation
first and the cross-referencing content (reviewer prompt, guide)
last:
01 - trace schema extensions (socketRisk + lastRevalidated)
02 - Socket integration (skill + CI)
03 - Renovate adoption
04 - major-bump re-evaluation flow
05 - trace revalidation workflow
06 - CodeQL + audit signatures
07 - gitleaks pre-commit
08 - reviewer prompt update
09 - CI security guide + docs
Also fixes a one-char status typo in the PRD frontmatter
(\`appoved\` -> \`approved\`) that landed with the decompose run.
Anchored by ADR-023 + the approved PRD at
docs/work/prds/2026-05-14-ci-security-and-supply-chain.prd.md.
Sequencing: depends on stories 01/02/04/06 of the in-flight
library-evaluation epic landing first.
- ADR-023 codifies the four-pillar enforcement stack: Renovate for
bumps + Action SHA pinning via pinGitHubActionDigests, Socket.dev
as a 9th hard filter in evaluate-library (free App + self-hosted
socket-cli + reviewer-prompt enforcement), weekly trace
revalidation cron with two-tier divergence action (rolling
dashboard issue + per-dep re-evaluation issues), and the baseline
GitHub-native gates (CodeQL, pnpm audit signatures, gitleaks
pre-commit + native push protection). Failure-mode hierarchy is
the single source of truth referenced by the sandcastle reviewer.
- Section 6 amends ADR-022 in place: major-bump re-evaluation
trigger (minor/patch bumps skip), last-revalidated frontmatter
field (preserves original date for adoption provenance), and
Socket as the 9th hard filter. ADR-022 stays unedited; both ADRs
read as a composed policy.
- PRD at docs/work/prds/2026-05-14-ci-security-and-supply-chain.prd.md
seeds the implementation epic; explicit sequencing -- depends on
the in-flight library-evaluation epic's stories 01/02/04/06
landing first.
- Glossary gains "Trace revalidation" + "Major-bump re-evaluation"
entries referenced by both ADRs.
Catalyst: 2026-05-14 audit confirmed zero security tooling in the
repo + GitHub Actions pinned to major-version tags (the tj-actions/
changed-files attack class). ADR-022 closes the adoption-time gate;
ADR-023 closes the post-adoption drift gate.
- ADR-022 codifies the tiered library-evaluation policy: 8 hard
auto-reject filters (license, types, maintenance, boundary-fit,
shadow-check, EU residency, CVE scan, named consumer), 3
discussion prompts, per-decision trace artifact at
docs/library-decisions/, and a 4-layer enforcement stack
(Claude PreToolUse/PostToolUse hook -> evaluate-library skill ->
pre-commit hook -> sandcastle reviewer prompt). Mirrors the
conformance-system latency pattern from ADR-012.
- PRD at docs/work/prds/2026-05-14-library-evaluation-policy.prd.md
seeds the implementation epic; status: approved, ready for
\`pnpm work decompose\`.
- Glossary gains "Library trace" + "Pre-shipped trace" entries
referenced by both artifacts.
Catalyst: the 2026-05-14 grill session nearly adopted
trpc-to-openapi + zod-to-json-schema before someone asked who the
HTTP consumer was. Honest answer: none -- all callers are TS via
createCaller. This policy makes that question structurally
unavoidable for any future feature- or core-tier dep.
Materialises the output of the improve-codebase-architecture skill's
grilling loop on Candidate 1 (binder duplication), sub-shape (a)
(helper-inside-binder).
Captured decisions:
- New wireUseCase helper at @repo/core-shared/conformance/
- Composes the existing withSpan + withCapture (+ optional
withAudit) wrappers; doesn't replace them
- Per-feature binders shrink to decision content + N wireUseCase
calls instead of N x ~12 lines of inline wrapping
- All 5 features migrated (10 binder files, ~24 inline wrap sites)
- Brand attachment stays in the existing wrappers
- Generator template emits the new shape so future scaffolds
don't regress
Sub-shape (b) (pre-wired factory exports) explicitly rejected in
favour of (a) — keeps the wrapping a binder concern, preserves
ADR-008's per-feature DI isolation.
Status: draft. Will not pass through pnpm work decompose until a
human reviewer flips status to approved. Expected to land as one
mid-sized epic with the helper + per-feature migrations as separate
stories.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Closes the staleness gap after the 10-commit coverage epic shipped.
Doc sync (item 1 from the user's choice):
- CLAUDE.md Quick Start: adds pnpm coverage:aggregate / coverage:diff
/ mutate to the command listing
- CLAUDE.md: new "Sibling architecture: coverage (ADR-020)" section
after the conformance gate table — captures the 4-layer table +
points at docs/guides/coverage.md + ADR-020 + says agents must run
coverage:diff before reporting complete
- AGENTS.md preamble: now lists coverage as a parallel multi-latency
quality system alongside conformance, with the same gate / latency
framing
- PRD frontmatter: status draft -> shipped + shipped date +
shipping-commits list (all 10 SHAs anchoring the trace)
- PRD findings table: each row gets a Resolution column citing the
commit that closed it; conclusion text updated to past tense
- ADR-020 implementation phasing: rewritten as a status table with
each step linked to the commit that shipped it + Boot-time
assertFeatureConformance explicitly marked Deferred with rationale
- docs/guides/coverage.md: removed "Boot wiring lands in the next
story" line; replaced with the deferral rationale + clarified
that two readers (vitest, coverage:diff) consume the manifest
Sandcastle prompts (item 2 from the user's choice):
- .sandcastle/implementer.prompt.md: new "Coverage gates" section
after the conformance-gates list, requiring `pnpm test --coverage`,
`pnpm coverage:aggregate`, and `pnpm coverage:diff` to all pass
before reporting `complete`. Machine-readable JSON shape of
coverage:diff documented (status / uncovered[] / kind enum), with
explicit instructions on how to interpret each kind. Allowlist
expansion requires justification + test.
- .sandcastle/reviewer.prompt.md: AC coverage relabeled to "AC
coverage (acceptance criteria, not test coverage)" to disambiguate;
new check #7 "Coverage gates (ADR-020)" requiring CI's
Coverage — diff (L1) step green + per-layer thresholds met +
no silent allowlist expansion + manifest band drift detection.
Effect: future agent runs through sandcastle now treat coverage as a
first-class blocking gate, parallel to conformance. PRs no longer
discover coverage failures only via CI; the implementer is required
to check before reporting done, and the reviewer is required to
verify.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Captures the brainstorm convergence (2026-05-13) into a draft PRD that
seeds the implementation epic. Decisions captured:
- 4-layer coverage architecture (L0 vitest thresholds, L1 diff coverage,
L2 aggregate summary.json, L3 mutation testing on entities + use-cases)
- Manifest-driven coverage band as the single source of truth — vitest
config, assertFeatureConformance boot check, and pnpm coverage:diff
all derive expectations from feature.manifest.ts
- Cover-the-diff (every changed line exercised) not cover-the-new-code
- Aggregate trend committed as coverage/summary.json; no SaaS dep
- Stryker for mutation, on-demand only, NOT in default pnpm test
L0 verification findings (also captured in the PRD):
- auth / blog / marketing-pages: green (100% layer bands hold)
- navigation: real test gaps in entities + controllers (~86%)
- media: missing @vitest/coverage-v8 dep + vitest.config has no
coverage block at all (entirely absent — the most extreme case of
the duplication problem the manifest-driven keystone eliminates)
Status remains draft until the human review pass. Decomposer will
refuse to run on draft.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
