The implementer + reviewer sandcastle prompts already enforce
conventional commits, but the convention was buried in those prompt
templates — agents not running through sandcastle (e.g. interactive
Claude sessions, ad-hoc fixups) had no visible signal that the format
is non-negotiable.
Four visibility surfaces now carry the signal:
- CLAUDE.md Key Conventions: new top bullet stating the spec
(<type>(<scope>): <subject>), the full type list, breaking-change
syntax (!), and three example commits
- AGENTS.md preamble: parallel callout alongside the vocabulary
and quality-gates notes
- .claude/hooks/session-start.sh: one-line reminder in the boot
pointers (every session now sees it at start)
- .claude/hooks/prompt-context.sh: new 10th keyword group fires
when a user prompt mentions commit/message/changelog/conventional,
injecting the full spec into the turn's context
Conventional Commits spec: https://www.conventionalcommits.org/
Verified: the prompt-context hook smoke-tests green when a prompt
containing "commit message" is piped in — it emits the conventional
commits pointer.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Architecture record for the agent-first coverage initiative seeded by
the 2026-05-13 PRD. Captures the durable decisions:
- 4-layer architecture (L0 vitest, L1 diff, L2 aggregate, L3 mutation)
- Manifest-driven coverage band as single source of truth (vitest +
assertFeatureConformance + pnpm coverage:diff all read from it)
- Cover-the-diff (changed lines), not cover-the-new-code
- Committed coverage/summary.json (no SaaS), trend via git log
- Mutation testing scoped to entities + use-cases, on-demand only
- Machine-first output format (JSON stdout, human stderr)
Glossary gets a new "Coverage" section with 7 entries (coverage band,
L0-L3 layers, diff coverage, mutation testing, mutation score,
coverage/summary.json), plus two relationship rows and a flagged
ambiguity for "coverage" qualifiers.
prompt-context.sh hook gets a 9th keyword group — when a prompt
mentions coverage / uncovered / lcov / mutation / stryker, the
relevant ADR + guide path are injected as additional context for
the turn.
This is the documentation layer of the coverage epic. Implementation
(manifest schema, vitest auto-derive, scripts, boot assertion,
mutation tooling) lands in subsequent stories.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Project-level Claude Code hooks committed to .claude/settings.json with
scripts under .claude/hooks/. Three tiers:
Tier 1 — hard guards (exit 2 to block the tool call):
- bash-guard.sh: blocks bypass flags (verify-skip, sign-skip), forceful
push variants, destructive resets, force clean, working-tree-wipe
checkouts/restores, force branch delete, amend, and rm -rf against
root or home. Reinforces CLAUDE.md Git Safety Protocol.
- generator-first-nudge.sh: blocks creating a new top-level
packages/<name> or apps/<name> directory by hand. Allows working
inside an existing package. Reinforces the non-negotiable
generator-first rule.
Tier 2 — context injection (stdout becomes additional context):
- session-start.sh: prints glossary, AGENTS.md, workflow CLI, and
conformance pointers on session boot.
- prompt-context.sh: keyword-matches the user prompt against eight
concept groups (events, realtime, audit, instrumentation, manifest,
workflow, DI, boundaries) and injects the relevant ADR + rule
pointers for the turn.
Tier 3 — side-effect automation:
- post-manifest-edit.sh: when Edit/Write touches feature.manifest.ts,
prints the manifest-first ordering reminder plus the per-feature
verify commands.
- stop-check-manifest-tests.sh: at agent Stop time, if the working
tree has manifest changes but no sibling test changes, exits 2 to
force continuation. Loop-guarded via stop_hook_active.
All hooks are bash + jq, use CLAUDE_PROJECT_DIR for safety, and were
smoke-tested end-to-end (block + allow paths both verified).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
