aw-ecc 1.4.21

package/scripts/hooks/session-start.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+/**
+ * SessionStart Hook - Load previous context on new session
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs when a new Claude session starts. Loads the most recent session
+ * summary into Claude's context via stdout, and reports available
+ * sessions and learned skills.
+ */
+
+const {
+  getSessionsDir,
+  getLearnedSkillsDir,
+  findFiles,
+  ensureDir,
+  readFile,
+  stripAnsi,
+  log,
+  output
+} = require('../lib/utils');
+const { getPackageManager, getSelectionPrompt } = require('../lib/package-manager');
+const { listAliases } = require('../lib/session-aliases');
+const { detectProjectType } = require('../lib/project-detect');
+
+async function main() {
+  const sessionsDir = getSessionsDir();
+  const learnedDir = getLearnedSkillsDir();
+
+  // Ensure directories exist
+  ensureDir(sessionsDir);
+  ensureDir(learnedDir);
+
+  // Check for recent session files (last 7 days)
+  const recentSessions = findFiles(sessionsDir, '*-session.tmp', { maxAge: 7 });
+
+  if (recentSessions.length > 0) {
+    const latest = recentSessions[0];
+    log(`[SessionStart] Found ${recentSessions.length} recent session(s)`);
+    log(`[SessionStart] Latest: ${latest.path}`);
+
+    // Read and inject the latest session content into Claude's context
+    const content = stripAnsi(readFile(latest.path));
+    if (content && !content.includes('[Session context goes here]')) {
+      // Only inject if the session has actual content (not the blank template)
+      output(`Previous session summary:\n${content}`);
+    }
+  }
+
+  // Check for learned skills
+  const learnedSkills = findFiles(learnedDir, '*.md');
+
+  if (learnedSkills.length > 0) {
+    log(`[SessionStart] ${learnedSkills.length} learned skill(s) available in ${learnedDir}`);
+  }
+
+  // Check for available session aliases
+  const aliases = listAliases({ limit: 5 });
+
+  if (aliases.length > 0) {
+    const aliasNames = aliases.map(a => a.name).join(', ');
+    log(`[SessionStart] ${aliases.length} session alias(es) available: ${aliasNames}`);
+    log(`[SessionStart] Use /sessions load <alias> to continue a previous session`);
+  }
+
+  // Detect and report package manager
+  const pm = getPackageManager();
+  log(`[SessionStart] Package manager: ${pm.name} (${pm.source})`);
+
+  // If no explicit package manager config was found, show selection prompt
+  if (pm.source === 'default') {
+    log('[SessionStart] No package manager preference found.');
+    log(getSelectionPrompt());
+  }
+
+  // Detect project type and frameworks (#293)
+  const projectInfo = detectProjectType();
+  if (projectInfo.languages.length > 0 || projectInfo.frameworks.length > 0) {
+    const parts = [];
+    if (projectInfo.languages.length > 0) {
+      parts.push(`languages: ${projectInfo.languages.join(', ')}`);
+    }
+    if (projectInfo.frameworks.length > 0) {
+      parts.push(`frameworks: ${projectInfo.frameworks.join(', ')}`);
+    }
+    log(`[SessionStart] Project detected — ${parts.join('; ')}`);
+    output(`Project type: ${JSON.stringify(projectInfo)}`);
+  } else {
+    log('[SessionStart] No specific project type detected');
+  }
+
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error('[SessionStart] Error:', err.message);
+  process.exit(0); // Don't block on errors
+});

package/scripts/hooks/shared/aw-phase-definitions.js

