Wave 4: harden risk proof and gate contracts

.github/PULL_REQUEST_TEMPLATE/wave-1-foundation.md

@@ -0,0 +1,6 @@
+## Wave 1 Foundation
+
+- [ ] Scope is limited to Wave 1 foundation contracts and identity work.
+- [ ] `make lint-fast`, `make test-fast`, and `make test-contracts` passed locally.
+- [ ] Contract/additive schema changes are documented and golden fixtures were updated.
+- [ ] Downstream Wave 2/3/4 work is not bundled into this PR.

.github/PULL_REQUEST_TEMPLATE/wave-2-core-detection-policy.md

@@ -0,0 +1,6 @@
+## Wave 2 Core Detection And Policy
+
+- [ ] Wave 1 is already merged and green on `main`.
+- [ ] Scope is limited to core detection, correlation, privilege, and policy work.
+- [ ] Detector precision, scenario, and policy fixtures were updated deterministically.
+- [ ] No Wave 3/4 coverage, proof, or docs hardening changes are bundled here.

.github/PULL_REQUEST_TEMPLATE/wave-3-coverage-quality.md

@@ -0,0 +1,6 @@
+## Wave 3 Coverage And Quality
+
+- [ ] Wave 2 is already merged and green on `main`.
+- [ ] Scope is limited to coverage expansion, benchmarks, and scenario/contract packs.
+- [ ] Benchmark thresholds and scenario packs were updated with deterministic outputs only.
+- [ ] No Wave 4 hardening/docs gating changes are bundled here.

.github/PULL_REQUEST_TEMPLATE/wave-4-hardening-docs.md

@@ -0,0 +1,6 @@
+## Wave 4 Hardening And Docs
+
+- [ ] Waves 1-3 are already merged and green on `main`.
+- [ ] Scope is limited to risk, proof, compliance, governance, and docs hardening.
+- [ ] `make prepush-full`, scenario/contract suites, and scan contract checks passed locally.
+- [ ] User-facing docs were updated for any externally visible behavior changes.

.github/required-checks.json

@@ -1,6 +1,8 @@
 {
   "required_checks": [
     "fast-lane",
+    "scan-contract",
+    "wave-sequence",
     "windows-smoke"
   ]
 }

.github/wave-gates.json

@@ -0,0 +1,93 @@
+{
+  "merge_gates": {
+    "required_pr_checks": [
+      "fast-lane",
+      "scan-contract",
+      "wave-sequence",
+      "windows-smoke"
+    ],
+    "required_release_commands": [
+      "make prepush-full",
+      "make test-contracts",
+      "make test-scenarios",
+      "scripts/run_v1_acceptance.sh --mode=local",
+      "go run ./cmd/wrkr scan --path scenarios/wrkr/scan-diff-no-noise/input/local-repos --json --quiet"
+    ]
+  },
+  "waves": [
+    {
+      "id": "wave-1",
+      "label": "foundation",
+      "order": 1,
+      "required_lanes": [
+        "fast",
+        "core",
+        "acceptance",
+        "cross_platform",
+        "risk"
+      ],
+      "required_story_checks": [
+        "story1_contracts_test.go",
+        "story2_contracts_test.go",
+        "story3_contracts_test.go",
+        "story4_contracts_test.go",
+        "story5_contracts_test.go"
+      ],
+      "successor": "wave-2"
+    },
+    {
+      "id": "wave-2",
+      "label": "core-detection-and-policy",
+      "order": 2,
+      "required_lanes": [
+        "fast",
+        "core",
+        "acceptance",
+        "cross_platform",
+        "risk"
+      ],
+      "required_story_checks": [
+        "story10_contracts_test.go",
+        "story7_contracts_test.go",
+        "story8_contracts_test.go",
+        "story9_contracts_test.go"
+      ],
+      "requires": "wave-1",
+      "successor": "wave-3"
+    },
+    {
+      "id": "wave-3",
+      "label": "coverage-and-quality",
+      "order": 3,
+      "required_lanes": [
+        "fast",
+        "core",
+        "acceptance",
+        "cross_platform",
+        "risk"
+      ],
+      "required_story_checks": [
+        "story14_contracts_test.go",
+        "story15_contracts_test.go"
+      ],
+      "requires": "wave-2",
+      "successor": "wave-4"
+    },
+    {
+      "id": "wave-4",
+      "label": "hardening-and-docs",
+      "order": 4,
+      "required_lanes": [
+        "fast",
+        "core",
+        "acceptance",
+        "cross_platform",
+        "risk"
+      ],
+      "required_story_checks": [
+        "story21_contracts_test.go"
+      ],
+      "requires": "wave-3"
+    }
+  ]
+}

.github/workflows/pr.yml

@@ -14,6 +14,23 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+  wave-sequence:
+    name: wave-sequence
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      - name: Validate branch protection and wave sequencing contracts
+        run: |
+          scripts/check_branch_protection_contract.sh
+          scripts/check_wave_gates.sh
+
   fast-lane:
     name: fast-lane
     runs-on: ubuntu-latest
@@ -152,6 +169,26 @@ jobs:
         if: steps.changes.outputs.go != 'true' && steps.changes.outputs.python != 'true' && steps.changes.outputs.workflow_or_policy != 'true'
         run: echo "no code, workflow, or policy changes; deep scanners skipped"
 
