feat(ci): add trusted local validation without Actions

Add complete local engine and configuration validation with pinned trusted checks, isolated stages, descendant cleanup and exact-source reports. Add independently signed policy-v2 evidence while retaining existing required checks and normal project Actions.

Validation: exact head a8552da passed all eight standalone stages with no skips, all 68 restoration/verification checks, independent archive readback and required hosted CI. Signed host adoption, recovery and protection migration remain separate cutover work.

Refs #135
Template follow-up: RandomDevelopment/ci-fleet-config-template#32

Author: Nickfost

.github/workflows/validate.yml

@@ -167,53 +167,25 @@ jobs:
       - name: Install static analysis tools
         run: sudo apt-get update && sudo apt-get install -y shellcheck python3-yaml
 
-      - name: Check shell scripts
-        run: shellcheck scripts/*.sh examples/project/scripts/ci/*.sh templates/config-repository/scripts/*.sh
-
-      - name: Check documentation links
-        run: python3 scripts/check_doc_links.py
-
-      - name: Build and inspect inert prototype
-        run: scripts/validate.sh
-
-      - name: Validate public configuration template
+      - name: Run the complete local suite
+        env:
+          SOURCE: ${{ github.event.pull_request.head.sha || github.sha }}
+          BASE: ${{ github.event.pull_request.base.sha || github.event.before }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+          EVENT_NAME: ${{ github.event_name }}
+          REF_TYPE: ${{ github.ref_type }}
+          TAG_NAME: ${{ github.ref_name }}
         run: |
-          cmp -s scripts/scan_committed_secrets.py templates/config-repository/scripts/scan_committed_secrets.py
-          python3 templates/config-repository/scripts/test_policy.py
-          python3 templates/config-repository/scripts/scan_committed_secrets.py
-          templates/config-repository/scripts/validate.sh
-          templates/config-repository/scripts/validate.sh --config templates/config-repository/examples/multi-host/fleet.json
-          temporary_directory="$(mktemp -d)"
-          if templates/config-repository/scripts/init.sh \
-            --organization test-company \
-            --project test-app \
-            --output "${temporary_directory}/missing-engine.json"; then
-            echo 'initializer accepted a missing engine revision' >&2
-            exit 1
-          fi
-          test ! -e "${temporary_directory}/missing-engine.json"
-          if templates/config-repository/scripts/init.sh \
-            --organization test-company \
-            --project test-app \
-            --registry BAD \
-            --engine-ref "$(git rev-parse HEAD)" \
-            --architecture amd64 \
-            --controller-image-digest "sha256:$(printf '3%.0s' {1..64})" \
-            --runner-image-digest "sha256:$(printf '4%.0s' {1..64})" \
-            --output "${temporary_directory}/invalid.json"; then
-            echo 'initializer accepted an invalid registry' >&2
-            exit 1
-          fi
-          test ! -e "${temporary_directory}/invalid.json"
-          templates/config-repository/scripts/init.sh \
-            --organization test-company \
-            --project test-app \
-            --engine-ref "$(git rev-parse HEAD)" \
-            --architecture amd64 \
-            --controller-image-digest "sha256:$(printf '3%.0s' {1..64})" \
-            --runner-image-digest "sha256:$(printf '4%.0s' {1..64})" \
-            --output "${temporary_directory}/fleet.json"
-          test "$(stat -c '%a' "${temporary_directory}/fleet.json")" = 644
+          main=$(git rev-parse origin/main)
+          if [[ -z "$BASE" || "$BASE" =~ ^0+$ ]]; then BASE=$(git merge-base "$SOURCE" "$main"); fi
+          args=()
+          if [[ "$EVENT_NAME" == pull_request ]]; then args+=(--pr-title "$PR_TITLE"); fi
+          if [[ "$REF_TYPE" == tag ]]; then args+=(--tag "$TAG_NAME" --tag-created); fi
+          # The convention job independently rejects moved tags. The trusted
+          # main scanner above remains a separate guard during migration.
+          sudo python3 scripts/local_validate.py --repository "$PWD" \
+            --source "$SOURCE" --base "$BASE" --policy "$(git rev-parse HEAD)" --main "$main" \
+            --disposable-host --output "$RUNNER_TEMP/local-validation" "${args[@]}"
 
       - name: Require successful convention validation
         env:

AGENTS.md

@@ -82,3 +82,15 @@ Keep changes small and reversible. Existing project CI must continue operating u
 - Identify the source engine issue/PR, full reviewed commit, gap, affected template files, acceptance checks, capability staging, migration requirements, and documentation impact. Mark unmerged features pending and update the follow-up with the full merged commit when available.
 - Link the template issue in the engine PR description and completion report, or explain why no template change is needed. If issue lookup, creation, or update fails, report the missing tracking as outstanding rollout work; do not claim template synchronization.
 - A tracked issue is not a completed template change. Engine availability, a published template release, adopter engine promotion, and live-host acceptance require separate evidence and authorization. This workflow grants no template merge, release, private configuration change, or host activation authority. Keep ordinary CI read-only; no new automation credentials are required.
+
+## Local validation and evidence
+
+- Use `scripts/local_validate.py` for complete exact-source/base validation.
+  Follow `docs/LOCAL-VALIDATION.md` for tools, isolation, profiles and logs.
+- A quick run or `scripts/validate.sh` alone is incomplete full-suite evidence.
+  Missing tools and unexpected skips must fail. Privileged fixtures belong on
+  disposable isolated execution machines, never active fleet hosts.
+- Trusted local acceptance uses policy-v2 signed evidence from an independent
+  authority and a pinned validator. Keep signing keys off execution machines.
+- Preserve current required checks until coverage, recovery and a deliberate
+  policy migration pass. Optional hosted convenience never creates a host gate.

README.md

@@ -14,6 +14,12 @@ Use one shared pool of disposable CI workers across multiple trusted private rep
 
 > **Status:** Controlled migration. The isolated one-job pilot passed on 2026-07-15. Reviewed schema-v3 desired state now governs managed ordinary-CI controller lifecycle. Tester and deployer components remain under review, and production readiness remains gated. See [accepted design decisions](docs/DESIGN-DECISIONS.md).
 
+Run the complete engine and embedded-configuration suites without Actions through
+[local validation](docs/LOCAL-VALIDATION.md). Signed local configuration evidence
+is opt-in; existing host and required-check policies need a reviewed migration.
+The [operator walkthrough](docs/LOCAL-VALIDATION-RUNBOOK.md) gives the setup,
+execution, signing and acceptance sequence.
+
 ## What problem does this solve?
 
 Self-hosted CI often grows one project at a time:

docs/COMPLIANCE-CHECKLIST.md

@@ -60,3 +60,13 @@ A project MUST complete this checklist before its existing required CI is moved
 - [ ] Existing required checks remained available during validation.
 - [ ] Rollback instructions were tested.
 - [ ] Project-specific runners were retained through the observation period.
+
+## Engine and configuration validation migration
+
+The [local validation contract](LOCAL-VALIDATION.md) governs replacement of
+engine and configuration hosted validation. It leaves application fleet jobs
+and their five-minute task contract unchanged. Preserve independent review,
+current required checks and recovery until complete local parity and deliberate
+policy cutover pass. Optional hosted convenience is separate from a policy
+requiring hosted success. Record template adoption and live-host acceptance
+separately from engine implementation.

docs/CONFIGURATION-APPROVAL.md

@@ -24,14 +24,16 @@ Rollback and uninstall preserve both. Only a trusted root operator can remove
 the gate; it does not defend against a compromised host root or trusted engine.
 
 The policy pins the configuration repository's numeric GitHub ID, a simple
-branch name such as `main`, the validation workflow's numeric ID, required job
-names, and allowed reviewer numeric IDs. These are trust anchors, not application
+branch name such as `main`, allowed reviewer numeric IDs and validation evidence
+requirements. Version 1 pins the workflow ID and required job names. Version 2
+pins signed local evidence and can additionally require hosted results. These are trust anchors, not application
 allowlists or host inventory. Account renames do not substitute a different
 reviewer identity. The verifier checks the requested repository against its
 numeric ID and default branch, and checks the local Git tree against GitHub.
 
-The existing host-side App needs read-only Contents, Pull requests, and Actions
-permissions on the configuration repository. It receives no approval or write
+The existing host-side App needs read-only Contents and Pull requests
+permissions on the configuration repository. Policies requiring hosted results
+also need read-only Actions permission. It receives no approval or write
 authority. Long-lived credentials remain on the controller, outside ordinary CI.
 Tokens travel to the verifier through stdin, never command arguments, policy,
 or logs. Errors do not print API responses, policy values, or credentials.
@@ -63,7 +65,9 @@ adapter's resume action, the trusted verifier requires all of the following:
    also accepts verified clean review evidence from an explicitly trusted bot.
    The review must follow any base-branch retargeting. Unavailable or incomplete
    PR base history rejects the candidate.
-4. The latest push run of the pinned workflow on the applied SHA completed
+4. The policy's validation evidence must pass. Version 2 requires the signed
+   local result described below. Policies with hosted requirements also require
+   the latest push run of the pinned workflow on the applied SHA to complete
    successfully for the trusted repository and branch. Each required named job
    also completed successfully in that exact run attempt. Skipped, failed,
    cancelled, queued, and missing evidence is rejected.
@@ -174,3 +178,106 @@ Deterministic tests cover review/check rejection, tree identity, API failures,
 pagination, policy permissions, direct installer modes, remote reconciliation,
 resume, and rollback. Real permissions, reviewer provisioning, systemd execution,
 and unattended bypass rejection require separately authorized live verification.
+
+## Signed local validation
+
+The [operator walkthrough](LOCAL-VALIDATION-RUNBOOK.md) covers prerequisite setup,
+key/policy bootstrap, independently verified transfer, signing, protected evidence
+installation and read-only host acceptance checks.
+
+Policy version 1 retains its hosted-workflow requirement. Policy version 2
+requires signed full local validation and omits Actions calls when both
+`workflow_id` and `required_jobs` are absent. Adding both fields makes hosted
+success an explicit additional operator requirement. An optional convenience
+workflow alone never adds this requirement. Use the
+[local policy example](../host/config-review-policy-local.json.example) only
+after replacing every fictional identity, revision and the public test key.
+The example key is a published test vector and must never authorize a host.
+
+Version 2 requires `configuration_local_validation` on the executing engine,
+candidate engine and checkpoint manager. Existing capability checks enforce
+this before activation and rollback restoration. Stage compatible managers,
+verify recovery, then provision the root-owned policy in a separate authorized
+host change. Policy and marker ownership rules remain unchanged. Downgrade
+requires a deliberate compatible policy migration, never ignoring an unknown
+policy or silently falling back to hosted results.
+
+The local policy pins the suite name, validator revision, exact required stage
+names, Ed25519 public key, protected evidence directory and maximum age. Its
+canonical JSON SHA-256 binds every policy field into the signed evidence. Key
+rotation, reviewer changes, a different suite or any other policy change
+invalidates earlier evidence. A result must name the exact integrated commit,
+its tree and first parent, the original reviewed history, the PR number and current reviewed head. All stages
+must pass with no skips. Future timestamps and evidence older than the policy
+limit reject acceptance. The installed-baseline ancestry rules continue to
+reject rollback replay; rechecking the same installed commit for drift remains
+idempotent and still requires fresh, valid evidence.
+
+The signer is a separately trusted operator authority. The signature attests
+that this authority independently verified execution of the pinned full suite
+with the recorded inputs and logs. It is not hardware attestation. The signer
+must obtain results through its own supervised execution or an authenticated
+execution channel outside candidate control. A candidate upload, success file,
+PR comment or an unverified copy of a report is insufficient. The signing helper
+checks report structure and log hashes; it cannot establish how an arbitrary
+uploaded report was produced. Never expose it as a blind upload-signing service.
+
+Keep the private signing key on a separate trusted machine or isolated signing
+service. Never place it in a checkout, workflow, test environment, Docker host,
+container or ordinary job. Docker access is host-root-equivalent. A second Unix
+user on the execution machine does not protect the signer. Use a fresh disposable
+execution machine without controller credentials, then independently verify and
+transfer its results through the authorized operator channel.
+
+After that independent verification, the trusted operator can sign on the
+separate signing machine using the reviewed helper:
+
+```bash
+python3 /trusted/ci-fleet/scripts/attest_local_validation.py \
+  --policy /etc/ci-fleet/config-review-policy.json \
+  --result /verified/config-run --key /protected/local-validation.key \
+  --reviewed-head REVIEWED_HEAD_SHA --pull-request 42 \
+  --output /verified/APPLIED_SHA.json
+```
+
+The signing machine needs a protected copy of the policy and activation marker.
+The helper refuses quick or incomplete results, unexpected coverage, changed
+logs and the wrong validator revision. It also rejects already unusable report
+timestamps before signing or creating output. Both timestamps must be integers,
+excluding booleans, with a positive start no later than the finish and a finish
+no later than the signer's current time. Age from the original start must not
+exceed the protected policy's `local_validation.max_age_seconds`. Signing
+preserves the recorded timestamps and does not extend their expiry. A candidate
+report alone never establishes execution provenance.
+Before publishing evidence, the helper verifies the generated signature with
+the protected policy's public key. A wrong private key fails without creating
+the exclusive output file; correct the key or reviewed rotation policy first.
+The pull-request number must be positive. Zero and negative values are rejected
+before the helper reads policy, uses the signing key or creates output.
+Before signing, it rejects a report, log,
+or encoded evidence envelope over the verifier's 1 MiB file limit.
+The signer must also check source, tree,
+base, metadata and tool versions against its independently observed run. The
+host verifier repeats context, freshness, policy, signature and coverage checks.
+
+Provision `APPLIED_SHA.json` and the stage logs as root-owned regular files with
+mode `0600` under the fixed policy directory. Put the logs at
+`APPLIED_SHA.logs/CHECK_NAME.log`. Parent directories must be root-owned and
+not group- or other-writable. Symlinks, hard-linked files, unsafe permissions,
+invalid JSON, missing logs and changed log digests reject acceptance. Each file
+has a 1 MiB limit. Keep larger diagnostic archives separately; reduce noisy
+output deliberately rather than truncating accepted logs after signing.
+Neither evidence nor keys belong in Git or runner configuration. The verifier
+uses bounded protected reads, invokes OpenSSL without a shell and never prints
+API bodies or evidence contents.
+
+GitHub remains required for repository identity, commits, PR association,
+ancestry comparisons, independent reviews, base-change history and optional
+Codex evidence. App token issuance and Git fetch also remain GitHub dependencies.
+Version 2 removes the Actions API dependency only when hosted fields are absent.
+GitHub review/API outages still reject new application. Trusted last-known-good
+recovery uses the existing protected recovery record and needs neither Actions
+nor a newly signed local result. It preserves the policy and credentials.
+
+See [local validation and cutover](LOCAL-VALIDATION.md) for execution commands,
+coverage, merge/squash evidence, remaining template work and migration gates.

docs/CONTRIBUTING.md

@@ -206,7 +206,8 @@ credentials; ordinary CI keeps read-only permissions. See the
 
 A version is released (tagged on `main`) only when:
 
-- the tagged commit passes all CI checks;
+- the tagged commit passes the complete [local suite](LOCAL-VALIDATION.md), and
+  all established required hosted checks until their deliberate migration;
 - the change set is reviewed and the SemVer bump matches the Conventional
   Commits classification;
 - an operator has confirmed the live pilot evidence for any engine rollout
@@ -252,3 +253,10 @@ python3 scripts/test_validate_commits.py
 python3 scripts/validate_commits.py --message - <<< 'feat: local example'
 python3 scripts/validate_commits.py --version 0.1.0
 ```
+
+The complete validation command and evidence contract are documented in
+[local validation](LOCAL-VALIDATION.md). Local execution needs no Actions event,
+`gh`, hosted allowance or Actions API. The current required check remains active
+while parity and rollback are pending. Issue #114 must reconcile auto-merge with
+the selected evidence policy before a required check is removed. A locally
+passing subset never permits a release or bypasses review.

docs/DESIGN-DECISIONS.md

@@ -225,9 +225,26 @@ Legacy checkpoint image IDs do not make their mutable build inputs reproducible.
 
 The remaining risks are incorrect operator sequencing and inaccurate host evidence. Issue #36 retains the operational bootstrap, repeated-build and private image-ID proof. Remove this transitional exception after participating hosts have adopted image enforcement and the retained pre-enforcement rollback paths are retired through reviewed policy.
 
+## Local engine and configuration validation
+
+Status: implementation proposed under issue #135. Operational cutover pending.
+
+The [complete local suite](LOCAL-VALIDATION.md) removes Actions scheduling from
+test execution. Policy-v2 [signed local evidence](CONFIGURATION-APPROVAL.md#signed-local-validation)
+can replace Actions results while retaining independent GitHub review and
+ancestry checks. An independently trusted signer attests supervised execution;
+this is not hardware attestation or an automatic candidate-upload signing path.
+Signing authority must remain outside the Docker execution boundary.
+
+Existing root-owned policies and required-check settings retain their behavior.
+Full isolated Docker proof, compatible manager/checkpoint recovery, template
+adoption and reviewed policy cutover remain required. No host, credential,
+branch-protection, auto-merge, engine promotion or production change is authorized
+by this implementation.
+
 ## Engine integration validation budget
 
-Status: proposed in PR #136.
+Status: accepted in merged PR #136.
 
 The read-only hosted engine integration job has a 45-minute ceiling. Repository
 regressions measured about 24 minutes before image acceptance; optional APT cache