feat: repair assurance roots of trust

Author: suyog19

README.md

@@ -34,18 +34,15 @@ Or supply an immutable released revision explicitly with `--revision <40-hex-sha
 
 ```bash
 engineering-process classify \
-  --sha "$GITHUB_SHA" \
-  --path src/payments/refund.py \
+  --base "$BASE_SHA" --head "$GITHUB_SHA" \
   --declared '{"observable_behavior":true}'
 
 engineering-process evaluate \
-  --sha "$GITHUB_SHA" \
-  --path src/payments/refund.py \
+  --base "$BASE_SHA" --head "$GITHUB_SHA" \
   --declared '{"observable_behavior":true}'
 
 engineering-process explain \
-  --sha "$GITHUB_SHA" \
-  --path src/payments/refund.py \
+  --base "$BASE_SHA" --head "$GITHUB_SHA" \
   --declared '{"observable_behavior":true}'
 
 engineering-process attest --predicate test-result/v1 \
@@ -58,7 +55,7 @@ engineering-process validate
 engineering-process metrics --obligations .engineering/effective-obligations.json
 ```
 
-`classify` is monotonic: declarations may strengthen routing but may not defeat deterministic Protected signals. Unknown Protected characteristics fail closed. `readiness` rejects malformed, failed, contradictory, wrong-SHA, wrong-process-revision, and invalid fresh-context review evidence.
+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).
 
 ## Policy model
 

docs/adoption.md

@@ -9,6 +9,17 @@
 
 Repository-local technology is deliberately opaque to policy. Put commands under `overrides.validation.commands`; add sensitive paths/characteristics and domain triggers when they strengthen classification. Never copy the canonical policy into the manifest.
 
+## Locked process upgrades
+
+CI executes the immutable Git SHA in `.engineering/process.lock`, never a floating
+package, tag, or branch. Change it only through a reviewed
+`engineering-process upgrade --version VERSION --revision 40_HEX_SHA`. The
+upgrade refreshes the manifest, lock, generated workflow, and policy snapshot
+together. Missing, unavailable, floating, or inconsistent revisions fail closed.
+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).
+
 ## 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/evidence-lifecycle.md

@@ -0,0 +1,80 @@
+# Exact-revision evidence lifecycle
+
+This is the authoritative operational contract for process evidence. Evidence
+JSON is data, never proof of its own producer. Canonical policy defines required
+predicates and producer classes; a platform adapter verifies transport identity
+and supplies a separate trust index.
+
+## Sequence and storage
+
+```text
+push H -> trusted diff(base,H) -> classification(H, process P)
+  -> CI/authenticated verdicts(H,P,repository) -> immutable artifact store
+  -> readiness joins artifacts + verified provenance -> merge status
+  -> merge creates M (H is stale) -> deployment-release(M,P) in release store
+```
+
+The manifest, lock, and policy are source controlled. Pre-merge classification,
+test, specialist, review, approval, and readiness evidence are not committed:
+GitHub stores them as immutable workflow artifacts or attestations keyed by
+repository, head SHA, process revision, workflow run and attempt. Equivalent
+platforms may use an external store with the same keys. Deployment evidence is
+post-merge evidence and is retained separately from the readiness join.
+
+`readiness` reads predicates from downloaded artifacts. Authenticated/trusted
+status comes only from a verified transport index outside the checkout. It maps
+each evidence content digest to repository, target revision, capability,
+producer class, and platform identity. GitHub records also carry workflow,
+run/attempt, and job identity. Repository-authored producer fields cannot elevate
+evidence.
+
+## Ordering, invalidation, and recovery
+
+1. Resolve immutable base/head commits and classify their complete Git diff.
+2. Publish classification before dependent jobs; every producer uses that exact
+   head and locked process revision.
+3. Collect all predicates and provenance, then run the readiness join.
+4. Any new head is a different key and immediately invalidates prior readiness.
+   Merge and post-merge release commits require their own evidence.
+
+A rerun creates a new immutable attempt. Any failing or conflicting verdict in a
+selected collection fails the join; success does not erase failure. Resolve a
+contradiction with a clean run and an explicitly selected, auditable attempt. A
+missing, expired, malformed, inaccessible, or unverifiable artifact fails closed:
+restore/fetch it or rerun; never copy evidence to a new SHA. Retention follows
+the platform policy and for Protected work should cover merge plus the audit
+period. Expired evidence requires rerun.
+
+Fork runs may create asserted diagnostics, but receive neither secrets nor trusted
+status. Protected readiness runs in the base repository after authorization,
+against the fork head SHA, with read-only source permissions. Human and agent
+verdicts enter through authenticated reviews, protected workflow dispatch, or an
+external service preserving actor/event audit identity; committed JSON remains
+an assertion.
+
+## Threat model
+
+- Contributors can create, replace, and replay repository JSON, but cannot create
+  authenticated/trusted provenance that way.
+- Workflow authors can alter repository workflows. Protected trusted CI is
+  restricted to approved workflow identities/refs and environment or ruleset;
+  workflow changes themselves classify Protected.
+- Platform administrators are inside the platform trust boundary. Audit logs and
+  artifact attestations reduce replacement risk.
+- Compromised credentials may impersonate their holder. Adapters require least
+  privilege, OIDC issuer/audience checks, and short-lived credentials.
+- Repository, exact SHA, process revision, content digest and run identity prevent
+  replay. Wrong repository/workflow/job and unauthorized capability fail.
+
+Lean v1 evidence remains proportionate and may be `asserted` where policy allows.
+Standard and Protected progressively require authenticated/trusted provenance per
+`policy/evidence/producer-authorization.yaml`. No self-declared v1 field is ever
+upgraded to trusted status.
+
+## Process upgrades and bootstrap trust
+
+The executable revision changes only through `engineering-process upgrade`, which
+updates the manifest, lock, generated workflow and snapshot together. Generated
+and reusable workflows install the exact 40-character lock SHA and pass it back
+to validation. Missing, floating, unavailable, or mismatched revisions fail.
+The initial checkout, Git host, and action runner are bootstrap trust assumptions.

enforcement/github/reusable-workflows/process-readiness.yml

@@ -13,7 +13,14 @@ jobs:
         with: {ref: "${{ inputs.target-sha }}", fetch-depth: 0}
       - uses: actions/setup-python@v5
         with: {python-version: "3.12"}
-      - run: pip install software-engineering-process
-      - run: engineering-process validate
+      - name: Resolve locked process revision
+        id: process
+        shell: bash
+        run: |
+          revision="$(python -c 'import json; print(json.load(open(".engineering/process.lock"))["revision"])')"
+          [[ "$revision" =~ ^[0-9a-f]{40}$ ]] || { echo 'invalid locked process revision' >&2; exit 2; }
+          echo "revision=$revision" >> "$GITHUB_OUTPUT"
+      - name: Install exact locked process revision
+        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 readiness --sha "${{ inputs.target-sha }}"
-

policy/classification/characteristics.yaml

@@ -1,5 +1,5 @@
 lean_hints: [typo, documentation_only, metadata_only, mechanical_test_only, established_css_only]
-standard: [observable_behavior, public_contract, user_journey, information_architecture, architecture, cross_service, state_transition, validation_or_error, performance, retry, concurrency]
+standard: [observable_behavior, public_contract, user_journey, information_architecture, architecture, cross_service, state_transition, validation_or_error, performance, retry, concurrency, dependency_change, generated_change]
 protected: [financial_consequence, payment, payment_provider_trust, authentication, authorization, iam, privilege_or_trust, secrets, sensitive_data, production_controls, irreversible_data, infrastructure, refund_or_cancellation, learner_entitlement, sensitive_admin_action]
 deterministic_files:
   - {pattern: "**/auth/**", characteristic: authentication}
@@ -8,5 +8,15 @@ deterministic_files:
   - {pattern: "**/secrets/**", characteristic: secrets}
   - {pattern: "**/migrations/**", characteristic: irreversible_data}
   - {pattern: "**/infra/**", characteristic: infrastructure}
-  - {pattern: ".github/workflows/deploy*.yml", characteristic: production_controls}
-
+  - {pattern: ".github/workflows/**", characteristic: production_controls}
+  - {pattern: "**/package-lock.json", characteristic: dependency_change}
+  - {pattern: "**/requirements*.txt", characteristic: dependency_change}
+  - {pattern: "**/poetry.lock", characteristic: dependency_change}
+  - {pattern: "**/uv.lock", characteristic: dependency_change}
+  - {pattern: "**/Cargo.lock", characteristic: dependency_change}
+  - {pattern: "**/go.sum", characteristic: dependency_change}
+  - {pattern: "**/generated/**", characteristic: generated_change}
+  - {pattern: ".engineering/process.yaml", characteristic: privilege_or_trust}
+  - {pattern: ".engineering/process.lock", characteristic: privilege_or_trust}
+  - {pattern: "AGENTS.md", characteristic: privilege_or_trust}
+  - {pattern: "CLAUDE.md", characteristic: privilege_or_trust}

policy/evidence/producer-authorization.yaml

@@ -0,0 +1,12 @@
+trust_levels: {asserted: 0, authenticated: 1, trusted: 2}
+predicates:
+  classification/v1: {producer_classes: [trusted-ci], minimum: {Lean: asserted, Standard: authenticated, Protected: trusted}}
+  test-result/v1: {producer_classes: [trusted-ci], minimum: {Lean: asserted, Standard: authenticated, Protected: trusted}}
+  ux-verdict/v1: {producer_classes: [authorized-human, authorized-agent], minimum: {Standard: authenticated, Protected: authenticated}}
+  architecture-decision/v1: {producer_classes: [authorized-human, authorized-agent], minimum: {Protected: authenticated}}
+  functional-qa-verdict/v1: {producer_classes: [authorized-human, authorized-agent, trusted-ci], minimum: {Standard: authenticated, Protected: authenticated}}
+  non-functional-qa-verdict/v1: {producer_classes: [authorized-human, authorized-agent, trusted-ci], minimum: {Protected: authenticated}}
+  independent-review/v1: {producer_classes: [authorized-human, authorized-agent], minimum: {Lean: asserted, Standard: authenticated, Protected: authenticated}}
+  solution-sufficiency/v1: {producer_classes: [authorized-human, authorized-agent], minimum: {Protected: authenticated}}
+  human-approval/v1: {producer_classes: [product-owner], minimum: {Protected: authenticated}}
+  deployment-release/v1: {producer_classes: [trusted-ci], minimum: {Protected: trusted}}

src/engineering_process/classification.py

@@ -20,12 +20,16 @@ class Signal:
 @dataclass
 class Classification:
     target_revision: str
+    base_revision: str
     delivery_profile: str
     characteristics: dict[str, bool | None]
     deterministic_signals: list[dict]
     semantic_rationale: str
     reasons: list[str]
     protected_ambiguity: bool = False
+    change_set: list[dict] | None = None
+    input_trust: str = "untrusted-manual"
+    path_explanations: list[dict] | None = None
 
     def to_dict(self) -> dict:
         return asdict(self)
@@ -44,8 +48,12 @@ def classify(
     semantic: dict[str, bool | None] | None = None,
     semantic_rationale: str = "",
     target_revision: str = "",
+    base_revision: str = "",
+    change_set: list[dict] | None = None,
+    input_trust: str = "untrusted-manual",
 ) -> Classification:
     cfg = load_yaml(policy_root / "classification" / "characteristics.yaml")
+    changed_paths = list(changed_paths)
     declared, semantic = declared or {}, semantic or {}
     characteristics: dict[str, bool | None] = {**declared, **semantic}
     rules = list(cfg["deterministic_files"])
@@ -92,4 +100,9 @@ def classify(
         reasons.append(f"Ignored requested downgrade to {explicit_profile}; classification is monotonic")
     if any(s.characteristic in protected for s in signals) and delivery != "Protected":
         raise ProcessError("internal classification integrity failure: Protected signal was downgraded")
-    return Classification(target_revision, delivery, characteristics, [asdict(s) for s in signals], semantic_rationale, reasons, bool(unresolved))
+    explanations = []
+    for path in changed_paths:
+        matched = sorted({signal.characteristic for signal in signals if signal.value == path})
+        explanations.append({"path": path, "deterministic_characteristics": matched,
+                             "effect": "matched deterministic rule(s)" if matched else "no deterministic rule matched"})
+    return Classification(target_revision, base_revision, delivery, characteristics, [asdict(s) for s in signals], semantic_rationale, reasons, bool(unresolved), change_set or [], input_trust, explanations)