@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/ba-develop/cli/compute-page-diff/index.ts

@@ -0,0 +1,89 @@
+#!/usr/bin/env node
+/**
+ * cli:compute-page-diff — entry point.
+ *
+ * PURE spec-diff for ba-develop Phase 3a targeted re-runs. Compares the
+ * canonical hash of every `pagespecs/<Entity>.<view>.md` machine block against
+ * the previous `.run-snapshot.json` and reports added / modified / removed /
+ * unchanged. `toRegenerate = added ∪ modified`.
+ *
+ * This CLI performs NO inspection of generated `.tsx` files — the disk-drift
+ * guard (closing the silent-skip class) is the orchestrator's job. See
+ * `references/gates.md` § "Phase 3 pre-entry" and `disk-drift.ts`.
+ *
+ * Invocation:
+ *   npx tsx skills/ba-develop/cli/compute-page-diff/index.ts \
+ *     --spec '{"moduleRoot":".smartstack/ba/<APP>/<MODULE>"}'
+ *
+ * Exit code: always 0 on a successful diff. An empty `toRegenerate` is a valid
+ * "nothing changed in the specs" answer, NOT a failure — the orchestrator still
+ * runs the disk-drift guard before deciding to skip Phase 3a.
+ */
+import { parseArgs } from 'node:util'
+import { validate } from './validate.js'
+import { computeDiff } from './compute-diff.js'
+import { executeEnvelope, failExecute, printEnvelope } from '../../../lib/output.js'
+import type { ComputePageDiffReport } from './types.js'
+
+const COMMAND = 'compute-page-diff'
+
+function main(): void {
+  const { values } = parseArgs({
+    options: { spec: { type: 'string' } },
+    strict: true,
+  })
+
+  if (!values.spec) {
+    printEnvelope(failExecute<ComputePageDiffReport>(COMMAND, ['--spec is required']))
+    process.exit(1)
+  }
+
+  let raw: unknown
+  try {
+    raw = JSON.parse(values.spec)
+  } catch {
+    printEnvelope(failExecute<ComputePageDiffReport>(COMMAND, ['Invalid JSON in --spec']))
+    process.exit(1)
+  }
+
+  const validation = validate(raw)
+  if (!validation.valid || !validation.spec) {
+    printEnvelope(failExecute<ComputePageDiffReport>(COMMAND, validation.errors))
+    process.exit(1)
+  }
+
+  const report = computeDiff(validation.spec)
+
+  const nextSteps: string[] = []
+  if (!report.snapshotFound) {
+    nextSteps.push(
+      'No .run-snapshot.json found (first run): every page is "added" → regenerate all, then write the snapshot via update-snapshot.',
+    )
+  }
+  nextSteps.push(
+    'Orchestrator: regenerate = toRegenerate ∪ disk-drift. For each page in diff.unchanged, run validate-page; ' +
+      'fold in any page whose .tsx is missing or has err violations. Skip Phase 3a ONLY if the union is empty. ' +
+      'After a successful regeneration, run update-snapshot. See references/gates.md § "Phase 3 pre-entry".',
+  )
+
+  printEnvelope(
+    executeEnvelope<ComputePageDiffReport>(COMMAND, {
+      success: true,
+      data: {
+        added: report.diff.added.length,
+        modified: report.diff.modified.length,
+        removed: report.diff.removed.length,
+        unchanged: report.diff.unchanged.length,
+        toRegenerate: report.toRegenerate.length,
+        snapshotFound: report.snapshotFound,
+      },
+      report,
+      warnings: report.warnings,
+      nextSteps,
+    }),
+  )
+
+  process.exit(0)
+}
+
+main()

package/templates/skills/ba-develop/cli/compute-page-diff/scan-pagespecs.ts

