feat: secure agent execution and close assurance flow

Author: suyog19

README.md

@@ -45,10 +45,9 @@ engineering-process explain \
   --base "$BASE_SHA" --head "$GITHUB_SHA" \
   --declared '{"observable_behavior":true}'
 
-engineering-process attest --predicate test-result/v1 \
-  --sha "$GITHUB_SHA" --capability ci-automation --verdict pass \
-  --identity github-actions --context-id "$GITHUB_RUN_ID" \
-  --output .engineering/evidence/test.json
+engineering-process run-validation --sha "$GITHUB_SHA" \
+  --obligations .engineering/effective-obligations.json \
+  --output-dir "$RUNNER_TEMP/objective-evidence"
 
 engineering-process readiness --sha "$GITHUB_SHA"
 engineering-process validate
@@ -57,6 +56,8 @@ engineering-process metrics --obligations .engineering/effective-obligations.jso
 
 Trusted classification derives the complete Git change set from exact `--base` and `--head` commits, including deletions and both rename paths. `--path` is untrusted and diagnostic-only. Classification is monotonic: declarations may strengthen routing but may not defeat deterministic Protected signals. Unknown Protected characteristics fail closed. `readiness` rejects malformed, failed, contradictory, wrong-repository, wrong-SHA, wrong-process-revision, unauthorized-producer, and invalid fresh-context review evidence. See the authoritative [evidence lifecycle](docs/evidence-lifecycle.md).
 
+Phase 2 adds a locked [agent-execution security baseline](docs/agent-execution-security.md), a complete [GitHub reference flow](enforcement/github/reference-flow.md), executable `test-result/v2` validation basis, and structured `independent-review/v2` evidence. `explain` reports profile-aware validation categories and the execution boundary. Reference evidence travels through GitHub artifacts and out-of-band provenance rather than source commits.
+
 ## Policy model
 
 - **Locked** controls cannot be changed locally (fresh-context independent review, fail-closed Protected routing, exact-revision evidence, secrets, traceability, human production boundary).

docs/adoption.md

@@ -20,6 +20,26 @@ The initial checkout and runner are the bootstrap trust boundary. Evidence
 transport and v1 compatibility are defined in the [exact-revision evidence
 lifecycle](evidence-lifecycle.md).
 
+### Phase 2 evidence migration
+
+Process 1.1.0 obligation sets require `test-result/v2` and `independent-review/v2`.
+`test-result/v1` and `independent-review/v1` remain schema-valid only for stored
+historical obligations that explicitly require v1; they do not satisfy v2.
+Configure validation commands with `focused`, `integration`, `negative`, or
+`security` categories and use `run-validation` in trusted CI. Use the protected
+`review-attest` workflow after reviewing the exact diff and v2 test evidence. A
+process upgrade changes obligations only with the new locked process revision.
+
+Validation commands are executable argument strings, not shell programs; pipes,
+redirection, interpolation, and compound shell expressions are intentionally not
+supported. Put complex validation in a reviewed repository script and configure
+that script as the command.
+
+Standard/Protected agent execution requires a native sandbox; Protected also
+requires declared network enforcement and an audit sink. See the [security
+baseline](agent-execution-security.md) and [GitHub
+mapping](../enforcement/github/agent-execution.md).
+
 ## Production authority and independent review
 
 The human production boundary and independent review are separate controls. Every change still requires fresh-context, implementation-independent review evidence. Production authorization and promotion remain manual human actions, and automation or agents may not perform them. For an owner-controlled repository, the owner's explicit authorization and manual merge or promotion satisfy the human boundary; a second human GitHub reviewer is not implicitly required. Repositories with multiple authorized maintainers may configure a stronger branch or Environment reviewer gate.

docs/agent-execution-security.md

