@ultimat3/cli 1.2.0 → 2.0.0

package/src/templates/guard.ts

@@ -0,0 +1,143 @@
+// `x g guard <name>` — the app's own convention, scaffolded as a build error. Not a primitive and
+// not a check the framework owns: what the emitted file has to get right is the directory (it is
+// the registration), the exported `guard` the gate looks for, and a rule that fires on something
+// real, so an author replacing the example knows what a working one looks like.
+
+import type { GeneratedFile } from './naming';
+import { kebab } from './naming';
+
+/**
+ * The code the emitted guard raises, derived from its name — the same shape `x g action` derives
+ * `X_<FEATURE>_NOT_FOUND` in. Derived and never written as a literal here for the same reason: an
+ * `X_*` literal in framework source is a framework code, and it would have to be registered and
+ * documented in `wiki/Error-Codes.md`. The app owns the codes its own conventions raise.
+ */
+export const guardCode = (name: string): string =>
+  `X_${kebab(name).toUpperCase().split('-').join('_')}`;
+
+const guardSource = (
+  name: string,
+): string => `// ${name}: one convention this app enforces, as a build error. \`x verify\` discovers every file in
+// \`guards/\` and runs its \`guard\` inside the \`boundaries\` step — nothing registers this file, so
+// nothing can forget to. Replace the rule below with the one this app needs; the shape is the
+// contract, and the findings it returns are what \`--json\` and the exit code are made of.
+
+import type { Finding, Guard } from '@ultimat3/cli';
+
+/**
+ * The example rule, and the class of failure a guard exists for: a migration that adds a NOT NULL
+ * column with no DEFAULT applies cleanly to an empty local database and fails on the first
+ * production table that already holds rows. Nothing else in the gate can see it — \`x verify\`'s
+ * \`drift\` step reads these same files and asks a different question (is every destructive
+ * statement declared?), and a test suite runs against a database this statement has never met.
+ *
+ * The code is this guard's own name: the line an agent reads has to say WHICH convention broke, so
+ * a guard is named after its convention and the two are renamed together.
+ */
+const CODE = '${guardCode(name)}';
+
+/** A column definition begins at \`add column\` and ends at the comma or semicolon after it. */
+const ADD_COLUMN = /add\\s+column\\s+(?:if\\s+not\\s+exists\\s+)?"?([\\w]+)"?([^,;]*)/gi;
+
+export interface MigrationFile {
+  /** App-root-relative POSIX path, so the finding names the file an author opens. */
+  readonly path: string;
+  readonly sql: string;
+}
+
+/**
+ * Pure — the caller does the I/O — so the rule is testable without a filesystem, which is the same
+ * split the framework's own checks use. A guard returns findings and nothing else: it never
+ * prints, never throws for a normal result and never decides the exit code.
+ */
+export function unsafeAdditions(files: readonly MigrationFile[]): readonly Finding[] {
+  const findings: Finding[] = [];
+  for (const file of files) {
+    // Comments first, block before line: a statement inside \`/* … */\` is a note, and reading one
+    // as real is a finding an author cannot act on — it blocks \`x verify\` over nothing.
+    const sql = file.sql.replaceAll(/\\/\\*[\\s\\S]*?\\*\\//g, ' ').replaceAll(/--[^\\n]*/g, ' ');
+    for (const statement of sql.split(';')) {
+      if (!/\\balter\\s+table\\b/i.test(statement)) continue;
+      for (const match of statement.matchAll(ADD_COLUMN)) {
+        const definition = match[2] ?? '';
+        if (!/\\bnot\\s+null\\b/i.test(definition)) continue;
+        // \`DEFAULT NULL\` is a default in syntax and none in effect: every existing row still
+        // takes NULL and still violates NOT NULL, which is this rule's whole subject.
+        const nullDefault = /\\bdefault\\s+\\(?\\s*null\\b/i.test(definition);
+        if (/\\bdefault\\b/i.test(definition) && !nullDefault) continue;
+        const column = match[1] ?? 'the column';
+        findings.push({
+          code: CODE,
+          cause: \`\${file.path} adds \${column} NOT NULL with no usable DEFAULT — every row already in the table takes NULL and violates it the moment this runs against data\`,
+          fix: \`give \${column} a non-null DEFAULT in \${file.path}, then: x db migrate\`,
+          at: file.path,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+export const guard: Guard = {
+  summary: 'a migration never adds a NOT NULL column without a DEFAULT',
+  async check(root) {
+    const files: MigrationFile[] = [];
+    for await (const path of new Bun.Glob('packages/db/migrations/*.sql').scan({
+      cwd: root,
+      absolute: false,
+    })) {
+      files.push({ path, sql: await Bun.file(\`\${root}/\${path}\`).text() });
+    }
+    return unsafeAdditions(files);
+  },
+};
+`;
+
+const guardTest = (
+  name: string,
+): string => `// The rule, driven directly. Failure case first: a guard whose rule silently stopped matching is
+// a green gate over the convention it was written to enforce.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import { unsafeAdditions } from './${name}';
+
+const migration = (sql: string) => [{ path: 'packages/db/migrations/0002_probe.sql', sql }];
+
+unitTest('a NOT NULL column added with no DEFAULT is refused', () => {
+  const findings = unsafeAdditions(migration('ALTER TABLE posts ADD COLUMN slug text NOT NULL;'));
+  expect(findings).toHaveLength(1);
+  expect(findings[0]?.at).toBe('packages/db/migrations/0002_probe.sql');
+  expect(findings[0]?.cause).toContain('slug');
+});
+
+unitTest('a DEFAULT makes the same addition safe', () => {
+  const sql = "ALTER TABLE posts ADD COLUMN slug text NOT NULL DEFAULT '';";
+  expect(unsafeAdditions(migration(sql))).toHaveLength(0);
+});
+
+unitTest('DEFAULT NULL is a default in syntax and none in effect', () => {
+  const sql = 'ALTER TABLE posts ADD COLUMN slug text NOT NULL DEFAULT NULL;';
+  expect(unsafeAdditions(migration(sql))).toHaveLength(1);
+});
+
+unitTest('a nullable column was always safe, and a new table is not an addition', () => {
+  expect(unsafeAdditions(migration('ALTER TABLE posts ADD COLUMN slug text;'))).toHaveLength(0);
+  expect(unsafeAdditions(migration('CREATE TABLE posts (slug text NOT NULL);'))).toHaveLength(0);
+});
+
+unitTest('a commented-out statement is not a statement', () => {
+  const block = '/* ALTER TABLE posts ADD COLUMN slug text NOT NULL; */';
+  expect(unsafeAdditions(migration(block))).toHaveLength(0);
+  const line = '-- ALTER TABLE posts ADD COLUMN slug text NOT NULL;';
+  expect(unsafeAdditions(migration(line))).toHaveLength(0);
+});
+`;
+
+/** `guards/<name>.ts` and its test. No index, no registry, no manifest row — the directory is it. */
+export function guardFiles(rawName: string): readonly GeneratedFile[] {
+  const name = kebab(rawName);
+  return [
+    { path: `guards/${name}.ts`, contents: guardSource(name) },
+    { path: `guards/${name}.test.ts`, contents: guardTest(name) },
+  ];
+}