@@ -0,0 +1,115 @@
+/**
+ * cli:compute-page-diff — scan-pagespecs.ts
+ *
+ * Reads every `<moduleRoot>/pagespecs/*.md`, extracts the fenced ```json
+ * machine block, and computes a canonical content hash per page. Unlike
+ * `scaffold-screen-controller/parse-pagespec.ts` (which filters by section +
+ * validates against PageSpecSchema), this scanner is NON-filtering and
+ * schema-agnostic: a diff only needs the page identity + a stable hash of the
+ * raw spec, so it keeps every JSON-valid pagespec in the module.
+ *
+ * Pure read-only. Malformed files (no fenced block / invalid JSON) produce a
+ * warning and are skipped — a single bad pagespec never aborts the diff.
+ */
+import { readFileSync, existsSync, readdirSync, statSync } from 'node:fs'
+import { join, basename } from 'node:path'
+import { canonicalHash } from '../../../lib/canonical-hash.js'
+
+export const SNAPSHOT_FILENAME = '.run-snapshot.json'
+
+export interface ScannedPage {
+  /** Page identity = pagespec filename without `.md` (convention `<Entity>.<view>`). */
+  key: string
+  /** Canonical sha256 of the parsed fenced JSON. */
+  hash: string
+}
+
+export interface ScanResult {
+  pages: ScannedPage[]
+  warnings: string[]
+}
+
+export interface RunSnapshot {
+  lastRun?: string
+  /** Flat `key → hash` map. */
+  pages: Record<string, string>
+}
+
+/** Extract the FIRST fenced ```json block. Identical regex to parse-pagespec. */
+export function extractFencedJson(md: string): string | null {
+  const m = md.match(/```json\s*\r?\n([\s\S]*?)\r?\n```/)
+  return m ? m[1] : null
+}
+
+/** Page identity from the pagespec filename (`TypeAffaire.list.md` → `TypeAffaire.list`). */
+export function pageKeyFromFilename(filename: string): string {
+  return basename(filename, '.md')
+}
+
+/**
+ * Scan `<moduleRoot>/pagespecs/*.md` → `{ key, hash }[]` sorted by key.
+ * Returns an empty result (no warning) when the `pagespecs/` dir is absent.
+ */
+export function scanPagespecs(moduleRoot: string): ScanResult {
+  const dir = join(moduleRoot, 'pagespecs')
+  const out: ScanResult = { pages: [], warnings: [] }
+  if (!existsSync(dir)) return out
+
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch (err) {
+    out.warnings.push(`cannot read ${dir}: ${(err as Error).message}`)
+    return out
+  }
+
+  for (const name of entries) {
+    if (!name.endsWith('.md')) continue
+    const full = join(dir, name)
+    try {
+      if (!statSync(full).isFile()) continue
+    } catch {
+      continue
+    }
+    let content: string
+    try {
+      content = readFileSync(full, 'utf8')
+    } catch (err) {
+      out.warnings.push(`${name}: cannot read file: ${(err as Error).message}`)
+      continue
+    }
+    const json = extractFencedJson(content)
+    if (json === null) {
+      out.warnings.push(`${name}: no fenced \`\`\`json block found — skipped`)
+      continue
+    }
+    let parsed: unknown
+    try {
+      parsed = JSON.parse(json)
+    } catch (err) {
+      out.warnings.push(`${name}: invalid JSON: ${(err as Error).message} — skipped`)
+      continue
+    }
+    out.pages.push({ key: pageKeyFromFilename(name), hash: canonicalHash(parsed) })
+  }
+
+  out.pages.sort((a, b) => a.key.localeCompare(b.key))
+  return out
+}
+
+/**
+ * Load `<moduleRoot>/.run-snapshot.json`. Returns an empty snapshot (and
+ * `found: false`) when the file is absent OR malformed — both cases mean
+ * "treat every current page as new", which the diff renders as `added`.
+ */
+export function loadSnapshot(moduleRoot: string): { snapshot: RunSnapshot; found: boolean } {
+  const path = join(moduleRoot, SNAPSHOT_FILENAME)
+  if (!existsSync(path)) return { snapshot: { pages: {} }, found: false }
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8')) as Partial<RunSnapshot>
+    const pages = raw.pages && typeof raw.pages === 'object' ? raw.pages : {}
+    return { snapshot: { pages, lastRun: raw.lastRun }, found: true }
+  } catch {
+    return { snapshot: { pages: {} }, found: false }
+  }
+}