+  scan-contract:
+    name: scan-contract
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25.7'
+          check-latest: false
+
+      - name: Enforce scan JSON and exit-code contracts
+        run: |
+          go test ./testinfra/contracts -run 'TestRequiredChecks_EnforceWaveSequence1To2To3To4|TestScanContract_NoJSONOrExitRegressionAcrossWaves' -count=1
+          mkdir -p .tmp
+          go run ./cmd/wrkr scan --path scenarios/wrkr/scan-diff-no-noise/input/local-repos --json --quiet > .tmp/scan-contract.json
+          test -s .tmp/scan-contract.json
+
   windows-smoke:
     name: windows-smoke
     runs-on: windows-latest

README.md

@@ -4,9 +4,9 @@
 [![CodeQL](https://github.com/Clyra-AI/wrkr/actions/workflows/github-code-scanning/codeql/badge.svg)](https://github.com/Clyra-AI/wrkr/actions/workflows/github-code-scanning/codeql)
 [![Nightly](https://github.com/Clyra-AI/wrkr/actions/workflows/nightly.yml/badge.svg?event=schedule)](https://github.com/Clyra-AI/wrkr/actions/workflows/nightly.yml)
 
-Most teams don't know what AI dev tools and agents are active across their repos, what permissions they have, or what changed since last week. Wrkr answers that in minutes. Scan your GitHub org, get ranked findings, and generate audit-ready evidence. Read-only. No integration required.
+Most teams don't know what AI dev tools and agents are active across their repos, what permissions they have, or what changed since last week. Wrkr answers that in minutes. Scan your GitHub org, get ranked findings for tools and agents, and generate audit-ready evidence. Read-only. No integration required.
 
-Wrkr is the **See** layer in the Clyra AI governance stack (See -> Prove -> Control -> Build). It discovers AI tooling across repositories and orgs, scores posture, tracks identity lifecycle, and emits signed proof artifacts ready for compliance review or downstream automation.
+Wrkr is the **See** layer in the Clyra AI governance stack (See -> Prove -> Control -> Build). It discovers AI tooling and agent declarations across repositories and orgs, scores posture, tracks identity lifecycle, and emits signed proof artifacts ready for compliance review or downstream automation.
 
 Docs: [clyra-ai.github.io/wrkr](https://clyra-ai.github.io/wrkr/) | Command contracts: [`docs/commands/`](docs/commands/) | Docs map: [`docs/map.md`](docs/map.md)
 
@@ -79,7 +79,7 @@ make build
 ./.tmp/wrkr score --json
 
 # Generate and verify evidence
-./.tmp/wrkr evidence --frameworks eu-ai-act,soc2 --output ./.tmp/evidence --json
+./.tmp/wrkr evidence --frameworks eu-ai-act,soc2,pci-dss --output ./.tmp/evidence --json
 ./.tmp/wrkr verify --chain --json
 
 # Baseline and drift gate
@@ -92,13 +92,14 @@ Expected JSON keys by command family:
 - `scan`: `status`, `target`, `findings`, `ranked_findings`, `top_findings`, `attack_paths`, `top_attack_paths`, `inventory`, `privilege_budget`, `agent_privilege_map`, `repo_exposure_summaries`, `profile`, `posture_score` (optional: `detector_errors`, `partial_result`, `source_errors`, `source_degraded`, `policy_warnings`, `report`, `sarif`)
 - `report`: `status`, `generated_at`, `top_findings`, `attack_paths`, `top_attack_paths`, `total_tools`, `tool_type_breakdown`, `compliance_gap_count`, `privilege_budget`, `summary` (optional: `md_path`, `pdf_path`)
 - `score`: `score`, `grade`, `breakdown`, `weighted_breakdown`, `weights`, `trend_delta` (optional: `attack_paths`, `top_attack_paths`)
-- `evidence`: `status`, `output_dir`, `manifest_path`, `chain_path`, `framework_coverage`, `report_artifacts`
+- `evidence`: `status`, `output_dir`, `frameworks`, `manifest_path`, `chain_path`, `framework_coverage`, `report_artifacts`
 - `verify`: `chain.intact`, `chain.head_hash`
 - `regress run`: deterministic drift status and reason fields
 
 Prompt-channel findings are emitted deterministically with stable reason codes and evidence hashes (no raw secret extraction).  
 When `scan --enrich` is enabled, MCP findings include enrich provenance and quality fields (`source`, `as_of`, `advisory_count`, `registry_status`, `enrich_quality`, schema IDs, and adapter error classes).
 Evidence bundles include deterministic inventory artifacts at `inventory.json`, `inventory-snapshot.json`, and `inventory.yaml`.
+Evidence framework IDs are normalized to upstream `Clyra-AI/proof` IDs in output (`eu-ai-act`, `pci-dss`); underscore aliases such as `eu_ai_act` and `pci_dss` are accepted as input.
 Canonical local path lifecycle for state, baseline, manifest, and proof chain: [`docs/state_lifecycle.md`](docs/state_lifecycle.md).
 
 ## What You Get
@@ -117,7 +118,7 @@ Deterministic identities in `wrkr:<tool_id>:<org>` format. Lifecycle transitions
 
 ### Audit-ready evidence
 
-Signed proof records for `scan_finding`, `risk_assessment`, and lifecycle events. Evidence bundles with compliance framework mappings and offline verification. No calling home required.
+Signed proof records for `scan_finding`, `risk_assessment`, and lifecycle events. Agent-aware proof events now carry additive `agent_context` fields for portability, and evidence bundles keep compliance framework mappings verifiable offline. No calling home required.
 
 ### CI drift gates