package/src/templates/index.ts

@@ -4,11 +4,17 @@
 export type { ActionOptions } from './action';
 export { actionFiles } from './action';
 export { adminFiles } from './admin';
+export type { AdminPageOptions } from './admin-page';
+export { adminPageFiles } from './admin-page';
+export { backfillFiles } from './backfill';
 export type { FeatureTarget } from './entity';
 export { entityFiles } from './entity';
+export { guardCode, guardFiles } from './guard';
+export type { IslandOptions } from './island';
+export { islandFiles } from './island';
 export { jobFiles, taskFiles } from './job';
 export { CATALOG_ROOT, catalogPath, DEFAULT_LOCALES, resolveLocales } from './locales';
-export type { GeneratedFile, NameSet } from './naming';
+export type { GeneratedFile, GeneratedFoundationFile, NameSet } from './naming';
 export { camel, kebab, names, pascal, plural, titleKey } from './naming';
 export { policyFiles } from './policy';
 export type { QueryOptions } from './query';
@@ -18,7 +24,12 @@ export { resourceFiles } from './resource';
 export type { RouteOptions, Surface } from './route';
 export { routeFiles } from './route';
 export { appFiles } from './scaffold-app';
+export { claudeFiles } from './scaffold-claude';
+export { claudeAgentFiles } from './scaffold-claude-agents';
+export { claudeCommandFiles } from './scaffold-claude-commands';
 export { containerFiles } from './scaffold-container';
 export { docsFiles, EXECUTABLE_FILES } from './scaffold-docs';
 export { i18nIndex } from './scaffold-i18n';
 export { repoFiles } from './scaffold-repo';