package/templates/skills/ba-develop/cli/compute-page-diff/types.ts

@@ -0,0 +1,63 @@
+/**
+ * cli:compute-page-diff — types.ts
+ *
+ * PURE spec-diff for ba-develop Phase 3a targeted re-runs. Compares the
+ * canonical hash of every `pagespecs/<Entity>.<view>.md` machine block against
+ * the previous `.run-snapshot.json` and reports added / modified / removed /
+ * unchanged pages.
+ *
+ * This CLI performs NO inspection of generated `.tsx` files — the disk-drift
+ * guard (closing the silent-skip class) lives in the orchestrator. See
+ * `ba-develop/references/gates.md` § "Phase 3 pre-entry" and `disk-drift.ts`.
+ */
+import { z } from 'zod'
+
+export const ComputePageDiffInputSchema = z
+  .object({
+    /**
+     * Module folder holding the `pagespecs/` subdir and where
+     * `.run-snapshot.json` lives — e.g. `.smartstack/ba/<APP>/<MODULE>`.
+     */
+    moduleRoot: z.string().min(1),
+  })
+  .strict()
+
+export type ComputePageDiffInput = z.infer<typeof ComputePageDiffInputSchema>
+
+export interface ModifiedPage {
+  key: string
+  previousHash: string
+  currentHash: string
+}
+
+export interface PageDiff {
+  /** Pages present now but absent from the snapshot (incl. every page on first run). */
+  added: string[]
+  /** Pages whose pagespec hash changed since the snapshot. */
+  modified: ModifiedPage[]
+  /** Pages in the snapshot whose pagespec file no longer exists. */
+  removed: string[]
+  /** Pages whose pagespec hash is identical to the snapshot. */
+  unchanged: string[]
+}
+
+export interface ComputePageDiffReport {
+  moduleRoot: string
+  /** False on the first run (no snapshot) — the orchestrator then regenerates all. */
+  snapshotFound: boolean
+  diff: PageDiff
+  /**
+   * `added ∪ modified.key`, sorted. PURE spec-diff — the orchestrator unions
+   * this with the disk-drift set before deciding what to regenerate.
+   */
+  toRegenerate: string[]
+  /** Non-fatal pagespec parse issues (malformed file skipped). */
+  warnings: string[]
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+  spec?: ComputePageDiffInput
+}

package/templates/skills/ba-develop/cli/compute-page-diff/validate.ts

