aw-ecc 1.4.32 → 1.4.48

package/commands/verify.md

@@ -32,6 +32,14 @@ This entrypoint inherits the same rule that the selected test or review scope sh
 
 - `.aw_docs/features/<feature_slug>/verification.md`
 - updated `.aw_docs/features/<feature_slug>/state.json`
+- `.aw_docs/features/<feature_slug>/verification.html` and/or `.aw_docs/features/<feature_slug>/verification.html` when the routed stage writes an HTML companion
+
+## Human HTML Companion
+
+`/aw:verify` inherits the `/aw:test` and `/aw:review` HTML companion contracts.
+Markdown remains canonical for agents, and the `aw:echo` subagent produces the human review companion when output mode is `dual` or `html`.
+Subagent authorization: invoking `/aw:verify` in `dual` or `html` output mode is an explicit user request to delegate the human-facing HTML companion to exactly one background `aw:echo` subagent. This authorization is scoped only to HTML companion generation; do not spawn unrelated subagents.
+HTML sidecars are required before the final handoff. Spawn exactly one `aw:echo` subagent and wait for the colocated `.html` sidecar unless the user explicitly asks not to wait. If the harness still cannot spawn `aw:echo`, create a conservative self-contained fallback HTML sidecar in the same turn, record `generated_fallback` with the blocker, and keep Markdown canonical.
 
 ## Must Not Do
 
@@ -52,4 +60,5 @@ Always end with:
 - `Canonical Flow`
 - `Evidence`
 - `Outcome`
+- `HTML Companion`
 - `Next`

package/hooks/hooks.json

@@ -240,6 +240,18 @@
           }
         ],
         "description": "Capture tool use results for continuous learning"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/aw-usage-post-tool-use.js\"",
+            "async": true,
+            "timeout": 10
+          }
+        ],
+        "description": "Usage telemetry: skill_invoked, agent_spawned, tool_error events"
       }
     ],
     "PostToolUseFailure": [
@@ -252,6 +264,18 @@
           }
         ],
         "description": "Track failed MCP tool calls, mark unhealthy servers, and attempt reconnect"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/aw-usage-post-tool-use-failure.js\"",
+            "async": true,
+            "timeout": 10
+          }
+        ],
+        "description": "Usage telemetry: tool_error event on tool failure"
       }
     ],
     "Stop": [
@@ -300,6 +324,18 @@
           }
         ],
         "description": "Track token and cost metrics per session"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/scripts/hooks/aw-usage-stop.js\"",
+            "async": true,
+            "timeout": 10
+          }
+        ],
+        "description": "Usage telemetry: response_completed and session_ended events"
       }
     ],
     "SessionEnd": [

package/manifests/install-components.json

@@ -17,6 +17,14 @@
         "agents-core"
       ]
     },
+    {
+      "id": "baseline:aw-stages",
+      "family": "baseline",
+      "description": "Canonical AW SDLC stage skills and the using-aw-skills router. Ships single source of truth to all harnesses.",
+      "modules": [
+        "aw-stages"
+      ]
+    },
     {
       "id": "baseline:commands",
       "family": "baseline",

package/manifests/install-modules.json

@@ -39,6 +39,88 @@
       "cost": "light",
       "stability": "stable"
     },
