@stonepandastudio/cairn 0.4.1 → 0.5.0

package/lib/render/index.js

@@ -0,0 +1,210 @@
+'use strict';
+
+// cairn render — turn the bundled `presets/` into a repo's `ai/` scaffolding.
+//
+// Greenfield only: it writes files that do not exist, records them in the
+// manifest, and leaves anything already on disk alone (reporting it). The
+// three-way merge that would let it re-render over local edits is `cairn sync`,
+// which is not built yet — for a fresh repo there is nothing to merge.
+
+const fs = require('fs');
+const path = require('path');
+
+const { render, stripHeaderComment } = require('./engine');
+const { hashContent } = require('../manifest');
+
+const PRIMARY_ONLY_SLOTS = new Set(['plan-step-ordering', 'architect-references']);
+
+const DEFAULT_WORKFLOW = {
+  steps: [
+    { id: 'brief', fn: 'create_brief', command: 'create-brief', role: 'architect', oneLine: 'creates the task brief scaffold' },
+    { id: 'describe', fn: 'enrich_description', command: 'enrich-description', role: 'architect', oneLine: 'iterative discussion, then writes the enriched description' },
+    { id: 'plan', fn: 'plan_task', command: 'plan-task', role: 'architect', oneLine: 'produces the implementation plan and context-doc updates' },
+    { id: 'execute', fn: 'execute_plan', command: 'execute-plan', role: 'developer', oneLine: 'implements the plan' },
+    { id: 'review', fn: 'code_review', command: 'code-review', role: 'reviewer', oneLine: 'checks the result against the plan and the guidelines' },
+  ],
+};
+
+const ROLE_MODEL = { architect: 'Sonnet', developer: 'Haiku', reviewer: 'Sonnet' };
+
+function cap(s) {
+  return s ? s[0].toUpperCase() + s.slice(1) : s;
+}
+
+function trackerContext(t = {}) {
+  const provider = t.provider || 'none';
+  const remote = provider === 'jira-server' || provider === 'youtrack';
+  return {
+    provider,
+    remote,
+    providerLabel: { 'jira-server': 'Jira', youtrack: 'YouTrack', none: 'no tracker' }[provider] || provider,
+    exampleKey: t.projectKey || (remote ? 'PROJ' : 'TASK'),
+    slug: provider === 'jira-server' ? 'jira' : provider === 'youtrack' ? 'youtrack' : 'tracker',
+    subtaskMarker: provider === 'youtrack' ? 'youtrack-subtask' : 'jira-subtask',
+    reviewStage: (t.statuses && t.statuses.done) || 'Review',
+    parentTerm: remote ? 'parent issue' : 'task',
+    childTerm: remote ? 'child issue' : 'step',
+  };
+}
+
+function loadWorkflow(config, presetsDir) {
+  if (config.workflow && Array.isArray(config.workflow.steps)) return config.workflow;
+  const file = path.join(presetsDir, 'core', 'workflow.json');
+  if (fs.existsSync(file)) {
+    try {
+      return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch {
+      /* fall through to the built-in default */
+    }
+  }
+  return DEFAULT_WORKFLOW;
+}
+
+function buildContext(config, presetsDir) {
+  const stack = config.stack && config.stack.length ? config.stack : ['unknown'];
+  const tracker = trackerContext(config.tracker);
+  const workflow = loadWorkflow(config, presetsDir);
+
+  const agents = config.agents || {};
+  const roleName = (role) =>
+    (agents[role] && agents[role].name) || `${cap(stack[0])}${cap(role)}Agent`;
+  const roleDoc = (role) => (agents[role] && agents[role].doc) || `ai/agents/${role}.md`;
+
+  workflow.steps.forEach((s) => {
+    s.agentName = roleName(s.role);
+    s.agentDoc = roleDoc(s.role);
+    s.model = ROLE_MODEL[s.role] || null;
+    s.trackerAction = tracker.remote ? s.trackerAction || 'sync — see the rows below' : 'n/a';
+    s.tracker = tracker.remote && s.role === 'architect' ? true : null;
+  });
+
+  return {
+    stack,
+    tracker,
+    workflow,
+    model: config.model || 'claude-sonnet-5',
+    architectAgent: roleName('architect'),
+    developerAgent: roleName('developer'),
+    reviewerAgent: roleName('reviewer'),
+    project: {
+      assistantName:
+        (config.vars && config.vars.assistantName) || `${cap(stack[0])} Dev Assistant`,
+    },
+    agents: ['architect', 'developer', 'reviewer'].map((r) => ({ name: roleName(r), doc: roleDoc(r) })),
+    ...(config.vars || {}),
+  };
+}
+
+function makeResolvePartial(stack, presetsDir) {
+  return (name) => {
+    const m = name.match(/^stack\/(.+)$/);
+    if (!m) return null;
+    const slot = m[1];
+    const entries = PRIMARY_ONLY_SLOTS.has(slot) ? stack.slice(0, 1) : stack;
+    const parts = [];
+    for (const entry of entries) {
+      const file = path.join(presetsDir, entry, 'slots', `${slot}.md`);
+      if (fs.existsSync(file)) parts.push(stripHeaderComment(fs.readFileSync(file, 'utf8')).trim());
+    }
+    if (!parts.length) return null;
+    // Table-row slots (every part starts with `|`) concatenate line-to-line;
+    // prose slots need a blank line between them.
+    const sep = parts.every((p) => p.startsWith('|')) ? '\n' : '\n\n';
+    return parts.join(sep);
+  };
+}
+
+function readPreset(presetsDir, rel) {
+  const file = path.join(presetsDir, rel);
+  return fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : null;
+}
+
+// Concatenate `<entry>/code-guidelines.md` for every stack entry that ships one.
+function codeGuidelines(stack, presetsDir, ctx, resolvePartial) {
+  const blocks = [];
+  for (const entry of stack) {
+    const raw = readPreset(presetsDir, `${entry}/code-guidelines.md`);
+    if (raw) blocks.push(render(raw, ctx, resolvePartial).trim());
+  }
+  return blocks.length ? blocks.join('\n\n---\n\n') + '\n' : null;
+}
+
+// Returns { planned: [[rel, content, source, note?]], kept: [{ rel, reason }] }.
+// `manifest` + `repoPath` drive the greenfield guard: a file cairn has not
+// written is never touched, and one it wrote but a human has since edited is
+// kept and reported (the re-render that respects local edits is `cairn sync`).
+function planRender({ config, presetsDir, manifest = { files: {} }, repoPath = null }) {
+  const ctx = buildContext(config, presetsDir);
+  const resolvePartial = makeResolvePartial(ctx.stack, presetsDir);
+
+  const targets = [];
+
+  const stub = readPreset(presetsDir, 'core/commands/_stub.md');
+  if (stub) {
+    for (const step of ctx.workflow.steps) {
+      targets.push([
+        `.claude/commands/${step.command}.md`,
+        render(stub, { ...ctx, step }, resolvePartial),
+        'core/commands/_stub.md',
+      ]);
+    }
+  }
+
+  const stepFor = (role) => ctx.workflow.steps.find((s) => s.role === role) || {};
+  for (const role of ['architect', 'developer', 'reviewer']) {
+    const raw = readPreset(presetsDir, `core/agents/${role}.md`);
+    if (raw) {
+      targets.push([
+        `ai/agents/${role}.md`,
+        render(raw, { ...ctx, step: stepFor(role) }, resolvePartial),
+        `core/agents/${role}.md`,
+      ]);
+    }
+  }
+
+  for (const [rel, src] of [
+    ['ai/AGENTS.md', 'core/AGENTS.md'],
+    ['ai/WORKFLOW.md', 'core/WORKFLOW.md'],
+  ]) {
+    const raw = readPreset(presetsDir, src);
+    if (raw) targets.push([rel, render(raw, ctx, resolvePartial), src]);
+  }
+
+  const guidelines = codeGuidelines(ctx.stack, presetsDir, ctx, resolvePartial);
+  if (guidelines) {
+    targets.push([
+      'ai/infrastructure/code-guidelines.md',
+      guidelines,
+      'presets:<stack>/code-guidelines.md',
+      'seed — fork it, cairn will not re-render over your edits',
+    ]);
+  }
+
+  const planned = [];
+  const kept = [];
+  for (const [rel, content, source, note] of targets) {
+    const entry = manifest.files[rel];
+    const abs = repoPath ? path.join(repoPath, rel) : null;
+    const onDisk = abs && fs.existsSync(abs) ? fs.readFileSync(abs, 'utf8') : null;
+
+    if (entry && onDisk !== null && hashContent(onDisk) !== entry.hash) {
+      kept.push({ rel, reason: 'hand-edited since cairn wrote it' });
+      continue;
+    }
+    if (entry && onDisk !== null && hashContent(content) === entry.hash) continue; // current, on disk
+    if (entry && onDisk !== null) {
+      kept.push({ rel, reason: 'the template changed — `cairn sync` will merge it' });
+      continue;
+    }
+    if (!entry && onDisk !== null) {
+      kept.push({ rel, reason: 'already on disk, not written by cairn' });
+      continue;
+    }
+    // Not on disk: brand new, or a manifested file that was deleted — (re)write it.
+    planned.push([rel, content, source, entry ? 'restoring' : note]);
+  }
+
+  return { planned, kept, context: ctx };
+}
+
+module.exports = { planRender, buildContext, trackerContext, DEFAULT_WORKFLOW };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stonepandastudio/cairn",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Shared AI workflow scaffolding for Stone Panda repos — issue tracker client and drift doctor.",
   "license": "UNLICENSED",
   "repository": {
@@ -24,6 +24,7 @@
     "bin/",
     "lib/",
     "templates/",
+    "presets/",
     "schema.json",
     "README.md"
   ],

package/presets/EXTRACTION.md

@@ -0,0 +1,210 @@
+# Extraction record
+
+What was pulled into `presets/`, from where, and — more importantly — what was
+deliberately left in the repos. Measured 2026-08-01 by splitting each
+`code-guidelines.md` on `## ` headings and running cairn's own line differ over
+matching sections.
+
+The file-level numbers in `DESIGN.md` (backend 43% same, frontend 76%) turned out
+to be the wrong resolution. Per section the picture is much sharper.
+
+## Backend — glossr-api (828 ln) vs snap-backend (404 ln)
+
+| Section | Same | Disposition |
+|---|---|---|
+| General TypeScript Guidelines | 100% | → `nestjs` |
+| NestJS Module Structure | 100% | → `nestjs` |
+| Services | 100% | → `nestjs` |
+| Error Handling | 100% | → `nestjs` |
+| Security | 100% | → `nestjs` |
+| Constants | 100% | → `nestjs` |
+| Enums | 100% | → `nestjs` |
+| Code Quality | 100% | → `nestjs` |
+| File Organization | 93% | → `nestjs` (union; glossr's `interfaces/` kept) |
+| File Naming Conventions | 80% | → `nestjs`, DTO lines to `dto-naming` slot |
+| TypeORM Entities | 100% | → `typeorm` |
+| Database Query Decomposition Pattern | 100% | → `typeorm` |
+| Mappers | 100% | → `typeorm` — **but see finding 1** |
+| Database Operations | 85% | → `typeorm` (glossr's stronger wording) |
+| Query Configuration | 75% | → `typeorm` (glossr is a strict superset) |
+| Validation | 43% | spine → `nestjs`, rest → `validation-stack` slot |
+| DTOs | 28% | spine → `nestjs`, rest → `dto-definition` slot |
+| Controllers | 16% | spine → `nestjs`, rest → `controller-response` slot |
+| Response Transformation | disjoint | entirely `response-transformation` slot |
+| **Testing** | **7%** | **stays project-owned** |
+| Interfaces, Error Codes, No Magic Strings, Pagination | glossr only | → `nestjs` (promoted, generic) |
+| QueryBuilder Field Selection, Migrations | glossr only | → `typeorm` (promoted, generic) |
+| Redis Key Naming | glossr only | **stays project-owned** — names a specific app prefix |
+
+### The backend divergence is one axis, not entropy
+
+Controllers 16%, DTOs 28%, Validation 43% and the two mutually exclusive Response
+Transformation sections are all the same disagreement:
+
+```
+glossr-api    Zod          nestjs-zod, createZodDto, @ZodResponse
+snap-backend  class-*      class-validator, class-transformer, @ResponseMapper
+```
+
+That is a **choice with two known values**, not accumulated rot — so it is a slot
+with two variants, not a reason to fork the file. The file-level 43% reading
+suggested "leave it alone"; the section-level reading says most of the document is
+shareable and one decision is not.
+
+## Frontend — glossr-frontend (231 ln) vs snap-frontend (191 ln)
+
+| Section | Same | Disposition |
+|---|---|---|
+| Preamble (Angular rules) | 100% | → `angular` |
+| Theming and Colors (+ 4 subsections, 94 ln) | 100% | → `angular` |
+| Component Selectors | 100% | → `angular` |
+| Constants | 100% | → `angular` |
+| Enums | 100% | → `angular` |
+| Translation Key Naming / Examples | 100% | → `angular` |
+| Translations — sourcing | 48% | → `translation-source` slot |
+| Change detection, Comments | snap only | → `angular` (promoted, generic) |
+
+Cleaner than the backend: after the sourcing slot is carved out, essentially the
+whole document is shared.
+
+## CLI — glossr-cli (203 ln)
+
+Not extracted. It shares no section headings with either pair, and per
+`DESIGN.md` it is a stack of one, so nothing can be measured against it. A
+`presets/cli/` should wait for a second CLI repo or a deliberate hand-authored
+decision — not be reverse-engineered from a sample of one.
+
+## Deliberately not extracted
+
+- **Testing (7% same).** Two genuinely different regimes: glossr keeps all tests
+  under `test/` with integration helpers and factories; snap colocates `.spec.ts`
+  and targets >80% coverage. Extracting this would force one project onto the
+  other's layout.
+- **Redis Key Naming.** Correct guidance, but it hardcodes `REDIS_APP_PREFIX =
+  'glossr'`. Generalising it would leave a rule with no concrete value in it.
+- **`code-guidelines.md` as a whole remains `fork` mode** per `DESIGN.md`. These
+  presets are seeds. A repo that takes one owns its copy; cairn does not plan to
+  rewrite these files on upgrade.
+
+## Findings
+
+Two things surfaced only because the content was read section by section.
+
+### 1. glossr-api's Mappers section documents a decorator it does not have
+
+The section is byte-identical to snap-backend's and says:
+
+> Basic entity-to-DTO conversion (use `@ResponseMapper` decorator)
+
+`grep -rl ResponseMapper glossr-api/src` returns **nothing**. glossr moved to Zod;
+the Mappers section was copied and never updated. It has been instructing agents to
+reach for a decorator that does not exist in that codebase.
+
+**A 100%-identical section is not automatically a correct one.** Identical means
+"nobody has diverged", which includes "nobody has noticed". The preset version now
+points at the response-transformation slot instead of naming a decorator.
+
+### 2. Stale line-number cross-references
+
+`glossr-api` contains *"See **Query Configuration** section below (lines 232-325)"*
+— the section actually starts at line 323. Both repos contain *"Create Maps for O(1)
+lookup (per guideline line 122)"*. Line numbers in a document that gets edited are
+wrong the moment it is edited. Replaced with section-name references.
+
+Also fixed in passing, present identically in both frontend repos: the typos
+`cosntants` and `inrastructure`. Identical typos across two repos are the clearest
+possible proof of copy-paste, and are a decent cheap signal for finding more.
+
+## Agents, workflow, commands — 2026-09-09
+
+Second pass, `snap-proof/{backend,frontend}` again. The 2026-07-31 survey scored the
+reviewer contract at 85–92% and treated that as a ceiling. Reading them in full, the
+**structure** is closer to identical — the divergence is confined to stack-specific
+rule tables and reference lists, which are exactly slot-shaped.
+
+| artefact | disposition | measurement |
+|---|---|---|
+| `.claude/commands/*.md` | → `core/commands/_stub.md` | every stub byte-identical modulo `{{ step.agentName }}` + `{{ step.agentDoc }}` (frontend copies carry a stray BOM) |
+| `ai/agents/{node,angular}-reviewer.md` | contract → `core/agents/reviewer.md`; Dimension-2 table → `{nestjs,angular}/slots/review-checklist.md` | `diff` shows ~15 changed lines out of 160, all in the rule table, the model-check string, and agent names |
+| `ai/agents/{node,angular}-developer.md` | spine → `core/agents/developer.md`; "Implementation reference" → `{nestjs,angular}/slots/implementation-reference.md` | E.1–E.5 identical; frontend carried 3 safety notes the backend lacked (folded into core) |
+| `ai/agents/{node-architect,architect-lead}.md` | Mode A/B + file-roles + Plan format → `core/agents/architect.md`; the rest → 5 small `{nestjs,angular}/slots/architect-*.md` | whole scaffold shared; slots are the mandatory-doc list, discussion topics, plan-step ordering, A.1 references |
+| `ai/WORKFLOW.md` | → `core/WORKFLOW.md`, rendered from `workflow.steps[].tracker` + `tracker.*` | same document both sides; only the provider block, stage names, and sync-point actions differ — all config |
+| `ai/AGENTS.md` | → `core/AGENTS.md` skeleton | same structure; rendering it removes live drift (frontend's still says "Jira" while its `.env` and commands are on YouTrack) |
+
+### `react` + `drizzle` seeded from charityiq-app — 2026-09-09
+
+`charityiq-app` is a separate product (single founder, UK charity SaaS), Next.js 16
+App Router + Drizzle + Supabase + Inngest, at Sprint 0 — a scaffold with documented
+intent (`CLAUDE.md` hard rules, `docs/adr/0001-stack.md`) and almost no code
+(everything under `lib/` is a `TODO(Sprint N)` stub).
+
+So the seed is **conventions and structure, not code patterns** — and there is no
+second repo to diff against, so what is "React-generic" vs "charityiq-specific" is
+hand-judged, not measured. Same limit as `preset-cli`.
+
+- `presets/react/` — components (folder-by-role: `ui`/`feature`/`brand`), no
+  `localStorage`, Tailwind v4 `@theme` tokens (no `tailwind.config.ts`), Vitest +
+  Testing Library + MSW + Playwright, Biome (tabs, double quotes). **Not** in it:
+  RSC, Server Actions, route handlers, the App Router — those are Next.js-specific
+  and belong in a future `presets/nextjs` that composes on top.
+- `presets/drizzle/` — one schema module (`lib/db/schema.ts`), `drizzle-kit
+  generate` for mechanical migrations, hand-SQL only in `supabase/migrations/`, RLS
+  policies in the migration not the schema, server client never imported from a
+  `"use client"` module. Parallel to `presets/typeorm`.
+- `presets/nextjs/` — the App-Router framework layer, added on top of `react`
+  (`--stack nextjs,react,…`, nextjs first so its fullstack plan ordering wins). Owns
+  the server/client boundary (`"use client"` discipline, no server-only imports
+  across it), Server Actions (`'use server'`, validate args, revalidate after a
+  write), Route Handlers (webhooks, verify caller), the App-Router file conventions,
+  `next/font` / `next/image` / `Metadata`, and a "the framework moves fast, read the
+  installed docs" note. **Not** in it: `requireTier()` + `audit.log()` on every
+  mutation — that is charityiq's business rule, tier-3 fork, not Next.js-generic.
+- `presets/tailwind/` — styling is a third composable axis, orthogonal to the
+  framework (proof: Angular repos use SCSS `theme.$variable`, charityiq uses
+  Tailwind `@theme`, either could use either). The generic rules: tokens in a
+  `@theme` block not a `tailwind.config.ts`, no raw hex in markup, dark mode by
+  re-mapping semantic tokens. The React preset was made styling-agnostic to match.
+  Angular's SCSS theming stays inline in `presets/angular` for now — one system
+  across its two repos, not worth its own preset until a second SCSS-theming repo
+  appears (then: `presets/scss-theme`).
+
+Stays charityiq-owned (tier 3, `fork`): the hard business rules — `requireTier()` +
+`audit.log()` on every mutation, RAG-grounded AI through `lib/ai/client.ts`, the
+audit row in the same transaction as the state change — plus `docs/adr/`, the build
+guide, and the versioned-prompt registry (`docs/prompts/<name>/<version>.md`). Those
+are the project's constitution, not shareable scaffolding.
+
+### The nestjs slots were split nestjs / typeorm — 2026-09-09
+
+The first cut of `presets/nestjs/slots/*` (review-checklist, implementation-reference,
+key-patterns, architect-mandatory-docs, architect-discussion-topics) mixed framework
+rules with TypeORM rules. Split: the framework half stays in `nestjs/slots/`, the ORM
+half moved to `presets/typeorm/slots/` under the same filenames. The renderer appends
+one from each `stack[]` entry, so `--stack nestjs,typeorm` reconstitutes the original
+and `--stack nestjs,drizzle` would pair the framework rules with a Drizzle slot set
+instead. `plan-step-ordering` and `architect-references` are primary-stack-only (not
+concatenated) — noted in their headers.
+
+### QA agents — preset-level, not extracted
+
+Backend runs three (`qa-architect` / `qa-developer` / `qa-orchestrator`, ~630 ln
+of Jest + factories + `src/feature/` layout + `yarn test:db` scripts); frontend runs
+one (`angular-qa`, Playwright + `data-testid` + page objects). 33% similar at best,
+confirming the 2026-07-31 read. The bodies are one project's test setup, not
+shareable content — vendoring them as a "preset" would over-claim. They belong under
+`{nestjs,angular}/agents/` once a second repo on the same stack shows what is
+actually shared, the same "no peer" limit `preset-cli` has.
+
+### Rot the renderer removes
+
+- backend `node-reviewer.md` still requires `claude-sonnet-4-6` — frontend already says `claude-sonnet-5`
+- frontend `AGENTS.md` + `WORKFLOW.md` are entirely Jira; the repo is on YouTrack (`.env`, `.claude/commands/youtrack-*`)
+- same review step is `code_review` in backend, `review_plan` in frontend — one verb, rendered from `workflow.steps[].command`
+- backend reviewer/developer hard-code an `ai/tasks/PROOF-[task]/` path — breaks on `LOCAL-` folders; the core versions use `ai/tasks/[task]/`
+
+## Not wired up yet
+
+There is no renderer. Nothing consumes `{{> slot: … }}` or `{{> stack/… }}`, and no
+repo reads these files. They are the input for the agent-preset roadmap step
+(`DESIGN.md`, "### Sequencing" step 4), and are already useful as the canonical
+version of scaffolding that currently exists as two drifting copies.

package/presets/README.md

@@ -0,0 +1,86 @@
+# Presets
+
+Extracted guideline content shared across the repos. Internal only — an in-repo
+folder, deliberately package-shaped so promotion to `@stonepandastudio/cairn-preset-*` is
+adding a `package.json` rather than a refactor.
+
+Nothing here is wired into a renderer yet. These are the *inputs* the renderer will
+consume once the projects layer and extension mechanisms land (see `DESIGN.md`,
+"Multi-repo projects"). Until then they are seeds: readable, diffable, and already
+useful as the canonical version of guidance that currently exists in two drifting
+copies.
+
+## Layout
+
+```
+presets/
+  core/       stack-agnostic — agent role contracts, command stub, WORKFLOW/AGENTS skeletons
+    agents/   architect.md, developer.md, reviewer.md   (85–92% identical across stacks)
+    commands/ _stub.md                                  (renders one file per workflow step)
+  nestjs/     NestJS + TypeScript framework spine, validation-stack + ORM agnostic
+    variants/ validation-zod.md, validation-class-validator.md
+    slots/    the framework side of each {{> stack/… }} point
+  typeorm/    ORM add-on — entities, queries, migrations, decomposition
+    slots/    the ORM side of the same {{> stack/… }} points (appended to nestjs)
+  drizzle/    ORM add-on — Drizzle schema, drizzle-kit migrations, RLS in migrations
+    slots/    the ORM side, for a Postgres/Supabase stack
+  angular/    Angular spine + SCSS theming + i18n (styling still inline here — one system, two repos)
+    variants/ i18n-glossr.md, i18n-external-service.md
+    slots/    the Angular side of the same {{> stack/… }} points
+  react/      React frontend spine — components, hooks, state, testing (styling-agnostic)
+    slots/    the React side of the same {{> stack/… }} points
+  nextjs/     App-Router layer over `react` — server/client boundary, actions, route handlers
+    slots/    the Next.js side of the same {{> stack/… }} points
+  tailwind/   styling add-on — @theme tokens, no tailwind.config.ts, dark mode via token re-map
+    slots/    the styling side of the same {{> stack/… }} points
+  EXTRACTION.md   what was extracted from where, and what deliberately was not
+```
+
+Compose the slots a repo needs. Rough axes — **framework** (`nestjs`, `react`,
+`nextjs` on top of `react`), **ORM** (`typeorm` / `drizzle`), **styling** (`tailwind`):
+
+```
+--stack nestjs,typeorm                  snap-proof / glossr backend
+--stack angular                         snap-proof / glossr frontend (SCSS theming inline for now)
+--stack nextjs,react,tailwind,drizzle   charityiq — nextjs primary (owns plan ordering + fullstack refs)
+--stack react,tailwind                  a Vite SPA against a separate API
+```
+
+`typeorm` and `angular` are seeded from two repos; `drizzle`, `react`, `nextjs`,
+`tailwind` from one (charityiq). A single-consumer preset is hand-judged, not
+measured, and gets refined when a second repo on that axis appears — the
+`preset-cli` "no peer" limit.
+
+`nestjs` and `typeorm` are separate on purpose. Every backend repo composes both
+today, but the split is what proves the composition model works — a future backend
+on Prisma or Drizzle takes `nestjs` without `typeorm`, and a repo declares the
+composition as `--stack nestjs,typeorm`.
+
+## Slots
+
+A slot marks a point where a shared template knows a decision exists but not which
+way a repo (or a stack) went. Two flavours:
+
+- **`{{> slot: validation-stack }}`** in a `code-guidelines.md` — the repo picks a
+  file from `variants/` by name. Where a repo needs something no variant covers, it
+  supplies its own partial — the signal that a third variant may be warranted.
+- **`{{> stack/review-checklist }}`** in a `core/` agent contract — filled from each
+  stack entry's `slots/` folder. Two fill modes:
+  - **concatenated** — the renderer appends the slot from every entry in `stack[]`,
+    in order. `--stack nestjs,typeorm` → `review-checklist` is the nestjs framework
+    rows followed by the typeorm ORM rows. Used for checklists, doc lists, reference
+    lists.
+  - **primary-only** — the slot is taken from `stack[0]` alone, because it is one
+    coherent thing that cannot be concatenated. `plan-step-ordering` (a numbered
+    sequence) and `architect-references` are primary-only; their file header says so.
+
+Slots exist to keep the merge cheap. A template update that does not touch a slot
+never conflicts with a repo's choice, which is the whole reason the extension
+mechanisms are three rather than one.
+
+## What is deliberately absent
+
+Sections that are genuinely per-project stay per-project — they are listed in
+`EXTRACTION.md` with the measurement that justified leaving them out. Extracting
+content that *should* differ is the failure mode this whole exercise is designed to
+avoid: it would report every legitimate project difference as drift, forever.