@@ -0,0 +1,20 @@
+/**
+ * cli:compute-page-diff — validate.ts
+ *
+ * Pure input validation (no I/O). Mirrors the validate/execute split used by
+ * every SmartStack dev CLI.
+ */
+import { ComputePageDiffInputSchema } from './types.js'
+import type { ValidationResult } from './types.js'
+
+export function validate(raw: unknown): ValidationResult {
+  const parsed = ComputePageDiffInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      valid: false,
+      errors: parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`),
+      warnings: [],
+    }
+  }
+  return { valid: true, errors: [], warnings: [], spec: parsed.data }
+}

package/templates/skills/ba-develop/cli/update-snapshot/__tests__/update-snapshot.test.ts

@@ -0,0 +1,73 @@
+/**
+ * update-snapshot — unit + writer/reader round-trip.
+ *
+ * The round-trip test is the important one: it proves the hashes WRITTEN by
+ * update-snapshot are byte-identical to the hashes compute-page-diff READS, so
+ * a snapshot taken right after a run reports every page as `unchanged`. Any
+ * drift between the two scanners would surface here as false `modified`.
+ */
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { execute } from '../execute.js'
+import { computeDiff } from '../../compute-page-diff/compute-diff.js'
+import { canonicalHash } from '../../../../lib/canonical-hash.js'
+import { SNAPSHOT_FILENAME } from '../../compute-page-diff/scan-pagespecs.js'
+
+const SPEC_A = { screenCode: 'SCR-A-001', entity: 'TypeAffaire', view: 'list', columns: [{ key: 'code' }] }
+const SPEC_B = { screenCode: 'SCR-B-001', entity: 'TypeAffaire', view: 'form', fields: ['code'] }
+
+describe('update-snapshot execute', () => {
+  let moduleRoot: string
+  beforeEach(() => {
+    moduleRoot = mkdtempSync(join(tmpdir(), 'update-snapshot-'))
+    mkdirSync(join(moduleRoot, 'pagespecs'), { recursive: true })
+  })
+  afterEach(() => rmSync(moduleRoot, { recursive: true, force: true }))
+
+  function writePagespec(name: string, spec: object): void {
+    writeFileSync(join(moduleRoot, 'pagespecs', name), '```json\n' + JSON.stringify(spec) + '\n```\n', 'utf8')
+  }
+
+  it('writes a snapshot with the canonical hash of every pagespec', () => {
+    writePagespec('TypeAffaire.list.md', SPEC_A)
+    writePagespec('TypeAffaire.form.md', SPEC_B)
+    const report = execute({ moduleRoot, timestamp: '2026-05-29T00:00:00Z' })
+
+    expect(report.pageCount).toBe(2)
+    expect(report.lastRun).toBe('2026-05-29T00:00:00Z')
+
+    const written = JSON.parse(readFileSync(join(moduleRoot, SNAPSHOT_FILENAME), 'utf8'))
+    expect(written.lastRun).toBe('2026-05-29T00:00:00Z')
+    expect(written.pages).toEqual({
+      'TypeAffaire.list': canonicalHash(SPEC_A),
+      'TypeAffaire.form': canonicalHash(SPEC_B),
+    })
+  })
+
+  it('round-trips: a diff taken right after update-snapshot is all-unchanged', () => {
+    writePagespec('TypeAffaire.list.md', SPEC_A)
+    writePagespec('TypeAffaire.form.md', SPEC_B)
+    execute({ moduleRoot, timestamp: '2026-05-29T00:00:00Z' })
+
+    const diff = computeDiff({ moduleRoot })
+    expect(diff.snapshotFound).toBe(true)
+    expect(diff.diff.unchanged).toEqual(['TypeAffaire.form', 'TypeAffaire.list'])
+    expect(diff.toRegenerate).toEqual([])
+  })
+
+  it('overwrites a stale snapshot so a later edit reads as modified', () => {
+    writePagespec('TypeAffaire.list.md', SPEC_A)
+    execute({ moduleRoot, timestamp: '2026-05-29T00:00:00Z' })
+
+    // Edit the pagespec, then diff WITHOUT re-snapshotting → modified.
+    writePagespec('TypeAffaire.list.md', { ...SPEC_A, columns: [{ key: 'code' }, { key: 'libelle' }] })
+    const diff = computeDiff({ moduleRoot })
+    expect(diff.diff.modified.map((m) => m.key)).toEqual(['TypeAffaire.list'])
+
+    // Re-snapshot → diff is clean again.
+    execute({ moduleRoot, timestamp: '2026-05-29T01:00:00Z' })
+    expect(computeDiff({ moduleRoot }).toRegenerate).toEqual([])
+  })
+})

package/templates/skills/ba-develop/cli/update-snapshot/execute.ts

@@ -0,0 +1,24 @@
+/**
+ * cli:update-snapshot — execute.ts
+ *
+ * Re-scans `<moduleRoot>/pagespecs/` and writes the flat `key → hash` baseline
+ * to `<moduleRoot>/.run-snapshot.json`. Reuses the SAME scanner as
+ * `compute-page-diff` so the hashes written here are byte-identical to the
+ * hashes that next run's diff compares against (no drift between writer/reader).
+ */
+import { writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { scanPagespecs, SNAPSHOT_FILENAME } from '../compute-page-diff/scan-pagespecs.js'
+import type { UpdateSnapshotInput, UpdateSnapshotReport } from './types.js'
+
+export function execute(input: UpdateSnapshotInput): UpdateSnapshotReport {
+  const scan = scanPagespecs(input.moduleRoot)
+  const pages: Record<string, string> = {}
+  for (const { key, hash } of scan.pages) pages[key] = hash
+
+  const lastRun = input.timestamp ?? new Date().toISOString()
+  const snapshotPath = join(input.moduleRoot, SNAPSHOT_FILENAME)
+  writeFileSync(snapshotPath, JSON.stringify({ lastRun, pages }, null, 2) + '\n', 'utf8')
+
+  return { snapshotPath, pageCount: scan.pages.length, lastRun, warnings: scan.warnings }
+}

package/templates/skills/ba-develop/cli/update-snapshot/index.ts

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * cli:update-snapshot — entry point.
+ *
+ * Writes `<moduleRoot>/.run-snapshot.json` from the current pagespecs. The
+ * orchestrator calls this ONLY after a successful Phase 3a regeneration so the
+ * baseline always reflects a known-good run.
+ *
+ * Invocation:
+ *   npx tsx skills/ba-develop/cli/update-snapshot/index.ts \
+ *     --spec '{"moduleRoot":".smartstack/ba/<APP>/<MODULE>"}'
+ */
+import { parseArgs } from 'node:util'
+import { validate } from './validate.js'
+import { execute } from './execute.js'
+import { generateEnvelope, failGenerate, printEnvelope } from '../../../lib/output.js'
+
+const COMMAND = 'update-snapshot'
+
+function main(): void {
+  const { values } = parseArgs({
+    options: { spec: { type: 'string' } },
+    strict: true,
+  })
+
+  if (!values.spec) {
+    printEnvelope(failGenerate(COMMAND, ['--spec is required']))
+    process.exit(1)
+  }
+
+  let raw: unknown
+  try {
+    raw = JSON.parse(values.spec)
+  } catch {
+    printEnvelope(failGenerate(COMMAND, ['Invalid JSON in --spec']))
+    process.exit(1)
+  }
+
+  const validation = validate(raw)
+  if (!validation.valid || !validation.spec) {
+    printEnvelope(failGenerate(COMMAND, validation.errors))
+    process.exit(1)
+  }
+
+  const report = execute(validation.spec)
+
+  printEnvelope(
+    generateEnvelope(COMMAND, {
+      data: { pageCount: report.pageCount, lastRun: report.lastRun },
+      filesModified: [report.snapshotPath],
+      warnings: report.warnings,
+      nextSteps: [
+        `Snapshot written with ${report.pageCount} page hash(es). Next \`compute-page-diff\` run will diff against this baseline.`,
+      ],
+    }),
+  )
+
+  process.exit(0)
+}
+
+main()

