feed-the-machine 1.6.0 → 1.7.0

package/ftm-git/evals/evals.json

@@ -1,26 +1,26 @@
-{
-  "skill_name": "ftm-git",
-  "evals": [
-    {
-      "id": 1,
-      "name": "python-stripe-aws",
-      "prompt": "I just finished the payments module. commit this and push it up",
-      "expected_output": "Should detect sk_live_ Stripe key, AKIA AWS access key, and AWS secret. Should extract all three to .env, refactor payments.py to use os.environ/os.getenv, add .env to .gitignore, and block the commit until remediated.",
-      "files": ["test-fixtures/payments.py"]
-    },
-    {
-      "id": 2,
-      "name": "js-config-unignored-env",
-      "prompt": "hey can you scan this repo for any secrets before I share it with the new contractor",
-      "expected_output": "Should find Google API key, Slack bot token, Slack webhook, and SendGrid key in config.js. Should also flag .env not being in .gitignore. Should extract secrets to .env, refactor config.js to use process.env, ensure .gitignore covers .env files.",
-      "files": ["test-fixtures/config.js", "test-fixtures/.env"]
-    },
-    {
-      "id": 3,
-      "name": "yaml-google-key-in-ci",
-      "prompt": "push to main",
-      "expected_output": "Should detect Google API key hardcoded in deploy.yml env block, the RSA private key, and the Slack webhook URL. Should flag that CI files need to use GitHub Actions secrets (${{ secrets.VAR }}) instead of hardcoded values. Should block the push.",
-      "files": ["test-fixtures/deploy.yml"]
-    }
-  ]
-}
+{
+  "skill_name": "ftm-git",
+  "evals": [
+    {
+      "id": 1,
+      "name": "python-stripe-aws",
+      "prompt": "I just finished the payments module. commit this and push it up",
+      "expected_output": "Should detect sk_live_ Stripe key, AKIA AWS access key, and AWS secret. Should extract all three to .env, refactor payments.py to use os.environ/os.getenv, add .env to .gitignore, and block the commit until remediated.",
+      "files": ["test-fixtures/payments.py"]
+    },
+    {
+      "id": 2,
+      "name": "js-config-unignored-env",
+      "prompt": "hey can you scan this repo for any secrets before I share it with the new contractor",
+      "expected_output": "Should find Google API key, Slack bot token, Slack webhook, and SendGrid key in config.js. Should also flag .env not being in .gitignore. Should extract secrets to .env, refactor config.js to use process.env, ensure .gitignore covers .env files.",
+      "files": ["test-fixtures/config.js", "test-fixtures/.env"]
+    },
+    {
+      "id": 3,
+      "name": "yaml-google-key-in-ci",
+      "prompt": "push to main",
+      "expected_output": "Should detect Google API key hardcoded in deploy.yml env block, the RSA private key, and the Slack webhook URL. Should flag that CI files need to use GitHub Actions secrets (${{ secrets.VAR }}) instead of hardcoded values. Should block the push.",
+      "files": ["test-fixtures/deploy.yml"]
+    }
+  ]
+}

package/ftm-git/evals/promptfoo.yaml

