Fix agent surface sync boundaries

Signed-off-by: jmclaughlin724 <31931302+jmclaughlin724@users.noreply.github.com>

Author: jmclaughlin724

.agents/prompts/supaschema-install.md

@@ -38,7 +38,7 @@ Use the matching local runner for every command after install:
 | Yarn | `yarn exec supaschema <cmd>` |
 | Bun | `bunx --no-install supaschema <cmd>` |
 
-Always run the matching explicit setup command from the owning package directory after install. The command is idempotent; it leaves existing config intact and refreshes the managed agent surfaces. `supaschema init` combines the consuming repo's detected package manager, workspace owner, provider markers, schema paths, and migration paths with the packaged supaschema rule, skill, hook, config, and prompt bundle.
+Always run the matching explicit setup command from the owning package directory after install. The command is idempotent; it leaves existing config intact, preserves existing hook entries, appends missing supaschema hook entries at the end of the relevant event array, and refreshes the managed agent surfaces. `supaschema init` combines the consuming repo's detected package manager, workspace owner, provider markers, schema paths, and migration paths with the packaged supaschema rule, skill, hook, config, and prompt bundle.
 
 ```bash
 npm exec -- supaschema init

.agents/skills/supaschema/SKILL.md

@@ -13,7 +13,7 @@ When the bundled PostToolUse hook is wired (`.claude/settings.json` / `.codex/ho
 
 ## Installed Setup
 
-The normal consumer setup is package install plus one explicit setup command through the consuming project's package manager. Read `.agents/prompts/supaschema-install.md` before installing, initializing, inspecting, or explaining setup. That prompt owns package-manager detection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. Treat `supaschema.config.json`, installed schema/migration directories, Claude/Codex rule and skill files, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addenda as the package-owned setup surface. Run `supaschema init` through the matching local runner from the schema-owning package directory after install; it is idempotent and uses the package scaffold to refresh managed setup surfaces. The package scaffold installs the full supaschema skill directories directly into `.agents/skills/supaschema` and `.claude/skills/supaschema`; it does not invoke `npx skills`.
+The normal consumer setup is package install plus one explicit setup command through the consuming project's package manager. Read `.agents/prompts/supaschema-install.md` before installing, initializing, inspecting, or explaining setup. That prompt owns package-manager detection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. Treat `supaschema.config.json`, installed schema/migration directories, Claude/Codex rule and skill files, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addenda as the package-owned setup surface. Run `supaschema init` through the matching local runner from the schema-owning package directory after install; it is idempotent, preserves existing hook entries, appends missing supaschema hook entries at the end of the relevant event array, and uses the package scaffold to refresh managed setup surfaces. The package scaffold installs the full supaschema skill directories directly into `.agents/skills/supaschema` and `.claude/skills/supaschema`; it does not invoke `npx skills`.
 
 If this skill was installed through `npx skills`, treat it as portable workflow context only. Agent Skills installs `SKILL.md`-based folders into a user-selected skill location; it does not create `supaschema.config.json`, schema/migration directories, passive rule files, hook scripts, or hook registration. To install those project enforcement surfaces, install the npm package with the consuming project's manager from the owning package directory, then run `supaschema init` through the same manager's local runner from that directory. The package scaffold installs the rule and hooks; the `npx skills` lane does not.
 

.claude/rules/supaschema.md

@@ -11,7 +11,7 @@ This rule owns how schema migrations are produced and protected in a repo that u
 ## Rules
 
 - Consumer migration policy must rely on project files, generated hook context, and supaschema command output. Repo-local maintainer tooling such as Code Atlas, cclsp, FastMCP, and context-enforcement hooks is not part of the published consumer install surface.
