fix(hygiene): enforce real source debt with controls

.cicd-hygiene-allow

@@ -5,5 +5,7 @@
 # required-files-check searches for template placeholders, so both necessarily
 # contain the strings they hunt. This is the same exemption the estate grants a
 # secret scanner for containing credential-shaped regexes.
-actions/code-hygiene-check/action.yml
+actions/code-hygiene-check/check.sh
+actions/code-hygiene-check/test.sh
 actions/required-files-check/action.yml
+actions/affirmation-check/check.sh

.github/workflows/code-hygiene-self-test.yml

@@ -0,0 +1,41 @@
+name: Code Hygiene Self-Test
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'actions/code-hygiene-check/**'
+      - 'actions/affirmation-check/**'
+      - 'actions/referencing-check/**'
+      - 'actions/secrets-check/**'
+      - 'actions/boj-cartridge-check/**'
+      - '.github/workflows/code-hygiene-self-test.yml'
+  pull_request:
+    paths:
+      - 'actions/code-hygiene-check/**'
+      - 'actions/affirmation-check/**'
+      - 'actions/referencing-check/**'
+      - 'actions/secrets-check/**'
+      - 'actions/boj-cartridge-check/**'
+      - '.github/workflows/code-hygiene-self-test.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Gate controls
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - run: bash actions/code-hygiene-check/test.sh
+      - run: bash actions/affirmation-check/test.sh
+      - run: bash actions/referencing-check/test.sh
+      - run: bash actions/secrets-check/test.sh
+      - run: bash actions/boj-cartridge-check/test.sh

.github/workflows/main-estate-audit.yml

@@ -10,82 +10,86 @@ jobs:
   estate-audit:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      # Test the actions from this revision, not the older implementations on
+      # main. The pinned checkout is the only remote action this job needs.
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
 
       - name: Required Files Gate
-        uses: hyperpolymath/cicd-suite/actions/required-files-check@main
+        uses: ./actions/required-files-check
 
       - name: Code Hygiene Gate
-        uses: hyperpolymath/cicd-suite/actions/code-hygiene-check@main
+        uses: ./actions/code-hygiene-check
 
       - name: Manifest Validation Gate
-        uses: hyperpolymath/cicd-suite/actions/manifest-check@main
+        uses: ./actions/manifest-check
 
       - name: Idris2 ABI Purity Gate
-        uses: hyperpolymath/cicd-suite/actions/idris2-abi-check@main
+        uses: ./actions/idris2-abi-check
 
       - name: Zig Hexadeca API Gate
-        uses: hyperpolymath/cicd-suite/actions/zig-hexadeca-check@main
+        uses: ./actions/zig-hexadeca-check
 
       - name: Contractile Validation Gate
-        uses: hyperpolymath/cicd-suite/actions/contractile-validation-check@main
+        uses: ./actions/contractile-validation-check
 
       - name: Recipes Set Validation Gate
-        uses: hyperpolymath/cicd-suite/actions/recipes-set-check@main
+        uses: ./actions/recipes-set-check
 
       - name: Affirmation Document Gate
-        uses: hyperpolymath/cicd-suite/actions/affirmation-check@main
+        uses: ./actions/affirmation-check
 
       - name: Academic Referencing Gate
-        uses: hyperpolymath/cicd-suite/actions/referencing-check@main
+        uses: ./actions/referencing-check
 
       - name: Semantic Audit Gate
-        uses: hyperpolymath/cicd-suite/actions/semantic-audit-check@main
+        uses: ./actions/semantic-audit-check
 
       - name: SPDX License Gate
-        uses: hyperpolymath/cicd-suite/actions/spdx-license-check@main
+        uses: ./actions/spdx-license-check
 
       - name: Proof Runner Gate
-        uses: hyperpolymath/cicd-suite/actions/proof-runner-check@main
+        uses: ./actions/proof-runner-check
 
       - name: PRAT Testing Gate
-        uses: hyperpolymath/cicd-suite/actions/prat-check@main
+        uses: ./actions/prat-check
 
       - name: Panic Attack & Pons Gate
-        uses: hyperpolymath/cicd-suite/actions/custom-tools-check@main
+        uses: ./actions/custom-tools-check
 
       - name: WWW & Well-Known Compliance Gate
-        uses: hyperpolymath/cicd-suite/actions/www-compliance-check@main
+        uses: ./actions/www-compliance-check
 
       - name: BoJ Cartridge Validation Gate
-        uses: hyperpolymath/cicd-suite/actions/boj-cartridge-check@main
+        uses: ./actions/boj-cartridge-check
 
       - name: Formatting Validation Gate
-        uses: hyperpolymath/cicd-suite/actions/formatting-check@main
+        uses: ./actions/formatting-check
 
       - name: Accreditations & Badges Gate
-        uses: hyperpolymath/cicd-suite/actions/badges-check@main
+        uses: ./actions/badges-check
 
       - name: Metrics Extraction Gate
-        uses: hyperpolymath/cicd-suite/actions/metrics-check@main
+        uses: ./actions/metrics-check
 
       - name: Linguist & Banned Languages Gate
