@ghl-ai/aw 0.1.44-beta.1 → 0.1.44-beta.2

package/c4/slimRouter.mjs

@@ -0,0 +1,472 @@
+/**
+ * c4/slimRouter.mjs — two slim-card variants + per-prompt ECC delegation
+ * + AW_SLIM_ROUTER=0 escape hatch.
+ *
+ * Why two cards: Claude Code Web invokes skills via the Skill tool (`aw:plan`,
+ * colon-separated), Cursor reads the SKILL.md file (`aw-plan`, hyphen-separated).
+ * Card text diverges only on invocation syntax, not policy. Both stay under
+ * SLIM_CARD_HARD_CEILING_BYTES (6144) so they fit in SessionStart inline-context.
+ *
+ * Why ECC delegation per-prompt: the slim card is SessionStart-only. The
+ * per-prompt reminder (UserPromptSubmit on Claude, beforeSubmitPrompt on
+ * Cursor) reuses ECC's existing scripts. Cursor's beforeSubmitPrompt is a
+ * request-rewrite hook that REQUIRES valid JSON output; using ECC's
+ * Node-adapter `before-submit-prompt.sh` is the only correct wiring (the
+ * shared text helper would emit plain text and break Cursor).
+ *
+ * Why an escape hatch: if the slim card breaks something in production,
+ * AW_SLIM_ROUTER=0 falls back to the full ECC SessionStart hook. No card,
+ * no slim-hook script — just the un-modified ECC entry-point.
+ *
+ * Contract: spec.md::§"c4/slimRouter.mjs", §"Slim card content".
+ */
+
+import { mkdirSync, writeFileSync, chmodSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { claudeHooksMerge, jsonMergeWithDedup } from './jsonMerge.mjs';
+
+export const SLIM_CARD_HARD_CEILING_BYTES = 6144;
+
+export const REQUIRED_ENFORCEMENT_PHRASES = [
+  'Naming a route is not invoking it.',
+  'BEFORE any other',
+  'routing miss',
+];
+
+export const REQUIRED_STAGE_MARKERS_CLAUDE = [
+  'aw:review',
+  'aw:plan',
+  'aw:build',
+  'Hard Gate',
+];
+
+export const REQUIRED_STAGE_MARKERS_CURSOR = [
+  'aw-review',
+  'aw-plan',
+  'aw-build',
+  'Hard Gate',
+];
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Card text — copied verbatim from spec.md::§"Slim card content".
+ * Trailing newline is intentional: Claude/Cursor parse the file as a single
+ * markdown document.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+export const SLIM_CARD_CLAUDE = `# AW Router (Compact) — using-aw-skills
+
+You have the AW Agentic Workspace engine. This compact router replaces the
+full using-aw-skills SKILL.md so it fits inside Claude Code Web's
+SessionStart inline cap. The full skill is still available via the Skill
+tool as \`aw:using-aw-skills\` for deep cases.
+
+## Hard Gate (MUST — in order, before any substantive response)
+
+1. Classify the user's intent (one line).
+2. Pick the SMALLEST correct stage skill from the table below.
+3. Invoke it via \`Skill(skill="aw:<stage>")\` BEFORE any other Skill, Edit,
+   Write, or Bash call that performs substantive work.
+4. Follow that stage skill's contract — do not improvise.
+
+Naming a route is not invoking it. Read = call the Skill tool.
+
+## Intent → Stage Skill (tier 1/2 — invoke these first)
+
+| Intent signal in the prompt | Stage skill |
+|---|---|
+| review, "review this PR", findings, governance, "is this ready" | \`aw:review\` |
+| plan, design, refactor strategy, propose approach | \`aw:plan\` |
+| build, implement, write code, add feature, TDD | \`aw:build\` |
+| bug, crash, alert, regression, debug, investigate | \`aw:investigate\` |
+| test, QA, e2e, coverage, regression suite | \`aw:test\` |
+| deploy, release, rollout, staging | \`aw:deploy\` |
+| ship, launch, rollback readiness, closeout | \`aw:ship\` |
+| feature end-to-end (research → ship) | \`aw:feature\` |
+| agent/skill/command/rule authoring | \`aw:adk\` |
+
+## Tier-3 domain skills are delegated, not invoked directly
+
+\`platform-core-pr-review\`, \`platform-services-development\`,
+\`platform-frontend-*\`, \`platform-sdet-*\`, \`platform-infra-*\`, etc. — these
+are domain transports. The stage skill (\`aw:review\`, \`aw:build\`, …) decides
+when to call them. Invoking a tier-3 skill before its parent stage is a
+routing miss.
+
+## Single-reviewer fallback (review only)
+
+You may skip \`aw:review\` and call \`platform-core-pr-review\` directly ONLY
+if ALL of the following hold:
+
+- the diff is < 50 lines AND touches a single file
+- no auth, payment, schema, or public API surface
+- assessed risk = Low
+- the user explicitly requested single-reviewer mode
+
+If any condition fails, route through \`aw:review\`.
+
+## Red flags (you skipped the gate)
+
+- "I know the route" without calling \`Skill(skill="aw:<stage>")\`
+- Pattern-matching a URL/keyword (e.g. PR link → pr-review) past the gate
+- Calling a \`platform-*\` skill before its parent \`aw:*\` stage skill
+- Single-reviewer review for >1 file or >50 lines without explicit request
+
+## Rule reminders (load on demand from disk)
+
+Platform rules live under \`.aw/.aw_rules/platform/\` — search in this order:
+\`./.aw/.aw_rules/platform/\`, \`~/.aw/.aw_rules/platform/\`, \`~/.aw_rules/platform/\`,
+\`~/.aw/.aw_registry/.aw_rules/platform/\`. Read \`universal/AGENTS.md\` and
+\`security/AGENTS.md\` first, then the touched-domain \`AGENTS.md\` plus
+\`references/*.md\` on demand.
+`;
+
+export const SLIM_CARD_CURSOR = `# AW Router (Compact) — using-aw-skills
+
+You have the AW Agentic Workspace engine. This compact router replaces the
+full using-aw-skills SKILL.md so it fits inside the harness's SessionStart
+inline-context cap. The full skill is still available on disk at
+\`~/.cursor/skills/using-aw-skills/SKILL.md\` for deep cases.
+
+## Hard Gate (MUST — in order, before any substantive response)
+
+1. Classify the user's intent (one line).
+2. Pick the SMALLEST correct stage skill from the table below.
+3. Read \`~/.cursor/skills/aw-<stage>/SKILL.md\` BEFORE any other Read, Edit,
+   Write, Shell, or MCP call that performs substantive work.
+4. Follow that stage skill's contract — do not improvise.
+
+Naming a route is not invoking it. Read = open the SKILL.md file.
+
+## Intent → Stage Skill (tier 1/2 — read these first)
+
+| Intent signal in the prompt | Stage skill |
+|---|---|
+| review, "review this PR", findings, governance, "is this ready" | \`aw-review\` |
+| plan, design, refactor strategy, propose approach | \`aw-plan\` |
+| build, implement, write code, add feature, TDD | \`aw-build\` |
+| bug, crash, alert, regression, debug, investigate | \`aw-investigate\` |
+| test, QA, e2e, coverage, regression suite | \`aw-test\` |
+| deploy, release, rollout, staging | \`aw-deploy\` |
+| ship, launch, rollback readiness, closeout | \`aw-ship\` |
+| feature end-to-end (research → ship) | \`aw-feature\` |
+| agent/skill/command/rule authoring | \`aw-adk\` |
+
+## Tier-3 domain skills are delegated, not invoked directly
+
+\`platform-core-pr-review\`, \`platform-services-development\`,
+\`platform-frontend-*\`, \`platform-sdet-*\`, \`platform-infra-*\`, etc. — these
+are domain transports. The stage skill (\`aw-review\`, \`aw-build\`, …) decides
+when to call them. Reading a tier-3 skill before its parent stage is a
+routing miss.
+
+## Single-reviewer fallback (review only)
+
+You may skip \`aw-review\` and use \`platform-core-pr-review\` directly ONLY
+if ALL of the following hold:
+
+- the diff is < 50 lines AND touches a single file
+- no auth, payment, schema, or public API surface
+- assessed risk = Low
+- the user explicitly requested single-reviewer mode
+
+If any condition fails, route through \`aw-review\`.
+
+## Red flags (you skipped the gate)
+
+- "I know the route" without reading \`aw-<stage>/SKILL.md\`
+- Pattern-matching a URL/keyword (e.g. PR link → pr-review) past the gate
+- Reading a \`platform-*\` skill before its parent \`aw-*\` stage skill
+- Single-reviewer review for >1 file or >50 lines without explicit request
+
+## Rule reminders (load on demand from disk)
+
+Platform rules live under \`.aw/.aw_rules/platform/\` — search in this order:
+\`./.aw/.aw_rules/platform/\`, \`~/.aw/.aw_rules/platform/\`, \`~/.aw_rules/platform/\`,
+\`~/.aw/.aw_registry/.aw_rules/platform/\`. Read \`universal/AGENTS.md\` and
+\`security/AGENTS.md\` first, then the touched-domain \`AGENTS.md\` plus
+\`references/*.md\` on demand.
+`;
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Hook scripts — embedded as bash one-liners that emit fixed JSON envelopes.
+ * ───────────────────────────────────────────────────────────────────────── */
+
+function buildClaudeSlimHookScript(cardPath) {
+  // Export CARD_PATH so the python child sees it via os.environ. The python
+  // body is inside a SINGLE-QUOTED heredoc so no shell expansion happens —
+  // the path is read from the env, not interpolated, which avoids quoting
+  // hazards if cardPath contains shell metacharacters.
+  return `#!/usr/bin/env bash
+# AW C4 SLIM ROUTER (Claude SessionStart) v1
+set -euo pipefail
+export CARD_PATH="${cardPath}"
+if [ ! -f "$CARD_PATH" ]; then
+  printf '%s' '{}'
+  exit 0
+fi
+python3 -c '
+import json, os
+card = open(os.environ["CARD_PATH"]).read()
+print(json.dumps({
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": card,
+  }
+}))
+'
+`;
+}
+
+function buildCursorSlimHookScript(cardPath) {
+  // Cursor uses the simpler top-level snake_case form. Same env-passing
+  // strategy as the Claude variant.
+  return `#!/usr/bin/env bash
+# AW C4 SLIM ROUTER (Cursor sessionStart) v1
+set -euo pipefail
+export CARD_PATH="${cardPath}"
+if [ ! -f "$CARD_PATH" ]; then
+  printf '%s' '{}'
+  exit 0
+fi
+python3 -c '
+import json, os
+card = open(os.environ["CARD_PATH"]).read()
+print(json.dumps({"additional_context": card}))
+'
+`;
+}
+
+/* ─────────────────────────────────────────────────────────────────────────
+ * Public API
+ * ───────────────────────────────────────────────────────────────────────── */
+
+/**
+ * Validate + return the slim card for a harness.
+ *
+ * @param {'claude-web'|'cursor-cloud'} harness
+ * @returns {{ card: string, bytes: number }}
+ */
+export function buildSlimRouterCard(harness) {
+  let card;
+  let stageMarkers;
+  if (harness === 'claude-web') {
+    card = SLIM_CARD_CLAUDE;
+    stageMarkers = REQUIRED_STAGE_MARKERS_CLAUDE;
+  } else if (harness === 'cursor-cloud') {
+    card = SLIM_CARD_CURSOR;
+    stageMarkers = REQUIRED_STAGE_MARKERS_CURSOR;
+  } else {
+    throw new Error(`buildSlimRouterCard: unsupported harness "${harness}"`);
+  }
+
+  const bytes = Buffer.byteLength(card, 'utf8');
+  if (bytes > SLIM_CARD_HARD_CEILING_BYTES) {
+    throw new Error(
+      `Slim card for ${harness} is ${bytes} bytes, exceeds ${SLIM_CARD_HARD_CEILING_BYTES} ceiling`
+    );
+  }
+
+  for (const phrase of REQUIRED_ENFORCEMENT_PHRASES) {
+    if (!card.includes(phrase)) {
+      throw new Error(`Slim card for ${harness} missing enforcement phrase: "${phrase}"`);
+    }
+  }
+  for (const marker of stageMarkers) {
+    if (!card.includes(marker)) {
+      throw new Error(`Slim card for ${harness} missing stage marker: "${marker}"`);
+    }
+  }
+
+  return { card, bytes };
+}
+
+function ensureDir(d) {
+  mkdirSync(d, { recursive: true });
+}
+
+function writeExecutable(path, content) {
+  ensureDir(dirname(path));
+  writeFileSync(path, content, { mode: 0o755 });
+  try { chmodSync(path, 0o755); } catch { /* best-effort */ }
+}
+
+function isEscaped(envVarName) {
+  const val = process.env[envVarName];
+  return val === '0';
+}
+
+/**
+ * Install the slim router for a harness.
+ *
+ * @param {'claude-web'|'cursor-cloud'} harness
+ * @param {string} home
+ * @param {{ escapeEnvVar?: string }} [opts]
+ * @returns {{
+ *   cardPath: string,
+ *   sessionHookPath: string,
+ *   promptHookCommand: string,
+ *   registeredIn: string,
+ *   escaped: boolean,
+ * }}
+ */
+export function installSlimRouter(harness, home, opts = {}) {
+  if (harness !== 'claude-web' && harness !== 'cursor-cloud') {
+    throw new Error(`installSlimRouter: unsupported harness "${harness}"`);
+  }
+  if (!home || typeof home !== 'string') {
+    throw new Error('installSlimRouter: home is required');
+  }
+
+  const escapeEnvVar = opts.escapeEnvVar ?? 'AW_SLIM_ROUTER';
+  const escaped = isEscaped(escapeEnvVar);
+
+  if (harness === 'claude-web') {
+    return installClaudeSlim({ home, escaped });
+  }
+  return installCursorSlim({ home, escaped });
+}
+
+function installClaudeSlim({ home, escaped }) {
+  const cardPath = join(home, '.claude/aw-router-card.md');
+  const sessionHookPath = join(home, '.claude/hooks/aw-slim-session-start.sh');
+  const settingsPath = join(home, '.claude/settings.json');
+
+  // Ensure the registry-config parent dir exists in BOTH modes — escape mode
+  // skips the card write that would otherwise create it, but settings.json
+  // still needs to land somewhere.
+  ensureDir(dirname(settingsPath));
+
+  // Per-prompt: ECC's existing rule-reminder script (NOT a card re-emitter).
+  const promptHookCommand =
+    `bash -lc 'exec bash "\${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/scripts/hooks/session-start-rules-context.sh"'`;
+
+  if (!escaped) {
+    ensureDir(dirname(cardPath));
+    writeFileSync(cardPath, SLIM_CARD_CLAUDE, { mode: 0o600 });
+
+    const hookScript = buildClaudeSlimHookScript(cardPath);
+    writeExecutable(sessionHookPath, hookScript);
+
+    const sessionCommand = `bash -lc 'exec bash "${sessionHookPath}"'`;
+
+    claudeHooksMerge({
+      settingsPath,
+      eventName: 'SessionStart',
+      matcher: 'startup|clear|compact',
+      command: sessionCommand,
+      description: 'AW slim router (SessionStart)',
+      commandPatterns: [
+        'aw-slim-session-start.sh',
+        'hooks/session-start',
+      ],
+    });
+  } else {
+    // Escape: register the full ECC SessionStart entry-point.
+    const fullEcc =
+      `bash -lc 'exec bash "\${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/hooks/session-start"'`;
+    claudeHooksMerge({
+      settingsPath,
+      eventName: 'SessionStart',
+      matcher: 'startup|clear|compact',
+      command: fullEcc,
+      description: 'AW full ECC SessionStart (slim escape hatch)',
+      commandPatterns: [
+        'aw-slim-session-start.sh',
+        'hooks/session-start',
+      ],
+    });
+  }
+
+  // Per-prompt hook is registered in BOTH default and escape modes — the
+  // reminder is independent of the slim card.
+  claudeHooksMerge({
+    settingsPath,
+    eventName: 'UserPromptSubmit',
+    command: promptHookCommand,
+    description: 'AW per-prompt rules reminder (ECC delegation)',
+    commandPatterns: ['session-start-rules-context.sh'],
+  });
+
+  return {
+    cardPath,
+    sessionHookPath,
+    promptHookCommand,
+    registeredIn: settingsPath,
+    escaped,
+  };
+}
+
+function installCursorSlim({ home, escaped }) {
+  const cardPath = join(home, '.cursor/aw-router-card.md');
+  const sessionHookPath = join(home, '.cursor/hooks/aw-slim-session-start.sh');
+  const hooksJsonPath = join(home, '.cursor/hooks.json');
+
+  // Same rationale as installClaudeSlim — escape mode skips the card write.
+  ensureDir(dirname(hooksJsonPath));
+
+  // (G1) The Node-adapter wrapper that satisfies Cursor's request-rewrite
+  // JSON contract. NEVER delegate to shared/user-prompt-submit.sh directly.
+  const promptHookCommand =
+    `bash -lc 'f="$PWD/.cursor/hooks/before-submit-prompt.sh"; ` +
+    `[ -f "$f" ] || f="$HOME/.cursor/hooks/before-submit-prompt.sh"; exec bash "$f"'`;
+
+  if (!escaped) {
+    ensureDir(dirname(cardPath));
+    writeFileSync(cardPath, SLIM_CARD_CURSOR, { mode: 0o600 });
+
+    const hookScript = buildCursorSlimHookScript(cardPath);
+    writeExecutable(sessionHookPath, hookScript);
+
+    const sessionCommand = `bash -lc 'exec bash "${sessionHookPath}"'`;
+
+    jsonMergeWithDedup({
+      filePath: hooksJsonPath,
+      jsonPointer: '/hooks/sessionStart',
+      newEntry: {
+        command: sessionCommand,
+        event: 'sessionStart',
+        description: 'AW slim router (sessionStart)',
+      },
+      commandPatterns: [
+        'aw-slim-session-start.sh',
+        '.cursor/hooks/session-start.sh',
+      ],
+    });
+  } else {
+    const fullEcc =
+      `bash -lc 'f="$PWD/.cursor/hooks/session-start.sh"; ` +
+      `[ -f "$f" ] || f="$HOME/.cursor/hooks/session-start.sh"; exec bash "$f"'`;
+    jsonMergeWithDedup({
+      filePath: hooksJsonPath,
+      jsonPointer: '/hooks/sessionStart',
+      newEntry: {
+        command: fullEcc,
+        event: 'sessionStart',
+        description: 'AW full ECC sessionStart (slim escape hatch)',
+      },
+      commandPatterns: [
+        'aw-slim-session-start.sh',
+        '.cursor/hooks/session-start.sh',
+      ],
+    });
+  }
+
+  jsonMergeWithDedup({
+    filePath: hooksJsonPath,
+    jsonPointer: '/hooks/beforeSubmitPrompt',
+    newEntry: {
+      command: promptHookCommand,
+      event: 'beforeSubmitPrompt',
+      description: 'AW per-prompt rules reminder (ECC Node-adapter)',
+    },
+    commandPatterns: ['before-submit-prompt.sh'],
+  });
+
+  return {
+    cardPath,
+    sessionHookPath,
+    promptHookCommand,
+    registeredIn: hooksJsonPath,
+    escaped,
+  };
+}

package/cli.mjs

@@ -27,6 +27,7 @@ const COMMANDS = {
   daemon:  () => import('./commands/daemon.mjs').then(m => m.daemonCommand),
   telemetry: () => import('./commands/telemetry.mjs').then(m => m.telemetryCommand),
   'slack-sim': () => import('./commands/slack-sim.mjs').then(m => m.slackSimCommand),
+  c4:      () => import('./commands/c4.mjs').then(m => m.c4Command),
 };
 
 function parseArgs(argv) {
@@ -115,6 +116,12 @@ function printHelp() {
     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('Cloud'),
+    cmd('aw c4', 'Bootstrap AW for cloud harnesses (Claude/Cursor/Codex)'),
+    cmd('aw c4 --dry-run', 'Run preflight + auth setup without installing'),
+    cmd('aw c4 --diagnose', 'Self-test post-init wiring (always exits 0)'),
+    cmd('aw c4 --harness <name>', 'Override harness detection (cursor-cloud|codex-web|claude-web)'),
+
     sec('Settings'),
     cmd('aw telemetry status', 'Show telemetry status'),
     cmd('aw telemetry disable', 'Opt out of anonymous analytics'),