affaan-m/ECC · error · Error

README.md is missing the quick-start catalog summary

Error message

README.md is missing the quick-start catalog summary

What it means

classify_events() shells out to the `claude` CLI (`claude -p <prompt> --model <model> --output-format text`) to classify tool calls against compliance steps. If the subprocess exits with a non-zero return code, the function raises a RuntimeError embedding the exit code and the first 500 characters of stderr, because classification cannot proceed without a valid LLM response. The subprocess call has a 60-second timeout.

Source

Thrown at scripts/ci/catalog.js:95

  }
}

function replaceOrThrow(content, regex, replacer, source) {
  if (!regex.test(content)) {
    throw new Error(`${source} is missing the expected catalog marker`);
  }

  return content.replace(regex, replacer);
}

function parseReadmeExpectations(readmeContent) {
  const expectations = [];

  const quickStartMatch = readmeContent.match(
    /access to\s+(\d+)\s+agents,\s+(\d+)\s+skills,\s+and\s+(\d+)\s+(?:commands|legacy command shims?)/i
  );
  if (!quickStartMatch) {
    throw new Error('README.md is missing the quick-start catalog summary');
  }

  expectations.push(
    { category: 'agents', mode: 'exact', expected: Number(quickStartMatch[1]), source: 'README.md quick-start summary' },
    { category: 'skills', mode: 'exact', expected: Number(quickStartMatch[2]), source: 'README.md quick-start summary' },
    { category: 'commands', mode: 'exact', expected: Number(quickStartMatch[3]), source: 'README.md quick-start summary' }
  );

  const projectTreeAgentsMatch = readmeContent.match(/^\|\s*--\s*agents\/\s*#\s*(\d+)\s+specialized subagents for delegation\s*$/im);
  if (!projectTreeAgentsMatch) {
    throw new Error('README.md project tree is missing the agents count');
  }

  expectations.push({
    category: 'agents',
    mode: 'exact',
    expected: Number(projectTreeAgentsMatch[1]),
    source: 'README.md project tree (agents)'

View on GitHub (pinned to 01e15490f0)

Solutions

Confirm `claude` is installed and on PATH: shutil.which('claude') returns a path.
Read the embedded stderr snippet (err message) — it usually names the real cause (auth, model, overload).
Retry with a smaller trace (fewer events) or a supported model name.
Ensure the CLI is authenticated in the running environment (run `claude` interactively once).

Example fix

# before
classify_events(spec, trace, model='haiku')  # RuntimeError if claude missing

# after
import shutil
if not shutil.which('claude'):
    raise SystemExit('claude CLI not found on PATH — install and authenticate it first')
try:
    result = classify_events(spec, trace, model='haiku')
except RuntimeError as e:
    logger.error('classifier failed: %s', e)
    result = {}

Defensive patterns

Strategy: try-catch

Validate before calling

# Verify the claude CLI exists and is authenticated before classifying.
import shutil
if not shutil.which('claude'):
    raise SystemExit('claude CLI not found on PATH — install and authenticate it first')

Type guard

import shutil

def claude_cli_available() -> bool:
    return shutil.which('claude') is not None

Try / catch

try:
    result = classify_events(spec, trace, model='haiku')
except RuntimeError as e:
    # e.args[0] contains 'rc=<code>: <stderr excerpt>' — inspect it.
    logger.error('classifier subprocess failed: %s', e)
    # degrade gracefully: skip classification, or retry with a smaller trace
    result = {}

Prevention

Ensure the `claude` CLI is installed, on PATH, and authenticated in every environment that runs classification.
Keep traces small — very large traces blow the context window and slow the subprocess toward the 60s timeout.
Log the embedded stderr excerpt; it usually pinpoints auth, model, or overload failures.
Treat a classifier failure as degradable (return empty mapping) only if your pipeline tolerates missing classifications.

When it happens

Trigger: The `claude` CLI binary is not installed or not on PATH (ENOENT); the --model name is invalid or unavailable; the CLI's auth token is missing/expired; the prompt is too large for the model's context window; the CLI hits an internal error; the 60-second timeout fires and the process is killed (non-zero exit).

Common situations: Running in a headless/CI environment without the claude CLI installed; passing a model name the local CLI does not support; expired or missing authentication; a very large trace that exceeds the model context limit; transient CLI/network failure.

Related errors

AI-assisted analysis of affaan-m/ECC@01e15490f0 (2026-08-13). Data as JSON: /api/errors/c41fc303bfbfc936. Report an issue: GitHub.