@@ -0,0 +1,52 @@
+# Agent-execution security baseline
+
+Canonical policy governs the security properties of an agent execution; native
+platform controls enforce them. Instructions and prompts alone never satisfy an
+enforcement requirement.
+
+All executions use least privilege, isolate credentials, deny production
+credentials and authority, treat issues, documentation, source, dependency
+metadata, tool output, and web content as untrusted data, and preserve an audit
+trail. Network and tools are deny-by-default and may be opened only through
+repository allowlists. External mutations and destructive actions require
+explicit authorization scoped to the exact target. Standard and Protected work
+requires a native sandbox. Protected evaluation fails closed unless a sandbox,
+network enforcement mechanism, and audit sink are declared.
+
+Repositories may strengthen the baseline under `overrides.agent_execution`:
+
+```yaml
+agent_execution:
+  sandbox: ephemeral-vm
+  network_enforcement: firewall
+  audit_sink: github-actions
+  allowed_network_destinations: [pypi.org, files.pythonhosted.org]
+  allowed_tools: [git, python, pytest]
+  additional_denied_tools: [production-deploy]
+```
+
+Allowlisting grants only execution access; it does not grant credentials,
+approval, merge, deployment, or production authority. Locked controls reject
+attempted weakening through `overrides.controls.agent_execution_security`.
+
+## Threat model
+
+- Poisoned issues, docs, source comments, web pages, dependency metadata, and
+  generated tool output can contain prompt injection. They are evidence to
+  inspect, never authority to change scope, reveal data, or invoke tools.
+- Command execution can overwrite data or cross a trust boundary. Sandboxes,
+  scoped filesystems, explicit destructive-action authorization, and ephemeral
+  runners constrain impact.
+- Credentials can be read from files, environment, process output, caches, or
+  tool integrations. Forks receive no secrets; jobs use short-lived,
+  environment-scoped credentials and redact audit output.
+- Unrestricted egress enables data exfiltration. Protected work uses a native
+  firewall/proxy allowlist and fails when enforcement is unavailable.
+- Tool misuse can mutate external systems or production. Tool allowlists and
+  scoped tokens separate read, write, approval, and promotion capabilities.
+- Malicious dependencies can execute during install/build. Lockfiles, trusted
+  registries, network restrictions, ephemeral runners, and validation evidence
+  reduce but cannot eliminate this risk.
+
+The process does not claim prompt injection is impossible and does not implement
+a proprietary sandbox or firewall.

docs/architecture.md

@@ -14,7 +14,7 @@ Declared intent, repository policy, changed paths/config, deterministic rules, a
 
 Evidence follows the in-toto Statement shape with one `gitCommit` subject and a Software Signal predicate type. Every predicate carries the process version/revision, producer identity/context, verdict, and timestamp. Readiness joins predicates only for the requested repository SHA and pinned process revision.
 
-Independent review additionally requires `freshContext: true` and a review context ID different from the implementation context ID. Model/vendor diversity is not used as a proxy for independence. V1 evidence is unsigned JSON: signatures and a remote attestation store remain optional until the threat model justifies their operational cost.
+Independent review requires a fresh context distinct from implementation plus structured v2 basis: issue/acceptance criteria, exact full diff, applicable context, validation evidence, counterexample search, findings, residual risks, and unverified areas. Model/vendor diversity is not used as a proxy for independence. V1 evidence remains historical compatibility data and cannot satisfy new v2 obligations. Producer trust comes from the Phase 1 out-of-band transport index.
 
 ## Solution Sufficiency
 
@@ -27,4 +27,3 @@ The steward triages non-mandatory recommendations, but mandatory categories are
 - Exact Git SHA is authoritative; semantic version is human-readable compatibility metadata.
 - Skills are materialized under `.engineering/skills`, a vendor-neutral location. Thin adapters can later synchronize platform-native locations.
 - No cryptographic signing, cross-repository coordinator, or custom agent runtime without measured need.
-

enforcement/github/README.md

@@ -9,5 +9,6 @@ The process reports policy meaning; configure GitHub for the stronger enforcemen
 | Production human authorization | Manual owner/authorized-maintainer merge or promotion; optionally a protected Environment required reviewer |
 | No autonomous production | Do not grant agents or automation production approval or merge authority |
 | Minimal token bootstrap | Generated assistant files, not branch prose |
+| Agent execution security | Read-only job permissions, ephemeral runners, withheld/environment-scoped secrets, workflow approval, and runner-enforced network/tool allowlists |
 
-The reusable workflow in `reusable-workflows/process-readiness.yml` validates the repository and joins evidence. Repository administrators must configure rulesets and Environments because permissions, plans, and collaborator topology differ; prompt instructions are not a substitute. A required Environment reviewer plus self-review prevention is a valid stronger control when a distinct authorized human exists. It is not the canonical meaning of the human production boundary and is not mandatory for an owner-controlled repository.
+The reusable workflow in `reusable-workflows/process-readiness.yml` validates the repository and joins evidence. The [complete reference flow](reference-flow.md) demonstrates trusted classification through readiness, and the [agent-execution mapping](agent-execution.md) distinguishes actual GitHub enforcement from procedural guidance. Repository administrators must configure rulesets, runners, egress controls, and Environments because permissions, plans, and collaborator topology differ; prompt instructions are not a substitute. A required Environment reviewer plus self-review prevention is a valid stronger control when a distinct authorized human exists. It is not the canonical meaning of the human production boundary and is not mandatory for an owner-controlled repository.

