@everystack/mcp 0.2.3 → 0.3.1

package/src/governance/grounding.ts

@@ -0,0 +1,344 @@
+/**
+ * grounding — enforce reading the project contract before any non-Read tool.
+ *
+ * Ported from local-agent's grounding gate (the proven implementation; see
+ * ~/Sites/local-agent/docs/grounding-gate.md). The contract: the CLAUDE.md files
+ * (global + project) and their declared `REQUIRED-READS:` companions define how
+ * the build is meant to go — for everystack that includes the Model/Module-first
+ * resources a project names. A model does not get to glide past them as scenery.
+ * Until the required files are actually Read this session, every tool EXCEPT Read
+ * is denied.
+ *
+ * everystack adaptation: state lives under ~/.everystack/governance/grounding so
+ * it never collides with local-agent's own gate (~/.agent/grounding). The pure
+ * functions (requiredFiles / gate / mark / context / groundStatus) are exported
+ * for governance/cli.ts to drive from hook JSON; the CLI shim lives there.
+ *
+ * Honest ceiling: this forces the *read* (deliberate, in-context, links followed).
+ * It cannot force comprehension. It kills the one specific failure — skipping the
+ * files — dead. Nothing more is claimed.
+ *
+ * Design decisions (from the bash → TS rewrite that proved this out):
+ *  - Required set is DECLARED, not inferred: the global and project CLAUDE.md are
+ *    always required, and each names its mandatory companions with an explicit
+ *    `REQUIRED-READS:` line. (Scraping every Markdown link over-captures incidental
+ *    prose links, so the contract declares its own reads instead.)
+ *  - Paths are canonicalised with realpath on BOTH sides, so a symlinked root
+ *    (/tmp -> /private/tmp) can't silently fail to match.
+ *  - Partial reads (Read with offset/limit) do NOT count as grounding.
+ *  - State is one JSON file per session; resets only on startup/clear, never on
+ *    resume/compact — and `context` re-injects the contract on compact so it
+ *    re-enters context after summarisation.
+ *  - Fail-OPEN on any internal error or empty required set (never brick tool use);
+ *    fail-CLOSED only on the explicit "not yet grounded" condition.
+ */
+
+import {
+  existsSync,
+  realpathSync,
+  readFileSync,
+  readdirSync,
+  statSync,
+  mkdirSync,
+  writeFileSync,
+  unlinkSync,
+} from 'fs';
+import { join, dirname, resolve, isAbsolute } from 'path';
+import { homedir } from 'os';
+
+const MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
+
+/** Home dir, overridable via $HOME (hook contexts + tests); falls back to os.homedir(). */
+function home(): string {
+  return process.env.HOME || homedir();
+}
+
+function globalClaudeMd(): string {
+  return join(home(), '.claude', 'CLAUDE.md');
+}
+
+function stateDir(): string {
+  return join(home(), '.everystack', 'governance', 'grounding');
+}
+
+/** Canonical absolute path: resolve symlinks if the file exists, else normalise. */
+function canonical(p: string): string {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+}
+
+/** Expand a leading `~` (or `~/`) to the home directory. */
+function expandTilde(p: string): string {
+  if (p === '~') return home();
+  if (p.startsWith('~/')) return join(home(), p.slice(2));
+  return p;
+}
+
+/** Nearest project CLAUDE.md walking up from cwd, stopping at $HOME or filesystem root. */
+function nearestProjectClaudeMd(cwd: string): string | null {
+  let d = resolve(cwd);
+  const stop = resolve(home());
+  while (d && d !== '/' && d !== stop) {
+    const candidate = join(d, 'CLAUDE.md');
+    if (existsSync(candidate)) return candidate;
+    const parent = dirname(d);
+    if (parent === d) break;
+    d = parent;
+  }
+  return null;
+}
+
+/** Parse an optional `REQUIRED-READS: a.md, b/c.md` line; paths relative to the CLAUDE.md dir. */
+function parseRequiredReads(claudeMdPath: string): string[] {
+  let text: string;
+  try {
+    text = readFileSync(claudeMdPath, 'utf-8');
+  } catch {
+    return [];
+  }
+  const m = text.match(/^[ \t]*REQUIRED-READS:[ \t]*(.+)$/im);
+  if (!m) return [];
+  const base = dirname(claudeMdPath);
+  return m[1]
+    .split(',')
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map(expandTilde)
+    .map((rel) => (isAbsolute(rel) ? rel : resolve(base, rel)));
+}
+
+export interface RequiredSet {
+  /** Canonical paths of required files that exist (the gate can be satisfied by these). */
+  present: string[];
+  /** Required paths referenced but missing on disk (logged/warned, never block on them). */
+  missing: string[];
+}
+
+/**
+ * Resolve the required-reads set for a working directory:
+ *   global CLAUDE.md + its REQUIRED-READS entries
+ *   + nearest project CLAUDE.md + its REQUIRED-READS entries.
+ * Returns canonical, de-duplicated paths partitioned into present / missing.
+ */
+export function requiredFiles(cwd: string): RequiredSet {
+  const candidates: string[] = [];
+
+  const gmd = globalClaudeMd();
+  if (existsSync(gmd)) {
+    candidates.push(gmd);
+    candidates.push(...parseRequiredReads(gmd));
+  }
+
+  const proj = nearestProjectClaudeMd(cwd);
+  if (proj) {
+    candidates.push(proj);
+    candidates.push(...parseRequiredReads(proj));
+  }
+
+  const present: string[] = [];
+  const missing: string[] = [];
+  const seen = new Set<string>();
+  for (const c of candidates) {
+    if (existsSync(c)) {
+      const canon = canonical(c);
+      if (!seen.has(canon)) {
+        seen.add(canon);
+        present.push(canon);
+      }
+    } else {
+      const norm = resolve(c);
+      if (!seen.has(norm)) {
+        seen.add(norm);
+        missing.push(norm);
+      }
+    }
+  }
+  return { present, missing };
+}
+
+// ---------------------------------------------------------------------------
+// Per-session state
+// ---------------------------------------------------------------------------
+
+interface State {
+  reads: string[];
+  grounded: boolean;
+  updated: string;
+}
+
+function safeId(sessionId: string): string {
+  return (sessionId || 'nosession').replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+
+function statePath(sessionId: string): string {
+  return join(stateDir(), `${safeId(sessionId)}.json`);
+}
+
+function loadState(sessionId: string): State {
+  try {
+    const raw = JSON.parse(readFileSync(statePath(sessionId), 'utf-8'));
+    return {
+      reads: Array.isArray(raw.reads) ? raw.reads : [],
+      grounded: !!raw.grounded,
+      updated: typeof raw.updated === 'string' ? raw.updated : '',
+    };
+  } catch {
+    return { reads: [], grounded: false, updated: '' };
+  }
+}
+
+function saveState(sessionId: string, state: State): void {
+  mkdirSync(stateDir(), { recursive: true });
+  writeFileSync(statePath(sessionId), JSON.stringify(state));
+}
+
+function resetState(sessionId: string): void {
+  try {
+    unlinkSync(statePath(sessionId));
+  } catch {
+    /* nothing to reset */
+  }
+}
+
+/** Delete session-state files older than 7 days. */
+function prune(): void {
+  let files: string[];
+  try {
+    files = readdirSync(stateDir());
+  } catch {
+    return;
+  }
+  const now = Date.now();
+  for (const f of files) {
+    const p = join(stateDir(), f);
+    try {
+      if (now - statSync(p).mtimeMs > MAX_AGE_MS) unlinkSync(p);
+    } catch {
+      /* skip */
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public surface: gate / mark / context
+// ---------------------------------------------------------------------------
+
+export interface GateResult {
+  decision: 'allow' | 'deny';
+  unread: string[];
+}
+
+/**
+ * PreToolUse decision. Always allows `Read`. Allows everything once the session
+ * is grounded. Fails open if no required files resolve. Otherwise denies any
+ * non-Read tool while required files remain unread.
+ */
+export function gate(sessionId: string, cwd: string, toolName: string): GateResult {
+  if (toolName === 'Read') return { decision: 'allow', unread: [] };
+
+  const { present } = requiredFiles(cwd);
+  if (present.length === 0) return { decision: 'allow', unread: [] }; // nothing to ground on
+
+  const state = loadState(sessionId);
+  if (state.grounded) return { decision: 'allow', unread: [] };
+
+  const read = new Set(state.reads);
+  const unread = present.filter((p) => !read.has(p));
+  if (unread.length === 0) {
+    saveState(sessionId, { reads: state.reads, grounded: true, updated: new Date().toISOString() });
+    return { decision: 'allow', unread: [] };
+  }
+  return { decision: 'deny', unread };
+}
+
+export interface MarkResult {
+  grounded: boolean;
+}
+
+/**
+ * PostToolUse(Read) record. A full read of a required file marks it grounded.
+ * Partial reads (offset/limit present) are ignored — a one-line peek is not
+ * grounding. Reads of non-required files are ignored.
+ */
+export function mark(sessionId: string, cwd: string, filePath: string, partial = false): MarkResult {
+  if (partial || !filePath) return { grounded: loadState(sessionId).grounded };
+
+  const { present } = requiredFiles(cwd);
+  const canon = canonical(filePath);
+  if (!present.includes(canon)) return { grounded: loadState(sessionId).grounded };
+
+  const state = loadState(sessionId);
+  const reads = state.reads.includes(canon) ? state.reads : [...state.reads, canon];
+  const grounded = present.every((p) => reads.includes(p));
+  saveState(sessionId, { reads, grounded, updated: new Date().toISOString() });
+  return { grounded };
+}
+
+/**
+ * SessionStart payload: the required-file list injected into context. Resets
+ * per-session state on `startup`/`clear` (fresh grounding required); leaves it
+ * intact on `resume`/`compact` but still re-injects the contract so it survives
+ * summarisation. Also runs 7-day housekeeping.
+ */
+export function context(sessionId: string, cwd: string, source: string): string {
+  prune();
+  if (source === 'startup' || source === 'clear') resetState(sessionId);
+
+  const { present, missing } = requiredFiles(cwd);
+  const lines: string[] = [];
+  lines.push('GROUNDING GATE ACTIVE — this is the contract for how this project is built.');
+  lines.push(
+    'Before ANY other tool this session you MUST Read these files (Read is the only tool allowed until you have). Read them, act on them, follow their links:'
+  );
+  if (present.length === 0) {
+    lines.push('  (no CLAUDE.md contract found for this directory — gate is inactive)');
+  } else {
+    for (const f of present) lines.push(`  - ${f}`);
+  }
+  if (missing.length > 0) {
+    lines.push('');
+    lines.push('Note — referenced but missing on disk (skipped, not required):');
+    for (const f of missing) lines.push(`  - ${f}`);
+  }
+  lines.push('');
+  lines.push('You do not get the right to ignore them.');
+  return lines.join('\n');
+}
+
+/** Human-readable grounding status for a session/cwd (the MCP introspection path). */
+export function groundStatus(cwd: string, sessionId?: string): string {
+  const { present, missing } = requiredFiles(cwd);
+  const lines: string[] = [];
+  lines.push(`Required reads for ${resolve(cwd)}:`);
+  if (present.length === 0) lines.push('  (none — no CLAUDE.md contract found; gate inactive)');
+
+  if (sessionId) {
+    const state = loadState(sessionId);
+    const read = new Set(state.reads);
+    for (const f of present) lines.push(`  [${read.has(f) ? 'x' : ' '}] ${f}`);
+    lines.push('');
+    lines.push(`Grounded: ${state.grounded ? 'yes' : 'no'} (session ${safeId(sessionId)})`);
+  } else {
+    for (const f of present) lines.push(`  - ${f}`);
+  }
+  if (missing.length > 0) {
+    lines.push('');
+    lines.push('Referenced but missing (skipped):');
+    for (const f of missing) lines.push(`  - ${f}`);
+  }
+  return lines.join('\n');
+}
+
+/** The PreToolUse deny reason shown when grounding is incomplete. */
+export function denyReason(unread: string[]): string {
+  return [
+    'GROUNDING INCOMPLETE — you have not read the contract. Read these files first',
+    '(Read is allowed; every other tool is blocked until you have):',
+    ...unread.map((f) => `  - ${f}`),
+    '',
+    'This is how this project is built. You do not get to skip it.',
+  ].join('\n');
+}

package/src/index.ts

@@ -1,58 +1,105 @@
-#!/usr/bin/env tsx
-
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { registerResources } from './resources/index.js';
 import { registerTools } from './tools/index.js';
 import { registerPrompts } from './prompts/index.js';
+import { GOVERNANCE_COMMANDS, runGovernanceCli } from './governance/cli.js';
+
+// Injected at build time by scripts/build.mjs (esbuild --define) from package.json.
+// Unbundled (dev via tsx), the identifier is undefined and we fall back to a literal.
+declare const __MCP_VERSION__: string | undefined;
+const version = (typeof __MCP_VERSION__ === 'string' ? __MCP_VERSION__ : null) ?? '0.3.0-dev';
+
+const INSTRUCTIONS = [
+  'You govern how any agent builds everystack — a self-hosted application stack for Expo apps on AWS.',
+  'Your job is not only to advise but to keep the build on-script: the architecture the maintainer',
+  'set up (Models/Modules, generated migrations, the ui package, the secrets boundary) is the way,',
+  'and the training-consensus shortcut (bundle the JSON, hand-write the migration, hand-roll a',
+  'component) is the cheat. The cheat gates enforce this structurally; you reinforce it in guidance.',
+  '',
+  '## Governance setup (do this once, early)',
+  '',
+  'This server is the knowledge + helpful path. The ENFORCEMENT (grounding gate + cheat gates) runs',
+  'as Claude Code hooks, NOT from this server alone. If the hooks are not installed, none of the',
+  'gates fire — so check and offer to install them at the start of work on an everystack project:',
+  '1. Look for the everystack governance hooks in the project\'s `.claude/settings.json` (a',
+  '   `hooks` block whose commands call `everystack-mcp gate`/`context`/`mark`/`validate`).',
+  '2. If they are absent, read this package\'s `hooks.example.json` and `docs/governance-setup.md`',
+  '   (in @everystack/mcp), then OFFER to merge the `hooks` block into `.claude/settings.json`.',
+  '3. NEVER install them silently — hooks run a shell command on every tool call. Show the human',
+  '   the exact block and the command form (workspace `npx tsx packages/mcp/src/index.ts <sub>` vs',
+  '   installed `everystack-mcp <sub>`), and let them confirm.',
+  '4. The `governance_setup` prompt produces the exact block for the current project.',
+  '',
+  '## The project contract (CLAUDE.md)',
+  '',
+  'The grounding gate has nothing to enforce without a project `CLAUDE.md` — and writing one is',
+  'what turns grounding ON (the nearest project CLAUDE.md is auto-required reading). Early in any',
+  'everystack project, ensure a CLAUDE.md exists AND is current:',
+  '- If it is missing, offer to scaffold it (the `claude_md` prompt; template at',
+  '  everystack://project-claude-md). It carries the non-negotiables the cheat gates enforce.',
+  '- If it exists, it is a living contract — as the project adds packages, models, or a tier, it',
+  '  drifts. Offer to reconcile it (also `claude_md`): suggest updates against the project reality',
+  '  and the current conventions, confirm-first, and never clobber the human\'s own content.',
+  '',
+  '## Beginner Detection',
+  '',
+  'Detect the user\'s experience level from context:',
+  '- If the user describes an app idea without technical terms, has no existing project, or asks basic questions ("how do I start?", "I want to build..."), treat them as a BEGINNER.',
+  '- If the user references specific packages, tiers (V1/V2/V3), tools (Drizzle, PostgREST, SST), or has an existing everystack project, treat them as a DEVELOPER.',
+  '',
+  '## Beginner Flow',
+  '',
+  'For beginners:',
+  '1. Read everystack://getting-started first. This is your guide for how to talk to beginners.',
+  '2. Ask what they want to build. Listen to their idea before anything technical. Do NOT categorize into tiers or ask them to choose V1/V2/V3.',
+  '3. Run check_environment with phase "local". Only V1 prerequisites matter now (Node.js, git, pnpm). PostgreSQL is NOT needed yet.',
+  '   Do NOT require AWS tools (AWS CLI, credentials, SST) upfront. The user will build and run locally first.',
+  '4. Walk through installing missing prerequisites ONE AT A TIME. Do not list them all at once. Install the first missing tool, confirm it works, then move to the next.',
+  '5. Create a stock Expo app: `npx create-expo-app@latest`, install V1 packages (`@everystack/server`, `@everystack/cli`, `@everystack/ui`), and `pnpm add -D sst`.',
+  '6. Run `npx expo start`. Read everystack://first-run for the walkthrough. The first milestone is seeing the app running in a browser.',
+  '7. Build together. Discuss what the app should look like. Create screens, navigation, components. Everything is static and visual.',
+  '8. When a feature needs user accounts or saved data, read everystack://adding-database. This introduces PostgreSQL, the API handler, auth, and database setup step by step.',
+  '9. When a feature needs file uploads or background tasks, add the relevant packages incrementally (everystack://storage, everystack://jobs, everystack://images).',
+  '10. When the user is ready to deploy to the internet, run check_environment with phase "deploy" and walk through AWS setup.',
+  '    For AWS credentials specifically, read everystack://aws-setup and walk them through account creation and IAM setup step by step.',
+  '11. Never use jargon without explaining it. "Lambda" is "the server that runs your code." "S3" is "file storage." "RDS" is "the database server." "CloudFront" is "the CDN that makes your app fast worldwide."',
+  '',
+  '## Developer Flow',
+  '',
+  'For experienced developers:',
+  '1. Read everystack://core for architecture and conventions.',
+  '2. Read everystack://security before any deployment or auth guidance.',
+  '3. Load detail resources on demand when the user asks about specific features.',
+  '4. Data lives in PostgreSQL via Models/Modules and is served through the API — never bundle large computed data into the app. Schema changes go through generated migrations (`db:generate`), never hand-written DDL. Reuse `@everystack/ui` components; never put secret values behind `EXPO_PUBLIC_*`.',
+  '5. When the user wants to start a new project, run check_environment (phase "local" for dev, "deploy" for deployment) to verify prerequisites.',
+  '6. When the user needs to interact with deployed infrastructure, guide them to use the everystack CLI.',
+].join('\n');
 
-const server = new McpServer(
-  { name: '@everystack/mcp', version: '0.2.0' },
-  {
-    instructions: [
-      'You are an everystack expert. everystack is a self-hosted application stack for Expo apps on AWS.',
-      '',
-      '## Beginner Detection',
-      '',
-      'Detect the user\'s experience level from context:',
-      '- If the user describes an app idea without technical terms, has no existing project, or asks basic questions ("how do I start?", "I want to build..."), treat them as a BEGINNER.',
-      '- If the user references specific packages, tiers (V1/V2/V3), tools (Drizzle, PostgREST, SST), or has an existing everystack project, treat them as a DEVELOPER.',
-      '',
-      '## Beginner Flow',
-      '',
-      'For beginners:',
-      '1. Read everystack://getting-started first. This is your guide for how to talk to beginners.',
-      '2. Ask what they want to build. Listen to their idea before anything technical. Do NOT categorize into tiers or ask them to choose V1/V2/V3.',
-      '3. Run check_environment with phase "local". Only V1 prerequisites matter now (Node.js, git, pnpm). PostgreSQL is NOT needed yet.',
-      '   Do NOT require AWS tools (AWS CLI, credentials, SST) upfront. The user will build and run locally first.',
-      '4. Walk through installing missing prerequisites ONE AT A TIME. Do not list them all at once. Install the first missing tool, confirm it works, then move to the next.',
-      '5. Create a stock Expo app: `npx create-expo-app@latest`, install V1 packages (`@everystack/server`, `@everystack/cli`, `@everystack/ui`), and `pnpm add -D sst`.',
-      '6. Run `npx expo start`. Read everystack://first-run for the walkthrough. The first milestone is seeing the app running in a browser.',
-      '7. Build together. Discuss what the app should look like. Create screens, navigation, components. Everything is static and visual.',
-      '8. When a feature needs user accounts or saved data, read everystack://adding-database. This introduces PostgreSQL, the API handler, auth, and database setup step by step.',
-      '9. When a feature needs file uploads or background tasks, add the relevant packages incrementally (everystack://storage, everystack://jobs, everystack://images).',
-      '10. When the user is ready to deploy to the internet, run check_environment with phase "deploy" and walk through AWS setup.',
-      '    For AWS credentials specifically, read everystack://aws-setup and walk them through account creation and IAM setup step by step.',
-      '11. Never use jargon without explaining it. "Lambda" is "the server that runs your code." "S3" is "file storage." "RDS" is "the database server." "CloudFront" is "the CDN that makes your app fast worldwide."',
-      '',
-      '## Developer Flow',
-      '',
-      'For experienced developers:',
-      '1. Read everystack://core for architecture and conventions.',
-      '2. Read everystack://security before any deployment or auth guidance.',
-      '3. Load detail resources on demand when the user asks about specific features.',
-      '4. Use the project_status tool to understand the user\'s current project state.',
-      '5. Use the schema_analyze tool when helping with database schema or RLS.',
-      '6. Use the project_validate tool to check for common mistakes before deployment.',
-      '7. When the user wants to start a new project, run check_environment (phase "local" for dev, "deploy" for deployment) to verify prerequisites.',
-      '8. When the user needs to interact with deployed infrastructure, guide them to use the everystack CLI.',
-    ].join('\n'),
-  },
-);
+async function startServer(): Promise<void> {
+  const server = new McpServer(
+    { name: '@everystack/mcp', version },
+    { instructions: INSTRUCTIONS },
+  );
+  registerResources(server);
+  registerTools(server);
+  registerPrompts(server);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
 
-registerResources(server);
-registerTools(server);
-registerPrompts(server);
+async function main(): Promise<void> {
+  const sub = process.argv[2];
+  // Hook-shim CLI: `everystack-mcp <context|gate|mark|validate|report>` reads hook JSON on stdin.
+  if (sub && (GOVERNANCE_COMMANDS as readonly string[]).includes(sub)) {
+    await runGovernanceCli(process.argv.slice(2));
+    return;
+  }
+  // Default: the stdio MCP server.
+  await startServer();
+}
 
-const transport = new StdioServerTransport();
-server.connect(transport).catch(console.error);
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/prompts/claude-md.ts

@@ -0,0 +1,92 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+
+/**
+ * `claude_md` — create or reconcile the project's CLAUDE.md.
+ *
+ * The CLAUDE.md is the project contract. Writing it activates the grounding gate
+ * (the nearest project CLAUDE.md is auto-required). But a contract is a living
+ * document — it drifts from reality as the project grows. So this prompt is
+ * bidirectional: scaffold it when missing, and review + suggest updates when it
+ * exists (a drift check on the contract itself), never clobbering human content.
+ */
+export function registerClaudeMdPrompt(server: McpServer): void {
+  server.prompt(
+    'claude_md',
+    'Create or keep the project CLAUDE.md current. Missing → scaffold from the everystack contract. Exists → review against the project reality + the cheat-gate rules and suggest updates (confirm-first, never clobber). Writing it activates the grounding gate.',
+    {
+      projectPath: z.string().optional().describe('Absolute path to the project root (where CLAUDE.md lives)'),
+    },
+    async ({ projectPath }) => {
+      const root = projectPath ?? '.';
+      return {
+        messages: [
+          {
+            role: 'user' as const,
+            content: {
+              type: 'text' as const,
+              text: [
+                `Create or reconcile the CLAUDE.md for the project at ${root}.`,
+                '',
+                '## Why this matters',
+                '',
+                'CLAUDE.md is this project\'s contract. The grounding gate auto-requires the nearest',
+                'project CLAUDE.md — so writing it is what turns grounding ON (the agent must read it',
+                'before editing). A contract also drifts as the project grows, so it must be kept current.',
+                '',
+                '## Step 1 — detect the project reality',
+                '',
+                `- Read ${root}/package.json: which @everystack/* packages are installed (tier: V1 server/cli/ui;`,
+                '  V2 adds api/auth/admin/logging/security/query; V3 adds jobs/storage/images).',
+                `- Check for a models/ directory (defineModel files) and a db/ directory.`,
+                `- Note the project name and what the app does.`,
+                '',
+                '## Step 2 — read the template',
+                '',
+                'Read the everystack://project-claude-md resource. It is the everystack contract: the',
+                'Non-negotiables (which mirror the cheat gates), Key Principles, Commands, and the',
+                'What NOT to Do list. Fill {PROJECT_NAME}, {ONE_LINE_DESCRIPTION}, {ANNOTATED_DIRECTORY_TREE}',
+                'and tailor Structure/Commands to the packages actually installed.',
+                '',
+                `## Step 3 — does ${root}/CLAUDE.md already exist?`,
+                '',
+                '### If it does NOT exist → scaffold',
+                '',
+                `- Write ${root}/CLAUDE.md from the template, tailored to the detected reality.`,
+                '- Keep it tight and load-bearing — a wall of prose gets read as scenery. Lead with the',
+                '  Non-negotiables.',
+                '- Tell the human: this activates the grounding gate; new sessions must read it first.',
+                '',
+                '### If it EXISTS → review and suggest updates (DO NOT clobber)',
+                '',
+                'Reconcile the existing CLAUDE.md against three things, and propose a concrete diff:',
+                '1. **Framework drift** — does it teach superseded ways (e.g. `drizzle-kit generate`,',
+                '   hand-written migrations, "pass your Drizzle schema") instead of the v3 Model flow',
+                '   (`defineModel` → `everystack db:generate`)? Suggest the current conventions.',
+                '2. **Project drift** — do the Structure / Commands / package list match what is actually',
+                '   installed now (new packages, a new tier, a new models/ dir)? Suggest updates. Also',
+                '   check the operations manual: if docs/RUNBOOK.md is missing, or stale per',
+                '   `everystack runbook --check`, suggest the `runbook` prompt.',
+                '3. **Contract-vs-gates drift** — is it missing any Non-negotiable the cheat gates enforce',
+                '   (data→DB, generated migrations, declared authz, reuse @everystack/ui, secrets boundary)?',
+                '   Suggest adding it, so the human contract and the enforced rules agree.',
+                '',
+                'Rules for reconciling:',
+                '- **Preserve all human/project-specific content** — project rules, domain notes, the',
+                '  REQUIRED-READS line. Only update the framework/structure/commands sections and flag gaps.',
+                '- **Propose, then confirm.** Show the human the suggested changes (a diff) and let them',
+                '  approve before writing. The CLAUDE.md is theirs; you assist, you do not own it.',
+                '- **Only flag real drift**, not cosmetic rewording.',
+                '',
+                '## Step 4 — confirm',
+                '',
+                'After writing/updating, confirm the file is at the project root so the grounding gate',
+                'picks it up, and summarize what changed.',
+              ].join('\n'),
+            },
+          },
+        ],
+      };
+    },
+  );
+}