Danijel Martinek
9b8c5f7416
Note that the branch is now maintained (grown beyond the snapshot) and enumerate the six ported clusters, including the auth-only reductions of core-cms and web-next. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_016j8z4VHjedXDTjEDNg7qHK
130 lines
6.8 KiB
Markdown
130 lines
6.8 KiB
Markdown
# 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
|
||
|
||
```bash
|
||
# 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.
|