Kodaxadev · Kodaxadev · May 16, 2026 · May 16, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,21 @@ Versions follow [Semantic Versioning](https://semver.org/).
 
 ---
 
+## v3.2.0 — 2026-05-16
+
+**Governance Evidence Artifact.**
+
+- Added `tools/governance-report.js` — single-pass governance report generator that runs file length, secrets, behavioral tests, source integrity, and runtime hook checks, producing a structured JSON artifact (`.code-warden-report.json`) and optional Markdown output
+- Three output modes: default (writes JSON artifact + prints summary), `--format=json` (JSON to stdout), `--format=md` (Markdown table to stdout for `$GITHUB_STEP_SUMMARY`)
+- Report includes git metadata (branch, commit), check results with violation details, and runtime hook registration status (Claude Code, Codex)
+- Exit code reflects overall result: `0` = all checks pass, `1` = one or more failures
+- Updated `templates/ci/github-actions.yml` — replaces individual lint/secrets steps with governance report, adds `$GITHUB_STEP_SUMMARY` Markdown publishing, adds artifact upload with 90-day retention
+- Added npm scripts: `report`, `report:json`, `report:md`
+- Updated README with "Governance Evidence" section and new positioning
+- New positioning: "Verifiable governance for AI-assisted development — checks, hooks, and evidence that agents stayed within policy"
+
+---
+
 ## v3.1.1 — 2026-05-15
 
 **Stabilization — behavioral tests, shared policy modules, line-count fix.**

diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
   <a href="https://github.com/Kodaxadev/Code-Warden/actions/workflows/code-warden.yml">
     <img src="https://github.com/Kodaxadev/Code-Warden/actions/workflows/code-warden.yml/badge.svg" alt="Code-Warden Quality Gate" />
   </a>
-  <img src="https://img.shields.io/badge/version-3.1.1-blue" alt="Version 3.1.1" />
+  <img src="https://img.shields.io/badge/version-3.2.0-blue" alt="Version 3.2.0" />
   <img src="https://img.shields.io/badge/license-MIT-yellow" alt="MIT License" />
   <img src="https://img.shields.io/badge/Claude%20Hooks-PreToolUse-purple" alt="Claude Code PreToolUse Hooks" />
   <img src="https://img.shields.io/badge/AI%20Governance-enforced-red" alt="AI Governance Enforced" />
@@ -148,7 +148,9 @@ node install.js --uninstall-hooks=codex  # remove Codex hooks
 ```bash
 npm run lint            # scan full project tree for oversized files
 npm run check-secrets   # scan full project tree for hardcoded credentials
-npm run ci              # lint + secrets + doctor
+npm run report          # governance report — writes .code-warden-report.json
+npm run report:md       # governance report as Markdown (pipe to PR summary)
+npm run ci              # lint + secrets + test + doctor
 npm run install-auto    # node install.js
 npm run install-doctor  # node install.js --doctor
 ```
@@ -198,20 +200,40 @@ Codex exposes `apply_patch` and `Bash` at `PreToolUse` — not `Write`/`Edit`. T
 
 Doctor and `--verify-target=<id>` validate hook script paths when hooks are registered.
 
+## Governance Evidence
+
+Code-Warden produces a machine-readable governance report — verifiable evidence that checks ran and passed:
+
+```bash
+node tools/governance-report.js .              # writes .code-warden-report.json
+node tools/governance-report.js . --format=md  # Markdown table for PR summaries
+```
+
+The report covers file length, hardcoded credentials, behavioral tests, source integrity, and runtime hook status in a single pass. In CI, it pipes directly into `$GITHUB_STEP_SUMMARY` so every PR shows what was checked.
+
 ## CI Integration
 
 ```yaml
 - name: Install Code-Warden
   run: |
     curl -fsSL -o cw.zip \
-      https://github.com/Kodaxadev/Code-Warden/releases/download/v3.1.0/code-warden-v3.1.0.zip
+      https://github.com/Kodaxadev/Code-Warden/releases/download/v3.2.0/code-warden-v3.2.0.zip
     unzip -q cw.zip -d .code-warden-ci
 
-- name: Lint — file length limits
-  run: node .code-warden-ci/tools/warden-lint.js .
+- name: Governance report
+  run: node .code-warden-ci/tools/governance-report.js .
+
+- name: Publish governance summary
+  if: always()
+  run: node .code-warden-ci/tools/governance-report.js . --format=md >> $GITHUB_STEP_SUMMARY
 
-- name: Secrets — zero-trust scan
-  run: node .code-warden-ci/tools/verify-secrets.js .
+- name: Upload governance artifact
+  if: always()
+  uses: actions/upload-artifact@v4
+  with:
+    name: code-warden-report
+    path: .code-warden-report.json
+    retention-days: 90
 ```
 
 Full template: [`code-warden/templates/ci/github-actions.yml`](code-warden/templates/ci/github-actions.yml)
@@ -234,7 +256,7 @@ Full template: [`code-warden/templates/ci/github-actions.yml`](code-warden/templ
 
 ## Version
 
-v3.1.0 — See [`code-warden/SKILL.md`](code-warden/SKILL.md) for full changelog.
+v3.2.0 — See [`CHANGELOG.md`](CHANGELOG.md) for full changelog.
 
 ## Author
 

diff --git a/code-warden/README.md b/code-warden/README.md
@@ -2,7 +2,10 @@
 
 > Portable AI Coding Governance Layer
 
-Code-Warden is a portable governance layer for AI coding agents. It enforces scoped planning, patch discipline, file-size limits, the zero-trust secrets policy, verification evidence, install health, and optional Claude Code pre-tool-use blocking.
+Code-Warden provides verifiable governance for AI-assisted development.
+It does not just ask agents to follow rules — it adds Scope Gates, Plan Gates,
+local checks, CI enforcement, runtime hooks where supported, and governance
+artifacts that show what was checked before code was accepted.
 
 ## Four Layers
 
@@ -17,6 +20,43 @@ Code-Warden is a portable governance layer for AI coding agents. It enforces sco
 | **Installer and health** | Cross-app auto-installer, manifest-backed installs, `--doctor`, `--verify-target`, Windsurf adapter |
 | **Hard enforcement** | Claude Code `PreToolUse` hooks — block oversized writes and hardcoded secrets before the file system is touched |
 
+## Governance Evidence
+
+Generate a machine-readable governance report that can be stored in CI, attached to PRs, or used as audit evidence:
+
+```bash
+node tools/governance-report.js .                   # write .code-warden-report.json + summary
+node tools/governance-report.js . --format=json      # JSON to stdout
+node tools/governance-report.js . --format=md        # Markdown to stdout
+```
+
+The report runs all checks in a single pass (file length, secrets, behavioral tests, source integrity) and produces a structured artifact:
+
+```json
+{
+  "tool": "code-warden",
+  "version": "3.2.0",
+  "checks": {
+    "fileLength":      { "status": "pass", "filesScanned": 34, "violations": 0 },
+    "secrets":         { "status": "pass", "filesScanned": 34, "violations": 0 },
+    "behavioralTests": { "status": "pass", "tests": 8, "failures": 0 },
+    "installHealth":   { "status": "pass" }
+  },
+  "result": "pass"
+}
+```
+
+In CI, the Markdown format pipes directly into `$GITHUB_STEP_SUMMARY` for PR-visible evidence:
+
+| Check | Result | Details |
+|-------|--------|---------|
+| File length | PASS | 34 files scanned, 0 violations |
+| Hardcoded credentials | PASS | 34 files scanned, 0 violations |
+| Behavioral tests | PASS | 8 tests, 0 failures |
+| Install health | PASS | All source files present |
+
+See [`templates/ci/github-actions.yml`](templates/ci/github-actions.yml) for the full CI template with artifact upload.
+
 ## Install
 
 ```bash
@@ -48,6 +88,9 @@ Each install writes a `.code-warden-install.json` manifest (version, target, for
 ```bash
 npm run lint            # warden-lint on full project tree
 npm run check-secrets   # verify-secrets on full project tree
+npm run report          # governance report, writes .code-warden-report.json
+npm run report:json     # governance report as JSON to stdout
+npm run report:md       # governance report as Markdown to stdout
 npm run install-auto    # node install.js
 npm run install-dry-run # node install.js --dry-run
 npm run install-list    # node install.js --list

diff --git a/code-warden/package.json b/code-warden/package.json
@@ -1,12 +1,15 @@
 {
   "name": "code-warden",
-  "version": "3.1.1",
-  "description": "Production-grade AI development governance skill for Codex, Claude Code, and Cowork.",
+  "version": "3.2.0",
+  "description": "Verifiable governance for AI-assisted development — checks, hooks, and evidence.",
   "main": "SKILL.md",
   "scripts": {
     "lint": "node tools/warden-lint.js .",
     "check-secrets": "node tools/verify-secrets.js .",
     "get-context": "node tools/get-context.js",
+    "report": "node tools/governance-report.js .",
+    "report:json": "node tools/governance-report.js . --format=json",
+    "report:md": "node tools/governance-report.js . --format=md",
     "install-auto": "node install.js",
     "install-dry-run": "node install.js --dry-run",
     "install-list": "node install.js --list",

diff --git a/code-warden/templates/ci/github-actions.yml b/code-warden/templates/ci/github-actions.yml
@@ -4,8 +4,15 @@
 # Copy this file to .github/workflows/code-warden.yml in your project.
 #
 # What it enforces:
-#   - File length limits (warden-lint.js, default 400 lines per codewarden.json)
-#   - Zero-trust secrets (verify-secrets.js, hardcoded-credential patterns)
+#   - File length limits (default 400 lines per codewarden.json)
+#   - Zero-trust secrets (hardcoded-credential patterns)
+#   - Behavioral tests (scanner and hook pass/fail verification)
+#   - Source integrity (required files present)
+#
+# What it produces:
+#   - .code-warden-report.json — machine-readable governance artifact
+#   - Markdown summary on the workflow run / PR (via GITHUB_STEP_SUMMARY)
+#   - Uploaded artifact for audit trail (90-day retention)
 #
 # How code-warden is made available in CI (choose one):
 #
@@ -33,7 +40,7 @@ on:
     branches: [main, master]
 
 env:
-  CODE_WARDEN_VERSION: v3.1.0
+  CODE_WARDEN_VERSION: v3.2.0
   CODE_WARDEN_PATH: .code-warden-ci
   FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
@@ -59,8 +66,18 @@ jobs:
           mkdir -p ${{ env.CODE_WARDEN_PATH }}
           unzip -q cw.zip -d ${{ env.CODE_WARDEN_PATH }}
 
-      - name: Lint — enforce file length limits
-        run: node ${{ env.CODE_WARDEN_PATH }}/tools/warden-lint.js .
+      - name: Governance report
+        run: node ${{ env.CODE_WARDEN_PATH }}/tools/governance-report.js .
+
+      - name: Publish governance summary
+        if: always()
+        run: node ${{ env.CODE_WARDEN_PATH }}/tools/governance-report.js . --format=md >> $GITHUB_STEP_SUMMARY
 
-      - name: Secrets — zero-trust scan
-        run: node ${{ env.CODE_WARDEN_PATH }}/tools/verify-secrets.js .
+      - name: Upload governance artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: code-warden-report
+          path: .code-warden-report.json
+          if-no-files-found: ignore
+          retention-days: 90