SCOPE v0.7.0: institutional pilot hardening

CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v0.7.0 (2026-06-28)
+
+Institutional pilot hardening release:
+
+- **Identity assurance (IAL0–IAL4)**: `scope/identity_assurance.py`, provenance on decisions/grants (including session grants), OIDC + org RBAC wiring; `identity_source` and `authority_checks` on decision/grant provenance
+- **RBAC vs SCOPE authority separation**: two-stage checks in `scope/authority.py` with explicit `authority_checks` provenance block
+- **Ledger delivery semantics**: `best_effort`, `at_least_once`, `fail_closed` modes with spool, `delivery_state`, and fail-closed blocking on high-risk grant issuance
+- **Review queue state machine**: explicit transitions (`in_review`, `needs_information`, `escalated`, `expired`, reopen)
+- **Signing assurance (SAL0–SAL4)**: minimum policy, production enforcement, HSM/KMS external interface
+- **Frozen AKTA review contract**: `summary.json` schema, `scope-akta-review-v0.7` adapter version
+- Policy bundle tagged `scope-core-v0.7`
+
+### Audit fixes (pre-release)
+
+- Grant provenance inherits `identity_claim_hash`, `authority_checks`, and `delegation_id` from issuing decisions (including session grants)
+- `summary.json` includes `production_mode` on all AKTA review paths; schema and docs aligned
+- Review queue: `information_received_at`, escalation reason/actor fields, ledger event on engine escalation
+- End-to-end tests and extended evals assert decision/grant provenance field parity
+
 ## v0.6.0 (2026-06-28)
 
 Institutional foundations release:

adapters/akta/examples/README.md

@@ -2,12 +2,39 @@
 
 Sample inputs for `adapters/akta/import_record.py` and `import_trigger.py`.
 
+## Fixtures
+
+| File | Description |
+|------|-------------|
+| `akta_record.json` | Minimal flat record stub |
+| `akta_record_nested.json` | Nested v0.4-style record (golden fixture) |
+| `akta_review_trigger_v04.json` | v0.4 trigger with alias fields |
+| `review_trigger.json` | Simple flat trigger |
+
+Richer scenario fixtures live under [examples/protocol_change_review/](../../examples/protocol_change_review/).
+
+## Primary integration path (v0.7)
+
+```bash
+scope akta review \
+  --akta-record adapters/akta/examples/akta_record_nested.json \
+  --akta-trigger adapters/akta/examples/akta_review_trigger_v04.json \
+  --grant-scope protocol_draft \
+  --reviewer examples/protocol_drift/reviewer_protocol_owner.json \
+  --decision-rationale "Narrow protocol draft approval only." \
+  --out-dir /tmp/akta_review_out
+```
+
+Output contract: [docs/akta_review_contract.md](../../docs/akta_review_contract.md).
+
+## Low-level Python import
+
 ```python
 from adapters.akta.import_record import load_akta_record
 from adapters.akta.import_trigger import load_review_trigger
 
-record = load_akta_record("adapters/akta/examples/akta_record.json")
-trigger = load_review_trigger("adapters/akta/examples/review_trigger.json")
+record = load_akta_record("adapters/akta/examples/akta_record_nested.json")
+trigger = load_review_trigger("adapters/akta/examples/akta_review_trigger_v04.json")
 ```
 
-These mirror `examples/protocol_change_review/` fixtures.
+Field mappings: [docs/external_integration_contracts.md](../../docs/external_integration_contracts.md).

adapters/generic_rest/server.py

@@ -181,6 +181,20 @@ class ReviewQueueCloseRequest(BaseModel):
     reason: str = ""
 
 
+class ReviewQueueNeedsInformationRequest(BaseModel):
+    reason: str = ""
+
+
+class ReviewQueueCancelRequest(BaseModel):
+    reason: str = ""
+
+
+class ReviewQueueEscalateEntryRequest(BaseModel):
+    reviewer: dict[str, Any] | None = None
+    reason: str = ""
+    actor_id: str | None = None
+
+
 class KeyRegisterRequest(BaseModel):
     reviewer_id: str
     public_key_path: str
@@ -208,6 +222,16 @@ def _http_error(exc: Exception) -> HTTPException:
     return HTTPException(status_code=400, detail=str(exc))
 
 
+@app.exception_handler(ScopeValidationError)
+async def _scope_validation_handler(_request: Request, exc: ScopeValidationError) -> HTTPException:
+    raise _http_error(exc)
+
+
+@app.exception_handler(GrantValidationError)
+async def _grant_validation_handler(_request: Request, exc: GrantValidationError) -> HTTPException:
+    raise _http_error(exc)
+
+
 @app.get("/v0/health")
 def health() -> dict[str, str]:
     return {"status": "ok", "version": __version__}