+    {
+      "id": "aw-stages",
+      "kind": "skills",
+      "description": "Canonical AW SDLC stage skills (aw-plan, aw-build, aw-investigate, aw-test, aw-review, aw-deploy, aw-ship, aw-feature) and supporting internal helpers. Shipped from the single canonical skills/ source; install pipeline transforms /aw: \u2192 /aw- for Cursor targets.",
+      "paths": [
+        "skills/aw-brainstorm",
+        "skills/aw-build",
+        "skills/aw-debug",
+        "skills/aw-deploy",
+        "skills/aw-design",
+        "skills/aw-execute",
+        "skills/aw-feature",
+        "skills/aw-finish",
+        "skills/aw-investigate",
+        "skills/aw-plan",
+        "skills/aw-prepare",
+        "skills/aw-review",
+        "skills/aw-rules",
+        "skills/aw-ship",
+        "skills/aw-spec",
+        "skills/aw-tasks",
+        "skills/aw-test",
+        "skills/aw-verify",
+        "skills/aw-yolo",
+        "skills/using-aw-skills"
+      ],
+      "targets": [
+        "claude",
+        "cursor",
+        "antigravity",
+        "codex",
+        "opencode"
+      ],
+      "dependencies": [],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "stable"
+    },
+    {
+      "id": "aw-adk",
+      "kind": "skills",
+      "description": "Agent Development Kit \u2014 centralized CASRE (Command, Agent, Skill, Rule, Eval) authoring with lint, scoring, eval creation, and cross-IDE sync.",
+      "paths": [
+        "skills/aw-adk",
+        "commands/adk.md"
+      ],
+      "targets": [
+        "claude",
+        "cursor",
+        "antigravity",
+        "codex",
+        "opencode"
+      ],
+      "dependencies": [
+        "aw-stages"
+      ],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "stable"
+    },
+    {
+      "id": "aw-publish",
+      "kind": "skills",
+      "description": "Registry publish skill \u2014 guides pushing locally created/modified CASRE artifacts to the remote platform-docs registry via PR. Intent-based with mandatory confirmation gate.",
+      "paths": [
+        "skills/aw-publish",
+        "commands/publish.md"
+      ],
+      "targets": [
+        "claude",
+        "cursor",
+        "antigravity",
+        "codex",
+        "opencode"
+      ],
+      "dependencies": [
+        "aw-stages"
+      ],
+      "defaultInstall": true,
+      "cost": "light",
+      "stability": "stable"
+    },
     {
       "id": "commands-core",
       "kind": "commands",
@@ -191,6 +273,7 @@
         "skills/continuous-learning-v2",
         "skills/e2e-testing",
         "skills/eval-harness",
+        "skills/finish-only-when-green",
         "skills/iterative-retrieval",
         "skills/plankton-code-quality",
         "skills/project-guidelines-example",

package/manifests/install-profiles.json

@@ -6,6 +6,7 @@
       "modules": [
         "rules-core",
         "agents-core",
+        "aw-stages",
         "commands-core",
         "hooks-runtime",
         "platform-configs",
@@ -17,6 +18,7 @@
       "modules": [
         "rules-core",
         "agents-core",
+        "aw-stages",
         "commands-core",
         "hooks-runtime",
         "platform-configs",
@@ -31,6 +33,7 @@
       "modules": [
         "rules-core",
         "agents-core",
+        "aw-stages",
         "commands-core",
         "hooks-runtime",
         "platform-configs",
@@ -43,6 +46,7 @@
       "modules": [
         "rules-core",
         "agents-core",
+        "aw-stages",
         "commands-core",
         "hooks-runtime",
         "platform-configs",
@@ -57,6 +61,9 @@
       "modules": [
         "rules-core",
         "agents-core",
+        "aw-stages",
+        "aw-adk",
+        "aw-publish",
         "commands-core",
         "hooks-runtime",
         "platform-configs",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aw-ecc",
-  "version": "1.4.32",
+  "version": "1.4.48",
   "description": "GoHighLevel Agentic Workspace Engine — forked from Everything Claude Code (ecc-universal)",
   "keywords": [
     "claude-code",
@@ -119,11 +119,11 @@
   },
   "dependencies": {
     "@iarna/toml": "^2.2.5",
+    "ajv": "^8.18.0",
     "sql.js": "^1.14.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "ajv": "^8.18.0",
     "c8": "^10.1.2",
     "eslint": "^9.39.2",
     "globals": "^17.1.0",

package/scripts/ci/validate-rules.js

@@ -42,6 +42,53 @@ function collectRuleFiles(dir) {
   return files;
 }
 
+/**
+ * Validate that .mdc files (Cursor rule format) have frontmatter at byte 0.
+ * Anything before the opening `---` — including HTML comments — makes Cursor
+ * treat the file as having no frontmatter, silently breaking alwaysApply/globs.
+ */
+function validateCursorMdcFrontmatter() {
+  const repoRoot = path.join(__dirname, '../..');
+  const errors = [];
+
+  function scan(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.git')) continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        scan(abs);
+        continue;
+      }
+      if (!entry.name.endsWith('.mdc')) continue;
+      const content = fs.readFileSync(abs, 'utf-8');
+      // Only flag files that HAVE frontmatter but in the wrong position.
+      // Files with no frontmatter at all are valid "plain content" Cursor rules.
+      const hasFrontmatter = /^---\s*$/m.test(content);
+      if (hasFrontmatter && !content.startsWith('---')) {
+        const firstLine = content.split('\n', 1)[0].slice(0, 80);
+        errors.push(`${path.relative(repoRoot, abs)}: frontmatter exists but is not at byte 0 (first line: ${firstLine})`);
+      }
+    }
+  }
+
+  scan(repoRoot);
+
+  if (errors.length > 0) {
+    console.error('ERROR: .mdc files with content before frontmatter (breaks Cursor alwaysApply/globs):');
+    for (const err of errors) {
+      console.error(`  - ${err}`);
+    }
+    return false;
+  }
+  return true;
+}
+
 function validateRules() {
   if (!fs.existsSync(RULES_DIR)) {
     console.log('No rules directory found, skipping validation');
@@ -71,6 +118,10 @@ function validateRules() {
     }
   }
 
+  if (!validateCursorMdcFrontmatter()) {
+    hasErrors = true;
+  }
+
   if (hasErrors) {
     process.exit(1);
   }

package/scripts/cursor-aw-home/hooks.json

@@ -3,7 +3,7 @@
   "hooks": {
     "sessionStart": [
       {
-        "command": "bash -lc \"for candidate in \\\"$PWD/.cursor/hooks/session-start.sh\\\" \\\"$HOME/.cursor/hooks/session-start.sh\\\"; do if [ -f \\\"$candidate\\\" ]; then exec bash \\\"$candidate\\\"; fi; done; exit 0\"",
+        "command": "bash -c 'f=\"$PWD/.cursor/hooks/session-start.sh\"; [ -f \"$f\" ] || f=\"$HOME/.cursor/hooks/session-start.sh\"; exec bash \"$f\"'",
         "event": "sessionStart",
         "description": "Load previous context and detect environment"
       }
@@ -64,7 +64,7 @@
     ],
     "beforeSubmitPrompt": [
       {
-        "command": "bash -lc \"for candidate in \\\"$PWD/.cursor/hooks/before-submit-prompt.sh\\\" \\\"$HOME/.cursor/hooks/before-submit-prompt.sh\\\"; do if [ -f \\\"$candidate\\\" ]; then exec bash \\\"$candidate\\\"; fi; done; exit 0\"",
+        "command": "bash -c 'f=\"$PWD/.cursor/hooks/before-submit-prompt.sh\"; [ -f \"$f\" ] || f=\"$HOME/.cursor/hooks/before-submit-prompt.sh\"; exec bash \"$f\"'",
         "event": "beforeSubmitPrompt",
         "description": "Detect secrets in prompts (sk-, ghp_, AKIA patterns)"
       }
@@ -83,6 +83,20 @@
         "description": "Log agent completion"
       }
     ],
+    "postToolUse": [
+      {
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"post-tool-use.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
+        "event": "postToolUse",
+        "description": "Telemetry: skill_invoked detection for Read tool and other non-shell/edit/MCP tools"
+      }
+    ],
+    "postToolUseFailure": [
+      {
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"post-tool-use-failure.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
+        "event": "postToolUseFailure",
+        "description": "Telemetry: tool_error detection on tool failure/timeout/denial"
+      }
+    ],
     "beforeTabFileRead": [
       {
         "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"before-tab-file-read.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
@@ -104,6 +118,13 @@
         "description": "Save state before context compaction"
       }
     ],
+    "afterAgentResponse": [
+      {
+        "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"after-agent-response.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",
+        "event": "afterAgentResponse",
+        "description": "Telemetry: response_completed with tokens and cost per turn"
+      }
+    ],
     "stop": [
       {
         "command": "node -e \"const fs=require('fs');const path=require('path');const os=require('os');const scriptName=\\\"stop.js\\\";const candidates=[path.join(process.cwd(), '.cursor', 'hooks', scriptName),path.join(os.homedir(), '.cursor', 'hooks', scriptName)];const target=candidates.find(candidate => fs.existsSync(candidate));if(!target) process.exit(0);require(target)\"",

package/scripts/cursor-aw-hooks/adapter.js

@@ -23,8 +23,9 @@ function readStdin() {
 }
 
 function getPluginRoot() {
-  const homeStyleRoot = path.resolve(__dirname, '..');
+  const os = require('os');
   const repoStyleRoot = path.resolve(__dirname, '..', '..');
+  const awEccHome = path.join(os.homedir(), '.aw-ecc');
 
   if (
     fs.existsSync(path.join(repoStyleRoot, 'package.json'))
@@ -34,7 +35,11 @@ function getPluginRoot() {
     return repoStyleRoot;
   }
 
-  return homeStyleRoot;
+  if (fs.existsSync(path.join(awEccHome, 'scripts', 'lib', 'aw-usage-telemetry.js'))) {
+    return awEccHome;
+  }
+
+  return path.resolve(__dirname, '..');
 }
 
 function transformToClaude(cursorInput, overrides = {}) {
@@ -43,12 +48,17 @@ function transformToClaude(cursorInput, overrides = {}) {
   const inferredToolName = cursorInput.tool_name
     || (server && tool ? `mcp__${server}__${tool}` : '');
 
+  // Preserve original tool_input fields (skill, subagent_type, description, etc.)
+  const originalToolInput = cursorInput.tool_input || {};
+
   return {
     tool_name: inferredToolName,
     server,
     tool,
+    exit_code: cursorInput.exit_code,
     tool_input: {
-      command: cursorInput.command || cursorInput.args?.command || '',
+      ...originalToolInput,
+      command: cursorInput.command || cursorInput.args?.command || originalToolInput.command || '',
       file_path: cursorInput.path || cursorInput.file || cursorInput.args?.filePath || '',
       server,
       mcp_server: server,
@@ -60,7 +70,28 @@ function transformToClaude(cursorInput, overrides = {}) {
       output: cursorInput.output || cursorInput.result || '',
       ...overrides.tool_output,
     },
+    tool_response: {
+      exit_code: cursorInput.exit_code,
+      output: cursorInput.output || cursorInput.result || '',
+    },
     transcript_path: cursorInput.transcript_path || cursorInput.transcriptPath || cursorInput.session?.transcript_path || '',
+    // Cursor common schema fields surfaced at top level for buildEvent()
+    generation_id: cursorInput.generation_id,
+    conversation_id: cursorInput.conversation_id,
+    workspace_roots: cursorInput.workspace_roots,
+    model: cursorInput.model,
+    user_email: cursorInput.user_email,
+    cursor_version: cursorInput.cursor_version,
+    status: cursorInput.status,
+    reason: cursorInput.reason,
+    // Token fields — Cursor sends these on afterAgentResponse and stop hooks
+    input_tokens: cursorInput.input_tokens,
+    output_tokens: cursorInput.output_tokens,
+    cache_read_tokens: cursorInput.cache_read_tokens,
+    cache_write_tokens: cursorInput.cache_write_tokens,
+    // Subagent fields
+    task: cursorInput.task,
+    description: cursorInput.description,
     _cursor: {
       conversation_id: cursorInput.conversation_id,
       hook_event_name: cursorInput.hook_event_name,
@@ -100,7 +131,13 @@ function runExistingHook(scriptName, stdinData) {
     path.join(root, 'scripts', 'hooks', scriptName),
     path.join(root, 'hooks', scriptName),
   ];
-  const scriptPath = candidates.find(candidate => fs.existsSync(candidate)) || candidates[0];
+  const scriptPath = candidates.find(candidate => fs.existsSync(candidate));
+  if (!scriptPath) {
+    if (process.env.AW_HOOK_DEBUG === '1') {
+      process.stderr.write(`[aw] Cannot find hook script: ${scriptName}\n`);
+    }
+    return undefined;
+  }
   return runManagedCommand('node', [scriptPath], stdinData);
 }
 

package/scripts/cursor-aw-hooks/before-submit-prompt.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-const { readStdin, runManagedShellHook } = require('./adapter');
+const { readStdin, runManagedShellHook, runExistingHook, transformToClaude } = require('./adapter');
 
 function emitAwPromptReminder(raw) {
   const result = runManagedShellHook('scripts/hooks/shared/user-prompt-submit.sh', raw);
@@ -37,5 +37,11 @@ readStdin().then(raw => {
   } catch (_error) {
     // Reminder emission is advisory and should not break the prompt flow.
   }
+  try {
+    const claudePayload = transformToClaude(JSON.parse(raw));
+    runExistingHook('aw-usage-prompt-submit.js', JSON.stringify(claudePayload));
+  } catch (_error) {
+    // Telemetry is best-effort and should not block prompt submission.
+  }
   process.stdout.write(raw);
 }).catch(() => process.exit(0));

package/scripts/hooks/aw-usage-commit-created.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Usage telemetry — commit_created event.
+ *
+ * Called from the post-commit git hook when the commit has an AW
+ * Co-Authored-By trailer. Works for all harnesses (Claude, Cursor, Codex)
+ * since it fires from a git-level hook, not a harness-specific one.
+ *
+ * Usage: node aw-usage-commit-created.js <commit_hash> <branch>
+ */
+
+'use strict';
+
+const { buildEvent, sendAsync, isDisabled } = require('../lib/aw-usage-telemetry');
+
+if (isDisabled()) process.exit(0);
+
+const commitHash = process.argv[2] || 'unknown';
+const branch = process.argv[3] || 'unknown';
+
+// Minimal input — no harness session context in a git hook.
+// detectHarness() will return 'claude' (default) but the event
+// payload makes it clear this is harness-agnostic.
+const event = buildEvent({}, 'commit_created', {
+  commit_hash: commitHash,
+  branch,
+});
+
+// Override harness to 'git' since this fires from a git hook, not a harness
+event.harness = 'git';
+
+sendAsync(event);

package/scripts/hooks/aw-usage-post-tool-use-failure.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+/**
+ * Usage telemetry — PostToolUseFailure hook.
+ *
+ * Claude: error (string/object) + is_interrupt (boolean).
+ * Cursor: error_message (string) + failure_type ("timeout"/"error"/"permission_denied").
+ * Codex: does NOT support PostToolUseFailure — this hook won't fire.
+ *
+ * Outputs {} on stdout.
+ */
+
+'use strict';
+
+const { buildEvent, sendAsync } = require('../lib/aw-usage-telemetry');
+
+const MAX_STDIN = 1024 * 1024;
+let raw = '';
+
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => {
+  if (raw.length < MAX_STDIN) {
+    raw += chunk.substring(0, MAX_STDIN - raw.length);
+  }
+});
+
+process.stdin.on('end', () => {
+  try {
+    const input = JSON.parse(raw);
+    const toolName = input.tool_name || 'unknown';
+
+    // Normalize error fields across Claude and Cursor
+    let errorMessage;
+    let failureType;
+
+    if (input.error_message !== undefined) {
+      // Cursor format
+      errorMessage = String(input.error_message || '');
+      failureType = input.failure_type || 'error';
+    } else {
+      // Claude format
+      const err = input.error;
+      errorMessage = typeof err === 'string' ? err : (err?.message || JSON.stringify(err) || 'unknown');
+      failureType = input.is_interrupt ? 'interrupt' : 'error';
+    }
+
+    sendAsync(buildEvent(input, 'tool_error', {
+      tool_name: toolName,
+      error_message: errorMessage.slice(0, 500),
+      failure_type: failureType,
+    }));
+  } catch {
+    // Non-blocking.
+  }
+
+  process.stdout.write('{}');
+});