package/templates/skills/ba-develop/cli/update-snapshot/types.ts

@@ -0,0 +1,40 @@
+/**
+ * cli:update-snapshot — types.ts
+ *
+ * Writes `<moduleRoot>/.run-snapshot.json` from the current pagespecs, so the
+ * NEXT `compute-page-diff` run has a baseline to diff against. The orchestrator
+ * calls this ONLY after a successful Phase 3a regeneration — never before, so a
+ * failed run never poisons the baseline.
+ *
+ * Kept separate from `compute-page-diff` (which stays a pure read-only spec-diff,
+ * AC-F4.1-011): persistence is this CLI's single responsibility.
+ */
+import { z } from 'zod'
+
+export const UpdateSnapshotInputSchema = z
+  .object({
+    /** Module folder holding `pagespecs/` — e.g. `.smartstack/ba/<APP>/<MODULE>`. */
+    moduleRoot: z.string().min(1),
+    /**
+     * ISO timestamp recorded as `lastRun`. Injectable for deterministic tests;
+     * the CLI fills `new Date().toISOString()` when omitted.
+     */
+    timestamp: z.string().optional(),
+  })
+  .strict()
+
+export type UpdateSnapshotInput = z.infer<typeof UpdateSnapshotInputSchema>
+
+export interface UpdateSnapshotReport {
+  snapshotPath: string
+  pageCount: number
+  lastRun: string
+  warnings: string[]
+}
+
+export interface ValidationResult {
+  valid: boolean
+  errors: string[]
+  warnings: string[]
+  spec?: UpdateSnapshotInput
+}