@@ -460,6 +484,104 @@ def close_review_queue(
     return ReviewQueue.load(path).status_summary()
 
 
+@app.post("/v0/review-queue/{queue_id}/in-review", dependencies=[Depends(_require_api_key)])
+def in_review_review_queue(
+    queue_id: str,
+    queue_dir: str | None = None,
+) -> dict[str, Any]:
+    from scope.review_queue import ReviewQueue
+
+    path = _find_queue_path(queue_id, queue_dir)
+    get_engine().in_review_review_queue(path)
+    return ReviewQueue.load(path).status_summary()
+
+
+@app.post(
+    "/v0/review-queue/{queue_id}/needs-information",
+    dependencies=[Depends(_require_api_key)],
+)
+def needs_information_review_queue(
+    queue_id: str,
+    req: ReviewQueueNeedsInformationRequest,
+    queue_dir: str | None = None,
+) -> dict[str, Any]:
+    from scope.review_queue import ReviewQueue
+
+    path = _find_queue_path(queue_id, queue_dir)
+    get_engine().needs_information_review_queue(path, reason=req.reason)
+    return ReviewQueue.load(path).status_summary()
+
+
+@app.post(
+    "/v0/review-queue/{queue_id}/information-received",
+    dependencies=[Depends(_require_api_key)],
+)
+def information_received_review_queue(
+    queue_id: str,
+    queue_dir: str | None = None,
+) -> dict[str, Any]:
+    from scope.review_queue import ReviewQueue
+
+    path = _find_queue_path(queue_id, queue_dir)
+    get_engine().information_received_review_queue(path)
+    return ReviewQueue.load(path).status_summary()
+
+
+@app.post("/v0/review-queue/{queue_id}/reopen", dependencies=[Depends(_require_api_key)])
+def reopen_review_queue(
+    queue_id: str,
+    queue_dir: str | None = None,
+) -> dict[str, Any]:
+    from scope.review_queue import ReviewQueue
+
+    path = _find_queue_path(queue_id, queue_dir)
+    get_engine().reopen_review_queue(path)
+    return ReviewQueue.load(path).status_summary()
+
+
+@app.post("/v0/review-queue/{queue_id}/expire", dependencies=[Depends(_require_api_key)])
+def expire_review_queue(
+    queue_id: str,
+    queue_dir: str | None = None,
+) -> dict[str, Any]:
+    from scope.review_queue import ReviewQueue
+
+    path = _find_queue_path(queue_id, queue_dir)
+    get_engine().expire_review_queue(path)
+    return ReviewQueue.load(path).status_summary()
+
+
+@app.post("/v0/review-queue/{queue_id}/cancel", dependencies=[Depends(_require_api_key)])
+def cancel_review_queue(
+    queue_id: str,
+    req: ReviewQueueCancelRequest,
+    queue_dir: str | None = None,
+) -> dict[str, Any]:
+    from scope.review_queue import ReviewQueue
+
+    path = _find_queue_path(queue_id, queue_dir)
+    get_engine().cancel_review_queue(path, reason=req.reason)
+    return ReviewQueue.load(path).status_summary()
+
+
+@app.post("/v0/review-queue/{queue_id}/escalate", dependencies=[Depends(_require_api_key)])
+def escalate_review_queue_entry(
+    queue_id: str,
+    req: ReviewQueueEscalateEntryRequest,
+    queue_dir: str | None = None,
+) -> dict[str, Any]:
+    from scope.review_queue import ReviewQueue
+
+    path = _find_queue_path(queue_id, queue_dir)
+    get_engine().escalate_review_queue_entry(
+        path,
+        req.reviewer,
+        reason=req.reason,
+        actor_id=req.actor_id,
+    )
+    return ReviewQueue.load(path).status_summary()
+
+
 def _policy_dir() -> Path:
     return Path(get_engine().policy.policy_dir)
 

adapters/pcs/examples/README.md

@@ -6,16 +6,34 @@ Sample PCS release layout produced by `adapters/pcs/export_artifact.py`:
 - `scope_decision.json`
 - `scope_grant.json`
 - `pf_obligation.json`
-- `release_manifest.json` (artifact hashes and source IDs)
+- `release_manifest.json` (artifact hashes, trust root, registry metadata)
 
-Generate live output:
+Manifest version: `pcs-v0.5`. See [docs/pcs_export.md](../../docs/pcs_export.md).
+
+## Generate live output
+
+Use artifacts from [examples/institutional_pilot/](../../examples/institutional_pilot/) or your own grant workflow:
+
+```bash
+scope export pcs \
+  --packet examples/institutional_pilot/scope_packet.json \
+  --decision examples/institutional_pilot/scope_decision.json \
+  --grant examples/institutional_pilot/scope_grant.json \
+  --out dist/pcs_scope_artifact/ \
+  --validate
+```
+
+Optional live contract validation:
 
 ```bash
+export PCS_CORE_REPO_PATH=/path/to/pcs-core
 scope export pcs \
-  --packet /tmp/packet.json \
-  --decision /tmp/decision.json \
-  --grant /tmp/grant.json \
-  --out dist/pcs_scope_artifact/
+  --packet examples/institutional_pilot/scope_packet.json \
+  --decision examples/institutional_pilot/scope_decision.json \
+  --grant examples/institutional_pilot/scope_grant.json \
+  --out dist/pcs_scope_artifact/ --validate --live
 ```
 
-The manifest includes canonical `sha256:` hashes for each artifact file.
+The manifest includes canonical `sha256:` hashes for each artifact file plus `scope_trust_root_hash` when policy and registry are configured.
+
+Field mapping: [docs/external_integration_contracts.md](../../docs/external_integration_contracts.md).

adapters/pf_core/examples/README.md

@@ -2,15 +2,28 @@
 
 Sample output from `adapters/pf_core/export_obligation.py` after issuing a protocol-draft grant.
 
-Generate live output:
+Contract version: `pf-core-v0.5`. See [docs/pf_core_bridge.md](../../docs/pf_core_bridge.md).
+
+## Generate live output
+
+After running a grant workflow (e.g. [examples/stale_grant_attempt/](../../examples/stale_grant_attempt/) or [examples/institutional_pilot/](../../examples/institutional_pilot/)):
 
 ```bash
 scope export pf \
-  --grant examples/protocol_change_review/scope_grant.json \
-  --out dist/pf_obligation.json
+  --grant examples/institutional_pilot/scope_grant.json \
+  --out dist/pf_obligation.json \
+  --validate
 ```
 
-Or from Python:
+Optional live contract validation:
+
+```bash
+export PF_CORE_REPO_PATH=/path/to/pf-core
+scope export pf --grant examples/institutional_pilot/scope_grant.json \
+  --out dist/pf_obligation.json --validate --live
+```
+
+## Python API
 
 ```python
 from adapters.pf_core.export_obligation import export_pf_obligation
@@ -19,4 +32,6 @@ import json
 obligation = export_pf_obligation(json.load(open("scope_grant.json")))
 ```
 
-See `pf_obligation.json` in this directory for the expected shape.
+## Sample shape
+
+See `pf_obligation.json` in this directory for a representative obligation layout. Regenerate from a live grant for current contract fields and signature metadata.

adapters/pf_core/examples/pf_obligation.json

@@ -1,5 +1,5 @@
 {
-  "obligation_version": "pf-core-v0.1",
+  "obligation_version": "pf-core-v0.5",
   "grant_id": "SCOPE-GRANT-EXAMPLE",
   "grant_hash": "sha256:example",
   "permitted_tools": ["protocol_editor.draft_change"],

docs/akta_integration.md

@@ -2,12 +2,32 @@
 
 SCOPE begins when AKTA returns `review_required` or `authorization_required`.
 
+## Primary integration path
+
+For packet → decision → grant in one step, use:
+
+```bash
+scope akta review \
+  --akta-record path/to/akta_record.json \
+  --akta-trigger path/to/review_trigger.json \
+  --grant-scope protocol_draft \
+  --reviewer path/to/reviewer.json \
+  --decision-rationale "Rationale text." \
+  --out-dir /tmp/akta_review_out
+```
+
+REST equivalent: `POST /v0/akta/review`.
+
+Output contract: [akta_review_contract.md](akta_review_contract.md). Full demo: [akta_scope_demo.md](akta_scope_demo.md). Field mappings: [external_integration_contracts.md](external_integration_contracts.md).
+
 ## Inputs
 
 - **AKTA Record** — scientific action context, artifacts, constraints
 - **Review trigger** — requested tool, action type, admissibility
 
-## Adapter
+Golden fixtures: `adapters/akta/examples/` (see [adapters/akta/examples/README.md](../adapters/akta/examples/README.md)).
+
+## Low-level adapter (Python)
 
 ```python
 from adapters.akta.import_trigger import load_review_trigger
@@ -18,10 +38,20 @@ engine = ScopeEngine.from_policy_dir("policy/")
 packet = engine.create_packet("akta_record.json", trigger)
 ```
 
+Use this path when you need custom packet enrichment (VSA reports, manual review steps) before decision submit.
+
 ## Required trigger fields
 
 - `scientific_action_type` (e.g. `A5_protocol_modification`)
 - `akta_admissibility` (`review_required` or `authorization_required`)
 - `requested_tool`
 
 SCOPE resolves required reviewer roles from `policy/role_to_action_matrix.yaml`.
+
+## v0.7 provenance on review output
+
+Decisions and grants from `scope akta review` record:
+
+- Identity assurance level (IAL0–IAL4) — see [identity_assurance.md](identity_assurance.md)
+- Signing assurance level (SAL0–SAL4) — see [signing_assurance.md](signing_assurance.md)
+- Two-stage `authority_checks` when RBAC is enforced — see [rbac_scope_authority.md](rbac_scope_authority.md)