@openora/create 0.4.1-canary.34 → 0.4.1-canary.340

package/template/__dot__rulesync/hooks/guard-core.mjs.tpl

@@ -1,44 +1,92 @@
 #!/usr/bin/env node
-// PreToolUse guard (Claude / Copilot CLI / Codex CLI / Gemini CLI).
-// Enforces the HARD RULE: never modify OSS core. Blocks shell write-primitives
-// and direct file edits that target the linked OSS checkout or node_modules.
-// Reads/blocks are allowed; only writes into protected paths are denied.
+// PreToolUse guard (Claude / Copilot CLI / Codex CLI / Gemini CLI - rulesync renders the same
+// script for every hook target, so the rule below holds identically in each tool).
+// Enforces the HARD RULE: the linked OSS checkout and node_modules are read-only. The one
+// exception is a git worktree under <oss>/.worktrees/ - the sanctioned place to change OSS
+// code from this repo (oss-boundaries rule, `pnpm oss:worktree`). Reads are always allowed.
 
-import { extractCommand, extractFilePath, readPayload, deny } from './_shared.mjs';
+import { readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve, sep } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { extractCommand, extractFilePaths, readPayload, deny } from './_shared.mjs';
 
 const payload = readPayload();
 
-// The linked OSS core checkout (baked in at generation time) plus any node_modules.
-const ossPath = String.raw`{{ossFromRoot}}`;
-const escapedOss = ossPath.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-const PROTECTED = `(?:${escapedOss}|node_modules\\b)`;
+// Paths resolve from the repo root (this file lives in <root>/.rulesync/hooks/), so an
+// absolute path - what most tools send - is caught as well as the relative form.
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const OSS_RELATIVE = String.raw`{{ossFromRoot}}`;
+// This repo is often checked out as a git worktree, whose `.git` is a file pointing at
+// <main>/.git/worktrees/<name>. The OSS checkout is a sibling of the MAIN checkout, so without
+// this the guard would resolve it inside the worktree, match nothing, and let core writes pass.
+const mainCheckoutOf = (dir) => {
+  try {
+    const pointer = readFileSync(join(dir, '.git'), 'utf8');
+    const gitdir = pointer.match(/^gitdir:\s*(.*[/\\]worktrees[/\\][^/\\]+?)\s*$/m)?.[1];
+    return gitdir ? resolve(dir, gitdir, '..', '..', '..') : dir;
+  } catch {
+    return dir; // `.git` is a directory (the main checkout) or missing
+  }
+};
+const OSS = resolve(mainCheckoutOf(ROOT), OSS_RELATIVE);
+
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+const OSS_PATH = `(?:${escape(OSS)}|${escape(OSS_RELATIVE)})`;
+const PROTECTED = `(?:${OSS_PATH}|node_modules\\b)`;
+// A path into a worktree with no `..` hop and no node_modules segment is sanctioned; it is
+// masked out before the write checks run, so the rest of the command is still judged.
+const WORKTREE_TOKEN = new RegExp(
+  String.raw`${OSS_PATH}/\.worktrees/(?![^\s'"|;&]*(?:\.\.|node_modules))[^\s'"|;&]*`,
+  'g',
+);
+// cp, install, and rsync write only to their last argument, so copying out of core stays a read.
+const LAST_ARG = String.raw`\s['"]?[^'"\s|;&]*${PROTECTED}[^'"\s|;&]*['"]?(?:\s+\d?>\S*)*\s*(?:[|;&]|$)`;
+const GIT_WRITES = 'apply|am|checkout|restore|reset|clean|stash|merge|rebase|pull|switch|cherry-pick|revert|rm|mv';
+
+const HOW_TO_CHANGE_OSS =
+  'To change OSS code, run `pnpm oss:worktree <branch>` and edit inside ' +
+  `${OSS_RELATIVE}/.worktrees/ (rule: oss-boundaries). Otherwise extend from the OUTSIDE ` +
+  '(overlay plugin, adapter rebinding, UI plugin, config).';
 