-- Consumer setup is package install plus one explicit setup command with the consuming project's package manager. The agent install protocol lives at `.agents/prompts/supaschema-install.md`; it owns package-manager selection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. The installed config, schema/migration directories, supaschema consumer rule/skill/hook bundle, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addendum are part of the package setup surface. Maintainer-only Claude/Codex optimization and context-enforcement tooling remains repo-local under Rule 13. `supaschema init` performs consumer setup through the shared scaffolder (`bin/scaffold.mjs`) — config, directories, agent bundle, hook wiring, and pending path-confirmation state when needed. Run it through the matching local runner from the schema-owning package directory after install. It is idempotent: existing JSON config files are left untouched unless explicit repair is requested, JavaScript config files are not loaded or converted, and the managed guidance block is upserted in place.
+- Consumer setup is package install plus one explicit setup command with the consuming project's package manager. The agent install protocol lives at `.agents/prompts/supaschema-install.md`; it owns package-manager selection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. The installed config, schema/migration directories, supaschema consumer rule/skill/hook bundle, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addendum are part of the package setup surface. Maintainer-only Claude/Codex optimization and context-enforcement tooling remains repo-local under Rule 13. `supaschema init` performs consumer setup through the shared scaffolder (`bin/scaffold.mjs`) — config, directories, agent bundle, hook wiring, and pending path-confirmation state when needed. Run it through the matching local runner from the schema-owning package directory after install. It is idempotent: existing JSON config files are left untouched unless explicit repair is requested, JavaScript config files are not loaded or converted, and the managed guidance block is upserted in place. Hook wiring preserves existing entries and appends missing supaschema hook entries at the end of the relevant event array; it only removes the known broken package-owned Claude script entries that passed `${CLAUDE_PROJECT_DIR}` script paths through `args`.
 - Normal resolved installs do not create `.supaschema/`. If `.supaschema/install.json` exists and records `"pathConfirmationNeeded": true`, inspect the detected candidates, ask the user which `schemaPaths`, `sources.to`, and `migrationsDir` to use, and update `supaschema.config.json` before the first diff. Do not generate from the installer's guessed first candidate; `config validate`, `doctor`, and zero-source `diff` block until all three fields are explicit, and the PostToolUse hook must skip auto-diff until all three fields are explicit.
 - `supaschema.config.json` owns four workflow decisions. Schema tree fields are `schemaPaths`, `sources.to`, and `migrationsDir`; `dir:` sources read nested `.sql` files recursively, and install writes `sources.to: "dir:<schemaPaths[0]>"`. Diff baseline fields are `sources.from` and `sources.to`; `sources.from: "auto"` resolves valid `git:HEAD`, then a database URL, then `empty:` for a first migration in a fresh repository. Generated contract fields are `typesFile`, `zodFile`, `workflow.type_generation`, `workflow.zod_generation`, and `workflow.type_usage`; defaults create or refresh TypeScript and Zod outputs after `diff` and tell agents to use generated Zod validators at runtime boundaries. Apply policy fields are `workflow.migration_sync` and `sync.targets`; default `workflow.migration_sync: "auto"` keeps bare `supaschema sync` apply-capable, while `sync.targets.<name>.mode` decides selected targets and remote targets require approval variables. `adapter: "auto"` is provider-neutral and is not a Supabase switch. Provider-specific behavior is expressed through paths, managed schemas, transaction mode, excluded grant roles, sync targets, and explicit verify flags. Generic PostgreSQL installs use `managedSchemas: []` and reuse detected existing database URL environment variable names in `sync.targets` when present; Supabase installs seed the Supabase platform schema list and use the Supabase CLI runner by default.
 - Schema intent changes only in the configured declarative SQL tree (`schemaPaths` in `supaschema.config.json`), such as `database/schemas/**`, `supabase/schemas/**`, `neon/schemas/**`, `aws-postgresql/schemas/**`, `cloud-sql/schemas/**`, `alloydb/schemas/**`, or `azure-postgresql/schemas/**`. Render the migration with `supaschema diff`; do not hand-author migration SQL for changes the tree can express.

.claude/skills/supaschema/SKILL.md