@@ -1,75 +1,75 @@
-description: "ftm-git secret detection and remediation"
-
-prompts:
-  - "{{input}}"
-
-providers:
-  - id: "exec:claude --print"
-    label: "claude-code"
-
-tests:
-  # Eval 1: python-stripe-aws
-  - description: "detects Stripe live key and AWS credentials, extracts to .env, blocks commit"
-    vars:
-      input: "I just finished the payments module. commit this and push it up"
-    assert:
-      - type: regex
-        value: "sk_live_|stripe|Stripe"
-        description: "Detects the Stripe live key"
-      - type: regex
-        value: "AKIA|AWS|aws"
-        description: "Detects the AWS access key"
-      - type: regex
-        value: "\\.env"
-        description: "References .env file for secret extraction"
-      - type: regex
-        value: "\\.gitignore"
-        description: "References .gitignore to prevent committing secrets"
-      - type: regex
-        value: "block|blocked|cannot commit|will not commit|stop|halt|remediat"
-        description: "Blocks the commit until secrets are remediated"
-
-  # Eval 2: js-config-unignored-env
-  - description: "detects multiple secrets in config.js, flags missing .gitignore entry, extracts to .env"
-    vars:
-      input: "hey can you scan this repo for any secrets before I share it with the new contractor"
-    assert:
-      - type: regex
-        value: "Google|GOOGLE|AIza"
-        description: "Detects the Google API key"
-      - type: regex
-        value: "Slack|slack|xoxb"
-        description: "Detects the Slack token"
-      - type: regex
-        value: "SendGrid|sendgrid|SG\\."
-        description: "Detects the SendGrid key"
-      - type: regex
-        value: "\\.env"
-        description: "References .env file for secret extraction"
-      - type: regex
-        value: "\\.gitignore"
-        description: "Flags .gitignore coverage issue"
-      - type: regex
-        value: "process\\.env"
-        description: "Recommends using process.env in refactored code"
-
-  # Eval 3: yaml-google-key-in-ci
-  - description: "detects hardcoded secrets in CI yaml, recommends GitHub Actions secrets, blocks push"
-    vars:
-      input: "push to main"
-    assert:
-      - type: regex
-        value: "Google|GOOGLE|AIza|deploy\\.yml|CI|ci"
-        description: "Detects the Google API key in the CI file"
-      - type: regex
-        value: "RSA|private key|BEGIN RSA|-----BEGIN"
-        description: "Detects the RSA private key"
-      - type: regex
-        value: "Slack|slack|webhook"
-        description: "Detects the Slack webhook URL"
-      - type: regex
-        value: "secrets\\.|\\$\\{\\{|GitHub Actions|github actions|Actions secret"
-        description: "Recommends using GitHub Actions secrets instead of hardcoded values"
-      - type: regex
-        value: "block|blocked|cannot push|will not push|stop|halt|remediat"
-        description: "Blocks the push until secrets are remediated"
+description: "ftm-git secret detection and remediation"
+
+prompts:
+  - "{{input}}"
+
+providers:
+  - id: "exec:claude --print"
+    label: "claude-code"
+
+tests:
+  # Eval 1: python-stripe-aws
+  - description: "detects Stripe live key and AWS credentials, extracts to .env, blocks commit"
+    vars:
+      input: "I just finished the payments module. commit this and push it up"
+    assert:
+      - type: regex
+        value: "sk_live_|stripe|Stripe"
+        description: "Detects the Stripe live key"
+      - type: regex
+        value: "AKIA|AWS|aws"
+        description: "Detects the AWS access key"
+      - type: regex
+        value: "\\.env"
+        description: "References .env file for secret extraction"
+      - type: regex
+        value: "\\.gitignore"
+        description: "References .gitignore to prevent committing secrets"
+      - type: regex
+        value: "block|blocked|cannot commit|will not commit|stop|halt|remediat"
+        description: "Blocks the commit until secrets are remediated"
+
+  # Eval 2: js-config-unignored-env
+  - description: "detects multiple secrets in config.js, flags missing .gitignore entry, extracts to .env"
+    vars:
+      input: "hey can you scan this repo for any secrets before I share it with the new contractor"
+    assert:
+      - type: regex
+        value: "Google|GOOGLE|AIza"
+        description: "Detects the Google API key"
+      - type: regex
+        value: "Slack|slack|xoxb"
+        description: "Detects the Slack token"
+      - type: regex
+        value: "SendGrid|sendgrid|SG\\."
+        description: "Detects the SendGrid key"
+      - type: regex
+        value: "\\.env"
+        description: "References .env file for secret extraction"
+      - type: regex
+        value: "\\.gitignore"
+        description: "Flags .gitignore coverage issue"
+      - type: regex
+        value: "process\\.env"
+        description: "Recommends using process.env in refactored code"
+
+  # Eval 3: yaml-google-key-in-ci
+  - description: "detects hardcoded secrets in CI yaml, recommends GitHub Actions secrets, blocks push"
+    vars:
+      input: "push to main"
+    assert:
+      - type: regex
+        value: "Google|GOOGLE|AIza|deploy\\.yml|CI|ci"
+        description: "Detects the Google API key in the CI file"
+      - type: regex
+        value: "RSA|private key|BEGIN RSA|-----BEGIN"
+        description: "Detects the RSA private key"
+      - type: regex
+        value: "Slack|slack|webhook"
+        description: "Detects the Slack webhook URL"
+      - type: regex
+        value: "secrets\\.|\\$\\{\\{|GitHub Actions|github actions|Actions secret"
+        description: "Recommends using GitHub Actions secrets instead of hardcoded values"
+      - type: regex
+        value: "block|blocked|cannot push|will not push|stop|halt|remediat"
+        description: "Blocks the push until secrets are remediated"