-// 1) Shell command writing into a protected path (sed -i, redirect, tee, rm, ...).
-const command = extractCommand(payload);
+// 1) Shell command writing into a protected path (sed -i, redirect, tee, cp, rm, git, ...).
+const command = extractCommand(payload).replace(WORKTREE_TOKEN, '<oss-worktree>');
 if (command) {
   const writeToCore = [
-    [new RegExp(String.raw`\b(?:sed|perl)\b[^|;&]*\s-\w*i\w*\b[^|;&]*(?:${PROTECTED})`), 'in-place edit (sed/perl -i)'],
-    [new RegExp(String.raw`(?:>>?|>\|)\s*['"]?[^'"\s|;&]*(?:${PROTECTED})`), 'shell redirection'],
-    [new RegExp(String.raw`\btee\b\s+(?:-a\s+)?['"]?[^'"\s|;&]*(?:${PROTECTED})`), 'tee'],
-    [new RegExp(String.raw`\b(?:rm|truncate|dd|chmod|chown|unlink|shred|mv)\b[^|;&]*(?:${PROTECTED})`), 'destructive file op'],
+    [new RegExp(String.raw`\b(?:sed|perl)\b[^|;&]*\s-\w*i\w*\b[^|;&]*${PROTECTED}`), 'in-place edit (sed/perl -i)'],
+    [new RegExp(String.raw`(?:>>?|>\|)\s*['"]?[^'"\s|;&]*${PROTECTED}`), 'shell redirection'],
+    [new RegExp(String.raw`\btee\b\s+(?:-a\s+)?['"]?[^'"\s|;&]*${PROTECTED}`), 'tee'],
+    [new RegExp(String.raw`(?<![\w-])(?:cp|install|rsync)\b[^|;&]*${LAST_ARG}`), 'copy'],
+    [new RegExp(String.raw`(?<![\w-])(?:rm|truncate|dd|chmod|chown|unlink|shred|mv|ln|patch)\b[^|;&]*${PROTECTED}`), 'destructive file op'],
+    [new RegExp(String.raw`\bgit\b[^|;&]*${PROTECTED}[^|;&]*\s(?:${GIT_WRITES})\b`), 'git command'],
   ];
-  const hit = writeToCore.find(([re]) => re.test(command));
+  const hit = writeToCore.find(([pattern]) => pattern.test(command));
   if (hit) {
-    deny(
-      `Blocked: this ${hit[1]} writes into OSS core / node_modules, which is read-only here. ` +
-        'Extend the platform from the OUTSIDE (overlay plugin, adapter rebinding, UI plugin, config). ' +
-        'If it can only be fixed in core, STOP and report it as an upstream OSS issue.',
-    );
+    deny(`Blocked: this ${hit[1]} writes into the OSS checkout or node_modules, which are read-only here. ${HOW_TO_CHANGE_OSS}`);
   }
 }
 
