The agent that produced the explainer guessed three ADR filenames
(adr-014-instrumentation-interfaces.md, adr-017-otel-migration.md,
adr-015-events-jobs.md). The actual files use different slugs.
Touches the deeper architecture surfaces the Phase 6 sweep skipped:
- overview.md: split must-have (core-shared, core-cms, core-api) from
optional (core-trpc, core-ui, core-realtime, core-events, core-audit);
add core-audit to the Five tags optional list
- dependency-flow.md: extend the bindAll diagram with resolveAudit;
add auditLog row to the BindContext table; rename the
TRACER/LOGGER/METRICS heading to include AUDIT (ADR-018); note the
R52-style boundary rule for @repo/core-audit (consume via protocol)
- vertical-feature-spec.md: target-state section now states 3 must-have
+ 5 optional cores; tag matrix includes the optional cores; bind-
production signature destructure includes auditLog
- di-explainer.html: §08 instrumentation gains an IAuditLog block + the
Wiring path tree shows resolveAudit + auditLog in ctx
- testing-strategy.md: RecordingAuditLog reference + reset() guidance
2-phase design for `pnpm turbo gen core-ui-component`. Prompts for tier
(atom/molecule/organism) + name (PascalCase) and emits the established
4-file component pattern (component.tsx, component.stories.tsx,
component.test.tsx, index.ts) into the matching `packages/core-ui/src/<tier>s/`
folder. Splices the new export into the tier barrel via `// <gen:<tier>s>`
anchors.
Phase A adds the anchors to the core-ui template's three tier barrels and
regenerates the byte-identical reconstruction snapshot. Phase B ships the
generator, templates, tests, and docs. Refuses to run if core-ui isn't
scaffolded; doesn't touch Storybook config (existing stories glob covers
new component stories).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- AGENTS.md bind-production code block: shows the slim default state
(no @repo/core-events / @repo/core-realtime imports, BindProductionContext
with no generic args) with a comment pointing to the scaffold workflow.
The previous block showed a fully-wired post-scaffold state without
signaling that none of those packages exist in main.
- bind-protocols.test.ts: top-of-file comment clarifies what these tests
actually verify (protocol shapes have required methods) vs what the
spec text might suggest (full assignability of optional packages'
interfaces — that's verified by the e2e reconstruction tests, not here).
- core-package-generator.md: drops two stale "Until Phases 3-6 land"
parentheticals — the phases shipped.
- config.test.ts: extends the choices assertion to cover all 4 names
(realtime, events, trpc, ui).
- marketing-pages bind-* comments: reverse the inverted optional/required
language. queue (IJobQueue) is from core-shared and always present;
bus is the optional one (from @repo/core-events when scaffolded).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- CLAUDE.md project-overview lists must-have core packages (shared/cms/api)
separately from the four optionals (realtime/events/trpc/ui) with their
scaffold command. Read first list adds template-tiers.md and notes that
the events + realtime guides require their package to be scaffolded first.
- overview.md "Five tags" updated: core-composition is 2 must-have plus
trpc (optional); core is 1 must-have plus ui/realtime/events (optional).
- dependency-flow.md fix: replaces the stale `// in packages/core-trpc`
example with `// in packages/core-shared` (core-trpc is now optional and
may not exist in a slim template).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- AGENTS.md (root): marks core-ui as optional in the package table and
boundary rules; points per-package docs to the .hbs template
- apps/storybook/AGENTS.md: rewrites around no-core-ui-by-default;
stories glob and globals.css import described as post-scaffold steps
- apps/web-next/AGENTS.md: cross-reference updated to template file
- apps/web-tanstack/AGENTS.md: cross-reference updated to template file
- docs/architecture/data-flow-explainer.html: core-ui bullet notes
optional status + generator command
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- ADR-015: Status → Optional with scaffold command + behavior note (bus absent
means no-op, IJobQueue unaffected)
- events-and-jobs.md: prerequisite callout block explaining core-events is
optional, how to scaffold, and which features require it
- data-flow-explainer.html: note bus is optional in BindProductionContext blurb;
add inline comment in code snippet that bus is scaffoldable
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Adds docs/scaffolding/core-package-generator.md with usage, template
table, and drift-verification instructions. Updates CLAUDE.md Quick
Start and AGENTS.md Key Commands with the new pnpm turbo gen core-package
entry. Creates templates/core-package/.gitkeep placeholder for Phase 3+.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- di-explainer.html: update stale JS data strings from positional-arg
form (bindAllProduction(config), bindProductionBlog(config,tracer,...))
to ctx-arg form (bindAllProduction(deps), bindProductionBlog(ctx)) with
a note on ctx shape.
- auth/sign-up.use-case: change bus param from IEventBus to
EventBusProtocol|undefined; guard bus.publish with if(bus) so the use
case is safe when core-events is absent (Phase 3+).
- auth/bind-production + bind-dev-seed: drop as IEventBus cast and unused
IEventBus import; ctx.bus is now passed directly (typed as
EventBusProtocol|undefined).
- marketing-pages/bind-production + bind-dev-seed: drop as IJobQueue cast
and unused IJobQueue import; wrap event-handler DI block in if(queue)
guard so the handler is only bound when core-jobs is wired.
- core-shared/src/index.ts: add `export * from "./di"` as the plan
specified (subpath export alone is no longer the only access path).
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Implementation plan for the design at docs/superpowers/specs/2026-05-09-core-
package-generator-design.md. Eight phases (numbered Phase 0..7 in the plan; Phase
0 is the read-first orientation, Phases 1-7 implement spec phases 0-5 plus a
final cross-doc sweep).
Phase 1 ships BindContext with bounded generics over protocol types in core-
shared. Phase 2 ships the generator framework (entry, prompt, dispatch table —
empty). Phases 3-6 each capture one optional package as a verbatim template,
ship the generator action, and remove the package from main with byte-identical
reconstruction verified via a snapshot. Phase 7 is the final cross-doc sweep
(template-tiers.md, README updates, HTML explainer pass).
Companion ADR will be assigned at implementation time (expected ADR-017).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6-phase design for slimming the default template to a minimal kernel
and providing turbo generators that scaffold optional core packages
(realtime, events, trpc, ui) back when needed.
Phase 0 introduces a BindContext object in core-shared with bounded
generics over minimal protocol types; optional packages keep their full
interfaces but extends-link to the protocols. This lets feature binders
take a single ctx arg and lets optional packages disappear without
breaking typechecks. Phases 1-5 ship the generator framework + per-
package templates + per-package removal from main.
Companion ADR will be assigned at implementation time (expected ADR-017).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Five fixes surfaced by the branch-wide code review on the realtime layer:
- server.ts: replace dynamic `import("@repo/auth/di/container")` with a
static top-of-file import. The dynamic-import workaround from 6a0ac63 is
no longer needed once the root tsconfig + TSX_TSCONFIG_PATH expose
decorator metadata to tsx; verified by booting `pnpm dev` clean.
- server.ts: correct the inline structural type for `validateSession` to
match the real `IAuthenticationService` contract (non-nullable, throws
on invalid session) and wrap the call in try/catch so unauthenticated
bubbles to a `null` return instead of dead-code `result ? ... : null`.
- bind-production.ts: extract `maybeRegisterRealtimePing()` that wraps the
built-in ping inbound handler in the same `withSpan(withCapture(...))`
sandwich the realtime-handler generator emits (R41–R44), so the
proof-of-life channel models the convention rather than registering raw.
- bind-production.test.ts: add 4 tests for the `REALTIME_PING_DISABLED`
env-gate (registered when unset in both binders, not registered when
"true", treated as enabled when "1").
- docs/guides/realtime.md: correct the integration-test reference at
line 285 — the test does not call `bindAllDevSeed()`; it builds the
Socket.IO server inline and exercises gates 1+2 only (gates 3+4 live in
socket-io-realtime-server.test.ts).
- adr-016: add a "Known follow-ups" section recording 6 lower-priority
refinements deferred from this branch (bridge stub test scaffolding,
registry register/registerChannel precedence, channel-template dot
constraint, server bare catch{}, BindAllDeps Partial widening, AGENTS.md
anchor count phrasing).
CI gates: lint 0 errors / 4 warnings (pre-existing turbo.json warnings),
typecheck clean, 24 web-next tests pass (was 20; 4 new env-gate tests),
boundaries 0 issues across 504 files.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Long-form design for the bidirectional realtime layer the user
brainstormed on 2026-05-08. Builds on ADR-015 (events and jobs);
hybrid pattern where IRealtimeBroadcaster is layered alongside
IEventBus, with a bridge for forwarding allowlisted bus events to
realtime channels.
v1 ships: @repo/core-realtime package, custom Node server in
apps/web-next, cookie-session auth, four scope kinds, two
generators (gen realtime channel|handler), three new anchors per
feature, RecordingRealtimeBroadcaster test helper, realtime-ping
proof-of-life. Dashboard, DB-backed roles/permissions, multi-instance
fanout, and a generic core-package generator are deferred — captured
in §13 / §14 / §15.
Companion HTML explainer at realtime-auth-explainer.html (project root,
uncommitted) walks the four-checkpoint auth model visually. ADR-016
will be created during implementation.
di-explainer and data-flow-explainer narratives still showed the
pre-ADR-014 1-arg bindProductionBlog(config) form. Updated both
explainers to (config, tracer, logger, bus, queue), and adjusted the
narrative arc so the production-swap step mentions the
resolveEventsAndJobs* preamble.
adding-a-feature's Step 16 sketch was the same 1-arg shape; replaced
with the canonical 5-arg signature and a short note that the bus/queue
params are accept-and-forward until gen event consume / gen job
generators inject usage at the anchors. Pointer to a real feature's
bind-production.ts for the complete reference.
Final sweep is clean — no stale (container, config) or 1-arg
bindProduction signatures remain in docs/.
Six per-package AGENTS.md tables and the di-explainer wiring trace all
showed pre-ADR-014 binder shapes. Refreshed to the post-ADR-015
reality:
- Per-package "Public exports" tables now show the
(config, tracer, logger, bus, queue) production signature and the
(tracer, logger, bus, queue) dev-seed companion. auth and
marketing-pages also list their newly-public ./di/container,
./di/symbols, and (marketing-pages only) ./services/mailer +
./services/recording-mailer subpaths.
- di-explainer's wiring trace adds the resolveEventsAndJobs* step in
bindAll(), the (config, tracer, logger, bus, queue) binder
signature, and the // <gen:event-handlers> / // <gen:jobs>
injection sites.
No code change; pre-existing AGENTS.md staleness predates ADR-014 +
ADR-015 — this commit catches both up.
Three follow-up corrections from the docs audit:
- vertical-feature-spec § 13 dropped the events/jobs bullet from the
"Out of scope (deferred)" list — they shipped, the bullet didn't
belong there. The spec already mentions ADR-015 elsewhere (§ 4
optional folders).
- vertical-feature-spec § 14 success criterion replaced "Any
cross-feature import fails pnpm lint" with the post-ADR-015 reality:
cross-feature imports are restricted to event contracts (the feature
boundary tag now accepts feature-tagged deps), but rule E1
(no-handler-reexport) keeps consumer handlers / use cases /
repositories private.
- dependency-flow now shows the resolveEventsAndJobs* step in bindAll
and the (config, tracer, logger, bus, queue) binder signature, plus
the // <gen:event-handlers> / // <gen:jobs> anchor lines where the
generators inject subscribe / register calls.
Also folds in the spec correction noted in the plan's known follow-up
\#1: subscribe takes consumerFeature: string as a second arg between
descriptor and handler. § 3.3 and § 5.4 updated.
Wires the existing turbo gen feature generator into AGENTS.md (Adding
a Feature section, Key Commands, Specification & Guides) and
CLAUDE.md (Quick Start, Read First). Adds a fast-path callout at the
top of the manual walkthrough in docs/guides/adding-a-feature.md
pointing at scaffolding-a-feature.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
gen event consume now emits a second file: an __events-<publisher>-
<event>.task.ts Payload task that delegates to the consumer's
container-resolved wrapped handler. The bind block also binds the
wrapped handler into the per-feature container by symbol so the
task can resolve it. With this, PayloadJobsEventBus is fully wired
end-to-end with no manual per-event task hand-write required.
Removes the corresponding Known Follow-up item.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
56 bite-sized tasks across 9 phases implementing the spec at
docs/superpowers/specs/2026-05-08-events-and-jobs-design.md:
core-shared/jobs (IJobQueue + 2 impls), core-events package
(IEventBus + 2 impls), recording test helpers, two ESLint rules,
existing-feature anchor retrofit (5 features × 6 anchors), bindAll
bus/queue swap, three Plop generators with anchor-comment protocol,
end-to-end proof-of-life (sign-up → welcome email), and the full
documentation set (ADR-015 + new guide + AGENTS/CLAUDE/scaffolding
updates). Self-review caught and fixed one type-inconsistency
(3-arg subscribe) and explicitly deferred the production task-
registration gap. TDD-ordered with one commit per task.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Long-form design for a future ADR-015. Defines IEventBus (new
@repo/core-events) and IJobQueue (@repo/core-shared/jobs); the bind/swap
rules; the events/, events/handlers/, jobs/, integrations/cms/jobs/
folder layout; the on-<publisher>-<event-kebab>.handler.ts naming rule;
the span+capture sandwich extension with op: "event-handler" and
op: "job"; three new ESLint rules; RecordingEventBus and RecordingJobQueue
for tests; pnpm turbo gen event {publish|consume} and gen job generators
plus the // <gen:*> anchor-comment protocol; and the existing-feature
retrofit. Status: draft pending user review.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Adds `pnpm turbo gen feature` to scaffold a Lazar-conformant feature
package matching the navigation reference shape: entity + Zod schema,
single use case (`get<Entity>`), controller, mock + Payload-stub real
repository (with span + capture), DI module/container/symbols, and tRPC
router with full BAD_REQUEST/NOT_FOUND error mapping. The generated
`bind-production.ts` and `bind-dev-seed.ts` compose the post-R44
`withSpan(tracer, opts, withCapture(logger, tags, factory(deps)))`
sandwich at bind time.
Verified by generating a sample `packages/example/` feature and running
`pnpm --filter @repo/example lint typecheck test` — all three pass
(9 test files, 25 tests). Cleaned up after verification so no example
package is committed.
Phase-1 limitations (documented in `docs/guides/scaffolding-a-feature.md`
and printed by the generator on success): no Payload CMS templates, no
React Query helpers, faker-driven factories left as stubs, single
entity / single use case, and aggregator wiring (core-api/root,
apps/web-next bindAll) is left as a manual checklist.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Six docs lagged after the post-merge R44 fix added withCapture +
reported-flag.ts. They mentioned withSpan only and described the
capture story as if it were inline in use-case / controller bodies.
This commit aligns them with what shipped.
CLAUDE.md (Key Conventions):
- "Spans applied at DI bind time" → "Spans + capture composed at DI
bind time" with the withSpan(withCapture(factory)) sandwich and the
outermost-span ordering note.
- "Capture at throw sites only" expanded to mention the
__sentryReported flag, the three flag-checking sites (withCapture,
SentryLogger, RecordingLogger), and where the helper lives.
AGENTS.md (Instrumentation conventions):
- Use case + controller wrapping example shows the full sandwich.
- Capture-rules table now explicitly says "via withCapture" for use
cases and controllers, and "flag set, withCapture bails" for the
bubbled cases.
packages/core-shared/AGENTS.md:
- "with-span.ts" entry split into a paired with-span + with-capture
block, including the actual sandwich code.
- New entry for reported-flag.ts explaining the helper and why
RecordingLogger inlines the check (boundary rule).
- Barrel re-export list updated.
docs/architecture/vertical-feature-spec.md (§16):
- The bind-production line now describes the withSpan(withCapture(...))
sandwich, the outermost-span rationale, and the bubbled-error bail.
docs/architecture/dependency-flow.md (TRACER/LOGGER subsection):
- bindAll diagram updated: real repo line annotates inline calls; use
case + controller lines show withSpan(withCapture(...)).
docs/guides/tdd-workflow.md (Asserting spans and captures):
- Direct-injection example shows the binder sandwich.
- Capture-assertion example explains the flag-bail behaviour and
links to the new tests/r44-no-double-capture.test.ts e2e example.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The .trace-tree blocks I added in §06 / §08 used var(--ink-2) (#5b4a3c —
medium brown), which clashed with the page's dedicated --code-bg
(#16110d, deep dark). Switched to --code-bg + --code-paper for text,
plus the same border + inset/drop shadow as pre.code, so the new blocks
read consistently with every other code block on the page.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