+export type { SliceModule } from './slice-foundation';
+export { sliceFoundation } from './slice-foundation';

package/src/templates/island.ts

@@ -0,0 +1,67 @@
+// `x g island <name>` — the one file on a route that ships JavaScript. Not a ninth primitive and
+// not a component generator: an island is a client ENTRY POINT, so what the scaffold has to get
+// right is the filename (the bundler discovers by it) and the `mount` export (the hydration
+// runtime calls it by name). Both are pinned by the emitted test.
+
+import type { GeneratedFile } from './naming';
+import { kebab, pascal } from './naming';
+
+export interface IslandOptions {
+  /** Directory the entry lands in, app-root-relative and POSIX — normally a route's own folder. */
+  readonly dir: string;
+}
+
+const islandSource = (name: string): string => {
+  const Name = pascal(name);
+  return `// ${Name}: the interactive half of an otherwise static page, and the only module on this
+// route the browser downloads.
+//
+// The page names this file by SPECIFIER, never by import:
+//   const ${Name} = island({ src: './${name}.island.tsx', props: ['label'] });
+// A string has no import edge, so nothing follows one into this file and the page's bundle graph
+// stays the page's (axiom 6). WHEN it wakes is the route's \`hydrate\`, never a declaration here.
+
+/** What the server sends. Declared here AND in the page's \`island({ props })\` — both, or neither. */
+export interface ${Name}Props {
+  /** Already translated: this runs in the browser, where \`t()\`'s catalog is not. */
+  readonly label: string;
+}
+
+/**
+ * The one export the hydration runtime calls — \`import(entry).then((m) => m.mount(el, props))\`.
+ * \`el\` is the wrapper the page rendered, with the server's own markup already inside it, so a
+ * mount that replaces the markup instead of taking it over is a visible flash on every load.
+ */
+export function mount(el: HTMLElement, props: ${Name}Props): void {
+  el.textContent = props.label;
+  el.addEventListener('click', () => {
+    // \`dataset.open\`, not \`dataset['open']\`: the bracket form is lint/complexity/useLiteralKeys,
+    // which the app's own \`biome check\` fails on — twice, in the one file every island copies.
+    el.dataset.open = el.dataset.open === 'true' ? 'false' : 'true';
+  });
+}
+`;
+};
+
+const islandTest = (
+  name: string,
+): string => `// The runtime boots an island by calling \`mount\` on whatever the module exports. A renamed or
+// deleted export is a page that renders, serves, passes every other gate and does nothing when
+// clicked — which is exactly the failure nothing else in the build can see.
+
+import { expect, unitTest } from '@ultimat3/testing';
+import * as entry from './${name}.island';
+
+unitTest('${name}.island exports the mount the hydration runtime calls', () => {
+  expect(typeof entry.mount).toBe('function');
+});
+`;
+
+export function islandFiles(rawName: string, options: IslandOptions): readonly GeneratedFile[] {
+  const name = kebab(rawName);
+  const dir = options.dir.replace(/\/+$/, '');
+  return [
+    { path: `${dir}/${name}.island.tsx`, contents: islandSource(name) },
+    { path: `${dir}/${name}.island.test.ts`, contents: islandTest(name) },
+  ];
+}

package/src/templates/job.ts

@@ -1,10 +1,12 @@
 // `x g job` / `x g task` — durable background work and the cron trigger that enqueues it. The