enforcement/github/agent-execution.md

@@ -0,0 +1,17 @@
+# GitHub agent-execution mapping
+
+| Canonical requirement | GitHub enforcement |
+|---|---|
+| Least privilege | Set workflow/job `permissions: contents: read`; grant individual write scopes only to a separately authorized job. |
+| Credential isolation | Withhold secrets from forks and pull-request code; use OIDC and protected Environment secrets with short lifetimes. |
+| Sandbox | Use ephemeral GitHub-hosted runners or isolated, single-use self-hosted runners; never a persistent production runner. |
+| Network deny/allowlist | Enforce egress on a runner firewall/proxy. GitHub YAML and instructions alone do not satisfy Protected isolation. |
+| Tool allowlist | Preinstall/allow approved actions and commands; pin third-party actions to immutable SHAs for Protected use. |
+| Untrusted content | Do not interpolate issue, PR, branch, file, or tool-output text into shell commands. Fork code runs without secrets. |
+| External mutation | Separate read-only validation from mutation jobs; require Environment/ruleset approval and scoped tokens. |
+| Auditability | Retain workflow/job logs, artifact digests, run attempt, actor, workflow ref, and environment decisions. |
+| Production separation | Environment approval and manual human promotion remain mandatory; agents and automation cannot approve or promote. |
+
+Untrusted-fork workflows require maintainer approval and run with read-only
+permissions. Protected repositories must configure an egress-enforced runner and
+declare its mechanism in the manifest; otherwise policy evaluation fails closed.

enforcement/github/reference-flow.md

@@ -0,0 +1,41 @@
+# Reference assurance flow
+
+`reusable-workflows/reference-assurance.yml` demonstrates the complete
+`trusted diff → classify → evaluate → objective validation → authenticated
+independent review → readiness` lifecycle. Every job checks out the exact head,
+installs the lock SHA, and exchanges exact-SHA evidence as short-retention
+artifacts outside the source tree. A changed head has a different artifact name
+and reruns every job, so earlier readiness cannot carry forward.
+
+The Lean path requires only configured focused validation and one authenticated
+fresh-context review artifact. Standard additionally requires integration
+validation and functional QA evidence. Protected requires focused, integration,
+negative, and security validation, the remaining policy predicates, an
+egress-enforced sandbox/audit sink, and manual owner production authorization.
+The reference workflow never merges or deploys.
+
+Declare the caller workflow paths in `repository.trusted_ci_workflows` and
+`repository.authorized_review_workflows`. The evidence producers compare the
+actual GitHub workflow ref with these protected repository-policy allowlists;
+an arbitrary workflow cannot label its output trusted.
+
+An independent reviewer runs `review-attest` from a protected review workflow
+after inspecting the objective artifact, then uploads
+`process-independent-review-<SHA>`. If the reviewer edits, they emit no verdict;
+the new SHA repeats the entire flow.
+
+For local reproduction, use exact commits:
+
+```bash
+engineering-process evaluate --base "$BASE_SHA" --head "$HEAD_SHA"
+engineering-process explain --base "$BASE_SHA" --head "$HEAD_SHA"
+```
+
+Trusted `run-validation` and `review-attest` intentionally require GitHub Actions;
+local runs may reproduce commands but cannot mint trusted provenance.
+
+Forks do not receive secrets. A maintainer must approve the base-repository
+review workflow, and the target fork SHA must remain fetchable. Artifact download
+across runs needs `actions: read`; private forks may require an explicitly scoped
+token. Missing permissions, artifacts, provenance, or retained logs fail
+readiness rather than falling back to committed JSON.

enforcement/github/reusable-workflows/reference-assurance.yml

