@everystack/mcp 0.3.1 → 0.3.3

package/dist/governance/cli.d.ts

@@ -0,0 +1,57 @@
+/**
+ * governance/cli — the hook-shim entry for `everystack-mcp <subcommand>`.
+ *
+ * Claude Code hooks pipe their JSON event on stdin to one of these subcommands;
+ * the hook config itself carries no logic (the local-agent grounding-gate shape).
+ * The handlers are exported so the same logic is unit-testable and so the operator
+ * CLI can self-gate on it later — no drift between what the hook blocks and what
+ * the gate-to-prod refuses.
+ *
+ * This module stays LIGHT to import: it pulls only grounding + the pure engine +
+ * telemetry. The one heavy dependency (the canonical secret scanner) is lazy-loaded
+ * inside its detector behind a cheap pre-filter, so the common tool call is fast.
+ *
+ * Fail-OPEN on any internal error or unknown input — a governance bug must never
+ * brick tool use globally. Only the explicit "ungrounded" / "off-script deny"
+ * conditions fail closed.
+ */
+export declare const GOVERNANCE_COMMANDS: readonly ["context", "gate", "mark", "validate", "report"];
+export type GovernanceCommand = (typeof GOVERNANCE_COMMANDS)[number];
+interface HookInput {
+    session_id?: string;
+    cwd?: string;
+    source?: string;
+    tool_name?: string;
+    tool_input?: {
+        file_path?: string;
+        content?: string;
+        new_string?: string;
+        old_string?: string;
+        command?: string;
+        offset?: number;
+        limit?: number;
+    };
+}
+/** SessionStart: the grounding contract text. */
+export declare function handleContext(input: HookInput): string;
+/**
+ * PreToolUse: grounding first (the contract must be read), then cheat gates. Returns
+ * a deny payload object to emit, or null to allow. Telemetry is recorded for any
+ * cheat findings at this boundary (the authoritative "attempt" event).
+ */
+export declare function handleGate(input: HookInput): Promise<unknown | null>;
+/**
+ * PostToolUse(Write|Edit): re-scan after the write and surface anything (a backstop
+ * for what a pre-write check couldn't see). Non-blocking. Does NOT re-record — the
+ * attempt was already counted at the gate — it only surfaces guidance.
+ */
+export declare function handleValidate(input: HookInput): Promise<unknown | null>;
+/** PostToolUse(Read): mark a required-file read toward grounding. */
+export declare function handleMark(input: HookInput): void;
+/**
+ * Dispatch a governance subcommand from hook JSON on stdin. `report` reads
+ * telemetry instead of stdin and prints a summary. Always fails open.
+ */
+export declare function runGovernanceCli(argv: string[]): Promise<void>;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/governance/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/governance/cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAQH,eAAO,MAAM,mBAAmB,4DAMtB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,mBAAmB,CAAC,CAAC,MAAM,CAAC,CAAC;AAErE,UAAU,SAAS;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE;QACX,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH;AAuCD,iDAAiD;AACjD,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAItD;AAED;;;;GAIG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAe1E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAM9E;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,CAOjD;AAoBD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BpE"}

package/dist/governance/cli.js