-        uses: hyperpolymath/cicd-suite/actions/linguist-check@main
+        uses: ./actions/linguist-check
 
       - name: Test & Benchmarks Dashboard Gate
-        uses: hyperpolymath/cicd-suite/actions/tests-benches-check@main
+        uses: ./actions/tests-benches-check
 
       - name: Hosting & Site Status Gate
-        uses: hyperpolymath/cicd-suite/actions/hosting-check@main
+        uses: ./actions/hosting-check
 
       - name: Git-Sea Analytics Gate
-        uses: hyperpolymath/cicd-suite/actions/gitsea-check@main
+        uses: ./actions/gitsea-check
 
       - name: Trust & Humans Validation Gate
-        uses: hyperpolymath/cicd-suite/actions/trust-humans-check@main
+        uses: ./actions/trust-humans-check
 
       - name: Are We UnAPI Gate (Secret Scanning)
-        uses: hyperpolymath/cicd-suite/actions/secrets-check@main
+        uses: ./actions/secrets-check
 
       - name: Reasonably Good Token Validation Gate
-        uses: hyperpolymath/cicd-suite/actions/vaulted-tokens-check@main
+        uses: ./actions/vaulted-tokens-check

actions/affirmation-check/action.yml

@@ -1,43 +1,15 @@
 name: 'Affirmation Document Gate'
-description: 'Validates that the AFFIRMATION document is signed and updated within the last 28 days.'
+description: 'Validates an applicable AFFIRMATION snapshot without treating it as a universal or self-proving document.'
+inputs:
+  required:
+    description: 'Set true only when the repository declares the governance-tier capability.'
+    required: false
+    default: 'false'
 runs:
   using: 'composite'
   steps:
     - name: Run Affirmation Check
       shell: bash
-      run: |
-        echo "Validating AFFIRMATION Document..."
-
-        # Check for existence (can be .md, .adoc, etc.)
-        aff_file=$(find . -maxdepth 1 -name "AFFIRMATION*" | head -n 1)
-        if [ -z "$aff_file" ]; then
-          echo "::error::AFFIRMATION document not found in the repository root."
-          exit 1
-        fi
-
-        echo "Found AFFIRMATION document: $aff_file"
-
-        # Check signature (heuristic: look for 'Signed:', 'Signature:', or PGP block)
-        if ! grep -E -i 'signed:|signature:|BEGIN PGP SIGNATURE' "$aff_file" > /dev/null; then
-           echo "::error::AFFIRMATION document does not appear to be signed."
-           exit 1
-        fi
-
-        # Check date (updated within last 28 days)
-        # First check git log for the file (if it is tracked in git)
-        last_update_ts=$(git log -1 --format="%at" -- "$aff_file" 2>/dev/null)
-
-        if [ -z "$last_update_ts" ]; then
-          # Fallback to filesystem mtime if not in git (e.g. during initial setup)
-          last_update_ts=$(stat -c %Y "$aff_file")
-        fi
-
-        current_ts=$(date +%s)
-        diff_days=$(( (current_ts - last_update_ts) / 86400 ))
-
-        if [ "$diff_days" -gt 28 ]; then
-           echo "::error::AFFIRMATION document is out of date! Last updated $diff_days days ago. Must be updated within 28 days."
-           exit 1
-        fi
-
-        echo "AFFIRMATION Document validation passed. (Updated $diff_days days ago)."
+      env:
+        AFFIRMATION_REQUIRED: ${{ inputs.required }}
+      run: "${{ github.action_path }}/check.sh"

actions/affirmation-check/check.sh

@@ -0,0 +1,70 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+
+set -euo pipefail
+
+root=${GITHUB_WORKSPACE:-.}
+required=${AFFIRMATION_REQUIRED:-false}
+aff_file=
+
+for candidate in AFFIRMATION.adoc AFFIRMATION.md AFFIRMATION; do
+  if [[ -f "$root/$candidate" ]]; then
+    aff_file=$candidate
+    break
+  fi
+done
+
+if [[ -z "$aff_file" ]]; then
+  if [[ "$required" == "true" ]]; then
+    echo "::error::AFFIRMATION.adoc is required by the declared governance-tier capability."
+    exit 1
+  fi
+  echo "::notice::AFFIRMATION is not applicable: governance-tier was not required."
+  exit 0
+fi
+
+path=$root/$aff_file
+echo "Found AFFIRMATION document: $aff_file"
+
+substantive_lines=$(awk '!/^[[:space:]]*(#|\/\/|;|$)/ { count++ } END { print count + 0 }' "$path")
+if (( substantive_lines < 5 )); then
+  echo "::error::$aff_file has only $substantive_lines substantive lines; it is a stub, not an affirmation."
+  exit 1
+fi
+
+if grep -qiE '\{\{|TODO: update|<PROJECT|YOUR_PROJECT|lorem ipsum|example\.com' "$path"; then
+  echo "::error::$aff_file contains template placeholders."
+  exit 1
+fi
+
+# The signature is the signature on the commit containing this content. Text
+# such as "Signed:" inside the document proves nothing. Shallow checkouts may
+# not contain the file-changing commit, so report that limitation honestly.
+signature=N
+last_update_ts=
+if git -C "$root" rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  signature=$(git -C "$root" log -1 --format='%G?' -- "$aff_file" 2>/dev/null || true)
+  last_update_ts=$(git -C "$root" log -1 --format='%at' -- "$aff_file" 2>/dev/null || true)
+fi
+
+case "$signature" in
+  G) echo "Affirmation commit signature verified with a trusted key." ;;
+  U) echo "::notice::Affirmation commit has a valid signature from an untrusted or locally unknown key." ;;
+  B|R|E) echo "::error::Affirmation commit signature is bad, revoked, or failed verification."; exit 1 ;;
+  *) echo "::notice::Affirmation commit signature could not be verified from the available Git history." ;;
+esac
+
+# A dated affirmation is a frozen receipt, not a claim that remains current
+# forever. Report age without invalidating historical evidence or forcing an
+# empty monthly rewrite.
+if [[ -n "$last_update_ts" ]]; then
+  current_ts=$(date +%s)
+  age_days=$(( (current_ts - last_update_ts) / 86400 ))
+  if (( age_days > 28 )); then
+    echo "::warning::$aff_file is a $age_days-day-old snapshot; verify its anchor before relying on it as current."
+  else
+    echo "$aff_file snapshot age: $age_days days."
+  fi
+fi
+
+echo "AFFIRMATION document validation passed."

