Enterprise Harness

Enterprise Harness

Orchestrator-only quality gate. Runs AFTER a builder agent returns code, BEFORE merge/cherry-pick. The builder never sees these checks and cannot game them.

Prerequisites

STACK RESOLUTION

Read .claude/enterprise-state/stack-profile.json at skill start. Extract:

• $TEST_CMD = commands.test_all
• $BUILD_CMD = commands.build_frontend
• $SOURCE_DIR = structure.source_dirs.backend
• $FRONTEND_DIR = structure.source_dirs.frontend
• $FILE_EXTENSIONS = conventions.file_extensions

If no profile exists: BLOCKED — run /enterprise-discover first.

Before running, collect:

• TASK_SLUG — the task identifier (e.g., sticky-notes-kanban, placeholder-products)
• BRANCH — the builder's feature branch
• BASE — the base branch to diff against (usually dev or main)

Determine changed files once and reuse throughout:

CHANGED_FILES=$(git diff --name-only $BASE...$BRANCH)
CHANGED_JS=$(echo "$CHANGED_FILES" | grep -E "\.($(echo "$FILE_EXTENSIONS" | tr ',' '|'))$" || true)
CHANGED_TEST_FILES=$(echo "$CHANGED_JS" | grep -E '(__tests__|\.test\.|\.spec\.)' || true)
CHANGED_SRC_FILES=$(echo "$CHANGED_JS" | grep -vE '(__tests__|\.test\.|\.spec\.)' || true)
CHANGED_FRONTEND=$(echo "$CHANGED_FILES" | grep "^$FRONTEND_DIR/" || true)

The 10 Checks

Run each check sequentially. Record PASS, FAIL, or WARN for each. Stop-on-first-FAIL is NOT used — run all 10 to give the builder a complete list.

CHECK 1: Contract Exists

A contract file must exist for the task.