package/ftm-git/hooks/post-commit-experience.sh

@@ -1,92 +1,92 @@
-#!/usr/bin/env bash
-
-# FTM Post-Commit Experience Recorder
-# Ensures every commit produces at least a minimal experience entry.
-# Only creates an entry if one hasn't been recorded recently (2+ min gap).
-
-set -euo pipefail
-
-STATE_DIR="$HOME/.claude/ftm-state/blackboard"
-EXPERIENCES_DIR="$STATE_DIR/experiences"
-INDEX_FILE="$EXPERIENCES_DIR/index.json"
-
-# Ensure directories exist
-mkdir -p "$EXPERIENCES_DIR"
-
-# Check if an experience was recorded in the last 2 minutes
-RECENT_THRESHOLD=$(($(date +%s) - 120))
-LATEST_EXPERIENCE=""
-
-if [ -d "$EXPERIENCES_DIR" ]; then
-  LATEST_EXPERIENCE=$(find "$EXPERIENCES_DIR" -name "*.json" -not -name "index.json" -newer /dev/null -maxdepth 1 2>/dev/null | sort -r | head -1)
-fi
-
-if [ -n "$LATEST_EXPERIENCE" ]; then
-  # Check if the latest experience file was modified within the last 2 minutes
-  if [ "$(uname)" = "Darwin" ]; then
-    FILE_TIME=$(stat -f %m "$LATEST_EXPERIENCE" 2>/dev/null || echo 0)
-  else
-    FILE_TIME=$(stat -c %Y "$LATEST_EXPERIENCE" 2>/dev/null || echo 0)
-  fi
-
-  if [ "$FILE_TIME" -gt "$RECENT_THRESHOLD" ]; then
-    # Experience was recently recorded by the LLM — skip
-    exit 0
-  fi
-fi
-
-# Extract commit metadata
-COMMIT_HASH=$(git rev-parse --short HEAD)
-COMMIT_MSG=$(git log -1 --pretty=%s)
-COMMIT_DATE=$(date +%Y-%m-%d)
-COMMIT_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
-FILES_CHANGED=$(git diff-tree --no-commit-id --name-only -r HEAD | tr '\n' ', ' | sed 's/,$//')
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-# Generate a slug from commit message
-SLUG=$(echo "$COMMIT_MSG" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-50)
-FILENAME="${COMMIT_DATE}_${SLUG}.json"
-
-# Don't create duplicate if file already exists
-if [ -f "$EXPERIENCES_DIR/$FILENAME" ]; then
-  exit 0
-fi
-
-# Create minimal experience entry
-cat > "$EXPERIENCES_DIR/$FILENAME" << EXPEOF
-{
-  "task_type": "commit",
-  "description": "$COMMIT_MSG",
-  "source": "git-hook",
-  "timestamp": "$COMMIT_TIME",
-  "commit_hash": "$COMMIT_HASH",
-  "branch": "$BRANCH",
-  "files_changed": "$FILES_CHANGED",
-  "complexity_estimated": "micro",
-  "complexity_actual": "micro",
-  "outcome": "success",
-  "confidence": 0.5,
-  "tags": ["auto-recorded", "git-commit"],
-  "lessons": []
-}
-EXPEOF
-
-# Update index.json
-# Read existing index, add new entry, write back
-if [ -f "$INDEX_FILE" ]; then
-  # Use node for reliable JSON manipulation (available in FTM environments)
-  node -e "
-    const fs = require('fs');
-    const idx = JSON.parse(fs.readFileSync('$INDEX_FILE', 'utf-8'));
-    idx.entries.push({
-      file: '$FILENAME',
-      task_type: 'commit',
-      tags: ['auto-recorded', 'git-commit'],
-      timestamp: '$COMMIT_TIME',
-      confidence: 0.5
-    });
-    idx.metadata.total_count = idx.entries.length;
-    idx.metadata.last_updated = '$COMMIT_TIME';
-    fs.writeFileSync('$INDEX_FILE', JSON.stringify(idx, null, 2));
-  " 2>/dev/null || true
-fi
+#!/usr/bin/env bash
+
+# FTM Post-Commit Experience Recorder
+# Ensures every commit produces at least a minimal experience entry.
+# Only creates an entry if one hasn't been recorded recently (2+ min gap).
+
+set -euo pipefail
+
+STATE_DIR="$HOME/.claude/ftm-state/blackboard"
+EXPERIENCES_DIR="$STATE_DIR/experiences"
+INDEX_FILE="$EXPERIENCES_DIR/index.json"
+
+# Ensure directories exist
+mkdir -p "$EXPERIENCES_DIR"
+
+# Check if an experience was recorded in the last 2 minutes
+RECENT_THRESHOLD=$(($(date +%s) - 120))
+LATEST_EXPERIENCE=""
+
+if [ -d "$EXPERIENCES_DIR" ]; then
+  LATEST_EXPERIENCE=$(find "$EXPERIENCES_DIR" -name "*.json" -not -name "index.json" -newer /dev/null -maxdepth 1 2>/dev/null | sort -r | head -1)
+fi
+
+if [ -n "$LATEST_EXPERIENCE" ]; then
+  # Check if the latest experience file was modified within the last 2 minutes
+  if [ "$(uname)" = "Darwin" ]; then
+    FILE_TIME=$(stat -f %m "$LATEST_EXPERIENCE" 2>/dev/null || echo 0)
+  else
+    FILE_TIME=$(stat -c %Y "$LATEST_EXPERIENCE" 2>/dev/null || echo 0)
+  fi
+
+  if [ "$FILE_TIME" -gt "$RECENT_THRESHOLD" ]; then
+    # Experience was recently recorded by the LLM — skip
+    exit 0
+  fi
+fi
+
+# Extract commit metadata
+COMMIT_HASH=$(git rev-parse --short HEAD)
+COMMIT_MSG=$(git log -1 --pretty=%s)
+COMMIT_DATE=$(date +%Y-%m-%d)
+COMMIT_TIME=$(date -u +%Y-%m-%dT%H:%M:%SZ)
+FILES_CHANGED=$(git diff-tree --no-commit-id --name-only -r HEAD | tr '\n' ', ' | sed 's/,$//')
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Generate a slug from commit message
+SLUG=$(echo "$COMMIT_MSG" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | cut -c1-50)
+FILENAME="${COMMIT_DATE}_${SLUG}.json"
+
+# Don't create duplicate if file already exists
+if [ -f "$EXPERIENCES_DIR/$FILENAME" ]; then
+  exit 0
+fi
+
+# Create minimal experience entry
+cat > "$EXPERIENCES_DIR/$FILENAME" << EXPEOF
+{
+  "task_type": "commit",
+  "description": "$COMMIT_MSG",
+  "source": "git-hook",
+  "timestamp": "$COMMIT_TIME",
+  "commit_hash": "$COMMIT_HASH",
+  "branch": "$BRANCH",
+  "files_changed": "$FILES_CHANGED",
+  "complexity_estimated": "micro",
+  "complexity_actual": "micro",
+  "outcome": "success",
+  "confidence": 0.5,
+  "tags": ["auto-recorded", "git-commit"],
+  "lessons": []
+}
+EXPEOF
+
+# Update index.json
+# Read existing index, add new entry, write back
+if [ -f "$INDEX_FILE" ]; then
+  # Use node for reliable JSON manipulation (available in FTM environments)
+  node -e "
+    const fs = require('fs');
+    const idx = JSON.parse(fs.readFileSync('$INDEX_FILE', 'utf-8'));
+    idx.entries.push({
+      file: '$FILENAME',
+      task_type: 'commit',
+      tags: ['auto-recorded', 'git-commit'],
+      timestamp: '$COMMIT_TIME',
+      confidence: 0.5
+    });
+    idx.metadata.total_count = idx.entries.length;
+    idx.metadata.last_updated = '$COMMIT_TIME';
+    fs.writeFileSync('$INDEX_FILE', JSON.stringify(idx, null, 2));
+  " 2>/dev/null || true
+fi