-// idempotency key is required by the type, so the generator always emits one; the generated test
-// pins it through a real driver, because a key that is not stable is a job that runs twice.
+// idempotency key and the tenant are both required by the type, so the generator always emits
+// both; the generated test pins them through a real driver, because a key that is not stable is a
+// job that runs twice and a tenant that is not declared is a job that reads the wrong org's rows.
 
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { sliceFoundation } from './slice-foundation';
 
 const jobSource = (
   name: NameSet,
@@ -16,7 +18,14 @@ import { job, t } from '@ultimat3/jobs';
 import * as repo from '../repo';
 
 export const ${name.camel} = job({
-  input: t.object({ id: t.uuid }),
+  input: t.object({ id: t.uuid, orgId: t.uuid }),
+  // The org this run's body acts as, derived from the job's OWN input — never from whoever
+  // enqueued it, who may have changed orgs by the time a retried job settles. \`orgId\` is in the
+  // input for this and no other reason: \`x g entity\` scaffolds \`tenant: 'orgId'\`, so every read
+  // below is tenant-scoped. \`tenant: 'none'\` is the other spelling and it STRIPS the org, which
+  // makes a tenant-scoped read fail closed with X_TENANCY_ACTOR_ORG_REQUIRED — use it only for a
+  // job that touches no tenanted table.
+  tenant: (input) => input.orgId,
   idempotencyKey: ({ id }) => \`${name.kebab}:\${id}\`,
   retry: { attempts: 5, backoff: 'exponential' },
   async run({ input, step }) {
@@ -42,17 +51,34 @@ import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
 export const ${name.camel} = task({
   cron: '0 3 * * *',
   tz: 'UTC',
-  enqueue: () => [[${jobName.camel}, { id: '00000000-0000-4000-8000-000000000001' }]],
+  // The org rides in the payload because the job DECLARES its tenant from its own input: a task
+  // has no request behind it, so there is no caller whose org could be read instead.
+  enqueue: () => [
+    [
+      ${jobName.camel},
+      {
+        id: '00000000-0000-4000-8000-000000000001',
+        orgId: '00000000-0000-4000-8000-000000000002',
+      },
+    ],
+  ],
 });
 `;
 
 const jobTest = (
   name: NameSet,
-): string => `import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+): string => `// ${name.camel} against a real driver: enqueue, drain, assert. Retries and the dead-letter path
+// are the framework's, so what this pins is that THIS job's steps run and are idempotent.
+import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
 
 const id = '00000000-0000-4000-8000-000000000001';
+const orgId = '00000000-0000-4000-8000-000000000002';
+const input = { id, orgId };
+// The key this job owes, spelled once. Named rather than inlined so the assertion below carries
+// the job's own name and still fits the formatter width the app's \`lint\` step enforces.
+const expectedKey = \`${name.kebab}:\${id}\`;
 
 // The driver is process-global, so it is installed and released around this file rather than
 // left behind for whichever test happens to run next.
@@ -61,14 +87,22 @@ beforeAll(() => {
 });
 afterAll(resetJobDriver);
 
-jobTest('${name.camel} declares an idempotency key and a retry policy', () => {
+jobTest('${name.camel} declares a key and a retry policy', () => {
   expect(${name.camel}.kind).toBe('job');
-  expect(${name.camel}.idempotencyKeyFor({ id })).toBe(\`${name.kebab}:\${id}\`);
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(expectedKey);
   expect(${name.camel}.retry.attempts).toBeGreaterThan(1);
 });
 
 jobTest('${name.camel} derives the same key for the same input', () => {
-  expect(${name.camel}.idempotencyKeyFor({ id })).toBe(${name.camel}.idempotencyKeyFor({ id }));
+  const key = ${name.camel}.idempotencyKeyFor(input);
+  expect(${name.camel}.idempotencyKeyFor(input)).toBe(key);
+});
+
+jobTest('${name.camel} runs as the org its own input names', () => {
+  // Not a formality: \`tenant: 'none'\` compiles just as well and strips the org, and every read in
+  // this job is tenant-scoped — so this declaration is the whole of what stands between the body
+  // and X_TENANCY_ACTOR_ORG_REQUIRED, or worse, another org's rows.
+  expect(${name.camel}.tenantFor(input)).toBe(orgId);
 });
 
 jobTest('${name.camel} projects itself into the manifest', () => {
@@ -80,9 +114,9 @@ jobTest('${name.camel} projects itself into the manifest', () => {
 jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
   // The whole point of the key: an at-least-once caller may enqueue twice and the work still
   // happens once. \`.enqueue()\` is the one queue path — a job is never run inline.
-  const first = await ${name.camel}.enqueue({ id });
+  const first = await ${name.camel}.enqueue(input);
   expect(first.deduped).toBe(false);
-  const again = await ${name.camel}.enqueue({ id });
+  const again = await ${name.camel}.enqueue(input);
   expect(again.deduped).toBe(true);
 });
 `;
@@ -90,7 +124,9 @@ jobTest('${name.camel} enqueues once, and dedupes the retry', async () => {
 const taskTest = (
   name: NameSet,
   jobName: NameSet,
-): string => `import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
+): string => `// ${name.camel}: the schedule it declares, the timezone it declares it in, and the job it
+// enqueues. A cron with no explicit IANA zone fires at a different hour twice a year.
+import { createMemoryDriver, resetJobDriver, setJobDriver } from '@ultimat3/jobs';
 import { afterAll, beforeAll, expect, jobTest } from '@ultimat3/testing';
 import { ${jobName.camel} } from '../jobs/${jobName.kebab}';
 import { ${name.camel} } from './${name.kebab}';
@@ -106,7 +142,7 @@ jobTest('${name.camel} declares a cron with an explicit time zone', () => {
   expect(${name.camel}.tz).toBe('UTC');
 });
 
-jobTest('${name.camel} enqueues ${jobName.camel} and nothing else', () => {
+jobTest('${name.camel} enqueues exactly one job', () => {
   const pairs = ${name.camel}.entries();
   expect(pairs).toHaveLength(1);
   expect(pairs[0]?.[0]).toBe(${jobName.camel});
@@ -118,7 +154,7 @@ jobTest('${name.camel} describes its schedule and its jobs', () => {
   expect(described.jobs).toHaveLength(1);
 });
 
-jobTest('${name.camel} fires its entries onto the same queue the scheduler would', async () => {
+jobTest('${name.camel} fires its declared entries', async () => {
   // \`.enqueue()\` is the backfill path: the declared entries, through the facade a job handle
   // uses, with no scheduler and no leader involved.
   const results = await ${name.camel}.enqueue();
@@ -131,6 +167,10 @@ export function jobFiles(rawName: string, target: FeatureTarget): readonly Gener
   const name = names(rawName);
   const dir = `${target.surfaceDir}/${target.feature}/jobs`;
   return [
+    // The job's steps read through `../repo`, which carries `../entity` for its row type. No
+    // policy: a job has no request behind it and evaluates none, so a generated one would be a
+    // file nobody asked for. `x g task` inherits this by composing `jobFiles` below.
+    ...sliceFoundation(target, ['entity']),
     { path: `${dir}/${name.kebab}.ts`, contents: jobSource(name) },
     { path: `${dir}/${name.kebab}.test.ts`, contents: jobTest(name) },
   ];

package/src/templates/naming.ts

@@ -27,13 +27,29 @@ export interface GeneratedSourceFile {
   readonly merge?: undefined;
 }
 
+/**
+ * A module the feature slice owns and no single generator does — `entity.ts`, `repo.ts`,
+ * `policy.ts`, `errors.ts`. Several generators import one and none of them wrote it, so `x g job`
+ * into a slice that has no `repo.ts` emitted an import against nothing. Emitting it as an ordinary
+ * file is the opposite failure: the copy on disk is the author's, and rewriting it (or reporting
+ * `X_GENERATE_CONFLICT` and abandoning the whole set) is how `x g action` into an existing slice
+ * stops working. `'if-absent'` is the third answer — written when the slice lacks it, left exactly
+ * as it is when the slice has it, `--force` included, and never a conflict either way.
+ */
+export interface GeneratedFoundationFile {
+  /** POSIX path relative to the app root. */
+  readonly path: string;
+  readonly contents: string;
+  readonly merge: 'if-absent';
+}
+
 /**
  * Split on `merge` rather than widening one shape's `contents` in place, so the split is
  * load-bearing, not cosmetic: a `merge: 'json'` file's `contents` stays a plain `string` at the
  * type level, which is what stops a byte-carrying file from ever reaching
  * `cmd-generate.ts`'s JSON parser — the compiler refuses the call before the code can run.
  */
-export type GeneratedFile = GeneratedJsonFile | GeneratedSourceFile;
+export type GeneratedFile = GeneratedJsonFile | GeneratedSourceFile | GeneratedFoundationFile;
 
 const words = (input: string): readonly string[] =>
   input

package/src/templates/policy.ts

@@ -4,16 +4,16 @@
 
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { wrapList } from './wrap';
 
 /** Biome would rewrap this itself, so the generator emits the already-formatted form. */
-const permissionSet = (feature: NameSet): string => {
-  const read = `'${feature.kebab}:read'`;
-  const write = `'${feature.kebab}:write'`;
-  const line = `export const ${feature.camel}Permissions = definePermissions([${read}, ${write}]);`;
-  return line.length <= 100
-    ? line
-    : `export const ${feature.camel}Permissions = definePermissions([\n  ${read},\n  ${write},\n]);`;
-};
+const permissionSet = (feature: NameSet): string =>
+  wrapList(
+    '',
+    `export const ${feature.camel}Permissions = definePermissions([`,
+    [`'${feature.kebab}:read'`, `'${feature.kebab}:write'`],
+    ']);',
+  );
 
 const policySource = (
   feature: NameSet,
@@ -67,38 +67,45 @@ export const can${feature.pascal}Write = can<${feature.pascal}Scope>(
 );
 `;
 
-const policyTest = (feature: NameSet): string => `import { testActor } from '@ultimat3/policy';
+const policyTest = (
+  feature: NameSet,
+): string => `// The ${feature.kebab} rules, from the DENIAL side: anonymous, cross-org, and the actor holding
+// only read. A policy whose tests all pass is a policy nobody has tried to get past.
+import { testActor } from '@ultimat3/policy';
 import { expect, unitTest } from '@ultimat3/testing';
 import { can${feature.pascal}Read, can${feature.pascal}Write } from './policy';
 
 const org = '00000000-0000-4000-8000-000000000002';
 const otherOrg = '00000000-0000-4000-8000-000000000009';
 
-// Direct grants rather than roles: the role map is app-global and defineRoles() replaces it
-// wholesale, so a generated test that installed one would decide authz for every other test in
-// the process. \`permissions\` is the same check one layer down.
-const reader = testActor('reader', { orgId: org, permissions: ['${feature.kebab}:read'] }).actor;
-const writer = testActor('writer', {
-  orgId: org,
-  permissions: ['${feature.kebab}:read', '${feature.kebab}:write'],
-}).actor;
-const outsider = testActor('outsider', {
-  orgId: otherOrg,
-  permissions: ['${feature.kebab}:read', '${feature.kebab}:write'],
-}).actor;
+// Direct grants rather than roles: defineRoles() MERGES into one app-global map that outlives this
+// file, so a role installed here would still be granting permissions to every later test in the
+// process — and a second test declaring the same name differently is X_ROLE_REDEFINED rather than
+// an override. The app's roles live in apps/web/shared/roles.ts, once. \`permissions\` is the same
+// check one layer down.
+// The two grants and the org, each named once. Not decoration: every assertion below then carries
+// the feature's own name and still fits the formatter's width, whatever that name is — a generated
+// file the app's \`lint\` step rewrites is a red gate over code nobody typed.
+const read = '${feature.kebab}:read';
+const write = '${feature.kebab}:write';
+const input = { orgId: org };
+
+const reader = testActor('reader', { orgId: org, permissions: [read] }).actor;
+const writer = testActor('writer', { orgId: org, permissions: [read, write] }).actor;
+const outsider = testActor('outsider', { orgId: otherOrg, permissions: [read, write] }).actor;
 
 unitTest('${feature.camel} read denies anonymous and cross-org actors', async () => {
-  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: null, input: { orgId: org } });
-  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: outsider, input: { orgId: org } });
-  await expect(can${feature.pascal}Read).not.toDenyPolicy({ actor: reader, input: { orgId: org } });
+  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: null, input });
+  await expect(can${feature.pascal}Read).toDenyPolicy({ actor: outsider, input });
+  await expect(can${feature.pascal}Read).not.toDenyPolicy({ actor: reader, input });
 });
 
-unitTest('${feature.camel} write denies an actor holding only the read grant', async () => {
+unitTest('${feature.camel} write denies the read-only actor', async () => {
   // The outsider holds the grant and is still denied: the predicate is a second, independent
   // gate, and this is the assertion that fails if someone deletes it.
-  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: reader, input: { orgId: org } });
-  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: outsider, input: { orgId: org } });
-  await expect(can${feature.pascal}Write).not.toDenyPolicy({ actor: writer, input: { orgId: org } });
+  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: reader, input });
+  await expect(can${feature.pascal}Write).toDenyPolicy({ actor: outsider, input });
+  await expect(can${feature.pascal}Write).not.toDenyPolicy({ actor: writer, input });
 });
 
 unitTest('${feature.camel} rules name the permission they require', () => {

package/src/templates/query.ts

@@ -5,6 +5,8 @@
 import type { FeatureTarget } from './entity';
 import type { GeneratedFile, NameSet } from './naming';
 import { names } from './naming';
+import { sliceFoundation } from './slice-foundation';
+import { wrapImport } from './wrap';
 
 /** A live read always fans out fresh, so a TTL on it would only ever be dead configuration. */
 const cacheLine = (feature: NameSet, live: boolean): string =>
@@ -20,7 +22,10 @@ const querySource = (
 
 import { from, query, t } from '@ultimat3/query';
 import type { ${feature.pascal} } from '../entity';
-import { can${feature.pascal}Read${live ? '' : `, ${feature.camel}Tag`} } from '../policy';
+${wrapImport(
+  live ? [`can${feature.pascal}Read`] : [`can${feature.pascal}Read`, `${feature.camel}Tag`],
+  '../policy',
+)}
 import * as repo from '../repo';
 
 export const ${name.camel} = query({
@@ -28,7 +33,7 @@ export const ${name.camel} = query({
   policy: can${feature.pascal}Read,
   live: ${String(live)},${cacheLine(feature, live)}
   // Opt-in, unlike an action's tool: a read hands rows to an agent, so silence exposes nothing.
-  mcp: { expose: true, description: '${name.raw} — generated, edit the description' },
+  mcp: { expose: true, description: '${name.raw} — edit this description' },
   sql: ({ orgId, limit }) =>
     // \`feature.table\`, not the kebab plural: \`from()\` quotes the identifier into the SQL text,
     // and the entity created the table as snake_case.
@@ -45,7 +50,9 @@ export const ${name.camel} = query({
 
 const queryTest = (name: NameSet, feature: NameSet, live: boolean): string => {
   const wrapper = live ? 'liveTest' : 'unitTest';
-  return `import { testActor } from '@ultimat3/policy';
+  return `// ${name.camel}: the shape it reads, the policy it asserts, and the actor it refuses. The read is
+// declarative, so what a test can get wrong is the authz, and that is what this pins.
+import { testActor } from '@ultimat3/policy';
 import { sourceFor } from '@ultimat3/query';
 import { expect, ${wrapper} } from '@ultimat3/testing';
 import { ${name.camel} } from './${name.kebab}';
@@ -74,8 +81,16 @@ ${wrapper}('${name.camel} is bounded and TOTALLY ordered', async () => {
   // The SQL text is the contract an agent reads to self-correct, so assert on it, not on a
   // shape. \`sourceFor\` is the one read path — it parses the input and builds the source exactly
   // as a request does. \`actor: null\` gives the call a context of its own rather than borrowing
-  // an ambient one, and \`enforce: false\` leaves the policy to the test below.
-  const source = await sourceFor(target, { orgId, limit: 50 }, { actor: null, enforce: false });
+  // an ambient one, and \`unenforced\` states WHY the policy is skipped: the escape hatch takes a
+  // written reason, never a boolean, because a boolean reads exactly like forgetting the policy.
+  const source = await sourceFor(
+    target,
+    { orgId, limit: 50 },
+    {
+      actor: null,
+      unenforced: 'a scaffolded test asserts the SQL text; the policy is asserted separately',
+    },
+  );
   const { sql } = source.toSQL();
   const text = sql.toLowerCase();
   expect(text).toContain('order by');
@@ -110,6 +125,10 @@ export function queryFiles(rawName: string, target: QueryOptions): readonly Gene
   const live = target.live === true;
   const dir = `${target.surfaceDir}/${target.feature}/${live ? 'live' : 'queries'}`;
   return [
+    // A read declares the row type it returns (`../entity`), the rule that admits it (`../policy`)
+    // and the one module allowed to query the table (`../repo`) — all three are the slice's, and
+    // `--live` changes only which directory this file lands in.
+    ...sliceFoundation(target, ['entity', 'policy']),
     { path: `${dir}/${name.kebab}.ts`, contents: querySource(name, feature, live) },
     { path: `${dir}/${name.kebab}.test.ts`, contents: queryTest(name, feature, live) },
   ];

package/src/templates/resource.ts

@@ -27,11 +27,16 @@ import * as repo from './repo';
 /** Derived from the row, never restated: a new column reaches this input without an edit here. */
 export type Create${feature.pascal}Input = Omit<${feature.pascal}, 'id' | 'createdAt'>;
 
-export async function create(input: Create${feature.pascal}Input): Promise<${feature.pascal}> {
+/** The row, aliased once, so every signature below reads at one width whatever the feature is
+ * called — a generated file the app's own formatter rewrites is a red \`lint\` over code nobody
+ * typed. */
+type Row = ${feature.pascal};
+
+export async function create(input: Create${feature.pascal}Input): Promise<Row> {
   return repo.insert(input);
 }
 
-export async function require${feature.pascal}(id: string): Promise<${feature.pascal}> {
+export async function require${feature.pascal}(id: string): Promise<Row> {
   const row = await repo.byId(id);
   if (row === undefined) throw new ${feature.pascal}NotFoundError({ id });
   return row;
@@ -40,7 +45,9 @@ export async function require${feature.pascal}(id: string): Promise<${feature.pa
 
 const serviceTest = (
   feature: NameSet,
-): string => `import { expect, unitTest } from '@ultimat3/testing';
+): string => `// The ${feature.kebab} feature's failure, pinned: a code an agent can match on, a cause naming
+// the row, and a fix that is an instruction. A bare Error would satisfy none of the three.
+import { expect, unitTest } from '@ultimat3/testing';
 import { ${feature.pascal}NotFoundError } from './errors';
 
 unitTest('${feature.pascal}NotFoundError carries a code, a cause and a fix', () => {
@@ -69,9 +76,10 @@ export function ${feature.pascal}List(props: ${feature.pascal}ListProps) {
   return (
     <ul class={styles.list}>
       <For each={props.rows} fallback={<li>{t('app.${feature.kebab}.empty')}</li>}>
-        {/* The item arrives as an accessor: reading it inside the row is what keeps the update
-            surgical instead of re-rendering the list. */}
-        {(row) => <li class={styles.item}>{row().title}</li>}
+        {/* <For> is keyed by value identity, so the item arrives directly and a row is only
+            re-created when its value changes. <Index> is the accessor-shaped one — reach for it
+            when the list is a fixed set of slots whose contents mutate. */}
+        {(row) => <li class={styles.item}>{row.title}</li>}
       </For>
     </ul>
   );
@@ -82,14 +90,14 @@ const uiStyle = (): string => `@use '@ultimat3/ui/tokens' as tokens;
 
 .list {
   display: grid;
-  gap: tokens.$space-2;
+  gap: tokens.space(2);
 }
 
 .item {
-  padding: tokens.$space-2;
-  border-radius: tokens.$radius-sm;
-  background: tokens.$surface-raised;
-  color: tokens.$text-primary;
+  padding: tokens.space(2);
+  border-radius: tokens.radius('sm');
+  background: tokens.role('surface-raised');
+  color: tokens.role('fg');
 }
 `;