CONTRACT=$(ls docs/contracts/*${TASK_SLUG}* 2>/dev/null)
if [ -z "$CONTRACT" ]; then
  echo "FAIL — no contract found matching *${TASK_SLUG}* in docs/contracts/"
else
  echo "PASS — $CONTRACT"
fi

FAIL if no contract file found.

CHECK 2: Tests Per Postcondition

Every postcondition in the contract must have at least one corresponding test.

# Count postconditions in contract
PC_COUNT=$(grep -cE '^[[:space:]]*-?\s*PC-' "$CONTRACT" 2>/dev/null || echo 0)

# Count test blocks in changed test files
TEST_COUNT=0
if [ -n "$CHANGED_TEST_FILES" ]; then
  TEST_COUNT=$(echo "$CHANGED_TEST_FILES" | xargs grep -cE '(^[[:space:]]*(it|test)\(|describe\()' 2>/dev/null | awk -F: '{s+=$NF} END {print s+0}')
fi

echo "Postconditions: $PC_COUNT | Tests: $TEST_COUNT"
if [ "$TEST_COUNT" -lt "$PC_COUNT" ]; then
  echo "FAIL — $TEST_COUNT tests < $PC_COUNT postconditions"
else
  echo "PASS"
fi

FAIL if test count < postcondition count.

CHECK 3: Tests Pass

Run tests and compare against the main baseline to isolate new failures.

# Get baseline failures on BASE branch (if any)
git stash --quiet 2>/dev/null
git checkout "$BASE" --quiet 2>/dev/null
BASELINE_FAILURES=$($TEST_CMD --no-coverage --json 2>/dev/null | jq '.numFailedTests' 2>/dev/null || echo 0)
git checkout "$BRANCH" --quiet 2>/dev/null
git stash pop --quiet 2>/dev/null

# Run tests on builder's branch
TEST_OUTPUT=$($TEST_CMD --no-coverage --json 2>&1)
CURRENT_FAILURES=$(echo "$TEST_OUTPUT" | jq '.numFailedTests' 2>/dev/null || echo 999)

NEW_FAILURES=$((CURRENT_FAILURES - BASELINE_FAILURES))
if [ "$NEW_FAILURES" -gt 0 ]; then
  echo "FAIL — $NEW_FAILURES new test failure(s) introduced"
  # Show which tests failed
  echo "$TEST_OUTPUT" | jq -r '.testResults[] | select(.status=="failed") | .name' 2>/dev/null
else
  echo "PASS — no new failures (baseline: $BASELINE_FAILURES, current: $CURRENT_FAILURES)"
fi

FAIL if any new test failures introduced by the builder's changes.

CHECK 4: Import Resolution

Every relative import in changed source files must resolve to an existing file.

IMPORT_FAILURES=0
IMPORT_DETAILS=""

if [ -n "$CHANGED_JS" ]; then
  while IFS= read -r file; do
    [ -z "$file" ] && continue
    DIR=$(dirname "$file")

    # Extract relative imports (require or import ... from)
    IMPORTS=$(grep -oE "(require\(['\"]\.\.?/[^'\"]+['\"]|from ['\"]\.\.?/[^'\"]+['\"])" "$file" 2>/dev/null | grep -oE '\.\.?/[^'\"]+' || true)

    while IFS= read -r imp; do
      [ -z "$imp" ] && continue
      RESOLVED="$DIR/$imp"

      # Check: exact path, .js, .jsx, /index.js, /index.jsx
      FOUND=0
      for EXT in "" ".js" ".jsx" "/index.js" "/index.jsx"; do
        if [ -f "${RESOLVED}${EXT}" ]; then
          FOUND=1
          break
        fi
      done

      if [ "$FOUND" -eq 0 ]; then
        IMPORT_FAILURES=$((IMPORT_FAILURES + 1))
        IMPORT_DETAILS="${IMPORT_DETAILS}\n  $file -> $imp (not found)"
      fi
    done <<< "$IMPORTS"
  done <<< "$CHANGED_JS"
fi

if [ "$IMPORT_FAILURES" -gt 0 ]; then
  echo "FAIL — $IMPORT_FAILURES unresolved import(s):$IMPORT_DETAILS"
else
  echo "PASS"
fi

FAIL if any relative import does not resolve to an existing file.

CHECK 5: Data Shape Verification

Components must not read fields that don't exist in their data source.

SHAPE_FAILURES=0
SHAPE_DETAILS=""

if [ -n "$CHANGED_FRONTEND" ]; then
  CHANGED_COMPONENTS=$(echo "$CHANGED_FRONTEND" | grep -E '\.(jsx|js)$' | grep -v '__tests__' || true)

  while IFS= read -r comp; do
    [ -z "$comp" ] && continue

    # Find props destructuring from hooks (useQuery, useSearch, useState patterns)
    # Look for data.fieldName or result.fieldName access patterns
    ACCESSED_FIELDS=$(grep -oE '(data|result|response|item|row)\.[a-zA-Z_]+' "$comp" 2>/dev/null | sort -u || true)

    if [ -n "$ACCESSED_FIELDS" ]; then
      # Check if the component file also defines or receives these fields
      # Flag any field accessed on data/result objects that isn't defined in the same file
      # or in the API route/service that feeds it
      HOOK_CALLS=$(grep -oE 'use(Query|Mutation|Search|Fetch)\([^)]*\)' "$comp" 2>/dev/null || true)

      if [ -n "$HOOK_CALLS" ] && [ -n "$ACCESSED_FIELDS" ]; then
        # Extract API endpoint from hook call
        API_PATH=$(grep -oE "['\"]/api/[^'\"]*['\"]" "$comp" 2>/dev/null | head -1 | tr -d "'\"" || true)

        if [ -n "$API_PATH" ]; then
          # Find the route handler
          ROUTE_FILE=$(grep -rl "$API_PATH" $SOURCE_DIR/routes/ 2>/dev/null | head -1 || true)

          if [ -n "$ROUTE_FILE" ]; then
            while IFS= read -r field_access; do
              FIELD=$(echo "$field_access" | cut -d. -f2)
              # Check if field exists in route handler or its service
              if ! grep -q "$FIELD" "$ROUTE_FILE" 2>/dev/null; then
                SHAPE_FAILURES=$((SHAPE_FAILURES + 1))
                SHAPE_DETAILS="${SHAPE_DETAILS}\n  $comp accesses .$FIELD but not found in $ROUTE_FILE"
              fi
            done <<< "$ACCESSED_FIELDS"
          fi
        fi
      fi
    fi
  done <<< "$CHANGED_COMPONENTS"
fi

if [ "$SHAPE_FAILURES" -gt 0 ]; then
  echo "FAIL — $SHAPE_FAILURES data shape mismatch(es):$SHAPE_DETAILS"
else
  echo "PASS"
fi

FAIL if a component reads a field that the data source does not provide.

CHECK 6: Build Passes (frontend only)

if [ -z "$CHANGED_FRONTEND" ]; then
  echo "SKIP — no frontend files changed"
else
  BUILD_OUTPUT=$(cd $FRONTEND_DIR && $BUILD_CMD 2>&1)
  BUILD_EXIT=$?

  if [ "$BUILD_EXIT" -ne 0 ]; then
    echo "FAIL — vite build exited $BUILD_EXIT"
    echo "$BUILD_OUTPUT" | tail -20
  else
    echo "PASS"
  fi
fi

FAIL if build exits non-zero. SKIP if no frontend files changed.

CHECK 7: File Size Limits

Soft limit 400 lines (WARN), hard limit 800 lines (FAIL). Only checks files changed by the builder, not pre-existing legacy.

SIZE_FAIL=0
SIZE_WARN=0
SIZE_DETAILS=""

if [ -n "$CHANGED_SRC_FILES" ]; then
  while IFS= read -r file; do
    [ -z "$file" ] && continue
    [ ! -f "$file" ] && continue

    LINES=$(wc -l < "$file")

    # Check if file existed before the builder's changes
    EXISTED_BEFORE=$(git show "$BASE:$file" 2>/dev/null && echo "yes" || echo "no")

    if [ "$EXISTED_BEFORE" = "yes" ]; then
      OLD_LINES=$(git show "$BASE:$file" 2>/dev/null | wc -l)
      # Only flag if the builder made it worse
      if [ "$LINES" -gt 800 ] && [ "$OLD_LINES" -le 800 ]; then
        SIZE_FAIL=$((SIZE_FAIL + 1))
        SIZE_DETAILS="${SIZE_DETAILS}\n  FAIL: $file ($OLD_LINES -> $LINES lines, crossed 800 hard limit)"
      elif [ "$LINES" -gt 400 ] && [ "$OLD_LINES" -le 400 ]; then
        SIZE_WARN=$((SIZE_WARN + 1))
        SIZE_DETAILS="${SIZE_DETAILS}\n  WARN: $file ($OLD_LINES -> $LINES lines, crossed 400 soft limit)"
      fi
    else
      # New file created by builder
      if [ "$LINES" -gt 800 ]; then
        SIZE_FAIL=$((SIZE_FAIL + 1))
        SIZE_DETAILS="${SIZE_DETAILS}\n  FAIL: $file (new file, $LINES lines > 800 hard limit)"
      elif [ "$LINES" -gt 400 ]; then
        SIZE_WARN=$((SIZE_WARN + 1))
        SIZE_DETAILS="${SIZE_DETAILS}\n  WARN: $file (new file, $LINES lines > 400 soft limit)"
      fi
    fi
  done <<< "$CHANGED_SRC_FILES"
fi

if [ "$SIZE_FAIL" -gt 0 ]; then
  echo "FAIL — $SIZE_FAIL file(s) over hard limit:$SIZE_DETAILS"
elif [ "$SIZE_WARN" -gt 0 ]; then
  echo "WARN — $SIZE_WARN file(s) over soft limit:$SIZE_DETAILS"
else
  echo "PASS"
fi

FAIL if any changed file crosses 800. WARN if any crosses 400.

CHECK 8: No Debug Artifacts

Scan the diff for debug statements and markers that should not ship.

DEBUG_HITS=""

DIFF=$(git diff "$BASE...$BRANCH" -- $CHANGED_SRC_FILES 2>/dev/null || true)

if [ -n "$DIFF" ]; then
  # Only look at added lines (starts with +, not ++)
  ADDED_LINES=$(echo "$DIFF" | grep '^+' | grep -v '^+++' || true)

  # Check for debug artifacts, excluding console.error in catch/error blocks
  ARTIFACTS=$(echo "$ADDED_LINES" | grep -nE '(console\.(log|debug|warn|info)|debugger;|// TODO|// FIXME|// HACK|// XXX)' || true)

  if [ -n "$ARTIFACTS" ]; then
    # Filter out console.error (allowed in error handlers)
    REAL_HITS=$(echo "$ARTIFACTS" | grep -v 'console\.error' || true)

    if [ -n "$REAL_HITS" ]; then
      DEBUG_HITS="$REAL_HITS"
    fi
  fi
fi

if [ -n "$DEBUG_HITS" ]; then
  echo "FAIL — debug artifacts found in diff:"
  echo "$DEBUG_HITS" | head -20
else
  echo "PASS"
fi

FAIL if any debug artifacts found in added lines (excluding test files and console.error in error handlers).

CHECK 9: Pattern Quality

Heuristic warnings for code smells. These produce WARN, not FAIL.

PATTERN_WARNS=""

if [ -n "$CHANGED_SRC_FILES" ]; then
  while IFS= read -r file; do
    [ -z "$file" ] && continue
    [ ! -f "$file" ] && continue

    # 9a: If-chains — 3+ type-check branches in same function
    IF_CHAINS=$(grep -cE '(typeof|instanceof|===?\s*['''"][a-z]+['''"])' "$file" 2>/dev/null || echo 0)
    if [ "$IF_CHAINS" -ge 3 ]; then
      PATTERN_WARNS="${PATTERN_WARNS}\n  WARN 9a: $file has $IF_CHAINS type-check branches (consider polymorphism/map)"
    fi

    # 9b: Duplicated patterns — same non-trivial line appears 3+ times
    DUPES=$(grep -vE '^\s*(//|$|\{|\}|import|const|let|var|return|export)' "$file" 2>/dev/null | sort | uniq -c | sort -rn | awk '$1 >= 3 && length($0) > 30 {print}' | head -3 || true)
    if [ -n "$DUPES" ]; then
      PATTERN_WARNS="${PATTERN_WARNS}\n  WARN 9b: $file has duplicated patterns:\n$DUPES"
    fi

    # 9c: Event listener consistency — modal event types should match listeners
    MODAL_OPENS=$(grep -oE "openModal\(['\"][^'\"]+['\"]" "$file" 2>/dev/null | grep -oE "['\"][^'\"]+['\"]" | sort -u || true)
    MODAL_LISTENERS=$(grep -oE "onModalClose\(['\"][^'\"]+['\"]|modalType\s*===?\s*['\"][^'\"]+['\"]" "$file" 2>/dev/null | grep -oE "['\"][^'\"]+['\"]" | sort -u || true)
    if [ -n "$MODAL_OPENS" ] && [ -n "$MODAL_LISTENERS" ]; then
      UNMATCHED=$(comm -23 <(echo "$MODAL_OPENS") <(echo "$MODAL_LISTENERS") 2>/dev/null || true)
      if [ -n "$UNMATCHED" ]; then
        PATTERN_WARNS="${PATTERN_WARNS}\n  WARN 9c: $file opens modal types with no matching listener: $UNMATCHED"
      fi
    fi
  done <<< "$CHANGED_SRC_FILES"
fi

if [ -n "$PATTERN_WARNS" ]; then
  echo "WARN — pattern quality issues:$PATTERN_WARNS"
else
  echo "PASS"
fi

WARN only, never FAIL.

CHECK 10: Uncommitted Files

Any untracked file that is imported by a committed file must also be committed.

UNCOMMITTED_FAILS=0
UNCOMMITTED_DETAILS=""

# Get untracked .js/.jsx/.sql/.md files
UNTRACKED=$(git ls-files --others --exclude-standard | grep -E '\.(js|jsx|sql|md)$' || true)

if [ -n "$UNTRACKED" ] && [ -n "$CHANGED_JS" ]; then
  while IFS= read -r untracked_file; do
    [ -z "$untracked_file" ] && continue
    BASENAME=$(basename "$untracked_file" | sed 's/\.\(js\|jsx\)$//')

    # Check if any committed changed file imports this untracked file
    IMPORTERS=$(echo "$CHANGED_JS" | xargs grep -l "$BASENAME" 2>/dev/null || true)

    if [ -n "$IMPORTERS" ]; then
      UNCOMMITTED_FAILS=$((UNCOMMITTED_FAILS + 1))
      UNCOMMITTED_DETAILS="${UNCOMMITTED_DETAILS}\n  $untracked_file (imported by: $IMPORTERS)"
    fi
  done <<< "$UNTRACKED"
fi

if [ "$UNCOMMITTED_FAILS" -gt 0 ]; then
  echo "FAIL — $UNCOMMITTED_FAILS uncommitted file(s) referenced by committed code:$UNCOMMITTED_DETAILS"
else
  echo "PASS"
fi

FAIL if any untracked file is imported by a committed file.

Output Format

After running all 10 checks, produce the final report:

═══════════════════════════════════════════
           AGENT HARNESS RESULTS
═══════════════════════════════════════════
CHECK 1  Contract Exists ........... [PASS/FAIL]
CHECK 2  Tests Per Postcondition ... [PASS/FAIL]
CHECK 3  Tests Pass ................ [PASS/FAIL]
CHECK 4  Import Resolution ......... [PASS/FAIL]
CHECK 5  Data Shape Verification ... [PASS/FAIL]
CHECK 6  Build Passes .............. [PASS/FAIL/SKIP]
CHECK 7  File Size Limits .......... [PASS/FAIL/WARN]
CHECK 8  No Debug Artifacts ........ [PASS/FAIL]
CHECK 9  Pattern Quality ........... [PASS/WARN]
CHECK 10 Uncommitted Files ......... [PASS/FAIL]
───────────────────────────────────────────
VERDICT: [PASS / FAIL]
FAILURES: [list each FAIL with details]
WARNINGS: [list each WARN with details]
═══════════════════════════════════════════

PERSIST HARNESS RESULTS (JSON)

After running all 10 checks, append results to the verification log JSON. This shares the same log file as enterprise-verify — all verification attempts (both verify and harness) appear in one audit trail.

node -e "
  const fs = require('fs');
  const f = '.claude/enterprise-state/<slug>-verification.json';
  let log = { verifications: [] };
  try { log = JSON.parse(fs.readFileSync(f)); } catch(e) {}
  log.verifications.push({
    type: 'harness',
    timestamp: new Date().toISOString(),
    checks: {
      contract_exists:       { result: '<PASS/FAIL>' },
      tests_per_pc:          { result: '<PASS/FAIL>', test_count: <N>, pc_count: <N> },
      tests_pass:            { result: '<PASS/FAIL>', new_failures: <N> },
      import_resolution:     { result: '<PASS/FAIL>', unresolved: <N> },
      data_shape:            { result: '<PASS/FAIL>', mismatches: <N> },
      build:                 { result: '<PASS/FAIL/SKIP>' },
      file_size:             { result: '<PASS/FAIL/WARN>' },
      debug_artifacts:       { result: '<PASS/FAIL>' },
      pattern_quality:       { result: '<PASS/WARN>' },
      uncommitted_files:     { result: '<PASS/FAIL>' }
    },
    overall: '<PASS/FAIL>'
  });
  fs.writeFileSync(f, JSON.stringify(log, null, 2));
  console.log('Harness results logged (' + log.verifications.length + ' total attempts)');
"

Rules:

• Same file as enterprise-verify — .claude/enterprise-state/<slug>-verification.json
• Always append, never overwrite
• Fill in actual values from the check results

Decision Rules

Re-run Policy

• Maximum 3 re-run iterations per task.
• After 3 failures, escalate to human with full harness output from all 3 runs.
• Each re-run must show improvement (fewer FAILs) or escalation triggers immediately.

Usage

The orchestrator invokes this skill after receiving code from a builder:

1. Set TASK_SLUG, BRANCH, BASE variables.
2. Run all 10 checks in order.
3. Format the output report.
4. Apply decision rules.
5. If FAIL: send failure details back to builder, increment iteration counter.
6. If PASS: proceed to merge/cherry-pick.