@@ -0,0 +1,190 @@
+const SHARED_AW_PHASE_STEPS = Object.freeze({
+  'session-start': [
+    {
+      hookId: 'session:start',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'shell',
+      relativeScriptPath: '.cursor/hooks/shared/session-start.sh',
+      payloadMode: 'raw',
+    },
+  ],
+  'user-prompt-submit': [
+    {
+      runner: 'shell',
+      relativeScriptPath: '.cursor/hooks/shared/user-prompt-submit.sh',
+      payloadMode: 'raw',
+    },
+  ],
+  'pre-tool-use-shell': [
+    {
+      hookId: 'pre:bash:dev-server-block',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-bash-dev-server-block.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'pre:bash:tmux-reminder',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-bash-tmux-reminder.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'pre:bash:git-push-reminder',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-bash-git-push-reminder.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'pre-tool-use-mcp': [
+    {
+      hookId: 'pre:mcp-health-check',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/mcp-health-check.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'pre:mcp:audit-log',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-mcp-log.js',
+      payloadMode: 'raw',
+    },
+  ],
+  'post-tool-use-shell': [
+    {
+      hookId: 'post:bash:pr-created',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-bash-pr-created.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:bash:build-complete',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-bash-build-complete.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'post-tool-use-file-edit': [
+    {
+      hookId: 'post:quality-gate',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/quality-gate.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:edit:format',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-edit-format.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:edit:typecheck',
+      allowedProfiles: ['strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-edit-typecheck.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'post:edit:console-warn',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-edit-console-warn.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'post-tool-use-mcp': [
+    {
+      hookId: 'post:mcp:audit-log',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/post-mcp-log.js',
+      payloadMode: 'raw',
+    },
+  ],
+  'pre-compact': [
+    {
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/pre-compact.js',
+      payloadMode: 'claude',
+    },
+  ],
+  'session-end': [
+    {
+      hookId: 'session:end:marker',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/session-end-marker.js',
+      payloadMode: 'claude',
+    },
+  ],
+  stop: [
+    {
+      hookId: 'stop:check-console-log',
+      allowedProfiles: ['standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/check-console-log.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'stop:session-end',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/session-end.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'stop:evaluate-session',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/evaluate-session.js',
+      payloadMode: 'claude',
+    },
+    {
+      hookId: 'stop:cost-tracker',
+      allowedProfiles: ['minimal', 'standard', 'strict'],
+      runner: 'node',
+      relativeScriptPath: 'scripts/hooks/cost-tracker.js',
+      payloadMode: 'claude',
+    },
+  ],
+});
+
+/**
+ * Canonical string constants for all AW hook phase names.
+ * Use these instead of raw string literals to get typo-safety and IDE
+ * auto-complete in files that call runNamedCursorAwPhase() or equivalent.
+ */
+const PHASE_NAMES = Object.freeze({
+  SESSION_START: 'session-start',
+  USER_PROMPT_SUBMIT: 'user-prompt-submit',
+  PRE_TOOL_USE_SHELL: 'pre-tool-use-shell',
+  PRE_TOOL_USE_MCP: 'pre-tool-use-mcp',
+  POST_TOOL_USE_SHELL: 'post-tool-use-shell',
+  POST_TOOL_USE_FILE_EDIT: 'post-tool-use-file-edit',
+  POST_TOOL_USE_MCP: 'post-tool-use-mcp',
+  PRE_COMPACT: 'pre-compact',
+  SESSION_END: 'session-end',
+  STOP: 'stop',
+});
+
+function getSharedAwPhaseSteps(phaseName) {
+  const steps = SHARED_AW_PHASE_STEPS[phaseName];
+  if (!steps) {
+    throw new Error(`Unknown shared AW phase: ${phaseName}`);
+  }
+  return steps;
+}
+
+module.exports = {
+  PHASE_NAMES,
+  SHARED_AW_PHASE_STEPS,
+  getSharedAwPhaseSteps,
+};

package/scripts/hooks/shared/aw-phase-runner.js

@@ -0,0 +1,61 @@
+function shouldRunStep(step, runtime) {
+  if (!step.hookId) {
+    return true;
+  }
+
+  return runtime.hookEnabled(step.hookId, step.allowedProfiles || ['standard', 'strict']);
+}
+
+function resolveStepPayload(step, raw, parsedInput, claudeInput) {
+  switch (step.payloadMode) {
+    case 'raw':
+      return raw;
+    case 'parsed':
+      return parsedInput;
+    case 'claude':
+    default:
+      return claudeInput;
+  }
+}
+
+function executeStep(runtime, step, payload) {
+  if (step.runner === 'shell') {
+    return runtime.runManagedShellHook(step.relativeScriptPath, payload);
+  }
+
+  return runtime.runManagedNodeHook(step.relativeScriptPath, payload);
+}
+
+async function runSharedAwPhase({ raw, steps, deps = {} }) {
+  const runtime = {
+    transformToClaude: deps.transformToClaude,
+    runManagedNodeHook: deps.runManagedNodeHook,
+    runManagedShellHook: deps.runManagedShellHook,
+    hookEnabled: deps.hookEnabled,
+  };
+
+  let parsedInput = {};
+  try {
+    parsedInput = JSON.parse(raw || '{}');
+  } catch {
+    return raw;
+  }
+
+  const needsClaudeInput = steps.some(step => (step.payloadMode || 'claude') === 'claude');
+  const claudeInput = needsClaudeInput ? runtime.transformToClaude(parsedInput) : null;
+
+  for (const step of steps) {
+    if (!shouldRunStep(step, runtime)) {
+      continue;
+    }
+
+    const payload = resolveStepPayload(step, raw, parsedInput, claudeInput);
+    await executeStep(runtime, step, payload);
+  }
+
+  return raw;
+}
+
+module.exports = {
+  runSharedAwPhase,
+};

package/scripts/hooks/shared/session-start.sh

@@ -0,0 +1,20 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+ROOT_DIR="$(cd "${SCRIPT_DIR}/../../.." && pwd)"
+
+CANDIDATES=(
+  "$ROOT_DIR/skills/using-aw-skills/hooks/session-start.sh"
+  "$HOME/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
+  "$HOME/.aw/.aw_registry/platform/core/skills/using-aw-skills/hooks/session-start.sh"
+)
+
+for TARGET_SCRIPT in "${CANDIDATES[@]}"; do
+  if [[ -f "$TARGET_SCRIPT" ]]; then
+    exec bash "$TARGET_SCRIPT"
+  fi
+done
+
+echo '{"hookSpecificOutput": {"hookEventName": "SessionStart", "additionalContext": "WARNING: AW session-start hook not found in the installed aw-ecc bundle or ~/.aw_registry."}}'
+exit 0

package/scripts/hooks/shared/user-prompt-submit.sh

@@ -0,0 +1,155 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — inject a compact AW routing reminder plus scoped rule reminders
+#
+# Output is printed to stdout as a plain-text prompt reminder.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TMPFILE=$(mktemp) || exit 0
+trap 'rm -f "$TMPFILE"' EXIT
+
+PYTHON_CMD=""
+PYTHON_ARGS=()
+
+resolve_python_cmd() {
+  if [ -n "${CLV2_PYTHON_CMD:-}" ] && command -v "$CLV2_PYTHON_CMD" >/dev/null 2>&1; then
+    PYTHON_CMD="$CLV2_PYTHON_CMD"
+    PYTHON_ARGS=()
+    return 0
+  fi
+
+  if command -v python3 >/dev/null 2>&1; then
+    PYTHON_CMD="python3"
+    PYTHON_ARGS=()
+    return 0
+  fi
+
+  if command -v python >/dev/null 2>&1; then
+    PYTHON_CMD="python"
+    PYTHON_ARGS=()
+    return 0
+  fi
+
+  if command -v py >/dev/null 2>&1; then
+    PYTHON_CMD="py"
+    PYTHON_ARGS=(-3)
+    return 0
+  fi
+
+  return 1
+}
+
+resolve_python_cmd || exit 0
+
+if [ "${#PYTHON_ARGS[@]}" -gt 0 ]; then
+  echo "$INPUT" | "$PYTHON_CMD" "${PYTHON_ARGS[@]}" -c "
+import os, sys, json, re
+d = json.load(sys.stdin)
+cwd = d.get('cwd', '')
+prompt = d.get('prompt', '')
+cwd = re.sub(r'[^a-zA-Z0-9./_@:\\\\~\ -]', '', cwd)
+prompt = prompt[:500]
+stack_overlays_enabled = os.environ.get('AW_ENABLE_STACK_OVERLAY_RULES') == '1'
+print(f'CWD={cwd}')
+prompt_lower = prompt.lower()
+if any(k in prompt_lower for k in ['controller', 'service', 'module', '@body', 'nestjs', 'worker', 'dto']):
+    print('DOMAIN=backend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nestjs', '@body', '@controller', '@module', 'class-validator', 'dto']):
+        print('STACK=nestjs')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['connectrpc', 'connect-go', 'buf.gen', 'protoc-gen-connect-go']):
+        print('STACK=go-connect')
+elif any(k in prompt_lower for k in ['vue', 'component', 'template', 'frontend', '<script', 'nuxt']):
+    print('DOMAIN=frontend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nuxt', 'app.vue', 'useasyncdata', 'definepagemeta']):
+        print('STACK=nuxt')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['vue', '<script', 'script setup', 'composable']):
+        print('STACK=vue')
+elif any(k in prompt_lower for k in ['mongo', 'redis', 'schema', 'migration', 'database', 'index']):
+    print('DOMAIN=data')
+elif any(k in prompt_lower for k in ['helm', 'terraform', 'kubernetes', 'k8s', 'deploy', 'dockerfile']):
+    print('DOMAIN=infra')
+else:
+    print('DOMAIN=universal')
+" > "$TMPFILE" 2>/dev/null || exit 0
+else
+  echo "$INPUT" | "$PYTHON_CMD" -c "
+import os, sys, json, re
+d = json.load(sys.stdin)
+cwd = d.get('cwd', '')
+prompt = d.get('prompt', '')
+cwd = re.sub(r'[^a-zA-Z0-9./_@:\\\\~\ -]', '', cwd)
+prompt = prompt[:500]
+stack_overlays_enabled = os.environ.get('AW_ENABLE_STACK_OVERLAY_RULES') == '1'
+print(f'CWD={cwd}')
+prompt_lower = prompt.lower()
+if any(k in prompt_lower for k in ['controller', 'service', 'module', '@body', 'nestjs', 'worker', 'dto']):
+    print('DOMAIN=backend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nestjs', '@body', '@controller', '@module', 'class-validator', 'dto']):
+        print('STACK=nestjs')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['connectrpc', 'connect-go', 'buf.gen', 'protoc-gen-connect-go']):
+        print('STACK=go-connect')
+elif any(k in prompt_lower for k in ['vue', 'component', 'template', 'frontend', '<script', 'nuxt']):
+    print('DOMAIN=frontend')
+    if stack_overlays_enabled and any(k in prompt_lower for k in ['nuxt', 'app.vue', 'useasyncdata', 'definepagemeta']):
+        print('STACK=nuxt')
+    elif stack_overlays_enabled and any(k in prompt_lower for k in ['vue', '<script', 'script setup', 'composable']):
+        print('STACK=vue')
+elif any(k in prompt_lower for k in ['mongo', 'redis', 'schema', 'migration', 'database', 'index']):
+    print('DOMAIN=data')
+elif any(k in prompt_lower for k in ['helm', 'terraform', 'kubernetes', 'k8s', 'deploy', 'dockerfile']):
+    print('DOMAIN=infra')
+else:
+    print('DOMAIN=universal')
+" > "$TMPFILE" 2>/dev/null || exit 0
+fi
+
+CWD="" DOMAIN="universal" STACK=""
+while IFS='=' read -r key value; do
+  # Strip trailing \r from Windows Python CRLF output
+  key="${key%$'\r'}"
+  value="${value%$'\r'}"
+  case "${key:-}" in
+    CWD)    CWD="$value" ;;
+    DOMAIN) DOMAIN="$value" ;;
+    STACK)  STACK="$value" ;;
+  esac
+done < "$TMPFILE"
+
+RULES_DIR=""
+DOMAIN_AGENTS=""
+STACK_AGENTS=""
+
+if [ -d "$CWD/.aw_registry/.aw_rules/platform" ]; then
+  RULES_DIR="$CWD/.aw_registry/.aw_rules/platform"
+  DOMAIN_AGENTS="$RULES_DIR/$DOMAIN/AGENTS.md"
+elif [ -d "$CWD/.aw_rules" ]; then
+  RULES_DIR="$CWD/.aw_rules"
+  DOMAIN_AGENTS="$RULES_DIR/$DOMAIN/AGENTS.md"
+fi
+
+[ -n "$RULES_DIR" ] || exit 0
+[ -f "$DOMAIN_AGENTS" ] || exit 0
+
+if [ -n "$STACK" ] && [ -f "$RULES_DIR/$DOMAIN/$STACK/AGENTS.md" ]; then
+  STACK_AGENTS="$RULES_DIR/$DOMAIN/$STACK/AGENTS.md"
+fi
+
+DOMAIN_RULES=$(head -20 "$DOMAIN_AGENTS" 2>/dev/null || echo "")
+STACK_RULES=""
+if [ -n "$STACK_AGENTS" ]; then
+  STACK_RULES=$(head -20 "$STACK_AGENTS" 2>/dev/null || echo "")
+fi
+
+RULE_BULLETS=$(printf '%s\n%s\n' "$DOMAIN_RULES" "$STACK_RULES" | grep -E "^\- .*(MUST|Never)" | awk '!seen[$0]++' | head -8 2>/dev/null || true)
+
+[ -z "$DOMAIN_RULES" ] && [ -z "$STACK_RULES" ] && exit 0
+
+cat << EOF
+[AW Router reminder] Re-apply using-aw-skills for this prompt and re-select the smallest correct AW route and stage skill before substantive work.
+[Rule reminder — $RULES_DIR/$DOMAIN${STACK_AGENTS:+/$STACK}] Active MUST rules for this scope. Follow them.
+${RULE_BULLETS:-See $DOMAIN_AGENTS${STACK_AGENTS:+ and $STACK_AGENTS}}
+EOF
+
+exit 0