package/ftm-git/references/patterns/SECRET-PATTERNS.md

@@ -1,104 +1,104 @@
-# Secret Patterns — Extended Pattern Library
-
-Full regex pattern library for Phase 1 scanning. Tier 1 patterns are high-confidence; Tier 2 require surrounding context validation.
-
----
-
-## Tier 1: High-Confidence Patterns (almost certainly real secrets)
-
-These patterns have distinctive prefixes or structures that make false positives rare. Run in parallel.
-
-```
-# AWS
-AKIA[0-9A-Z]{16}                                          # AWS Access Key ID
-amzn\.mws\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}  # AWS MWS
-
-# GitHub
-ghp_[A-Za-z0-9_]{36}                                      # GitHub PAT (classic)
-gho_[A-Za-z0-9_]{36}                                      # GitHub OAuth
-ghu_[A-Za-z0-9_]{36}                                      # GitHub user token
-ghs_[A-Za-z0-9_]{36}                                      # GitHub server token
-github_pat_[A-Za-z0-9_]{82}                                # GitHub fine-grained PAT
-
-# Slack
-xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}           # Slack bot token
-xoxp-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack user token
-xoxa-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack app token
-xoxr-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack refresh token
-
-# Google
-AIza[0-9A-Za-z\-_]{35}                                    # Google API key
-
-# Stripe
-sk_live_[0-9a-zA-Z]{24,}                                  # Stripe secret key (live)
-sk_test_[0-9a-zA-Z]{24,}                                  # Stripe secret key (test)
-rk_live_[0-9a-zA-Z]{24,}                                  # Stripe restricted key
-
-# Other services
-SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}               # SendGrid
-SK[0-9a-fA-F]{32}                                          # Twilio
-npm_[A-Za-z0-9]{36}                                        # npm token
-pypi-[A-Za-z0-9\-_]{100,}                                 # PyPI token
-glpat-[A-Za-z0-9\-_]{20,}                                 # GitLab PAT
------BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY-----      # Private keys
-```
-
----
-
-## Tier 2: Context-Dependent Patterns (need surrounding context to confirm)
-
-These match common assignment patterns. Check that the value isn't a placeholder, empty string, or env var reference before flagging:
-
-```
-# Generic key/secret assignments — flag if value looks real (not placeholder)
-(api_key|apikey|api-key)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
-(secret|secret_key|client_secret)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
-(password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{8,}["']?
-(token|access_token|auth_token)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{16,}["']?
-(database_url|db_url|connection_string)\s*[:=]\s*["']?[^\s"']{20,}["']?
-
-# Bearer tokens in code
-bearer\s+[A-Za-z0-9\-._~+/]{20,}
-
-# Webhook URLs with tokens
-https://hooks\.slack\.com/services/T[A-Z0-9]{8,}/B[A-Z0-9]{8,}/[a-zA-Z0-9]{24}
-```
-
----
-
-## What to Ignore (false positive suppression)
-
-Skip matches that are clearly not real secrets:
-
-- Values that are `""`, `''`, `None`, `null`, `undefined`, `TODO`, `CHANGEME`, `your-key-here`, `xxx`, `placeholder`, `example`, `test`, `dummy`, `fake`, `sample`
-- References to environment variables: `os.environ[`, `process.env.`, `ENV[`, `${`, `os.getenv(`
-- Lines that are comments (`#`, `//`, `/*`, `--`)
-- Files in `node_modules/`, `.git/`, `vendor/`, `__pycache__/`, `dist/`, `build/`
-- Files that are themselves `.env.example`, `.env.sample`, `.env.template`
-- Lock files (`package-lock.json`, `yarn.lock`, `Gemfile.lock`, `poetry.lock`)
-- Test fixtures where the "secret" is obviously fake (e.g., `test_api_key = "sk_test_abc123"` in a test file — but still flag `sk_live_*` in test files, those are real)
-
----
-
-## Severity Classification
-
-After validation, findings are sorted by severity:
-
-| Severity | Meaning |
-|---|---|
-| **CRITICAL** | Tier 1 match (high-confidence secret) in a tracked or staged file |
-| **HIGH** | Tier 2 confirmed match in a tracked or staged file |
-| **MEDIUM** | `.env` file not in `.gitignore`, or secret in a fallback default |
-| **LOW** | Secret in a gitignored file but the gitignore rule might be fragile |
-
----
-
-## Per-Finding Record Format
-
-For each finding, record:
-- **file**: absolute path
-- **line**: line number
-- **pattern**: which pattern matched
-- **tier**: 1 or 2
-- **value_preview**: first 8 chars + `...` + last 4 chars (never log the full secret)
-- **context**: the surrounding code (with the secret value masked)
+# Secret Patterns — Extended Pattern Library
+
+Full regex pattern library for Phase 1 scanning. Tier 1 patterns are high-confidence; Tier 2 require surrounding context validation.
+
+---
+
+## Tier 1: High-Confidence Patterns (almost certainly real secrets)
+
+These patterns have distinctive prefixes or structures that make false positives rare. Run in parallel.
+
+```
+# AWS
+AKIA[0-9A-Z]{16}                                          # AWS Access Key ID
+amzn\.mws\.[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}  # AWS MWS
+
+# GitHub
+ghp_[A-Za-z0-9_]{36}                                      # GitHub PAT (classic)
+gho_[A-Za-z0-9_]{36}                                      # GitHub OAuth
+ghu_[A-Za-z0-9_]{36}                                      # GitHub user token
+ghs_[A-Za-z0-9_]{36}                                      # GitHub server token
+github_pat_[A-Za-z0-9_]{82}                                # GitHub fine-grained PAT
+
+# Slack
+xoxb-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24}           # Slack bot token
+xoxp-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack user token
+xoxa-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack app token
+xoxr-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}        # Slack refresh token
+
+# Google
+AIza[0-9A-Za-z\-_]{35}                                    # Google API key
+
+# Stripe
+sk_live_[0-9a-zA-Z]{24,}                                  # Stripe secret key (live)
+sk_test_[0-9a-zA-Z]{24,}                                  # Stripe secret key (test)
+rk_live_[0-9a-zA-Z]{24,}                                  # Stripe restricted key
+
+# Other services
+SG\.[A-Za-z0-9\-_]{22}\.[A-Za-z0-9\-_]{43}               # SendGrid
+SK[0-9a-fA-F]{32}                                          # Twilio
+npm_[A-Za-z0-9]{36}                                        # npm token
+pypi-[A-Za-z0-9\-_]{100,}                                 # PyPI token
+glpat-[A-Za-z0-9\-_]{20,}                                 # GitLab PAT
+-----BEGIN (RSA|DSA|EC|OPENSSH|PGP) PRIVATE KEY-----      # Private keys
+```
+
+---
+
+## Tier 2: Context-Dependent Patterns (need surrounding context to confirm)
+
+These match common assignment patterns. Check that the value isn't a placeholder, empty string, or env var reference before flagging:
+
+```
+# Generic key/secret assignments — flag if value looks real (not placeholder)
+(api_key|apikey|api-key)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
+(secret|secret_key|client_secret)\s*[:=]\s*["']?[A-Za-z0-9\-_]{16,}["']?
+(password|passwd|pwd)\s*[:=]\s*["']?[^\s"']{8,}["']?
+(token|access_token|auth_token)\s*[:=]\s*["']?[A-Za-z0-9\-_.]{16,}["']?
+(database_url|db_url|connection_string)\s*[:=]\s*["']?[^\s"']{20,}["']?
+
+# Bearer tokens in code
+bearer\s+[A-Za-z0-9\-._~+/]{20,}
+
+# Webhook URLs with tokens
+https://hooks\.slack\.com/services/T[A-Z0-9]{8,}/B[A-Z0-9]{8,}/[a-zA-Z0-9]{24}
+```
+
+---
+
+## What to Ignore (false positive suppression)
+
+Skip matches that are clearly not real secrets:
+
+- Values that are `""`, `''`, `None`, `null`, `undefined`, `TODO`, `CHANGEME`, `your-key-here`, `xxx`, `placeholder`, `example`, `test`, `dummy`, `fake`, `sample`
+- References to environment variables: `os.environ[`, `process.env.`, `ENV[`, `${`, `os.getenv(`
+- Lines that are comments (`#`, `//`, `/*`, `--`)
+- Files in `node_modules/`, `.git/`, `vendor/`, `__pycache__/`, `dist/`, `build/`
+- Files that are themselves `.env.example`, `.env.sample`, `.env.template`
+- Lock files (`package-lock.json`, `yarn.lock`, `Gemfile.lock`, `poetry.lock`)
+- Test fixtures where the "secret" is obviously fake (e.g., `test_api_key = "sk_test_abc123"` in a test file — but still flag `sk_live_*` in test files, those are real)
+
+---
+
+## Severity Classification
+
+After validation, findings are sorted by severity:
+
+| Severity | Meaning |
+|---|---|
+| **CRITICAL** | Tier 1 match (high-confidence secret) in a tracked or staged file |
+| **HIGH** | Tier 2 confirmed match in a tracked or staged file |
+| **MEDIUM** | `.env` file not in `.gitignore`, or secret in a fallback default |
+| **LOW** | Secret in a gitignored file but the gitignore rule might be fragile |
+
+---
+
+## Per-Finding Record Format
+
+For each finding, record:
+- **file**: absolute path
+- **line**: line number
+- **pattern**: which pattern matched
+- **tier**: 1 or 2
+- **value_preview**: first 8 chars + `...` + last 4 chars (never log the full secret)
+- **context**: the surrounding code (with the secret value masked)