actions/affirmation-check/test.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+
+set -euo pipefail
+
+here=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)
+fixture=$(mktemp -d)
+trap 'rm -rf -- "$fixture"' EXIT
+
+GITHUB_WORKSPACE=$fixture AFFIRMATION_REQUIRED=false "$here/check.sh"
+
+if GITHUB_WORKSPACE=$fixture AFFIRMATION_REQUIRED=true "$here/check.sh"; then
+  echo "required-but-absent affirmation unexpectedly passed" >&2
+  exit 1
+fi
+
+printf '= AFFIRMATION\n' > "$fixture/AFFIRMATION.adoc"
+if GITHUB_WORKSPACE=$fixture AFFIRMATION_REQUIRED=true "$here/check.sh"; then
+  echo "stub affirmation unexpectedly passed" >&2
+  exit 1
+fi
+
+printf '%s\n' \
+  '= AFFIRMATION — controlled fixture' \
+  'This snapshot makes a falsifiable claim.' \
+  'The claim is anchored to a named revision.' \
+  'Tests were run and their scope is stated.' \
+  'Unproved properties are not called proved.' \
+  'Later revisions must be assessed separately.' \
+  > "$fixture/AFFIRMATION.adoc"
+GITHUB_WORKSPACE=$fixture AFFIRMATION_REQUIRED=true "$here/check.sh"
+
+echo 'affirmation-check controls passed'

actions/boj-cartridge-check/action.yml

@@ -1,19 +1,15 @@
 name: 'BoJ Cartridge Gate'
-description: 'Validates that a cartridge is present for use with the BoJ server.'
+description: 'Checks for a BoJ cartridge when BoJ integration is applicable.'
+inputs:
+  required:
+    description: 'Set true when this repository declares BoJ integration.'
+    required: false
+    default: 'false'
 runs:
   using: 'composite'
   steps:
     - name: Run BoJ Cartridge Check
       shell: bash
-      run: |
-        echo "Validating BoJ Cartridge presence..."
-
-        # Check for typical cartridge files
-        if [ -f "cartridge.json" ] || [ -f "cartridge.yml" ] || [ -f "cartridge.yaml" ] || [ -d ".cartridges" ] || find . -maxdepth 2 -name "*cartridge*" | grep -q .; then
-          echo "BoJ cartridge detected."
-        else
-          echo "::error::No BoJ cartridge found. A cartridge should be present for use of the tool in full with the BoJ server."
-          exit 1
-        fi
-
-        echo "BoJ Cartridge validation passed."
+      env:
+        BOJ_CARTRIDGE_REQUIRED: ${{ inputs.required }}
+      run: "${{ github.action_path }}/check.sh"

actions/boj-cartridge-check/check.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# SPDX-License-Identifier: MPL-2.0
+
+set -euo pipefail
+
+root=${GITHUB_WORKSPACE:-.}
+required=${BOJ_CARTRIDGE_REQUIRED:-false}
+found=
+
+for candidate in cartridge.json cartridge.yml cartridge.yaml; do
+  if [[ -f "$root/$candidate" ]]; then
+    found=$candidate
+    break
+  fi
+done
+if [[ -z "$found" && -d "$root/.cartridges" ]]; then
+  found=.cartridges/
+fi
+
+if [[ -z "$found" ]]; then
+  if [[ "$required" == "true" ]]; then
+    echo '::error::A BoJ cartridge is required but no canonical cartridge path exists.'
+    exit 1
+  fi
+  echo '::notice::BoJ cartridge is not applicable to this repository.'
+  exit 0
+fi
+
+echo "BoJ cartridge present at $found."