package/scripts/hooks/suggest-compact.js

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+/**
+ * Strategic Compact Suggester
+ *
+ * Cross-platform (Windows, macOS, Linux)
+ *
+ * Runs on PreToolUse or periodically to suggest manual compaction at logical intervals
+ *
+ * Why manual over auto-compact:
+ * - Auto-compact happens at arbitrary points, often mid-task
+ * - Strategic compacting preserves context through logical phases
+ * - Compact after exploration, before execution
+ * - Compact after completing a milestone, before starting next
+ */
+
+const fs = require('fs');
+const path = require('path');
+const {
+  getTempDir,
+  writeFile,
+  log
+} = require('../lib/utils');
+
+async function main() {
+  // Track tool call count (increment in a temp file)
+  // Use a session-specific counter file based on session ID from environment
+  // or parent PID as fallback
+  const sessionId = (process.env.CLAUDE_SESSION_ID || 'default').replace(/[^a-zA-Z0-9_-]/g, '') || 'default';
+  const counterFile = path.join(getTempDir(), `claude-tool-count-${sessionId}`);
+  const rawThreshold = parseInt(process.env.COMPACT_THRESHOLD || '50', 10);
+  const threshold = Number.isFinite(rawThreshold) && rawThreshold > 0 && rawThreshold <= 10000
+    ? rawThreshold
+    : 50;
+
+  let count = 1;
+
+  // Read existing count or start at 1
+  // Use fd-based read+write to reduce (but not eliminate) race window
+  // between concurrent hook invocations
+  try {
+    const fd = fs.openSync(counterFile, 'a+');
+    try {
+      const buf = Buffer.alloc(64);
+      const bytesRead = fs.readSync(fd, buf, 0, 64, 0);
+      if (bytesRead > 0) {
+        const parsed = parseInt(buf.toString('utf8', 0, bytesRead).trim(), 10);
+        // Clamp to reasonable range — corrupted files could contain huge values
+        // that pass Number.isFinite() (e.g., parseInt('9'.repeat(30)) => 1e+29)
+        count = (Number.isFinite(parsed) && parsed > 0 && parsed <= 1000000)
+          ? parsed + 1
+          : 1;
+      }
+      // Truncate and write new value
+      fs.ftruncateSync(fd, 0);
+      fs.writeSync(fd, String(count), 0);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    // Fallback: just use writeFile if fd operations fail
+    writeFile(counterFile, String(count));
+  }
+
+  // Suggest compact after threshold tool calls
+  if (count === threshold) {
+    log(`[StrategicCompact] ${threshold} tool calls reached - consider /compact if transitioning phases`);
+  }
+
+  // Suggest at regular intervals after threshold (every 25 calls from threshold)
+  if (count > threshold && (count - threshold) % 25 === 0) {
+    log(`[StrategicCompact] ${count} tool calls - good checkpoint for /compact if context is stale`);
+  }
+
+  process.exit(0);
+}
+
+main().catch(err => {
+  console.error('[StrategicCompact] Error:', err.message);
+  process.exit(0);
+});