@ghl-ai/aw 0.1.44-beta.4 → 0.1.44-beta.7

package/c4/cursorRulesShim.mjs

@@ -0,0 +1,222 @@
+/**
+ * c4/cursorRulesShim.mjs — Cursor Cloud slash-command expansion shim.
+ *
+ * Why: Cursor Cloud Agent's chat UI does not pre-expand `/aw:<NAME>` slash
+ * commands the way Cursor Desktop's plugin does. The model sees the raw
+ * literal `/aw:...` and falls through to natural-language interpretation,
+ * losing the contract from the matching command file even though the file
+ * is correctly installed on disk by `commandSurface.mjs`.
+ *
+ * Workaround: write `<repoRoot>/.cursor/rules/aw-slash-expand.mdc` — a
+ * Cursor project rule that teaches the MODEL itself to read the matching
+ * command file and execute its contract verbatim. Cursor's `.mdc` rule
+ * format is honored in Agent mode (verified via Cursor docs); the rule
+ * loads on every session when `alwaysApply: true`.
+ *
+ * Per-harness behavior:
+ *   - cursor-cloud → write the rule (idempotent on byte-equal content)
+ *   - claude-web   → skip (UI expands slash commands natively)
+ *   - codex-web    → skip (different routing surface — see
+ *                    aw-c4-codex-slash-shim future work in overview.md)
+ *   - any other    → skip (defensive default)
+ *
+ * Refs: .aw_docs/features/aw-c4-cursor-slash-shim/{overview,spec,tasks}.md
+ */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+const RULE_FILENAME = 'aw-slash-expand.mdc';
+const CURSOR_RULES_SUBPATH = '.cursor/rules';
+
+/**
+ * Canonical project-rule body. Exported so tests can assert the on-disk
+ * file matches byte-for-byte without re-reading from a fixture. Must NOT
+ * be mutated at runtime.
+ *
+ * The body lives here (not in a separate fixture file) so that bumping
+ * the rule wording is a single-file change that ships with `@ghl-ai/aw`
+ * via npm — no additional asset bundling needed.
+ */
+export const CURSOR_SLASH_SHIM_RULE = `---
+description: Expand \`/aw:<NAME>\` user messages by reading the matching command file
+alwaysApply: true
+---
+
+# AW slash-command expansion (Cursor Cloud workaround)
+
+When the user message starts with \`/aw:<NAME>\` (case-sensitive; \`<NAME>\` may
+contain hyphens — both in the namespace path and in the command name), do
+the following BEFORE producing any other response.
+
+## 1. Stage-command lookup (primary)
+
+Read \`~/.cursor/commands/aw/<NAME>.md\`. If the file exists, jump to step 3
+with its content as the resolved instructions.
+
+## 2. Registry-command lookup (fallback, hyphen-disambiguation)
+
+If step 1 did not resolve and \`<NAME>\` contains at least one hyphen, the
+slash form is a flattened \`<ns_segments...>-<cmd_segments...>\` token. The
+boundary between namespace and command is ambiguous because both can
+contain hyphens (registry has e.g. \`pr-review\`, \`capture-learning\`,
+\`ship-auto\`, \`draw-architecture\`).
+
+Disambiguate by **iterating every hyphen position in \`<NAME>\` from
+RIGHTMOST to LEFTMOST**, and use the first candidate file that exists. The
+repo registry root is \`.aw/.aw_registry/\` (relative to the agent's CWD —
+the repo root in Cursor Cloud).
+
+For each split position \`i\` from rightmost to leftmost:
+- \`prefix = <NAME>[:i]\` (everything before the hyphen at position \`i\`)
+- \`suffix = <NAME>[i+1:]\` (everything after; may itself contain hyphens)
+- candidate = \`.aw/.aw_registry/<prefix-with-hyphens-replaced-by-slashes>/commands/<suffix>.md\`
+- Try \`Read\` on the candidate. If the file exists, jump to step 3 with
+  that content.
+
+### Worked examples
+
+| User typed                                         | Registry file                                              | Splits tried (rightmost first)                                                                                          |
+|----------------------------------------------------|------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|
+| \`/aw:platform-core-brainstorm\`                     | \`platform/core/commands/brainstorm.md\`                     | \`platform/core/commands/brainstorm.md\` ✓ (first try)                                                                    |
+| \`/aw:platform-core-pr-review\`                      | \`platform/core/commands/pr-review.md\`                      | \`platform/core/pr/commands/review.md\` ❌ → \`platform/core/commands/pr-review.md\` ✓                                      |
+| \`/aw:platform-core-capture-learning\`               | \`platform/core/commands/capture-learning.md\`               | \`platform/core/capture/commands/learning.md\` ❌ → \`platform/core/commands/capture-learning.md\` ✓                        |
+| \`/aw:platform-data-clickhouse-cluster-creation\`    | \`platform/data/clickhouse/commands/cluster-creation.md\`    | \`…/cluster/commands/creation.md\` ❌ → \`platform/data/clickhouse/commands/cluster-creation.md\` ✓                         |
+
+## 3. Execute
+
+Treat the resolved file's full content as your operating instructions for
+this turn. Execute the command's phased contract on the text that follows
+the slash command in the user message. Do not summarize or paraphrase the
+command file — execute it verbatim, including any "ask one question at a
+time and wait" interaction protocol.
+
+## 4. No match
+
+If neither lookup resolves to an existing file, do NOT silently fall back
+to natural-language interpretation. Reply with exactly:
+
+> \`/aw:<NAME>\` is not a registered AW command on this machine. Run
+> \`aw c4 --diagnose\` and check the output of
+> \`ls ~/.cursor/commands/aw/\` for available stage commands and
+> \`find .aw/.aw_registry -path '*/commands/*.md'\` for available registry
+> commands.
+
+This precise reply text is the smoke-test fingerprint for the rule itself.
+The string is unique enough that it cannot be confused with the model's
+natural-language fallback.
+
+---
+
+This rule exists because Cursor Cloud's chat UI does not pre-expand slash
+commands the way Cursor Desktop does. The command files ARE installed on
+disk by \`aw c4\`; this rule teaches the model to load them itself. See
+\`.aw_docs/features/aw-c4-cursor-slash-shim/overview.md\` for context. Do
+not edit this file by hand — \`aw c4 --harness cursor-cloud\` regenerates
+it on every run.
+`;
+
+/**
+ * @typedef {object} InstallCursorSlashShimResult
+ * @property {string} harness        The harness echoed from input.
+ * @property {string} path           Absolute path of the rule file (or '' on skip).
+ * @property {'wrote'|'unchanged'|'skipped:harness'|'skipped:no-repo-root'} action
+ */
+
+/**
+ * Write the canonical AW slash-expand rule into the pilot repo.
+ *
+ * Idempotent: a re-run on byte-equal content returns 'unchanged' and does
+ * NOT touch the file (mtime preserved). Drift recovery: any stale content
+ * (including a symlink at the rule path) is replaced with a regular file
+ * containing the canonical template.
+ *
+ * @param {object} opts
+ * @param {string} opts.harness    'cursor-cloud' (writes) or other (skips).
+ * @param {string} opts.repoRoot   Absolute path to the repo root.
+ * @returns {InstallCursorSlashShimResult}
+ */
+export function installCursorSlashShim(opts) {
+  if (!opts || typeof opts !== 'object') {
+    throw new Error('installCursorSlashShim: opts object is required');
+  }
+  const { harness, repoRoot } = opts;
+
+  if (harness !== 'cursor-cloud') {
+    return { harness, path: '', action: 'skipped:harness' };
+  }
+
+  if (!repoRoot || typeof repoRoot !== 'string' || !isExistingDir(repoRoot)) {
+    return { harness, path: '', action: 'skipped:no-repo-root' };
+  }
+
+  const rulesDir = join(repoRoot, CURSOR_RULES_SUBPATH);
+  const rulePath = join(rulesDir, RULE_FILENAME);
+
+  // Idempotency check: if a regular file with byte-identical content
+  // already exists, return 'unchanged' WITHOUT writing — preserves mtime
+  // for the test contract and avoids spurious file-watcher noise.
+  if (isRegularFileWithIdenticalContent(rulePath)) {
+    return { harness, path: rulePath, action: 'unchanged' };
+  }
+
+  // Drift recovery: clear the existing entry (regular file with stale
+  // bytes, or any symlink) before writing a fresh regular file. Symlinks
+  // get unlinked rather than overwritten so we never write through to
+  // their targets.
+  if (lstatExists(rulePath)) {
+    try {
+      unlinkSync(rulePath);
+    } catch {
+      // Ignore — writeFileSync below will overwrite a regular file
+      // anyway. If it's something stranger (e.g. a directory we can't
+      // delete), the writeFileSync will throw and bubble up to safe().
+    }
+  }
+
+  mkdirSync(rulesDir, { recursive: true });
+  writeFileSync(rulePath, CURSOR_SLASH_SHIM_RULE, 'utf8');
+
+  return { harness, path: rulePath, action: 'wrote' };
+}
+
+function isExistingDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function lstatExists(p) {
+  try {
+    lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function isRegularFileWithIdenticalContent(rulePath) {
+  if (!existsSync(rulePath)) return false;
+  let isSym = false;
+  try {
+    isSym = lstatSync(rulePath).isSymbolicLink();
+  } catch {
+    return false;
+  }
+  if (isSym) return false; // Always replace symlinks with regular files.
+  try {
+    return readFileSync(rulePath, 'utf8') === CURSOR_SLASH_SHIM_RULE;
+  } catch {
+    return false;
+  }
+}

package/c4/diagnostics.mjs

@@ -112,6 +112,10 @@ export function summarizeAsOneLine(state) {
 
   if (state.mcpProbe) parts.push(`mcp ${state.mcpProbe}`);
 
+  if (state.slashShim) {
+    parts.push(`slashShim ${slashShimSummaryToken(state.slashShim.action)}`);
+  }
+
   const seconds = Number(state.durationMs ?? 0) / 1000;
   parts.push(`init ${seconds.toFixed(1)}s`);
   parts.push(state.didInit ? 'ready' : 'skipped');
@@ -119,6 +123,18 @@ export function summarizeAsOneLine(state) {
   return parts.join(DOT);
 }
 
+/**
+ * Map the structured slashShim action into a 1-token line summary glyph.
+ * 'wrote' is loud (something changed). 'unchanged' is quiet ('ok'). Both
+ * skip variants collapse to 'skip' so the line stays short on Claude/Codex
+ * harnesses where slashShim is a no-op.
+ */
+function slashShimSummaryToken(action) {
+  if (action === 'wrote') return 'wrote';
+  if (action === 'unchanged') return 'ok';
+  return 'skip';
+}
+
 /* ─────────────────────────────────────────────────────────────────────────
  * diagnoseAwRouterView
  * ───────────────────────────────────────────────────────────────────────── */
@@ -455,6 +471,19 @@ export function dumpPostInitState(opts = {}) {
   for (const skillPath of sampleRegistrySkillPaths(opts.awHome, 10)) {
     lines.push(`  ${skillPath}`);
   }
+  lines.push('');
+
+  // Cursor slash-shim block (cursor-cloud only; opt.slashShim absent on
+  // other harnesses, where the block is intentionally suppressed).
+  if (opts.slashShim && typeof opts.slashShim === 'object') {
+    const shim = opts.slashShim;
+    lines.push('slashShim:');
+    lines.push(`  harness=${shim.harness ?? '<unknown>'}`);
+    lines.push(`  action=${shim.action ?? '<unknown>'}`);
+    if (shim.path) lines.push(`  path=${shim.path}`);
+    lines.push('');
+  }
+
   lines.push('─── end ───');
   lines.push('');
 

package/c4/index.mjs

@@ -35,7 +35,6 @@ export {
   REQUIRED_ENFORCEMENT_PHRASES,
   REQUIRED_STAGE_MARKERS_CLAUDE,
   REQUIRED_STAGE_MARKERS_CURSOR,
-  REQUIRED_MCP_FALLBACK_MARKERS,
   SLIM_CARD_CLAUDE,
   SLIM_CARD_CURSOR,
   buildSlimRouterCard,
@@ -51,6 +50,7 @@ export { MCP_URL_DEFAULT, registerGhlAiMcp } from './mcpServer.mjs';
 export { probeMcpServer } from './mcpSmokeProbe.mjs';
 export { ensureClaudeMarketplace } from './claudePluginRegistry.mjs';
 export { ensureCommandSurface, diagnoseCommandResolution } from './commandSurface.mjs';
+export { installCursorSlashShim, CURSOR_SLASH_SHIM_RULE } from './cursorRulesShim.mjs';
 export { ensureRepoLocalClaudeSettings } from './repoLocalClaudeSettings.mjs';
 export { copyRepoRootInstructions } from './repoRootInstructions.mjs';
 export { ensureRepoLocalIgnore } from './repoLocalIgnore.mjs';

package/c4/slimRouter.mjs

@@ -47,94 +47,6 @@ export const REQUIRED_STAGE_MARKERS_CURSOR = [
   'Hard Gate',
 ];
 
-/* MCP fallback markers — must be present on every cloud-harness card.
- * Cursor Cloud only honors MCPs added via the dashboard; if the native
- * `mcp_ghl-ai_*` surface is missing, the agent must reach ghl-ai via
- * direct JSON-RPC over HTTP. These substrings let the slim-card validator
- * fail loudly if a future edit accidentally drops the section. */
-export const REQUIRED_MCP_FALLBACK_MARKERS = [
-  'MCP fallback',
-  'services.leadconnectorhq.com/agentic-workspace/mcp',
-  'GITHUB_PAT',
-  'Bearer',
-  'tools/list',
-  'tools/call',
-  'text/event-stream',
-];
-
-/* ─────────────────────────────────────────────────────────────────────────
- * MCP fallback sections — appended to both slim cards. Cursor variant adds
- * the dashboard-upgrade hint (cursor.com/agents); Claude variant omits it
- * (Claude Code Web reads ~/.claude/settings.json::mcpServers natively).
- * ───────────────────────────────────────────────────────────────────────── */
-
-const MCP_FALLBACK_CURSOR = `
-## MCP fallback — cloud harness only (use ONLY if native MCP is missing)
-
-\`aw c4\` registers \`ghl-ai\` in \`~/.cursor/mcp.json\`, but Cursor Cloud
-agents only honor MCPs added via the dashboard
-(\`cursor.com/dashboard?tab=integrations\` for Team plans, or the MCP
-dropdown at \`cursor.com/agents\` for personal). When \`mcp_ghl-ai_*\`
-tools are missing from your tool surface, fall back to direct HTTP
-JSON-RPC.
-
-- Endpoint: \`https://services.leadconnectorhq.com/agentic-workspace/mcp\`
-- Headers: \`Authorization: Bearer $GITHUB_PAT\`,
-  \`Content-Type: application/json\`,
-  \`Accept: application/json, text/event-stream\`
-- Protocol: JSON-RPC 2.0 — call \`tools/list\` to discover, then
-  \`tools/call\` with \`{ name, arguments }\`. SSE responses arrive as
-  \`data: <json>\` lines; parse the first JSON payload.
-
-Example (list GKE clusters):
-
-\`\`\`bash
-curl -sS -X POST \\
-  https://services.leadconnectorhq.com/agentic-workspace/mcp \\
-  -H "Authorization: Bearer $GITHUB_PAT" \\
-  -H "Content-Type: application/json" \\
-  -H "Accept: application/json, text/event-stream" \\
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
-       "params":{"name":"gcp_kube-list-clusters",
-                 "arguments":{"location":"-"}}}'
-\`\`\`
-
-Security: NEVER echo, log, or print \`$GITHUB_PAT\` — it is sensitive.
-Use this fallback ONLY when the native MCP tools are unavailable.
-`;
-
-const MCP_FALLBACK_CLAUDE = `
-## MCP fallback (use ONLY if native MCP is missing)
-
-\`aw c4\` registers \`ghl-ai\` in \`~/.claude/settings.json::mcpServers\`.
-If the \`mcp_ghl-ai_*\` tool surface is unavailable in this runtime,
-fall back to direct HTTP JSON-RPC.
-
-- Endpoint: \`https://services.leadconnectorhq.com/agentic-workspace/mcp\`
-- Headers: \`Authorization: Bearer $GITHUB_PAT\`,
-  \`Content-Type: application/json\`,
-  \`Accept: application/json, text/event-stream\`
-- Protocol: JSON-RPC 2.0 — call \`tools/list\` to discover, then
-  \`tools/call\` with \`{ name, arguments }\`. SSE responses arrive as
-  \`data: <json>\` lines; parse the first JSON payload.
-
-Example (list GKE clusters):
-
-\`\`\`bash
-curl -sS -X POST \\
-  https://services.leadconnectorhq.com/agentic-workspace/mcp \\
-  -H "Authorization: Bearer $GITHUB_PAT" \\
-  -H "Content-Type: application/json" \\
-  -H "Accept: application/json, text/event-stream" \\
-  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
-       "params":{"name":"gcp_kube-list-clusters",
-                 "arguments":{"location":"-"}}}'
-\`\`\`
-
-Security: NEVER echo, log, or print \`$GITHUB_PAT\` — it is sensitive.
-Use this fallback ONLY when the native MCP tools are unavailable.
-`;
-
 /* ─────────────────────────────────────────────────────────────────────────
  * Card text — copied verbatim from spec.md::§"Slim card content".
  * Trailing newline is intentional: Claude/Cursor parse the file as a single
@@ -206,7 +118,7 @@ Platform rules live under \`.aw/.aw_rules/platform/\` — search in this order:
 \`~/.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.
-${MCP_FALLBACK_CLAUDE}`;
+`;
 
 export const SLIM_CARD_CURSOR = `# AW Router (Compact) — using-aw-skills
 
@@ -273,7 +185,7 @@ Platform rules live under \`.aw/.aw_rules/platform/\` — search in this order:
 \`~/.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.
-${MCP_FALLBACK_CURSOR}`;
+`;
 
 /* ─────────────────────────────────────────────────────────────────────────
  * Hook scripts — embedded as bash one-liners that emit fixed JSON envelopes.
@@ -364,11 +276,6 @@ export function buildSlimRouterCard(harness) {
       throw new Error(`Slim card for ${harness} missing stage marker: "${marker}"`);
     }
   }
-  for (const marker of REQUIRED_MCP_FALLBACK_MARKERS) {
-    if (!card.includes(marker)) {
-      throw new Error(`Slim card for ${harness} missing MCP fallback marker: "${marker}"`);
-    }
-  }
 
   return { card, bytes };
 }

package/commands/c4.mjs

@@ -346,6 +346,17 @@ export async function c4Command(rawArgs, overrides = {}) {
   // Step 12 — slash command surface.
   safe('ensureCommandSurface', () => c4.ensureCommandSurface({ harness, home, eccHome }), writer);
 
+  // Step 12b — Cursor Cloud slash-expand rule (no-op on other harnesses).
+  // The model-side workaround for Cursor Cloud's chat UI not pre-expanding
+  // `/aw:<NAME>` slash commands. The function self-skips on other
+  // harnesses, so the orchestrator does not pre-filter; the resulting
+  // action is surfaced in the one-line summary and post-init dump.
+  const slashShim = safe(
+    'installCursorSlashShim',
+    () => c4.installCursorSlashShim({ harness, repoRoot: cwd }),
+    writer,
+  );
+
   // Step 13 — repo-root context.
   safe('copyRepoRootInstructions', () => c4.copyRepoRootInstructions(harness, cwd, eccHome), writer);
 
@@ -368,7 +379,13 @@ export async function c4Command(rawArgs, overrides = {}) {
   }
 
   // Step 17 — post-init dump.
-  c4.dumpPostInitState({ harness, cwd, awHome, configPaths: [] });
+  c4.dumpPostInitState({
+    harness,
+    cwd,
+    awHome,
+    configPaths: [],
+    slashShim: slashShim?.ok ? slashShim.value : null,
+  });
 
   // Step 18 — one-line summary.
   writer.stdout(c4.summarizeAsOneLine({
@@ -381,6 +398,7 @@ export async function c4Command(rawArgs, overrides = {}) {
     bridge: branch?.bridge,
     injector: branch?.injector,
     mcpProbe: mcpProbe?.value?.authStatus,
+    slashShim: slashShim?.ok ? slashShim.value : null,
   }) + '\n');
 
   return exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghl-ai/aw",
-  "version": "0.1.44-beta.4",
+  "version": "0.1.44-beta.7",
   "description": "Agentic Workspace CLI — pull, push & manage agents, skills and commands from the registry",
   "type": "module",
   "bin": {