agentic-dev/TEMPLATE.md

Template snapshot — provenance and usage

This branch (template/clean-slate) is a curated, product-agnostic snapshot of the Clean Architecture monorepo template — "template-vertical v2". It is a single orphan commit with no shared history with main.

Provenance

• Source: the Veect monorepo (local repo Projects/Veect), commit bb4a0c7219b62aefb77d3eede3d29ccedc970c97 on the platform-retrofit line ("test(web-next): boot smoke asserts auth-only bindAll").
• Snapshot date: 2026-07-12.
• Why that commit: it is the maximally generic moment of the retrofit — demo content deleted, auth as the only (reference) feature, web-next a clean authenticated shell, all gates green including live lint — before any product-specific optional cores or agent-docs rewrites landed.

What was curated out (relative to the source commit)

Product-specific material was removed; everything else is content-identical to the source tree (the commit hook's Prettier pass normalized line-wrapping in ~96 files that predated Prettier conformance — cosmetic only, gates unaffected):

• docs/product/ — the entire product spec bundle + reference prototypes.
• docs/decisions/adr-027-*.md, adr-028-*.md, adr-029-*.md — the three product-domain ADRs (ADR-001–026, which are template-generic, remain).
• The "Veect product domain" section of docs/glossary.md (the rest of the glossary is untouched).
• docs/work/prds/platform-retrofit.prd.md, docs/work/prds/walking-skeleton.prd.md and their epics docs/work/epics/{platform-retrofit,walking-skeleton}/.
• docs/work/archive/ — the source repo's archived template-era work items. Choice: deleted, not kept — it was the source repo's history bookkeeping (epic/story state for work already merged), which has no value to a project starting fresh; the material remains in the source repo's git history.
• docs/library-decisions/2026-07-12-zustand.md and 2026-07-12-@xyflow/react.md — product-editor library traces for dependencies that are not present in any package.json of this tree (they referenced the deleted ADR-028/029).
• Product naming in the app shell (apps/web-next/src/app/{layout,page}.tsx now say "Template"), the docs/product/reference/ lint/format/coverage excludes in eslint.config.js, .prettierignore, scripts/coverage/diff.mjs (+ its test case), and the release-please workflow comment.
• docs/work/_system/_state.json regenerated for the curated tree (0 epics).

The only intentional occurrence of the source product's name on this branch is this provenance note (grep target: Veect).

Baseline defects fixed relative to the original template

This snapshot carries repairs the original template-vertical shipped broken:

1. Broken turbo lint graph — a demo-feature dependency cycle made pnpm lint unable to run across the workspace. The demo features are gone and lint runs live across the whole graph.
2. Missing @vitest/coverage-v8 — 9 packages declared coverage without the provider devDep, so --coverage runs failed. Every package that runs vitest with coverage now has the provider installed.
3. Unparseable documented L0 invocation — docs prescribed pnpm test -- --coverage, which turbo cannot parse. The root test:coverage script (turbo run test -- --coverage) is the supported invocation and the docs reference it.

Also retained: calibrated per-package coverage excludes, generator anchors + generators, the web-next shell + boot smoke test, and the root-only release-please config as the template default (hybrid per-feature versioning is a documented alternative — see ADR-021, docs/guides/releasing.md, and the pre-retrofit config in the source repo's git history).

Audit-fix sync — 2026-07-13

This branch is now a maintained template branch (it has grown beyond the original 2-commit snapshot). On 2026-07-13 the applicable subset of the upstream template audit-fix effort was ported here, adapted to the clean-slate auth-only shape. Six coherent commits landed on top of the snapshot:

• chore(tooling) — root playwright config in test:visual, pruned dead VERCEL_ENV from turbo.json, single Chromium install in CI, a dedicated vitest.scripts.config.mjs + pnpm test:scripts runner for scripts/ (node:test → vitest), repo-wide *.tsbuildinfo gitignore + untrack, and every @trpc/* range aligned on ^11.18.0.
• fix(compliance) — DSR caller-scoping + audit-trail exports, consent allow-list/merge/superjson, core-audit keyed 128-bit pseudonyms + audit-logs collection + GDPR erasure hook, core-shared retention-purge (task + tombstone + boot registration) and the require-authenticated tRPC helper. core-cms was reduced to the auth-only collection set (users + audit-logs; the users+workspaces shape from the product fork does not apply — there is no workspaces feature here).
• fix(auth) — server-side jti session-revocation denylist, constant-time signature compare, server-derived clientIp (dropped from the public sign-in schema), crypto-path tests, and the users DSR pii map.
• refactor(core-trpc) — removed the illegal core-trpc → core-api edge; the context + providers are now AnyTRPCRouter-generic.
• feat(web-next) — per-request createWebNextTrpcContext (server user resolution + live consent/dsr bindings), compliance bindings in bind-production, and manifest-seeded InMemoryRateLimit on the production path. Reduced to the auth-only shell — no workspaces binder, no product discovery/runner provisioning.
• test(coverage) — cover-the-diff repairs for the ported auth router + core-dsr export, plus mirrored coverage-diff excludes.

The four upstream demo-feature fixes (blog/media/marketing-pages/navigation) were skipped — those features do not exist on this branch. No product code or naming was introduced; the sole intentional occurrence of the source product's name remains this provenance note.

How to start a project from this branch

# 1. Create a fresh repo from the snapshot (no template history needed):
git clone <this-repo> my-app && cd my-app
git checkout template/clean-slate
git checkout --orphan main && git commit -m "chore: init from template/clean-slate"

# 2. Bootstrap:
pnpm install                 # installs + wires husky pre-commit hooks
pnpm dev                     # boots in dev-seed mode (no Postgres needed)

# 3. Verify the gates:
pnpm typecheck && pnpm lint && pnpm test && pnpm conformance

# 4. Rename the root package (optional) and add your first feature:
pnpm turbo gen feature <name>

Read docs/guides/runbook.md first; CLAUDE.md is the conventions reference. The auth package is the reference feature — study it, don't delete it until you have a second feature to learn from.