---
phase: 07-import-cicd
plan: 06
type: execute
wave: 2
depends_on: ["07-04", "07-05"]
files_modified:
  - docs/CI-CD.md
  - README.md
autonomous: true
requirements: [CICD-01, CICD-02]
must_haves:
  truths:
    - "Users have a documented GitHub Actions workflow example that runs keyhunter and uploads SARIF"
    - "Pre-commit hook setup is documented with install/uninstall commands"
    - "README references the new CI/CD document"
  artifacts:
    - path: docs/CI-CD.md
      provides: "CI/CD integration guide (GitHub Actions + pre-commit hook)"
      contains: "github/codeql-action/upload-sarif"
    - path: README.md
      provides: "Top-level project README (updated to link CI/CD guide)"
  key_links:
    - from: README.md
      to: docs/CI-CD.md
      via: "markdown link"
      pattern: "docs/CI-CD\\.md"
---

<objective>
Document the Phase 7 deliverables: import command usage, pre-commit hook lifecycle, and GitHub Actions workflow for SARIF upload.

Purpose: CICD-01 and CICD-02 require the integration to be discoverable by users. Code alone is not enough — a working workflow example and hook setup walkthrough are part of the requirement.
Output: docs/CI-CD.md, README section linking to it.
</objective>

<execution_context>
@$HOME/.claude/get-shit-done/workflows/execute-plan.md
@$HOME/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/phases/07-import-cicd/07-CONTEXT.md
@README.md
</context>

<tasks>

<task type="auto">
  <name>Task 1: Write docs/CI-CD.md with GitHub Actions + pre-commit guide</name>
  <files>docs/CI-CD.md</files>
  <action>
    Create docs/CI-CD.md with the following sections (markdown):

    1. **Title & intro** — "KeyHunter CI/CD Integration" — one paragraph explaining scope: pre-commit hooks, GitHub Actions SARIF upload, importing external scanner output.

    2. **Pre-commit Hook** section:
       - Install: `keyhunter hook install` (explain what file is written, where).
       - Override: `--force` flag backs up existing pre-commit as `pre-commit.bak.<timestamp>`.
       - Bypass a single commit: `git commit --no-verify`.
       - Uninstall: `keyhunter hook uninstall`.
       - Note: only scans staged files via `git diff --cached --name-only --diff-filter=ACMR`.

    3. **GitHub Actions (SARIF upload to Code Scanning)** section, with a full working workflow example saved as a fenced yaml block:
       ```yaml
       name: KeyHunter
       on:
         push:
           branches: [main]
         pull_request:
       jobs:
         scan:
           runs-on: ubuntu-latest
           permissions:
             contents: read
             security-events: write
           steps:
             - uses: actions/checkout@v4
               with:
                 fetch-depth: 0
             - name: Install KeyHunter
               run: |
                 curl -sSL https://github.com/salvacybersec/keyhunter/releases/latest/download/keyhunter_linux_amd64.tar.gz | tar -xz
                 sudo mv keyhunter /usr/local/bin/
             - name: Scan repository
               run: keyhunter scan . --output sarif > keyhunter.sarif
               continue-on-error: true
             - name: Upload SARIF to GitHub Code Scanning
               uses: github/codeql-action/upload-sarif@v3
               with:
                 sarif_file: keyhunter.sarif
                 category: keyhunter
       ```
       - Explain `continue-on-error: true` — scan exits 1 on findings; we want the SARIF upload step to still run. The findings show up in the Security tab.
       - Explain the required `security-events: write` permission.

    4. **Importing External Scanner Output** section:
       - Running TruffleHog then importing:
         ```
         trufflehog filesystem . --json > trufflehog.json
         keyhunter import --format=trufflehog trufflehog.json
         ```
       - Gitleaks JSON:
         ```
         gitleaks detect -f json -r gitleaks.json
         keyhunter import --format=gitleaks gitleaks.json
         ```
       - Gitleaks CSV:
         ```
         gitleaks detect -f csv -r gitleaks.csv
         keyhunter import --format=gitleaks-csv gitleaks.csv
         ```
       - Dedup guarantee: re-running the same import is idempotent.

    5. **Exit Codes** section — table of 0/1/2 semantics for CI integration.

    Keep the whole file under ~200 lines. No emojis.
  </action>
  <verify>
    <automated>test -f docs/CI-CD.md && grep -q "upload-sarif" docs/CI-CD.md && grep -q "keyhunter hook install" docs/CI-CD.md && grep -q "keyhunter import --format=trufflehog" docs/CI-CD.md</automated>
  </verify>
  <done>
    - docs/CI-CD.md exists with all 5 sections
    - Required strings present (upload-sarif, hook install, import --format=trufflehog)
  </done>
</task>

<task type="auto">
  <name>Task 2: Update README.md with CI/CD integration link</name>
  <files>README.md</files>
  <action>
    Read current README.md first.

    Add (or update if a stub section exists) a "CI/CD Integration" H2 section that:
    - Contains 2-4 sentences summarizing pre-commit hook + GitHub SARIF upload support.
    - Links to `docs/CI-CD.md` for the full guide.
    - Mentions `keyhunter import` for TruffleHog/Gitleaks consolidation.

    Place the section after any existing "Installation" / "Usage" section and before "Development" or "License" sections. If those anchors don't exist, append near the end but before "License".

    Do not rewrite unrelated parts of the README.
  </action>
  <verify>
    <automated>grep -q "docs/CI-CD.md" README.md && grep -q "CI/CD" README.md</automated>
  </verify>
  <done>
    - README.md references docs/CI-CD.md
    - CI/CD Integration section exists
  </done>
</task>

</tasks>

<verification>
grep -q "upload-sarif" docs/CI-CD.md && grep -q "docs/CI-CD.md" README.md
</verification>

<success_criteria>
CICD-01 and CICD-02 are discoverable end-to-end: a user landing on the README can find CI/CD guidance, follow it to docs/CI-CD.md, and copy a working GitHub Actions workflow + pre-commit setup.
</success_criteria>

<output>
After completion, create `.planning/phases/07-import-cicd/07-06-SUMMARY.md`.
</output>