-// 2) Direct file edit/write whose target is inside a protected path.
-const filePath = extractFilePath(payload);
-if (filePath && new RegExp(PROTECTED).test(filePath)) {
-  deny(
-    `Blocked: ${filePath} is inside OSS core / node_modules, which is read-only here. ` +
-      'Extend from the OUTSIDE (overlay, adapter, UI plugin, config), or report an upstream OSS issue.',
-  );
+// The path on disk, symlinks followed, so a link in this repo that points into the checkout
+// does not pass as a local path. A file not yet created resolves through its nearest existing
+// ancestor.
+const physical = (path) => {
+  try {
+    return realpathSync(path);
+  } catch {
+    const parent = dirname(path);
+    return parent === path ? path : join(physical(parent), basename(path));
+  }
+};
+
+// 2) Direct file edit/write whose target resolves inside a protected path.
+const oss = physical(OSS);
+for (const filePath of extractFilePaths(payload)) {
+  const written = resolve(payload.cwd ?? process.cwd(), filePath);
+  const target = physical(written);
+  const isInside = (dir) => target.startsWith(dir + sep);
+  const inNodeModules = [written, target].some((path) => /(?:^|[\\/])node_modules(?:[\\/]|$)/.test(path));
+  if (inNodeModules || (isInside(oss) && !isInside(join(oss, '.worktrees')))) {
+    deny(`Blocked: ${filePath} is inside the OSS checkout or node_modules, which are read-only here. ${HOW_TO_CHANGE_OSS}`);
+  }
 }
 
 process.exit(0);

package/template/__dot__rulesync/hooks/guard-generated.mjs

@@ -1,34 +1,36 @@
 #!/usr/bin/env node
-// PreToolUse guard (Claude / Copilot CLI / Codex CLI).
-// Blocks edits to files generated by rulesync (`pnpm sync:agents`). The single
+// PreToolUse guard (Claude / Copilot CLI / Codex CLI / Gemini CLI).
+// Blocks edits to files generated by rulesync (`pnpm gen:agents`). The single
 // source of truth is .rulesync/; editing a generated mirror is lost on the next
 // sync. Fail-open: only a positive match denies.
 
-import { extractFilePath, readPayload, deny } from './_shared.mjs';
+import { extractFilePaths, readPayload, deny } from './_shared.mjs';
 import { relative, isAbsolute } from 'node:path';
 
-const payload = readPayload();
-const filePath = extractFilePath(payload);
-if (!filePath) process.exit(0);
-
-const rel = isAbsolute(filePath) ? relative(process.cwd(), filePath) : filePath;
-
+// Everything rulesync generates from .rulesync/.
 const generated = [
   /^AGENTS\.md$/,
   /^CLAUDE\.md$/,
+  /^GEMINI\.md$/,
   /^\.github\/copilot-instructions\.md$/,
   /^\.mcp\.json$/,
   /^\.vscode\/mcp\.json$/,
   /^\.codex\/config\.toml$/,
+  /^\.gemini\/settings\.json$/,
   /^\.claude\/(agents|commands)\//,
   /^\.github\/(agents|prompts)\//,
+  /^\.gemini\/(agents|commands)\//,
 ];
 
-if (generated.some((re) => re.test(rel))) {
-  deny(
-    `Blocked: ${rel} is generated by rulesync (\`pnpm sync:agents\`). ` +
-      'Edit the source under .rulesync/ instead (rules/, subagents/, commands/, mcp.json), then run `pnpm sync:agents`.',
-  );
+for (const filePath of extractFilePaths(readPayload())) {
+  // Repo-relative (hooks run with cwd = repo root) - name-agnostic.
+  const rel = isAbsolute(filePath) ? relative(process.cwd(), filePath) : filePath;
+  if (generated.some((re) => re.test(rel))) {
+    deny(
+      `Blocked: ${rel} is generated by rulesync (\`pnpm gen:agents\`). ` +
+        'Edit the source under .rulesync/ instead (rules/, subagents/, commands/, mcp.json), then run `pnpm gen:agents`.',
+    );
+  }
 }
 
 process.exit(0);

package/template/__dot__rulesync/hooks/guard-mr.mjs

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+// PreToolUse guard: no merge/pull request until `pnpm verify` passed on the commit being sent.
+// `pnpm verify` ends with `node .rulesync/hooks/guard-mr.mjs --stamp`, which records HEAD in
+// node_modules/.cache/verify-head when the tree is clean; a `--stamp` outside the verify script is
+// refused. Opening an MR/PR (CLI, push option, REST or GraphQL) is denied unless that record matches
+// the current HEAD of a clean tree. Git errors fail open, like every other guard.
+
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { deny, extractCommand, readPayload } from './_shared.mjs';
+
+const OPENS_REVIEW =
+  /\b(?:glab\s+mr\s+create|gh\s+pr\s+create|createPullRequest|mergeRequestCreate)\b|merge_request\.create/;
+const API_CALL = /\b(?:gh|glab)\s+api\b/;
+const REVIEW_COLLECTION = /\/(?:pulls|merge_requests)(?=["'\s?]|$)/;
+// `gh api` and `glab api` default to POST once a field or body is passed.
+const WRITES = /\s(?:(?:-X\s*|--method[=\s]+)POST\b|(?:-f|-F|--field|--raw-field|--input)\b)/i;
+const READS = /\s(?:-X\s*|--method[=\s]+)GET\b/i;
+
+const opensReview = (command) =>
+  OPENS_REVIEW.test(command) ||
+  (API_CALL.test(command) &&
+    REVIEW_COLLECTION.test(command) &&
+    WRITES.test(command) &&
+    !READS.test(command));
+
+const git = (cwd, ...args) => execFileSync('git', args, { cwd, encoding: 'utf8' }).trim();
+const stampFile = (root) => join(root, 'node_modules', '.cache', 'verify-head');
+
+const checkout = (cwd) => {
+  try {
+    const root = git(cwd, 'rev-parse', '--show-toplevel');
+    return {
+      root,
+      head: git(root, 'rev-parse', 'HEAD'),
+      isClean: git(root, 'status', '--porcelain') === '',
+    };
+  } catch {
+    return undefined;
+  }
+};
+
+if (process.argv.includes('--stamp')) {
+  if (process.env.npm_lifecycle_event !== 'verify') {
+    process.stderr.write('--stamp is recorded by `pnpm verify` only: run `pnpm verify`.\n');
+    process.exit(1);
+  }
+  const state = checkout(process.cwd());
+  if (state?.isClean) {
+    mkdirSync(dirname(stampFile(state.root)), { recursive: true });
+    writeFileSync(stampFile(state.root), state.head);
+  } else {
+    process.stderr.write(
+      'verify passed on uncommitted changes: commit, then rerun `pnpm verify` before opening an MR/PR.\n',
+    );
+  }
+  process.exit(0);
+}
+
+const payload = readPayload();
+if (!opensReview(extractCommand(payload))) {
+  process.exit(0);
+}
+const state = checkout(payload.cwd ?? process.cwd());
+if (!state) {
+  process.exit(0);
+}
+const readStamp = () => {
+  try {
+    return readFileSync(stampFile(state.root), 'utf8').trim();
+  } catch {
+    return '';
+  }
+};
+if (!state.isClean || readStamp() !== state.head) {
+  deny(
+    'Blocked: run `pnpm verify` on a clean, committed HEAD before opening a merge/pull request. It records the verified commit; this check compares it with HEAD.',
+  );
+}
+process.exit(0);

package/template/__dot__rulesync/hooks/guard-subagent.mjs

@@ -1,8 +1,8 @@
 #!/usr/bin/env node
 // PreToolUse(Task) guard: keep the orchestrator from spawning a GENERIC subagent
 // (general-purpose / claude) for work a roster agent is purpose-built for. The
-// Agent roster in AGENTS.md is prose the model sometimes skips out of habit; this
-// is the deterministic backstop.
+// Agent roster in the workflow rule is prose the model sometimes skips out of
+// habit; this is the deterministic backstop.
 //
 // Conservative by design: it acts ONLY when (a) the chosen subagent is generic AND
 // (b) the task text contains a HIGH-SIGNAL phrase that maps unambiguously to one
@@ -16,14 +16,16 @@ const ti = payload.tool_input ?? {};
 const sub = String(ti.subagent_type ?? '').toLowerCase();
 
 const GENERIC = new Set(['general-purpose', 'claude', '']);
-if (!GENERIC.has(sub)) process.exit(0);
+if (!GENERIC.has(sub)) {
+  process.exit(0);
+}
 
 const text = `${ti.description ?? ''}\n${ti.prompt ?? ''}`.toLowerCase();
 
 // High-signal phrase -> the roster agent that owns it. Keep each pattern SPECIFIC;
 // err toward missing a case over false-blocking a generic task.
 const ROUTES = [
-  { agent: 'qa', re: /\b(playwright|e2e test|end-to-end test|e2e coverage)\b/ },
+  { agent: 'tester', re: /\b(playwright|e2e test|end-to-end test|e2e coverage)\b/ },
   {
     agent: 'debugger',
     re: /\b(build (failure|error)|turbopack|tsc error|module resolution|runtime error|stack trace)\b/,
@@ -40,14 +42,28 @@ const ROUTES = [
     agent: 'deployer',
     re: /\b(dockerfile|containerize|deploy pipeline|deploy to (ecs|kubernetes|fly|railway|render)|ci\/cd deploy|helm chart)\b/,
   },
+  {
+    agent: 'compliance-reviewer',
+    re: /\b(compliance|responsible gambling|ledger|audit trail) review\b/,
+  },
+  {
+    agent: 'quality-reviewer',
+    re: /\b(quality review|code quality|over-engineer(ed|ing)?|simplification review|duplication review)\b|\breview (the )?(mr|pr|diff|changed files)\b/,
+  },
+  {
+    agent: 'security-reviewer',
+    re: /\bsecurity (review|audit)\b|\baudit\b[^.]*\bvulnerabilit|\b(authz|owasp)\b/,
+  },
 ];
 
 const hit = ROUTES.find((r) => r.re.test(text));
-if (!hit) process.exit(0);
+if (!hit) {
+  process.exit(0);
+}
 
 process.stderr.write(
   `Use the \`${hit.agent}\` subagent for this task, not \`${sub || 'general-purpose'}\`. ` +
-    `It is pre-scoped for this work (tools + model + brief) - see the Agent roster in AGENTS.md. ` +
+    `It is pre-scoped for this work (tools + model + brief) - see the Agents list in the workflow rule. ` +
     `Re-issue the Task with subagent_type: "${hit.agent}". ` +
     `If it genuinely does not fit ${hit.agent}, rephrase the description to say why.\n`,
 );

package/template/__dot__rulesync/hooks/post-edit.mjs.tpl

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+// PostToolUse hook (Claude / Copilot CLI / Codex CLI / Gemini CLI).
+// Lint-fixes the edited files, then typechecks the apps that own them and reports
+// (exit 2) only if the error is in a file just edited. Output is capped so a
+// failure can't balloon the model context. Fail-open on anything unexpected.
+
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { basename, join, isAbsolute } from 'node:path';
+import { extractFilePaths, readPayload } from './_shared.mjs';
+
+const CAP_LINES = 40;
+const CAP_CHARS = 2000;
+
+const filePaths = extractFilePaths(readPayload()).filter(
+  (filePath) =>
+    /\.(ts|tsx)$/.test(filePath) &&
+    !filePath.endsWith('.d.ts') &&
+    !filePath.includes('/templates/') &&
+    !filePath.includes('/generated/') &&
+    existsSync(filePath),
+);
+if (filePaths.length === 0) {
+  process.exit(0);
+}
+const edited = filePaths.join(', ');
+
+/**
+ * node_modules/.bin/<name> when it exists, else the bare name off PATH. `pnpm exec`
+ * costs ~2.2s of package-manager startup per call against ~0.12s for the binary, and
+ * this hook runs on every edit.
+ */
+function bin(name) {
+  const local = join(process.env.CLAUDE_PROJECT_DIR ?? process.cwd(), 'node_modules/.bin', name);
+  return existsSync(local) ? local : name;
+}
+
+function cap(text) {
+  const out = text.split('\n').slice(0, CAP_LINES).join('\n').slice(0, CAP_CHARS);
+  return out.length < text.length ? `${out}\n... (truncated)` : out;
+}
+
+// Lint-fix (best effort - never block on the linter).
+try {
+  execFileSync(bin('oxlint'), ['--fix', ...filePaths], { stdio: 'pipe' });
+} catch {
+  /* oxlint unavailable or errored - fall through to the re-lint / typecheck */
+}
+
+// Re-lint WITHOUT --fix to surface UNFIXABLE errors the agent must resolve by
+// hand - import/no-cycle and the no-restricted-imports boundary rules (deep @openora
+// or {{scope}}/ui imports, app-to-app imports). oxlint exits non-zero on errors
+// only (warnings don't fail), so this blocks on a real boundary/cycle violation
+// in an edited file and feeds the message back. Fail-open on anything else.
+try {
+  execFileSync(bin('oxlint'), filePaths, { stdio: 'pipe' });
+} catch (e) {
+  const out = (e.stdout?.toString() ?? '') + (e.stderr?.toString() ?? '');
+  if (/\berror\b/.test(out)) {
+    process.stderr.write(`Boundary/lint error in ${edited} - fix before continuing:\n${cap(out)}`);
+    process.exit(2);
+  }
+}
+
+// Resolve the owning workspace app (apps/<x> or packages/<x>).
+function packageNameFor(fp) {
+  const m = fp.match(/(.*?\/(?:apps|packages)\/[^/]+)\//);
+  if (!m) {
+    return null;
+  }
+  try {
+    const pkg = JSON.parse(readFileSync(join(m[1], 'package.json'), 'utf8'));
+    if (!pkg.name || !pkg.scripts?.['check:types']) {
+      return null;
+    }
+    return pkg.name;
+  } catch {
+    return null;
+  }
+}
+
+const owners = [
+  ...new Set(
+    filePaths
+      .map((filePath) => packageNameFor(isAbsolute(filePath) ? filePath : join(process.cwd(), filePath)))
+      .filter(Boolean),
+  ),
+];
+if (owners.length === 0) {
+  process.exit(0);
+}
+
+try {
+  execFileSync(
+    bin('turbo'),
+    [
+      'run',
+      'check:types',
+      ...owners.flatMap((owner) => ['--filter', owner]),
+      '--output-logs=errors-only',
+      '--ui=stream',
+    ],
+    { stdio: 'pipe' },
+  );
+  process.exit(0);
+} catch (e) {
+  const output = (e.stdout?.toString() ?? '') + (e.stderr?.toString() ?? '');
+  const failing = filePaths.map((filePath) => basename(filePath)).filter((name) => output.includes(name));
+  if (failing.length > 0) {
+    process.stderr.write(
+      `Typecheck failed for ${owners.join(', ')} after editing ${failing.join(', ')}:\n${cap(output)}`,
+    );
+    process.exit(2);
+  }
+  process.exit(0);
+}

package/template/__dot__rulesync/hooks.json

@@ -2,10 +2,33 @@
   "version": 1,
   "hooks": {
     "preToolUse": [
-      { "type": "command", "command": "node .rulesync/hooks/guard-core.mjs" },
-      { "type": "command", "command": "node .rulesync/hooks/guard-generated.mjs" },
-      { "type": "command", "matcher": "Task", "command": "node .rulesync/hooks/guard-subagent.mjs" }
+      {
+        "type": "command",
+        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
+        "command": "node \"${CLAUDE_PROJECT_DIR:-.}/.rulesync/hooks/guard-core.mjs\""
+      },
+      {
+        "type": "command",
+        "matcher": "Bash|Edit|Write|MultiEdit|NotebookEdit",
+        "command": "node \"${CLAUDE_PROJECT_DIR:-.}/.rulesync/hooks/guard-generated.mjs\""
+      },
+      {
+        "type": "command",
+        "matcher": "Bash",
+        "command": "node \"${CLAUDE_PROJECT_DIR:-.}/.rulesync/hooks/guard-mr.mjs\""
+      },
+      {
+        "type": "command",
+        "matcher": "Task|Agent",
+        "command": "node \"${CLAUDE_PROJECT_DIR:-.}/.rulesync/hooks/guard-subagent.mjs\""
+      }
     ],
-    "postToolUse": [{ "type": "command", "command": "node .rulesync/hooks/post-edit.mjs" }]
+    "postToolUse": [
+      {
+        "type": "command",
+        "matcher": "Edit|Write|MultiEdit|NotebookEdit",
+        "command": "node \"${CLAUDE_PROJECT_DIR:-.}/.rulesync/hooks/post-edit.mjs\""
+      }
+    ]
   }
 }

package/template/__dot__rulesync/rules/conventions.md

@@ -0,0 +1,114 @@
+---
+root: false
+targets:
+  - '*'
+globs:
+  - 'apps/**'
+  - 'packages/**'
+  - 'tools/**'
+  - '*.config.*'
+  - 'package.json'
+description: Engineering code conventions (TS, DB, frontend, testing, git) - the always-on core, with a routing table to full detail in docs/standards/.
+---
+
+# Engineering conventions
+
+The always-on core of the code standard: what you must obey while typing. Detail, examples, and
+rationale live in `docs/standards/` - read the one file that matches the change instead of
+carrying all of it. The enforced import graph lives in `oss-boundaries`; Playwright rules in
+`e2e-conventions`; the always-on UI and SQL cores in `frontend-conventions` and `db-conventions`.
+
+| Change you are making                 | Read first                           |
+| ------------------------------------- | ------------------------------------ |
+| schema, type, enum-like value set     | `docs/standards/types.md`            |
+| function, service method, constructor | `docs/standards/functions.md`        |
+| new package, overlay, module layout   | `docs/standards/module-structure.md` |
+| a comment or JSDoc                    | `docs/standards/comments.md`         |
+| error class, catch, money path        | `docs/standards/errors.md`           |
+| a test                                | `docs/standards/testing.md`          |
+| commit, PR                            | `docs/standards/git-delivery.md`     |
+| a failing gate, a new lint rule       | `docs/standards/enforcement.md`      |
+| React/UI component, page, styling     | `docs/standards/frontend.md`         |
+| SQL, Drizzle, migration, seed         | `docs/standards/database.md`         |
+
+`docs/standards/frontend.md` doesn't apply to a headless/api-only repo - delete it (and its row
+above) if this repo has no UI apps.
+
+## Philosophy
+
+- Functional and declarative: pure functions, immutable data, composition. No stateful classes, no
+  imperative accumulation loops.
+- Explicit over magic: no decorators, no auto-discovery, no reflection. Every wiring point is a
+  greppable typed call (`ctx.provide(TOKEN, factory)`).
+- Self-documenting: clear names beat comments (`percentChange`, not `d` + a comment).
+- YAGNI then DRY: don't build for imagined futures; abstract on the third occurrence, not the
+  first.
+- Boring and consistent: match the surrounding code's idiom, naming, and density.
+
+## Never (lint-enforced unless noted)
+
+- `any` outside tests, `!` non-null assertions, `as` casts to silence the compiler (`as const` is
+  fine). Two sanctioned casts: test doubles through one `mock<T>()` helper (never inline in a
+  test), and a third-party inference boundary a library gives no honest way to satisfy (one cast,
+  one-line `// Library boundary:` note).
+- `interface`, TS `enum`, decorators, inheritance for reuse, default exports (exceptions:
+  `*.config.*`, `plugin.ts`, Next.js App Router files).
+- Hand-written duplicates of an inferrable type, re-inferring an imported schema, re-typing
+  derived schema fields, ad-hoc/duplicated Zod schemas outside a module's `contract/`.
+- Re-exporting types "to be nice" - import from where defined.
+- Inline `fetch`/`axios` in module code - third-party access is a port + adapter bound at the
+  composition root.
+- Deep (`../../`+) relative imports that leave your module/zone, imports of another module's
+  internals, import cycles, deep `dist/`/`src/` paths into another package.
+- SQL anti-patterns (bare `timestamp()`, CamelCase identifiers, hand-edited migrations) - detail
+  in `docs/standards/database.md`.
+- Silent catches - log with context and rethrow. `ORPCError.message` rendered to a player - UI copy
+  keys off `.code` + typed `.data` through `t()`.
+- Comments, unless one states a fact the code cannot contain (an external system's behaviour, a
+  spec constraint); a reason goes in the commit or PR, never inline. Never in tests. Detail:
+  `docs/standards/comments.md`.
+- An in-process test that mocks the database, a repository, or a sibling service - found one in
+  the diff, delete it and replace it with the API E2E; never add to it.
+
+## Always
+
+- **Naming:** files `kebab-case.ts`, one concept per file, filename names the concept
+  (`wallet.service.ts`, never `helpers.ts`); types `PascalCase`; values/functions `camelCase`;
+  true global constants `SCREAMING_SNAKE_CASE`; Zod schemas `<Name>Schema` with inferred type
+  `<Name>`; booleans read as predicates (`isActive`, `canEdit`); money is a decimal string plus a
+  `currency` field alongside it, never `amountCents`; IO functions are verbs (`fetchInvoice`); names
+  carry units and intent (`delayMs`, `maxRetries`).
+- **One source of truth per shape** - infer, never hand-write: `z.infer<typeof XSchema>`,
+  `typeof x.$inferSelect`. Full detail: `docs/standards/types.md`.
+- **Literal config arrays/objects (option lists, key sets) use `as const`**, not an explicit union
+  type annotation - let TypeScript infer the literal types.
+- **Schema-first at every boundary** (HTTP, config, env, events); validate once at the edge, trust
+  the type after.
+- **Entity ids typed through their owning type** (`playerId: Player['id']`), never a bare
+  `string`.
+- **Guard clauses first, main path last; more than 3 params -> one named object** (a leading
+  `tx` handle may stay positional). Always brace control statements, even one-liners (lint:
+  `curly`). Detail: `docs/standards/functions.md`.
+- **Construct objects by spread + override**, never a hand-copied field list.
+- **Side effects at the edges**; money paths are transactional AND idempotent (a DB guard inside
+  the transaction, not just an idempotency key). Detail: `docs/standards/errors.md`.
+- **Typed, named error classes** from the shared factories, mapped to transport in the router's
+  `mapErrors`.
+- **Pin exact dependency versions** (no `^`/`~`); add a dependency deliberately - std lib or a few
+  lines often beat a tree.
+- **A feature or fix PR ships its own tests** - no separate test PR. It ships the change, the
+  manual verification pass that proves it (drive the running stack by hand, attach a short video
+  per acceptance criterion, or the request/response trace for an API-only change, to the PR
+  description), and the tests that pass exercised, listed in the description's "Tests" list.
+  Which tier each one belongs to, and how to run the manual pass: `docs/standards/testing.md`.
+- **Green before review:** `/check` (typecheck + lint + unit tests) while iterating, `pnpm verify`
+  on the committed tree before the PR (the `guard-mr` hook refuses to open one until it passed on
+  HEAD). Conventional commits, lowercase subject (PR
+  title too - a squash merge turns it into the commit), one PR per concern. Never push without
+  explicit confirmation. The description carries what / why / acceptance criteria / bare ticket
+  key, the manual-verification evidence (a short video per acceptance criterion, before and after on
+  a fix) and the "Tests" list - but no CI checklist the pipeline already shows, no URLs,
+  hostnames, secrets, or PII. Detail: `docs/standards/git-delivery.md`.
+- **Fix the import, never work around a lint or boundary violation.** Agent rules are generated
+  from `.rulesync/` via `pnpm gen:agents` - never hand-edit a generated file. Detail:
+  `docs/standards/enforcement.md`.