Fix compliance audit and source standards from handbook (#20)

* Fix compliance audit workflow and source standards from handbook

- Add missing permissions (id-token, contents, issues) for OIDC auth
  and issue creation
- Fix direct_prompt → prompt (direct_prompt is not a valid input)
- Check out engineering-handbook repo as authoritative standards source
  instead of hardcoding the checklist in the workflow
- Create compliance label on-the-fly if it doesn't exist in target repo

* Fix compliance audit violation detection

Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com>

---------

Co-authored-by: Cursor Agent <cursoragent@cursor.com>
Co-authored-by: Adam Moussa <amoussa1229@users.noreply.github.com>

.github/workflows/compliance-audit.yaml

@@ -5,6 +5,11 @@ on:
     - cron: "0 14 * * 1" # Every Monday at 10am ET (14:00 UTC)
   workflow_dispatch:
 
+permissions:
+  id-token: write
+  contents: read
+  issues: write
+
 jobs:
   get-repos:
     runs-on: ubuntu-latest
@@ -49,7 +54,7 @@ jobs:
           app-id: ${{ secrets.CLAUDE_CI_APP_ID }}
           private-key: ${{ secrets.CLAUDE_CI_APP_PRIVATE_KEY }}
           owner: Sea-Haven-Industries
-          repositories: ${{ matrix.repo }}
+          repositories: ${{ matrix.repo }},engineering-handbook
 
       - name: Checkout repo
         uses: actions/checkout@v4
@@ -57,41 +62,51 @@ jobs:
           repository: Sea-Haven-Industries/${{ matrix.repo }}
           token: ${{ steps.app-token.outputs.token }}
 
+      - name: Checkout engineering handbook
+        uses: actions/checkout@v4
+        with:
+          repository: Sea-Haven-Industries/engineering-handbook
+          token: ${{ steps.app-token.outputs.token }}
+          path: .engineering-handbook
+
       - name: Run compliance audit
+        id: audit
         uses: anthropics/claude-code-action@v1
         with:
           anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
-          direct_prompt: |
-            Audit this repository for Sea Haven Industries compliance. Check each item and report pass/fail:
+          prompt: |
+            Audit this repository for Sea Haven Industries compliance.
 
-            **Naming:**
-            - All resource names in IaC templates use kebab-case (no snake_case or PascalCase)
-            - Stack name matches repo name
+            The engineering handbook in `.engineering-handbook/` is the authoritative source for all conventions. Read every markdown file in that directory to understand the full set of standards, then audit this repo against them.
 
-            **Secrets:**
-            - No secrets in Lambda environment variables
-            - No secrets in SSM Parameter Store (should be in Secrets Manager)
-            - No hardcoded API keys, tokens, or credentials in source code
-            - Secret names follow `stack-name/secret-name` convention
+            Focus on these categories:
+            - **Naming:** kebab-case for all resource names in IaC templates, stack name matches repo name
+            - **Secrets:** no secrets in Lambda env vars or SSM, secrets belong in Secrets Manager with `stack-name/secret-name` naming
+            - **Lambda defaults:** Python 3.12+ or Node 22.x, arm64, explicit 60-day log retention in IaC
+            - **CI/CD:** pipeline exists with CI on PR and CD on push to main, using reusable workflows from `.github` repo
+            - **Git/GitHub:** branch protection on main, PR-based workflow, repo has a description
+            - **SAM layout:** template.yaml at root, samconfig.toml gitignored with .example committed, src/ directory structure
+            - **Project hygiene:** README describes architecture, .gitignore covers .env/.aws-sam/__pycache__, CloudFormation outputs include ARNs and URLs
 
-            **Lambda defaults (if applicable):**
-            - Runtime is Python 3.12+ or Node 22.x
-            - Architecture is arm64
-            - Log retention is explicitly set to 60 days in the IaC template
+            Return structured output with:
+            - `has_violations`: true only when one or more actual compliance violations are found.
+            - `report`: a concise markdown report with pass/fail per applicable item.
 
-            **Project hygiene:**
-            - README exists and describes the project architecture
-            - .gitignore exists and covers .env, .aws-sam/, __pycache__
-            - samconfig.toml is gitignored (samconfig.toml.example committed if SAM project)
-            - CloudFormation outputs include function ARNs and URLs
-
-            Output a concise markdown report. Only flag actual violations — don't report items that don't apply (e.g., skip Lambda checks if no Lambdas exist).
+            Only flag actual violations — skip items that don't apply to this repo (e.g., skip Lambda checks if no Lambdas exist).
+            Do not create or modify files, issues, pull requests, or comments.
+          claude_args: |
+            --json-schema '{"type":"object","properties":{"has_violations":{"type":"boolean","description":"True when one or more actual compliance violations are found."},"report":{"type":"string","description":"Concise markdown report with pass/fail per applicable compliance item."}},"required":["has_violations","report"],"additionalProperties":false}'
 
       - name: Create issue if violations found
-        if: failure()
+        if: ${{ fromJSON(steps.audit.outputs.structured_output).has_violations == true }}
         env:
           GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          AUDIT_RESULT: ${{ steps.audit.outputs.structured_output }}
         run: |
+          gh label create compliance \
+            --repo "Sea-Haven-Industries/${{ matrix.repo }}" \
+            --description "Weekly compliance audit" \
+            --color "D93F0B" 2>/dev/null || true
           existing=$(gh issue list \
             --repo "Sea-Haven-Industries/${{ matrix.repo }}" \
             --label "compliance" \
@@ -99,9 +114,20 @@ jobs:
             --json number \
             --jq 'length')
           if [ "$existing" -eq 0 ]; then
+            report=$(jq -r '.report' <<< "$AUDIT_RESULT")
+            body_file=$(mktemp)
+            {
+              echo "The weekly compliance audit found violations in this repo."
+              echo
+              echo "## Audit report"
+              echo
+              printf '%s\n' "$report"
+              echo
+              echo "Check the [latest audit run](https://github.com/Sea-Haven-Industries/.github/actions/workflows/compliance-audit.yaml) for details."
+            } > "$body_file"
             gh issue create \
               --repo "Sea-Haven-Industries/${{ matrix.repo }}" \
               --title "Compliance audit: violations found" \
-              --body "The weekly compliance audit found violations in this repo. Check the [latest audit run](https://github.com/Sea-Haven-Industries/.github/actions/workflows/compliance-audit.yaml) for details." \
+              --body-file "$body_file" \
               --label "compliance"
           fi