@ghl-ai/aw 0.1.37-beta.9 → 0.1.37

package/cli.mjs

@@ -15,6 +15,7 @@ const COMMANDS = {
   init:   () => import('./commands/init.mjs').then(m => m.initCommand),
   pull:    () => import('./commands/pull.mjs').then(m => m.pullCommand),
   push:    () => import('./commands/push.mjs').then(m => m.pushCommand),
+  'push-rules': () => import('./commands/push-rules.mjs').then(m => m.pushRulesCommand),
   drop:    () => import('./commands/drop.mjs').then(m => m.dropCommand),
   status:  () => import('./commands/status.mjs').then(m => m.statusCommand),
   search:  () => import('./commands/search.mjs').then(m => m.searchCommand),
@@ -88,6 +89,7 @@ function printHelp() {
     sec('Upload'),
     cmd('aw push', 'Push all modified files (creates one PR)'),
     cmd('aw push <path>', 'Push file, folder, or namespace to registry'),
+    cmd('aw push-rules [path]', 'Push platform rules to platform-docs'),
     cmd('aw push --dry-run [path]', 'Preview what would be pushed'),
 
     sec('Discover'),
@@ -102,6 +104,8 @@ function printHelp() {
     cmd('aw daemon install --interval 30m', 'Set custom interval (e.g. 30m, 2h, 3600)'),
     cmd('aw daemon uninstall', 'Stop the background daemon'),
     cmd('aw daemon status', 'Check if daemon is running'),
+    cmd('aw slack-sim run <scenario>', 'Replay Slack-like scenarios against real runtime'),
+    cmd('aw slack-sim list-scenarios', 'List built-in Slack simulator scenarios'),
 
     sec('Settings'),
     cmd('aw telemetry status', 'Show telemetry status'),
@@ -122,6 +126,8 @@ function printHelp() {
     cmd('aw push .aw_registry/<team>/', 'Push entire namespace (one PR)'),
     cmd('aw push .aw_registry/agents/<name>.md', 'Push a single agent'),
     cmd('aw push .aw_registry/skills/<name>/', 'Push a single skill folder'),
+    cmd('aw push .aw_rules', 'Auto-redirects to aw push-rules'),
+    cmd('aw push-rules', 'Pushes .aw_rules or .aw_registry/.aw_rules'),
     '',
     `  ${chalk.dim('# Remove content from workspace')}`,
     cmd('aw drop <team>', 'Stop syncing a namespace (removes all files)'),

package/commands/init.mjs

@@ -4,7 +4,17 @@
 // Uses core.hooksPath (git-lfs pattern) for system-wide hook interception.
 // Uses IDE tasks for auto-pull on workspace open.
 
-import { existsSync, writeFileSync, symlinkSync, lstatSync, readdirSync, readFileSync, rmSync, realpathSync, appendFileSync } from 'node:fs';
+import {
+  existsSync,
+  writeFileSync,
+  symlinkSync,
+  lstatSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  realpathSync,
+  appendFileSync,
+} from 'node:fs';
 import { execSync } from 'node:child_process';
 import { join, dirname, sep } from 'node:path';
 import { homedir } from 'node:os';
@@ -15,6 +25,7 @@ import { chalk } from '../fmt.mjs';
 import { linkWorkspace } from '../link.mjs';
 import { generateCommands, copyInstructions, initAwDocs } from '../integrate.mjs';
 import { setupMcp } from '../mcp.mjs';
+import { installLocalCommitHook } from '../hooks.mjs';
 import { autoUpdate, promptUpdate } from '../update.mjs';
 import { installGlobalHooks } from '../hooks.mjs';
 import { installAwEcc } from '../ecc.mjs';
@@ -31,7 +42,8 @@ import {
   syncWorktreeSparseCheckout,
   findNearestWorktree,
 } from '../git.mjs';
-import { REGISTRY_DIR, REGISTRY_REPO, REGISTRY_URL } from '../constants.mjs';
+import { REGISTRY_DIR, REGISTRY_REPO, REGISTRY_URL, RULES_SOURCE_DIR } from '../constants.mjs';
+import { syncFileTree } from '../file-tree.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const VERSION = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf8')).version;
@@ -195,7 +207,7 @@ export async function initCommand(args) {
     }
 
     if (choice === 'platform-only') {
-      namespace = null; team = null; subTeam = null; folderName = null;
+      namespace = 'platform'; team = 'platform'; subTeam = null; folderName = null;
     }
   }
 
@@ -210,7 +222,7 @@ export async function initCommand(args) {
     const isNewSubTeam = folderName && cfg && !cfg.include.includes(folderName);
     if (isNewSubTeam) {
       if (!silent) fmt.logStep(`Adding sub-team ${chalk.cyan(folderName)}...`);
-      const newSparsePaths = [`.aw_registry/${folderName}`, `content`];
+      const newSparsePaths = [`.aw_registry/${folderName}`, 'content', RULES_SOURCE_DIR];
       addToSparseCheckout(AW_HOME, newSparsePaths);
       config.addPattern(GLOBAL_AW_DIR, folderName);
     } else {
@@ -235,6 +247,9 @@ export async function initCommand(args) {
 
     ensureAwGitignore(AW_HOME);
     const freshCfg = config.load(GLOBAL_AW_DIR);
+    if (existsSync(GLOBAL_AW_DIR)) {
+      syncFileTree(join(AW_HOME, RULES_SOURCE_DIR), join(GLOBAL_AW_DIR, RULES_SOURCE_DIR));
+    }
 
     // Ensure project worktree sparse checkout matches the global clone.
     // Covers the case where a namespace was added from HOME (or another project)
@@ -279,6 +294,7 @@ export async function initCommand(args) {
     const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
     const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
     const commands = generateCommands(HOME, { silent: true });
+    if (cwd !== HOME) installLocalCommitHook(cwd);
 
     if (silent) {
       autoUpdate(await args._updateCheck);
@@ -317,7 +333,7 @@ export async function initCommand(args) {
   }
 
   // Determine sparse paths
-  const sparsePaths = [`.aw_registry/platform`, `content`, `.aw_registry/AW-PROTOCOL.md`, `CODEOWNERS`];
+  const sparsePaths = [`.aw_registry/platform`, `content`, RULES_SOURCE_DIR, `.aw_registry/AW-PROTOCOL.md`, `CODEOWNERS`];
   if (folderName) {
     sparsePaths.push(`.aw_registry/${folderName}`);
   }
@@ -363,11 +379,14 @@ export async function initCommand(args) {
     }
   }
 
-  // Create sync config
-  const cfg = config.create(GLOBAL_AW_DIR, { namespace: team, user });
+  // Create sync config — default to 'platform' when no namespace specified
+  const cfg = config.create(GLOBAL_AW_DIR, { namespace: team || 'platform', user });
   if (folderName) {
     config.addPattern(GLOBAL_AW_DIR, folderName);
   }
+  if (existsSync(GLOBAL_AW_DIR)) {
+    syncFileTree(join(AW_HOME, RULES_SOURCE_DIR), join(GLOBAL_AW_DIR, RULES_SOURCE_DIR));
+  }
 
   // Step 3: Setup tasks, MCP, hooks
   await installAwEcc(cwd, { silent });
@@ -406,6 +425,7 @@ export async function initCommand(args) {
   const projectRegistryDir = cwd !== HOME ? join(cwd, '.aw', REGISTRY_DIR) : null;
   const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
   const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
+  if (cwd !== HOME) installLocalCommitHook(cwd);
   ideSpinner.message('Generating commands...');
   const commands = generateCommands(HOME, { silent: true });
   ideSpinner.stop(`IDE wired — ${chalk.bold(symlinks)} symlinks · ${chalk.bold(commands)} commands`);

package/commands/link-project.mjs

@@ -9,6 +9,7 @@ import { addProjectWorktree, isWorktree, isValidClone } from '../git.mjs';
 import { REGISTRY_DIR, REGISTRY_URL } from '../constants.mjs';
 import { linkWorkspace } from '../link.mjs';
 import { generateCommands } from '../integrate.mjs';
+import { installLocalCommitHook } from '../hooks.mjs';
 
 const HOME = homedir();
 const AW_HOME = join(HOME, '.aw');
@@ -40,6 +41,7 @@ export function linkProjectCommand(args) {
     const awDirForLinks = existsSync(projectRegistryDir) ? projectRegistryDir : null;
     const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
     const commands = generateCommands(HOME, { silent: true });
+    installLocalCommitHook(cwd);
     fmt.logSuccess(`Already linked — refreshed ${chalk.bold(symlinks)} IDE symlinks · ${chalk.bold(commands)} commands`);
     return;
   }
@@ -50,6 +52,7 @@ export function linkProjectCommand(args) {
     const awDirForLinks = existsSync(projectRegistryDir) ? projectRegistryDir : null;
     const symlinks = linkWorkspace(HOME, awDirForLinks, { silent: true });
     const commands = generateCommands(HOME, { silent: true });
+    installLocalCommitHook(cwd);
     fmt.logSuccess([
       `Project linked — ${chalk.bold(symlinks)} IDE symlinks · ${chalk.bold(commands)} commands`,
       '',

package/commands/nuke.mjs

@@ -143,19 +143,24 @@ async function removeProjectSymlinks() {
   }
 
   // Also remove legacy local .git/hooks/post-checkout installed by old aw versions
+  // and prepare-commit-msg hooks installed by installLocalCommitHook
   let hooksRemoved = 0;
-  const { stdout: hookFiles } = await exec(
-    `find "${HOME}" -maxdepth 5 -path "*/.git/hooks/post-checkout" -type f 2>/dev/null || true`,
-    { encoding: 'utf8', timeout: 30000 }
-  );
-  for (const hookPath of hookFiles.trim().split('\n').filter(Boolean)) {
-    try {
-      const content = readFileSync(hookPath, 'utf8');
-      if (content.includes('aw: auto-link registry') || content.includes('ln -s "$AW_REGISTRY"')) {
-        unlinkSync(hookPath);
-        hooksRemoved++;
-      }
-    } catch { /* best effort */ }
+  const hookNames = ['post-checkout', 'prepare-commit-msg'];
+  for (const hookName of hookNames) {
+    const { stdout: hookFiles } = await exec(
+      `find "${HOME}" -maxdepth 5 -path "*/.git/hooks/${hookName}" -type f 2>/dev/null || true`,
+      { encoding: 'utf8', timeout: 30000 }
+    );
+    for (const hookPath of hookFiles.trim().split('\n').filter(Boolean)) {
+      try {
+        const content = readFileSync(hookPath, 'utf8');
+        // Only remove hooks that AW installed — identified by our marker comment
+        if (content.includes('aw:') || content.includes('aw: auto-link registry') || content.includes('ln -s "$AW_REGISTRY"')) {
+          unlinkSync(hookPath);
+          hooksRemoved++;
+        }
+      } catch { /* best effort */ }
+    }
   }
 
   return { removed, hooksRemoved };

package/commands/pull.mjs

@@ -1,17 +1,34 @@
 // commands/pull.mjs — Pull content from registry using persistent git clone
 
-import { existsSync, lstatSync } from 'node:fs';
+import {
+  existsSync,
+  lstatSync,
+} from 'node:fs';
 import { join, extname } from 'node:path';
 import { homedir } from 'node:os';
-import { exec as execCb } from 'node:child_process';
+import { exec as execCb, execSync } from 'node:child_process';
 import { promisify } from 'node:util';
 
 const exec = promisify(execCb);
 import * as config from '../config.mjs';
 import * as fmt from '../fmt.mjs';
 import { chalk } from '../fmt.mjs';
-import { fetchAndMerge, addToSparseCheckout, removeFromSparseCheckout, syncWorktreeSparseCheckout, isValidClone, findNearestWorktree, rebaseOntoOriginMain } from '../git.mjs';
-import { REGISTRY_DIR, REGISTRY_REPO, REGISTRY_URL } from '../constants.mjs';
+import {
+  fetchAndMerge,
+  addToSparseCheckout,
+  removeFromSparseCheckout,
+  syncWorktreeSparseCheckout,
+  isValidClone,
+  findNearestWorktree,
+  rebaseOntoOriginMain,
+} from '../git.mjs';
+import {
+  REGISTRY_DIR,
+  REGISTRY_URL,
+  DOCS_SOURCE_DIR,
+  RULES_SOURCE_DIR,
+} from '../constants.mjs';
+import { collectAllPaths, syncFileTree } from '../file-tree.mjs';
 import { linkWorkspace } from '../link.mjs';
 import { generateCommands, copyInstructions } from '../integrate.mjs';
 
@@ -52,6 +69,15 @@ export async function pullCommand(args) {
     return;
   }
 
+  // Ensure platform pulls also fetch docs and rules on older installs that
+  // pre-date the new sparse-checkout paths.
+  if (input === 'platform') {
+    addToSparseCheckout(AW_HOME, [`.aw_registry/platform`, DOCS_SOURCE_DIR, RULES_SOURCE_DIR]);
+    if (!cfg.include.includes('platform')) {
+      config.addPattern(GLOBAL_AW_DIR, 'platform');
+    }
+  }
+
   // If input is a new namespace to add
   let addedInput = null;
   let addedSparsePath = null;
@@ -64,7 +90,7 @@ export async function pullCommand(args) {
     const label = input.split('/').pop();
     if (!cfg.include.includes(input)) {
       log.logStep(`Adding ${chalk.cyan(label)} to sparse checkout...`);
-      addToSparseCheckout(AW_HOME, [sparsePath, 'content']);
+      addToSparseCheckout(AW_HOME, [sparsePath, DOCS_SOURCE_DIR]);
       config.addPattern(GLOBAL_AW_DIR, input);
       addedInput = input;
       addedSparsePath = sparsePath;
@@ -79,33 +105,33 @@ export async function pullCommand(args) {
   const rebaseInProgress = existsSync(join(awGitDir, 'rebase-merge')) || existsSync(join(awGitDir, 'rebase-apply'));
   const mergeInProgress = existsSync(join(awGitDir, 'MERGE_HEAD'));
   if (rebaseInProgress || mergeInProgress) {
-    // Check for still-unresolved files (conflict markers present in index)
     let unresolved = [];
     try {
       const { stdout } = await exec(`git -C "${AW_HOME}" diff --name-only --diff-filter=U`);
       unresolved = stdout.trim().split('\n').filter(Boolean);
-    } catch { /* best effort */ }
+    } catch {
+      // best effort
+    }
 
     if (unresolved.length > 0) {
-      // Still has conflicts — user needs to finish resolving
-      log.logWarn(`Rebase paused — resolve conflicts in your IDE, then run \`aw pull\` again.`);
+      log.logWarn('Rebase paused — resolve conflicts in your IDE, then run `aw pull` again.');
       if (!silent) fmt.outro(chalk.yellow('Pull skipped'));
       return;
     }
 
-    // All conflicts resolved (files are staged) — continue the rebase automatically
     try {
       await exec(`git -C "${AW_HOME}" rebase --continue`, { env: { ...process.env, GIT_EDITOR: 'true' } });
       log.logStep('Rebase continued after conflict resolution.');
-      // Force-push if on a push branch so origin stays in sync
       const { stdout: branchOut } = await exec(`git -C "${AW_HOME}" rev-parse --abbrev-ref HEAD`);
       const resumedBranch = branchOut.trim();
-      if (['upload/', 'remove/', 'sync/'].some(p => resumedBranch.startsWith(p))) {
-        try { await exec(`git -C "${AW_HOME}" push --force-with-lease origin "${resumedBranch}"`); } catch { /* non-blocking */ }
+      if (['upload/', 'remove/', 'sync/'].some(prefix => resumedBranch.startsWith(prefix))) {
+        try {
+          await exec(`git -C "${AW_HOME}" push --force-with-lease origin "${resumedBranch}"`);
+        } catch {
+          // non-blocking
+        }
       }
     } catch {
-      // Could happen if there are more conflicting commits in the rebase sequence,
-      // or if the resolved changes result in an empty commit (skip it).
       try {
         await exec(`git -C "${AW_HOME}" rebase --skip`);
         log.logStep('Empty commit skipped during rebase continuation.');
@@ -115,10 +141,8 @@ export async function pullCommand(args) {
         return;
       }
     }
-    // Fall through to re-link IDE dirs after successful rebase continuation
   }
 
-  // Fetch + merge latest
   const s = log.spinner();
   s.start('Fetching latest from registry...');
   let fetchResult = { updated: false, conflicts: [] };
@@ -130,16 +154,15 @@ export async function pullCommand(args) {
     if (!silent) log.logWarn(`Fetch error: ${e.message}`);
   }
 
-  // Validate that the requested path actually exists in the registry after fetch.
-  // If not, undo the sparse checkout addition and inform the user.
   if (addedInput) {
     const localPath = join(AW_HOME, REGISTRY_DIR, addedInput);
     if (!existsSync(localPath)) {
-      // Undo: remove from sparse checkout and config
       try {
         removeFromSparseCheckout(AW_HOME, [addedSparsePath]);
         config.removePattern(GLOBAL_AW_DIR, addedInput);
-      } catch { /* best effort */ }
+      } catch {
+        // best effort
+      }
       log.cancel(`Path ${chalk.red(addedInput)} not found in the registry.\nCheck the exact path with ${chalk.bold('aw search <query>')} or browse ${chalk.dim('~/.aw_registry/')}.`);
       return;
     }
@@ -147,23 +170,31 @@ export async function pullCommand(args) {
 
   if (fetchResult.conflicts.length > 0) {
     if (!silent) {
-      // Interactive mode: rebase is paused with conflict markers in the working tree.
-      // Leave it for the user to resolve in their IDE, then re-run `aw pull`.
       log.logWarn(`Merge conflict in: ${fetchResult.conflicts.join(', ')}`);
       log.logWarn('Merge aborted — your branch is unchanged. Resolve conflicts and run `aw pull` again.');
       return;
     }
-    // Silent mode: rebase was already aborted in fetchAndMerge; just report.
     log.logWarn(`Conflicts in: ${fetchResult.conflicts.join(', ')}`);
   }
 
+  const rulesSrc = join(AW_HOME, RULES_SOURCE_DIR);
+  if (existsSync(rulesSrc)) {
+    const rulesDest = join(GLOBAL_AW_DIR, RULES_SOURCE_DIR);
+    syncFileTree(rulesSrc, rulesDest);
+    if (!silent) log.logSuccess('Synced .aw_rules');
+  }
+
   // Rebase project worktree branch onto origin/main — only for legacy git worktrees.
   // In the symlink model, <project>/.aw IS ~/.aw (same repo), so fetchAndMerge already
   // brought it up to date. Nothing to rebase.
   const localAw = cwd !== HOME ? findNearestWorktree(cwd, HOME) : null;
   let isSymlinkWorktree = false;
   if (localAw) {
-    try { isSymlinkWorktree = lstatSync(localAw).isSymbolicLink(); } catch {}
+    try {
+      isSymlinkWorktree = lstatSync(localAw).isSymbolicLink();
+    } catch {
+      // ignore
+    }
   }
   if (localAw && !isSymlinkWorktree) {
     const rebaseSpinner = log.spinner();
@@ -173,7 +204,9 @@ export async function pullCommand(args) {
       rebaseSpinner.stop('Local branch up to date');
     } catch (e) {
       const isConflict = e.message?.includes('could not apply') || e.message?.includes('CONFLICT');
-      const isAlreadyInProgress = e.message?.includes('rebase-merge') || e.message?.includes('rebase-apply') || e.message?.includes('already in progress');
+      const isAlreadyInProgress = e.message?.includes('rebase-merge')
+        || e.message?.includes('rebase-apply')
+        || e.message?.includes('already in progress');
 
       if (isAlreadyInProgress) {
         rebaseSpinner.stop(chalk.yellow('Rebase paused — conflicts pending'));
@@ -184,26 +217,31 @@ export async function pullCommand(args) {
         try {
           const { stdout } = await exec(`git -C "${localAw}" diff --name-only --diff-filter=U`);
           conflictedFiles = stdout.trim().split('\n').filter(Boolean);
-        } catch { /* best effort */ }
+        } catch {
+          // best effort
+        }
 
         if (!silent) {
-          try { await exec(`git -C "${localAw}" rebase --abort`); } catch { /* best effort */ }
+          try {
+            await exec(`git -C "${localAw}" rebase --abort`);
+          } catch {
+            // best effort
+          }
           log.logWarn('Rebase aborted — your branch is unchanged.');
           if (conflictedFiles.length > 0) {
             log.logWarn(`Conflicting file${conflictedFiles.length > 1 ? 's' : ''}:`);
-            for (const f of conflictedFiles) log.logMessage(`  ${chalk.red('✗')} ${f}`);
+            for (const file of conflictedFiles) log.logMessage(`  ${chalk.red('✗')} ${file}`);
           }
           log.logWarn('Resolve the conflict and run `aw pull` again, or check with `aw status`.');
         }
       } else {
-        const msg = e.message?.split('\n').find(l => l.trim()) ?? e.message;
+        const msg = e.message?.split('\n').find(line => line.trim()) ?? e.message;
         rebaseSpinner.stop(chalk.dim('Rebase skipped'));
         if (!silent) log.logWarn(`Rebase skipped: ${msg}`);
       }
     }
   }
 
-  // Re-link IDE dirs
   if (!args._skipIntegrate) {
     const projectRegistryDir = cwd !== HOME ? join(cwd, '.aw', REGISTRY_DIR) : null;
     const awDirForLinks = (projectRegistryDir && existsSync(projectRegistryDir)) ? projectRegistryDir : null;
@@ -237,6 +275,10 @@ export async function pullAsync(args) {
   return { pattern: args._positional?.[0] || '', actions: [], conflictCount: 0 };
 }
 
+export const __test__ = {
+  collectAllPaths,
+  syncFileTree,
+};
 
 function registerMcp(namespace) {
   const mcpUrl = process.env.GHL_MCP_URL;

package/commands/push-rules.mjs

@@ -0,0 +1,212 @@
+import { existsSync, mkdtempSync, statSync } from 'node:fs';
+import { execFileSync, execSync } from 'node:child_process';
+import { join, normalize, relative } from 'node:path';
+import { tmpdir } from 'node:os';
+
+import * as fmt from '../fmt.mjs';
+import { chalk } from '../fmt.mjs';
+import { REGISTRY_BASE_BRANCH, REGISTRY_REPO, RULES_SOURCE_DIR, AW_CO_AUTHOR } from '../constants.mjs';
+import { syncFileTree } from '../file-tree.mjs';
+
+function normalizeSlashes(path) {
+  return path.replace(/\\/g, '/');
+}
+
+export function isRulesPushInput(input) {
+  if (!input) return false;
+  const normalized = normalizeSlashes(input).replace(/\/+$/, '');
+  return normalized === RULES_SOURCE_DIR
+    || normalized.startsWith(`${RULES_SOURCE_DIR}/`)
+    || normalized === `.aw_registry/${RULES_SOURCE_DIR}`
+    || normalized.startsWith(`.aw_registry/${RULES_SOURCE_DIR}/`);
+}
+
+export function resolveRulesPushSource(input, cwd = process.cwd()) {
+  const localRulesRoot = join(cwd, RULES_SOURCE_DIR);
+  const syncedRulesRoot = join(cwd, '.aw_registry', RULES_SOURCE_DIR);
+
+  if (!input) {
+    if (existsSync(localRulesRoot)) return { sourceRoot: localRulesRoot, sourceType: 'local' };
+    if (existsSync(syncedRulesRoot)) return { sourceRoot: syncedRulesRoot, sourceType: 'synced' };
+    return null;
+  }
+
+  const normalizedInput = normalizeSlashes(input).replace(/\/+$/, '');
+
+  if (normalizedInput === RULES_SOURCE_DIR || normalizedInput.startsWith(`${RULES_SOURCE_DIR}/`)) {
+    if (!existsSync(localRulesRoot)) return null;
+    return { sourceRoot: localRulesRoot, sourceType: 'local' };
+  }
+
+  if (normalizedInput === `.aw_registry/${RULES_SOURCE_DIR}` || normalizedInput.startsWith(`.aw_registry/${RULES_SOURCE_DIR}/`)) {
+    if (!existsSync(syncedRulesRoot)) return null;
+
+    const relativeRulesPath = normalizedInput.slice(`.aw_registry/${RULES_SOURCE_DIR}`.length).replace(/^\/+/, '');
+    const localOverridePath = relativeRulesPath ? join(localRulesRoot, relativeRulesPath) : localRulesRoot;
+    if (existsSync(localOverridePath)) {
+      return { sourceRoot: localRulesRoot, sourceType: 'local' };
+    }
+
+    return { sourceRoot: syncedRulesRoot, sourceType: 'synced' };
+  }
+
+  return null;
+}
+
+export function hasRulesChanges(cwd = process.cwd()) {
+  const candidateDirs = [RULES_SOURCE_DIR, `.aw_registry/${RULES_SOURCE_DIR}`]
+    .filter(rel => existsSync(join(cwd, rel)));
+
+  if (candidateDirs.length === 0) return false;
+
+  try {
+    const output = execSync(
+      `git status --short --untracked-files=all -- ${candidateDirs.map(dir => `"${dir}"`).join(' ')}`,
+      { cwd, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }
+    ).trim();
+    return output.length > 0;
+  } catch {
+    return false;
+  }
+}
+
+export function buildRulesPushFile(input, cwd = process.cwd()) {
+  const resolved = resolveRulesPushSource(input, cwd);
+  if (!resolved) return null;
+
+  return {
+    absPath: resolved.sourceRoot,
+    registryTarget: RULES_SOURCE_DIR,
+    type: 'rules',
+    namespace: 'platform',
+    slug: 'rules',
+    isDir: true,
+  };
+}
+
+function buildRulesPrTitle(sourceRoot, cwd) {
+  const rel = normalizeSlashes(relative(cwd, sourceRoot));
+  return rel === RULES_SOURCE_DIR
+    ? 'sync: update platform rules'
+    : `sync: update platform rules from ${rel}`;
+}
+
+function buildRulesPrBody(sourceRoot, sourceType, cwd) {
+  const rel = normalizeSlashes(relative(cwd, sourceRoot)) || RULES_SOURCE_DIR;
+  return [
+    '## Platform Rules Sync',
+    '',
+    `- **Source:** \`${rel}\``,
+    `- **Mode:** ${sourceType === 'local' ? 'canonical local rules' : 'synced rules copy'}`,
+    '',
+    'Uploaded via `aw push-rules`',
+  ].join('\n');
+}
+
+function pushRulesTree(sourceRoot, { repo, dryRun, cwd }) {
+  if (!existsSync(sourceRoot) || !statSync(sourceRoot).isDirectory()) {
+    fmt.cancel(`Rules path not found: ${sourceRoot}`);
+  }
+
+  if (dryRun) {
+    fmt.logInfo(`Would push rules from ${chalk.cyan(normalizeSlashes(relative(cwd, sourceRoot)) || RULES_SOURCE_DIR)}`);
+    fmt.logWarn('No changes made (--dry-run)');
+    fmt.outro(chalk.dim('Remove --dry-run to push'));
+    return;
+  }
+
+  const s = fmt.spinner();
+  s.start('Cloning registry...');
+
+  const tempDir = mkdtempSync(join(tmpdir(), 'aw-push-rules-'));
+
+  try {
+    const repoUrl = repo.startsWith('http') ? repo : `https://github.com/${repo}.git`;
+    execSync(`git clone --filter=blob:none --no-checkout "${repoUrl}" "${tempDir}"`, { stdio: 'pipe' });
+    execSync(`git checkout ${REGISTRY_BASE_BRANCH}`, { cwd: tempDir, stdio: 'pipe' });
+    s.stop('Repository cloned');
+
+    const branch = `sync/rules-${Date.now().toString(36).slice(-5)}`;
+    execSync(`git checkout -b ${branch}`, { cwd: tempDir, stdio: 'pipe' });
+
+    const s2 = fmt.spinner();
+    s2.start('Copying platform rules...');
+
+    syncFileTree(sourceRoot, join(tempDir, RULES_SOURCE_DIR));
+    execSync(`git add -A "${RULES_SOURCE_DIR}"`, { cwd: tempDir, stdio: 'pipe' });
+
+    const diffStatus = execSync('git diff --cached --name-only', { cwd: tempDir, encoding: 'utf8' }).trim();
+    if (!diffStatus) {
+      s2.stop('No changes');
+      fmt.cancel('Nothing to push — remote rules already match local content.');
+    }
+
+    const sourceType = normalize(sourceRoot).includes(normalize(join('.aw_registry', RULES_SOURCE_DIR)))
+      ? 'synced'
+      : 'local';
+    const prTitle = buildRulesPrTitle(sourceRoot, cwd);
+    const prBody = buildRulesPrBody(sourceRoot, sourceType, cwd);
+
+    execSync(`git commit -m "registry: sync platform rules\n\n${AW_CO_AUTHOR}"`, { cwd: tempDir, stdio: 'pipe' });
+    s2.stop('Rules sync prepared');
+
+    const s3 = fmt.spinner();
+    s3.start('Pushing and creating PR...');
+
+    execSync(`git push -u origin ${branch}`, { cwd: tempDir, stdio: 'pipe' });
+
+    let prUrl;
+    try {
+      prUrl = execFileSync('gh', [
+        'pr', 'create',
+        '--base', REGISTRY_BASE_BRANCH,
+        '--title', prTitle,
+        '--body', prBody,
+      ], { cwd: tempDir, encoding: 'utf8' }).trim();
+    } catch {
+      const repoBase = repo.replace(/\.git$/, '');
+      prUrl = `https://github.com/${repoBase}/compare/${REGISTRY_BASE_BRANCH}...${branch}?expand=1`;
+    }
+
+    s3.stop('Branch pushed');
+    fmt.logSuccess(`PR: ${chalk.cyan(prUrl)}`);
+    fmt.outro('Rules push complete');
+  } catch (e) {
+    fmt.cancel(`Rules push failed: ${e.message}`);
+  } finally {
+    execSync(`rm -rf "${tempDir}"`, { stdio: 'pipe' });
+  }
+}
+
+export function pushRulesCommand(args) {
+  const input = args._positional?.[0];
+  const dryRun = args['--dry-run'] === true;
+  const repo = args['--repo'] || REGISTRY_REPO;
+  const cwd = process.cwd();
+
+  fmt.intro('aw push-rules');
+
+  const resolved = resolveRulesPushSource(input, cwd);
+  if (!resolved) {
+    fmt.cancel([
+      'Could not find a rules source to push.',
+      '',
+      `  Checked ${chalk.cyan('.aw_rules/')} and ${chalk.cyan('.aw_registry/.aw_rules/')}.`,
+      '',
+      '  Use `aw pull platform` first or create a local `.aw_rules/` authoring tree.',
+    ].join('\n'));
+  }
+
+  if (resolved.sourceType === 'synced') {
+    fmt.logWarn('Pushing from synced `.aw_registry/.aw_rules/`. Local `.aw_rules/` is safer for authoring.');
+  }
+
+  pushRulesTree(resolved.sourceRoot, { repo, dryRun, cwd });
+}
+
+export const __test__ = {
+  buildRulesPushFile,
+  isRulesPushInput,
+  resolveRulesPushSource,
+  hasRulesChanges,
+};