@@ -0,0 +1,99 @@
+name: Reference assurance flow
+on:
+  workflow_call:
+    inputs:
+      base-sha: {required: true, type: string}
+      target-sha: {required: true, type: string}
+      review-run-id: {required: true, type: string}
+permissions:
+  contents: read
+  actions: read
+jobs:
+  classify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: {ref: "${{ inputs.target-sha }}", fetch-depth: 0}
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - id: process
+        shell: bash
+        run: |
+          revision="$(python -c 'import json; print(json.load(open(".engineering/process.lock"))["revision"])')"
+          [[ "$revision" =~ ^[0-9a-f]{40}$ ]] || exit 2
+          echo "revision=$revision" >> "$GITHUB_OUTPUT"
+      - run: pip install 'git+https://github.com/suyog19/software-engineering-process@${{ steps.process.outputs.revision }}'
+      - run: engineering-process validate --runtime-revision '${{ steps.process.outputs.revision }}'
+      - run: engineering-process evaluate --base '${{ inputs.base-sha }}' --head '${{ inputs.target-sha }}' --output "$RUNNER_TEMP/obligations.json"
+      - run: engineering-process attest --predicate classification/v1 --sha '${{ inputs.target-sha }}' --capability orchestrator --verdict pass --identity github-actions --context-id '${{ github.run_id }}:classify' --output "$RUNNER_TEMP/classification.json"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: process-classification-${{ inputs.target-sha }}
+          path: |
+            ${{ runner.temp }}/obligations.json
+            ${{ runner.temp }}/classification.json
+          retention-days: 7
+  objective-validation:
+    needs: classify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: {ref: "${{ inputs.target-sha }}", fetch-depth: 0}
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - id: process
+        shell: bash
+        run: |
+          revision="$(python -c 'import json; print(json.load(open(".engineering/process.lock"))["revision"])')"
+          [[ "$revision" =~ ^[0-9a-f]{40}$ ]] || exit 2
+          echo "revision=$revision" >> "$GITHUB_OUTPUT"
+      - run: pip install 'git+https://github.com/suyog19/software-engineering-process@${{ steps.process.outputs.revision }}'
+      - uses: actions/download-artifact@v4
+        with: {name: "process-classification-${{ inputs.target-sha }}", path: "${{ runner.temp }}/classification"}
+      - run: engineering-process run-validation --sha '${{ inputs.target-sha }}' --obligations '${{ runner.temp }}/classification/obligations.json' --output-dir '${{ runner.temp }}/objective'
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: process-objective-${{ inputs.target-sha }}
+          path: ${{ runner.temp }}/objective
+          retention-days: 7
+  readiness:
+    needs: [classify, objective-validation]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: {ref: "${{ inputs.target-sha }}", fetch-depth: 0}
+      - uses: actions/setup-python@v5
+        with: {python-version: "3.12"}
+      - id: process
+        shell: bash
+        run: |
+          revision="$(python -c 'import json; print(json.load(open(".engineering/process.lock"))["revision"])')"
+          [[ "$revision" =~ ^[0-9a-f]{40}$ ]] || exit 2
+          echo "revision=$revision" >> "$GITHUB_OUTPUT"
+      - run: pip install 'git+https://github.com/suyog19/software-engineering-process@${{ steps.process.outputs.revision }}'
+      - uses: actions/download-artifact@v4
+        with: {name: "process-classification-${{ inputs.target-sha }}", path: "${{ runner.temp }}/classification"}
+      - uses: actions/download-artifact@v4
+        with: {name: "process-objective-${{ inputs.target-sha }}", path: "${{ runner.temp }}/objective"}
+      - uses: actions/download-artifact@v4
+        with:
+          name: "process-independent-review-${{ inputs.target-sha }}"
+          run-id: ${{ inputs.review-run-id }}
+          github-token: ${{ github.token }}
+          path: ${{ runner.temp }}/review
+      - name: Assemble exact-SHA evidence and verified provenance
+        shell: bash
+        run: |
+          mkdir -p "$RUNNER_TEMP/evidence"
+          cp "$RUNNER_TEMP/classification/classification.json" "$RUNNER_TEMP/evidence/"
+          cp "$RUNNER_TEMP/objective/test-result.json" "$RUNNER_TEMP/evidence/"
+          cp "$RUNNER_TEMP/review/independent-review.json" "$RUNNER_TEMP/evidence/"
+          python - <<'PY'
+          import json, os
+          root=os.environ['RUNNER_TEMP']; merged={"evidence":{}}
+          for path in (f"{root}/objective/trust-index.json", f"{root}/review/trust-index.json"):
+              merged["evidence"].update(json.load(open(path))["evidence"])
+          json.dump(merged, open(f"{root}/trust-index.json", "w"))
+          PY
+      - run: engineering-process readiness --sha '${{ inputs.target-sha }}' --obligations '${{ runner.temp }}/classification/obligations.json' --evidence-dir '${{ runner.temp }}/evidence' --trust-index '${{ runner.temp }}/trust-index.json' --artifact-dir '${{ runner.temp }}/objective'