@@ -0,0 +1,169 @@
+/**
+ * governance/cli — the hook-shim entry for `everystack-mcp <subcommand>`.
+ *
+ * Claude Code hooks pipe their JSON event on stdin to one of these subcommands;
+ * the hook config itself carries no logic (the local-agent grounding-gate shape).
+ * The handlers are exported so the same logic is unit-testable and so the operator
+ * CLI can self-gate on it later — no drift between what the hook blocks and what
+ * the gate-to-prod refuses.
+ *
+ * This module stays LIGHT to import: it pulls only grounding + the pure engine +
+ * telemetry. The one heavy dependency (the canonical secret scanner) is lazy-loaded
+ * inside its detector behind a cheap pre-filter, so the common tool call is fast.
+ *
+ * Fail-OPEN on any internal error or unknown input — a governance bug must never
+ * brick tool use globally. Only the explicit "ungrounded" / "off-script deny"
+ * conditions fail closed.
+ */
+import { context, gate, mark, denyReason } from './grounding.js';
+import { evaluateGates, decide, findingsReason } from '../gates/engine.js';
+import { gatesFor } from '../gates/registry.js';
+import { recordFindings, summarize, renderSummary } from '../gates/telemetry.js';
+export const GOVERNANCE_COMMANDS = [
+    'context', // SessionStart: inject the grounding contract
+    'gate', // PreToolUse: allow/deny (grounding + cheat gates)
+    'mark', // PostToolUse(Read): record a required-file read
+    'validate', // PostToolUse(Write|Edit): surface any cheat the write landed
+    'report', // summarize the per-session telemetry (the sensor)
+];
+/** Deny payload for PreToolUse. */
+function denyPayload(reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    };
+}
+/** Non-blocking advisory payload for PostToolUse. */
+function contextPayload(text) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PostToolUse',
+            additionalContext: text,
+        },
+    };
+}
+function toToolContext(input) {
+    const ti = input.tool_input ?? {};
+    return {
+        tool: input.tool_name ?? '',
+        filePath: ti.file_path,
+        // Write carries `content`; Edit carries `new_string` (what is about to land).
+        content: ti.content ?? ti.new_string,
+        command: ti.command,
+        cwd: input.cwd ?? process.cwd(),
+    };
+}
+// ---------------------------------------------------------------------------
+// Handlers (exported for tests; pure-ish — telemetry is the only side effect)
+// ---------------------------------------------------------------------------
+/** SessionStart: the grounding contract text. */
+export function handleContext(input) {
+    const sid = input.session_id ?? 'nosession';
+    const cwd = input.cwd ?? process.cwd();
+    return context(sid, cwd, input.source ?? 'startup');
+}
+/**
+ * PreToolUse: grounding first (the contract must be read), then cheat gates. Returns
+ * a deny payload object to emit, or null to allow. Telemetry is recorded for any
+ * cheat findings at this boundary (the authoritative "attempt" event).
+ */
+export async function handleGate(input) {
+    const sid = input.session_id ?? 'nosession';
+    const cwd = input.cwd ?? process.cwd();
+    const tool = input.tool_name ?? '';
+    // 1) Grounding: until the contract is read, every non-Read tool is denied.
+    const g = gate(sid, cwd, tool);
+    if (g.decision === 'deny')
+        return denyPayload(denyReason(g.unread));
+    // 2) Cheat gates.
+    const ctx = toToolContext(input);
+    const findings = await evaluateGates(ctx, gatesFor(cwd));
+    if (findings.length)
+        recordFindings(sid, { cwd, tool }, findings);
+    if (decide(findings).decision === 'deny')
+        return denyPayload(findingsReason(findings));
+    return null; // allow (any warn-tier findings are recorded, not blocked)
+}
+/**
+ * PostToolUse(Write|Edit): re-scan after the write and surface anything (a backstop
+ * for what a pre-write check couldn't see). Non-blocking. Does NOT re-record — the
+ * attempt was already counted at the gate — it only surfaces guidance.
+ */
+export async function handleValidate(input) {
+    const cwd = input.cwd ?? process.cwd();
+    const ctx = toToolContext(input);
+    const findings = await evaluateGates(ctx, gatesFor(cwd));
+    if (!findings.length)
+        return null;
+    return contextPayload(findingsReason(findings));
+}
+/** PostToolUse(Read): mark a required-file read toward grounding. */
+export function handleMark(input) {
+    const sid = input.session_id ?? 'nosession';
+    const cwd = input.cwd ?? process.cwd();
+    const ti = input.tool_input ?? {};
+    if (!ti.file_path)
+        return;
+    const partial = ti.offset !== undefined || ti.limit !== undefined;
+    mark(sid, cwd, ti.file_path, partial);
+}
+// ---------------------------------------------------------------------------
+// stdin / dispatch
+// ---------------------------------------------------------------------------
+function readStdin() {
+    return new Promise((res) => {
+        let data = '';
+        if (process.stdin.isTTY) {
+            res('');
+            return;
+        }
+        process.stdin.setEncoding('utf-8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => res(data));
+        process.stdin.on('error', () => res(data));
+    });
+}
+/**
+ * Dispatch a governance subcommand from hook JSON on stdin. `report` reads
+ * telemetry instead of stdin and prints a summary. Always fails open.
+ */
+export async function runGovernanceCli(argv) {
+    const mode = argv[0];
+    if (!mode || !GOVERNANCE_COMMANDS.includes(mode))
+        return;
+    try {
+        if (mode === 'report') {
+            process.stdout.write(renderSummary(summarize(argv[1])) + '\n');
+            return;
+        }
+        let input = {};
+        try {
+            input = JSON.parse((await readStdin()) || '{}');
+        }
+        catch {
+            return; // fail open on malformed input
+        }
+        if (mode === 'context') {
+            process.stdout.write(handleContext(input) + '\n');
+        }
+        else if (mode === 'gate') {
+            const payload = await handleGate(input);
+            if (payload)
+                process.stdout.write(JSON.stringify(payload));
+        }
+        else if (mode === 'mark') {
+            handleMark(input);
+        }
+        else if (mode === 'validate') {
+            const payload = await handleValidate(input);
+            if (payload)
+                process.stdout.write(JSON.stringify(payload));
+        }
+    }
+    catch {
+        /* fail open: stay silent, exit 0 */
+    }
+}

package/dist/governance/grounding.d.ts

@@ -0,0 +1,78 @@
+/**
+ * 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.
+ */
+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 declare function requiredFiles(cwd: string): RequiredSet;
+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 declare function gate(sessionId: string, cwd: string, toolName: string): GateResult;
+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 declare function mark(sessionId: string, cwd: string, filePath: string, partial?: boolean): MarkResult;
+/**
+ * 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 declare function context(sessionId: string, cwd: string, source: string): string;
+/** Human-readable grounding status for a session/cwd (the MCP introspection path). */
+export declare function groundStatus(cwd: string, sessionId?: string): string;
+/** The PreToolUse deny reason shown when grounding is incomplete. */
+export declare function denyReason(unread: string[]): string;
+//# sourceMappingURL=grounding.d.ts.map

package/dist/governance/grounding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grounding.d.ts","sourceRoot":"","sources":["../../src/governance/grounding.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AA+EH,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,0FAA0F;IAC1F,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW,CAkCtD;AAqED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,GAAG,MAAM,CAAC;IAC3B,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU,CAgBjF;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED;;;;GAIG;AACH,wBAAgB,IAAI,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,UAAQ,GAAG,UAAU,CAYlG;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAuB9E;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAqBpE;AAED,qEAAqE;AACrE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAQnD"}

package/dist/governance/grounding.js

@@ -0,0 +1,299 @@
+/**
+ * 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() {
+    return process.env.HOME || homedir();
+}
+function globalClaudeMd() {
+    return join(home(), '.claude', 'CLAUDE.md');
+}
+function stateDir() {
+    return join(home(), '.everystack', 'governance', 'grounding');
+}
+/** Canonical absolute path: resolve symlinks if the file exists, else normalise. */
+function canonical(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return resolve(p);
+    }
+}
+/** Expand a leading `~` (or `~/`) to the home directory. */
+function expandTilde(p) {
+    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) {
+    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) {
+    let text;
+    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)));
+}
+/**
+ * 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) {
+    const candidates = [];
+    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 = [];
+    const missing = [];
+    const seen = new Set();
+    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 };
+}
+function safeId(sessionId) {
+    return (sessionId || 'nosession').replace(/[^A-Za-z0-9_.-]/g, '_');
+}
+function statePath(sessionId) {
+    return join(stateDir(), `${safeId(sessionId)}.json`);
+}
+function loadState(sessionId) {
+    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, state) {
+    mkdirSync(stateDir(), { recursive: true });
+    writeFileSync(statePath(sessionId), JSON.stringify(state));
+}
+function resetState(sessionId) {
+    try {
+        unlinkSync(statePath(sessionId));
+    }
+    catch {
+        /* nothing to reset */
+    }
+}
+/** Delete session-state files older than 7 days. */
+function prune() {
+    let files;
+    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 */
+        }
+    }
+}
+/**
+ * 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, cwd, toolName) {
+    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 };
+}
+/**
+ * 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, cwd, filePath, partial = false) {
+    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, cwd, source) {
+    prune();
+    if (source === 'startup' || source === 'clear')
+        resetState(sessionId);
+    const { present, missing } = requiredFiles(cwd);
+    const lines = [];
+    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, sessionId) {
+    const { present, missing } = requiredFiles(cwd);
+    const lines = [];
+    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) {
+    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/dist/index.cjs

@@ -23050,8 +23050,10 @@ function registerClaudeMdPrompt(server) {
                 "",
                 "Reconcile the existing CLAUDE.md against three things, and propose a concrete diff:",
                 "1. **Framework drift** \u2014 does it teach superseded ways (e.g. `drizzle-kit generate`,",
-                '   hand-written migrations, "pass your Drizzle schema") instead of the v3 Model flow',
-                "   (`defineModel` \u2192 `everystack db:generate`)? Suggest the current conventions.",
+                '   hand-written migrations, a migration journal, "pass your Drizzle schema") instead of',
+                "   the migration-authority flow (`defineModel` in db/models/ \u2192 `everystack db:sync` on",
+                "   dev; `db:plan` \u2192 `db:apply` on protected stages; `db:check` in CI; data moves in",
+                "   db/backfills/ via `db:backfill`)? Suggest the current conventions.",
                 "2. **Project drift** \u2014 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",
@@ -23399,7 +23401,7 @@ function renderFinding(f) {
 // src/gates/detectors/hand-written-migration.ts
 var import_path2 = require("path");
 var MIGRATION_SQL = /(?:^|\/)(?:drizzle|migrations)\/[^/]+\.sql$/i;
-var GENERATED_SCHEMA = /(?:^|\/)(?:db|drizzle)\/schema\.ts$/;
+var GENERATED_SCHEMA = /schema\.generated\.tsx?$/;
 function rel(ctx, p) {
   try {
     return (0, import_path2.relative)(ctx.cwd, p) || p;
@@ -23411,15 +23413,15 @@ var handWrittenMigration = {
   id: "hand-written-migration",
   tier: "framework",
   severity: "deny",
-  guide: "Schema and migrations are generated from your Models \u2014 edit the Model and run db:generate, never hand-write SQL migrations or edit the generated schema.",
-  conform: "everystack db:generate",
-  verify: "everystack db:generate produces no diff (a clean no-op)",
+  guide: "Nobody authors migrations. Schema changes have three homes: tables/constraints/authz are declared in db/models/ (edit the Model, then `everystack db:sync` on dev \u2014 protected stages take `db:plan` \u2192 `db:apply`); functions/views/matviews are authored in db/sql/ (deployed by db:reconcile/db:sync); one-shot DATA moves are authored in db/backfills/*.sql (run via db:backfill, never as a schema side effect). No migration file, ever \u2014 and generated artifacts (schema.generated.ts) are never edited.",
+  conform: "edit db/models/ then `everystack db:sync` (dev) or `db:plan` \u2192 `db:apply` (protected) \xB7 db/sql/ for derived objects \xB7 db/backfills/ for data moves",
+  verify: "everystack db:check passes (declared state composes; generated artifacts match regeneration) AND everystack db:fingerprint reports MATCH",
   detect(ctx) {
     if (ctx.tool !== "Write" && ctx.tool !== "Edit") return null;
     const p = ctx.filePath;
     if (!p) return null;
     if (MIGRATION_SQL.test(p)) return `${rel(ctx, p)} is a SQL migration being written by hand`;
-    if (GENERATED_SCHEMA.test(p)) return `${rel(ctx, p)} is generated from your Models`;
+    if (GENERATED_SCHEMA.test(p)) return `${rel(ctx, p)} is a generated artifact (compiled from your Models \u2014 db:check refuses hand edits)`;
     return null;
   }
 };
@@ -23705,7 +23707,7 @@ async function runGovernanceCli(argv) {
 }
 
 // src/index.ts
-var version2 = (true ? "0.3.1" : null) ?? "0.3.0-dev";
+var version2 = (true ? "0.3.3" : null) ?? "0.3.0-dev";
 var INSTRUCTIONS = [
   "You govern how any agent builds everystack \u2014 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",
@@ -23767,7 +23769,7 @@ var INSTRUCTIONS = [
   "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 \u2014 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_*`.",
+  '4. Data lives in PostgreSQL via Models/Modules and is served through the API \u2014 never bundle large computed data into the app. NOBODY AUTHORS MIGRATIONS. Schema work has three homes: tables/constraints/authz are DECLARED in `db/models/` (edit the Model, then `everystack db:sync` moves the dev database to the checkout \u2014 verified by fingerprint); functions/views/matviews are authored in `db/sql/` (deployed by `db:reconcile`/`db:sync`); one-shot DATA moves are authored in `db/backfills/*.sql` (run via `db:backfill`, never as a schema side effect). Protected stages never take a sync: `db:plan` mints a reviewable, fingerprint-pinned edge and `db:apply` verifies at both ends \u2014 the checkout must descend from the commit declaring the target\'s state ("rebase first"), and destructive plans are confirmed, snapshotted, and approver-gated (`db:approvers`). CI runs `everystack db:check` (the merged declared state must compose; generated artifacts must match regeneration byte-for-byte). Per-branch dev databases: `db:template:refresh` + `db:branch`; deployed feature stages fork data with `db:fork`. 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");