@@ -13,7 +13,7 @@ When the bundled PostToolUse hook is wired (`.claude/settings.json` / `.codex/ho
 
 ## Installed Setup
 
-The normal consumer setup is package install plus one explicit setup command through the consuming project's package manager. Read `.agents/prompts/supaschema-install.md` before installing, initializing, inspecting, or explaining setup. That prompt owns package-manager detection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. Treat `supaschema.config.json`, installed schema/migration directories, Claude/Codex rule and skill files, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addenda as the package-owned setup surface. Run `supaschema init` through the matching local runner from the schema-owning package directory after install; it is idempotent and uses the package scaffold to refresh managed setup surfaces. The package scaffold installs the full supaschema skill directories directly into `.agents/skills/supaschema` and `.claude/skills/supaschema`; it does not invoke `npx skills`.
+The normal consumer setup is package install plus one explicit setup command through the consuming project's package manager. Read `.agents/prompts/supaschema-install.md` before installing, initializing, inspecting, or explaining setup. That prompt owns package-manager detection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. Treat `supaschema.config.json`, installed schema/migration directories, Claude/Codex rule and skill files, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addenda as the package-owned setup surface. Run `supaschema init` through the matching local runner from the schema-owning package directory after install; it is idempotent, preserves existing hook entries, appends missing supaschema hook entries at the end of the relevant event array, and uses the package scaffold to refresh managed setup surfaces. The package scaffold installs the full supaschema skill directories directly into `.agents/skills/supaschema` and `.claude/skills/supaschema`; it does not invoke `npx skills`.
 
 If this skill was installed through `npx skills`, treat it as portable workflow context only. Agent Skills installs `SKILL.md`-based folders into a user-selected skill location; it does not create `supaschema.config.json`, schema/migration directories, passive rule files, hook scripts, or hook registration. To install those project enforcement surfaces, install the npm package with the consuming project's manager from the owning package directory, then run `supaschema init` through the same manager's local runner from that directory. The package scaffold installs the rule and hooks; the `npx skills` lane does not.
 

.codex/hooks.json

@@ -25,6 +25,17 @@
       }
     ],
     "PostToolUse": [
+      {
+        "matcher": "^(Bash|apply_patch|Edit|Write|edit_file)$",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CODEX_PROJECT_DIR:-$PWD}/.codex/hooks/sync-llm-on-claude-surface-change.mjs\"",
+            "timeout": 130,
+            "statusMessage": "Syncing Claude agent surfaces after edits"
+          }
+        ]
+      },
       {
         "matcher": "^(apply_patch|Edit|Write|edit_file)$",
         "hooks": [

.codex/hooks/general-guard.mjs

@@ -4,16 +4,27 @@ import { fileURLToPath } from "node:url";
 
 import { evaluateBashPolicy } from "./guards/bash-policy-checks.mjs";
 
-export function evaluateGeneralGuardHook({ payload = {}, env = process.env } = {}) {
+export function evaluateGeneralGuardHook({
+  payload = {},
+  env = process.env,
+} = {}) {
   if ((payload?.hook_event_name ?? "PreToolUse") !== "PreToolUse") {
     return {};
   }
-  const toolName = String(payload?.tool_name ?? "");
-  if (!["Bash", "exec_command", "functions.exec_command"].includes(toolName)) {
+  if (
+    !["Bash", "exec_command", "functions.exec_command"].includes(
+      String(payload?.tool_name ?? "")
+    )
+  ) {
     return {};
   }
+
   const result = evaluateBashPolicy(payload, env);
-  return result.action === "block" ? deny(result.message) : {};
+  if (result.action !== "block") {
+    return {};
+  }
+
+  return deny(result.message);
 }
 
 function deny(reason) {
@@ -39,10 +50,13 @@ function runtimeErrorResult(error) {
 }
 
 async function main() {
+  let payload = {};
   try {
     const raw = readFileSync(0, "utf8");
-    const payload = raw.trim() ? JSON.parse(raw) : {};
-    process.stdout.write(`${JSON.stringify(evaluateGeneralGuardHook({ payload }))}\n`);
+    payload = raw.trim() ? JSON.parse(raw) : {};
+    process.stdout.write(
+      `${JSON.stringify(evaluateGeneralGuardHook({ payload }))}\n`
+    );
   } catch (error) {
     process.stdout.write(`${JSON.stringify(runtimeErrorResult(error))}\n`);
   }

.codex/rules/supaschema.rules

@@ -15,7 +15,7 @@
 # ## Rules
 #
 # - Consumer migration policy must rely on project files, generated hook context, and supaschema command output. Repo-local maintainer tooling such as Code Atlas, cclsp, FastMCP, and context-enforcement hooks is not part of the published consumer install surface.
-# - Consumer setup is package install plus one explicit setup command with the consuming project's package manager. The agent install protocol lives at `.agents/prompts/supaschema-install.md`; it owns package-manager selection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. The installed config, schema/migration directories, supaschema consumer rule/skill/hook bundle, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addendum are part of the package setup surface. Maintainer-only Claude/Codex optimization and context-enforcement tooling remains repo-local under Rule 13. `supaschema init` performs consumer setup through the shared scaffolder (`bin/scaffold.mjs`) — config, directories, agent bundle, hook wiring, and pending path-confirmation state when needed. Run it through the matching local runner from the schema-owning package directory after install. It is idempotent: existing JSON config files are left untouched unless explicit repair is requested, JavaScript config files are not loaded or converted, and the managed guidance block is upserted in place.
+# - Consumer setup is package install plus one explicit setup command with the consuming project's package manager. The agent install protocol lives at `.agents/prompts/supaschema-install.md`; it owns package-manager selection, workspace targeting, local runner commands, setup commands, and wrong-manager stop conditions. The installed config, schema/migration directories, supaschema consumer rule/skill/hook bundle, hook wiring, and tagged `AGENTS.md` / `CLAUDE.md` addendum are part of the package setup surface. Maintainer-only Claude/Codex optimization and context-enforcement tooling remains repo-local under Rule 13. `supaschema init` performs consumer setup through the shared scaffolder (`bin/scaffold.mjs`) — config, directories, agent bundle, hook wiring, and pending path-confirmation state when needed. Run it through the matching local runner from the schema-owning package directory after install. It is idempotent: existing JSON config files are left untouched unless explicit repair is requested, JavaScript config files are not loaded or converted, and the managed guidance block is upserted in place. Hook wiring preserves existing entries and appends missing supaschema hook entries at the end of the relevant event array; it only removes the known broken package-owned Claude script entries that passed `${CLAUDE_PROJECT_DIR}` script paths through `args`.
 # - Normal resolved installs do not create `.supaschema/`. If `.supaschema/install.json` exists and records `"pathConfirmationNeeded": true`, inspect the detected candidates, ask the user which `schemaPaths`, `sources.to`, and `migrationsDir` to use, and update `supaschema.config.json` before the first diff. Do not generate from the installer's guessed first candidate; `config validate`, `doctor`, and zero-source `diff` block until all three fields are explicit, and the PostToolUse hook must skip auto-diff until all three fields are explicit.
 # - `supaschema.config.json` owns four workflow decisions. Schema tree fields are `schemaPaths`, `sources.to`, and `migrationsDir`; `dir:` sources read nested `.sql` files recursively, and install writes `sources.to: "dir:<schemaPaths[0]>"`. Diff baseline fields are `sources.from` and `sources.to`; `sources.from: "auto"` resolves valid `git:HEAD`, then a database URL, then `empty:` for a first migration in a fresh repository. Generated contract fields are `typesFile`, `zodFile`, `workflow.type_generation`, `workflow.zod_generation`, and `workflow.type_usage`; defaults create or refresh TypeScript and Zod outputs after `diff` and tell agents to use generated Zod validators at runtime boundaries. Apply policy fields are `workflow.migration_sync` and `sync.targets`; default `workflow.migration_sync: "auto"` keeps bare `supaschema sync` apply-capable, while `sync.targets.<name>.mode` decides selected targets and remote targets require approval variables. `adapter: "auto"` is provider-neutral and is not a Supabase switch. Provider-specific behavior is expressed through paths, managed schemas, transaction mode, excluded grant roles, sync targets, and explicit verify flags. Generic PostgreSQL installs use `managedSchemas: []` and reuse detected existing database URL environment variable names in `sync.targets` when present; Supabase installs seed the Supabase platform schema list and use the Supabase CLI runner by default.
 # - Schema intent changes only in the configured declarative SQL tree (`schemaPaths` in `supaschema.config.json`), such as `database/schemas/**`, `supabase/schemas/**`, `neon/schemas/**`, `aws-postgresql/schemas/**`, `cloud-sql/schemas/**`, `alloydb/schemas/**`, or `azure-postgresql/schemas/**`. Render the migration with `supaschema diff`; do not hand-author migration SQL for changes the tree can express.

.gitignore

@@ -36,11 +36,45 @@ services/license-worker/
 scripts/agent-hooks/
 scripts/code-atlas/
 scripts/stripe/
+.agents/*
+!.agents/prompts/
+.agents/prompts/*
+!.agents/prompts/supaschema-install.md
+!.agents/skills/
+.agents/skills/*
+!.agents/skills/supaschema/
+!.agents/skills/supaschema/**
+.claude/*
 .claude/agents/
 .claude/cclsp.json
+!.claude/hooks/
+.claude/hooks/*
+!.claude/hooks/guards/
+.claude/hooks/guards/*
+!.claude/hooks/guards/bash-policy-checks.mjs
+!.claude/hooks/sync-llm-on-claude-surface-change.mjs
+!.claude/rules/
+.claude/rules/*
+!.claude/rules/supaschema.md
 .claude/settings.json
+!.claude/skills/
+.claude/skills/*
+!.claude/skills/supaschema/
+!.claude/skills/supaschema/**
+.codex/*
 .codex/agents/
 .codex/config.toml
+!.codex/hooks.json
+!.codex/hooks/
+.codex/hooks/*
+!.codex/hooks/guards/
+.codex/hooks/guards/*
+!.codex/hooks/guards/bash-policy-checks.mjs
+!.codex/hooks/general-guard.mjs
+!.codex/hooks/sync-llm-on-claude-surface-change.mjs
+!.codex/rules/
+.codex/rules/*
+!.codex/rules/supaschema.rules
 wrangler.toml
 cloudflare/
 pyproject.toml