package/templates/skills/ba-develop/cli/update-snapshot/validate.ts

@@ -0,0 +1,17 @@
+/**
+ * cli:update-snapshot — validate.ts  (pure, no I/O)
+ */
+import { UpdateSnapshotInputSchema } from './types.js'
+import type { ValidationResult } from './types.js'
+
+export function validate(raw: unknown): ValidationResult {
+  const parsed = UpdateSnapshotInputSchema.safeParse(raw)
+  if (!parsed.success) {
+    return {
+      valid: false,
+      errors: parsed.error.issues.map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`),
+      warnings: [],
+    }
+  }
+  return { valid: true, errors: [], warnings: [], spec: parsed.data }
+}

package/templates/skills/ba-develop/references/anti-patterns.md

@@ -0,0 +1,101 @@
+# `/ba-develop` — Anti-patterns
+
+> Loaded on demand when the orchestrator (or a reviewer) needs the full list
+> of failure modes the design forbids. Each entry is one incident that proved
+> the rule necessary.
+
+## Orchestrator-level anti-patterns
+
+- **Loading all slices at once** into your own context. Defeats the phased
+  approach — subagents must each see only their slice (Phase 1 sees entities
+  + data combined; Phases 2 + 3 see only their own).
+- **Skipping a gate because it's "obvious"**. Every gate exists because a
+  previous incident proved it necessary. Never skip.
+- **Hand-editing the Core providers in Phase 0**. They are deterministic and
+  overwritten on every re-run. If you need a different shape, fix the upstream
+  BA tables (menu / actors / permissions) and re-run `scaffold-core-seed`. The
+  Phase 0 agent NEVER writes `.cs` files itself.
+- **Generating per-module nav/roles/permissions in Phase 1**. That's Phase 0's
+  job. Phase 1's `scaffold-seed` is for module-scoped REFERENCE DATA only
+  (lookup tables, enum codes).
+- **Refusing to start on a weak PRD**. The pre-flight verdict is advisory, not
+  a gate: a PRD with score < 80 (or a missing `_audit/prd.md`) becomes a
+  `prd.not-dev-ready` blocker and the run proceeds. Running anyway may cost
+  rework — but stopping the user is the worse failure. The blocker makes the
+  risk loud in the final report.
+- **Editing PRD content during development**. If a phase discovers a real gap
+  in the PRD, do NOT patch it locally — **defer it** as a `prd.gap` blocker
+  (`userAction` names the slice to regenerate) and continue with what the PRD
+  does specify. Discovering a gap never halts the run.
+- **Parallelizing phases**. Phase 1 depends on Phase 0 nav (controllers
+  reference module codes); Phase 2 on Phase 1 entities; Phase 3 on Phase 2
+  controllers. Strictly sequential.
+- **Skipping Phases 0-2 on re-run without the pre-entry coverage check**.
+  A compile + test gate that passes proves EXISTING code is correct — it
+  says nothing about whether the PRD has NEW items not yet implemented.
+  The pre-entry coverage check (< 5 seconds per phase) is the only
+  mechanism that detects PRD additions. Without it, a UC added after the
+  first run is never generated.
+
+## Auto-healing anti-patterns
+
+- **Halting the run, or asking the user mid-flight.** There is no hard-halt
+  list any more (`references/auto-healing.md`): a fixable failure is healed, an
+  unhealable one is **deferred** (blocker + safe best-effort action), and the
+  run always reaches the end of the module. Never stop to ask the user to
+  regenerate the PRD, edit a BA file, pick a key, or review a migration — that
+  goes in `blockers[]` and surfaces only in the final report.
+- **Swallowing a deferred item silently.** A defer is not a success: it MUST
+  push a blocker. Best-effort (skip / keep / stub) ≠ done.
+- **Increasing the retry budget beyond 25** to "force it through". The
+  25-retry ceiling exists so a genuinely incorrigible item is deferred (not
+  spun on forever). Cranking it to 100 masks a real problem before deferring.
+- **Re-running all phases when only one failed**. After exhausting heal
+  retries on Phase 2, re-run only Phase 2 — the prior commits are intact.
+
+## Phase 3 anti-patterns
+
+- **Declaring Phase 3 "already done" on re-runs without running validate-page**.
+  Pages may exist but be hand-written (missing `@generated-by scaffold-component`
+  marker). They compile and even pass `npm run build` — but render raw i18n keys
+  at runtime. The orchestrator MUST run the Phase 3 pre-entry check
+  (`validate-page` on all existing pages) before declaring Phase 3 complete.
+  See `references/gates.md` § "Phase 3 pre-entry".
+- **Scaffolding routes or writing `componentRegistry.generated.ts` before the
+  page `.tsx` files exist**. Vite fails at launch because
+  `lazyWithRetry(() => import('@/missing'))` cannot be resolved (retry can't
+  rescue a true 404 — only transient flakes). Complete 3a (all pages) strictly
+  before 3b (module registries) and 3c (aggregator).
+- **Listing phantom entries in the aggregated registry**. Every `import('@/…')`
+  in `componentRegistry.generated.ts` must resolve to a real file. Deferred
+  pages → do NOT write the entry.
+- **Skipping the audit-apply pass on a no-op generate run**. Orchestrator MUST
+  always invoke `audit-dev-frontend --mode apply` + `ui-polish --mode apply`
+  after 3c, regardless of whether 3a-3c reported file changes. Catches drift
+  in files no generator touched this run.
+- **Failing the build gate without first running audit-apply**. `npm run build`
+  catches Vite-level errors only. Convention drift (missing PageTemplate,
+  unguarded actions, broken permission keys, ghost pages, missing i18n) is
+  invisible to Vite. Audit-apply's `0-err` exit status IS the gate.
+- **Hand-editing `src/index.css` or `PageTemplate.tsx`** without the
+  `/* @customised */` marker. Deterministic files; overwritten on every re-run.
+- **Writing page `.tsx` files by hand in Phase 3a**. Subagent's only allowed
+  Bash invocations are `scaffold-api-client`, `scaffold-component`,
+  `validate-page`. Any `Edit` or `Write` of a `.tsx` under `src/pages/**` or
+  `src/components/ui/**` is a contract violation.
+- **Parallelizing two features of the same module in Phase 3a**. They share
+  one `src/i18n/locales/{locale}/{module}.json`; deep-merge is safe only
+  serialized. Parallelize across DIFFERENT modules; serialize within a module.
+- **A feature-subagent writing outside its entity**. A Phase 3a feature
+  subagent owns only its `src/features/{module}/{entity}/` + its
+  `{Entity}*Page.tsx` + its keys in the module i18n catalogue. The
+  routes/registry (3b/3c), theme/layout (3.0), cross-feature aggregation
+  belong to the orchestrator.
+
+## Phase 2 anti-patterns
+
+- **Shipping a business-rule or use-case stub**. Letting a `// TODO[BR-…]`,
+  `// TODO[UC-…]` or `NotImplementedException` survive the Phase 2 gate. The
+  scaffolder emits these markers deliberately for the hard logic; the
+  business-logic pass MUST implement them. Never weaken a `Category=Business`
+  test to make a stub pass — auto-heal `business.todo-br` is the correct path.