blocksifrdev · Apr 25, 2026 · Apr 25, 2026 · Apr 25, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -17,3 +17,7 @@
   - robust changed-file serialization,
   - local fallback receipts in no-op/misconfigured environments,
   - step-up approval satisfaction in enforcement.
+- Runtime authority model aligned to compact production prompt:
+  - decision outcomes constrained to `PERMIT|STEP_UP|ESCALATE|DENY`,
+  - constrained behavior represented with `mode=CONSTRAINED`,
+  - receipt upgraded to include `execution`, `decision`, `trust`, `risk`, `cost`, `compliance`, `evidence`, and `integrity` sections.
diff --git a/README.md b/README.md
@@ -2,6 +2,8 @@
 
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
 [![Positioning](https://img.shields.io/badge/focus-trust--before--execution-purple.svg)](#blocksifr-agent-trust-infrastructure)
+[![CI / Repository Health](https://github.com/blocksifrdev/ttp-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/blocksifrdev/ttp-protocol/actions/workflows/ci.yml)
+[![TTP / Governed Execution Proof](https://github.com/blocksifrdev/ttp-protocol/actions/workflows/governed_execution.yml/badge.svg)](https://github.com/blocksifrdev/ttp-protocol/actions/workflows/governed_execution.yml)
 
 Trust-before-execution infrastructure for enterprise agent systems.
 
@@ -39,6 +41,7 @@ This repository is positioned as:
 
 ## Repository layout
 
+- `docs/` — user and administrator documentation center.
 - `specs/` — protocol and operational specs for TTP, SCIM-RE, RAP, trust decay, and receipts.
 - `sdk/node` — Node SDK for `/re/authorize` integration.
 - `sdk/python` — Python SDK for `/re/authorize` integration.
@@ -52,11 +55,35 @@ This repository is positioned as:
 3. Wire callers through `POST /re/authorize` using the Node or Python SDK.
 4. Persist and verify each generated `ExecutionReceipt` for auditability.
 
+## Verify everything works
+
+Run the same checks validated in CI:
+
+```bash
+npm test
+python -m py_compile sdk/python/client.py
+```
+
+Optional local smoke test:
+
+```bash
+node reference-implementations/runtime-authority-gate/server.mjs
+```
+
+Then call:
+- `GET /healthz`
+- `POST /re/authorize`
+
+## Documentation by audience
+
+- **User / Integrator documentation:** `docs/user-guide.md`
+- **Administrator / Governance documentation:** `docs/admin-guide.md`
+- **Documentation index:** `docs/README.md`
+
 ## Non-goals
 
 This repository does **not** position:
 
 - TTP as a standalone runtime.
 - TTP as an independent execution authorizer.
 - Blockchain as a required runtime dependency.
-
diff --git a/docs/README.md b/docs/README.md
@@ -9,6 +9,7 @@ This repository is documented for two primary audiences:
 
 - **User documentation:** [`docs/user-guide.md`](./user-guide.md)
 - **Administrator documentation:** [`docs/admin-guide.md`](./admin-guide.md)
+- **Repository completeness assessment:** [`docs/repo-completeness-assessment.md`](./repo-completeness-assessment.md)
 - **Protocol specifications:** [`specs/README.md`](../specs/README.md)
 - **Examples:** [`examples/README.md`](../examples/README.md)
 

diff --git a/docs/admin-guide.md b/docs/admin-guide.md
@@ -1,48 +1,78 @@
 # Administrator Guide (Security, Compliance, Operations)
 
-## Who this is for
+## Audience
+Security architects, platform admins, governance owners, and audit/compliance teams.
 
-This guide is for governance owners responsible for policy, approvals, controls, and audit readiness.
+## Administrative objective
+Operate runtime authorization as a non-bypassable control plane with deterministic approvals, evidentiary receipts, and fail-closed behavior.
 
-## Governance model
+## 1) Control architecture
 
-The runtime authority layer evaluates:
+### Mandatory control points
+- pre-execution authorization (`POST /re/authorize`)
+- decision enforcement at runtime boundaries
+- receipt persistence and integrity validation
 
-- authority grant validity
-- trust posture
-- risk posture
-- cost governance
-- compliance obligations
+### Recommended deployment model
+- FrontDesk deployed per environment (`dev`, `staging`, `prod`)
+- policy set versioning and promotion process
+- centralized receipt retention with immutable storage controls
 
-Default control behavior is fail-closed when evidence is missing or uncertain.
+## 2) Policy governance
 
-## Operational responsibilities
+Define and version:
+- trust thresholds
+- risk thresholds and critical triggers
+- budget and quota policies
+- compliance obligations by classification/jurisdiction
+- approver roles for `STEP_UP` and `ESCALATE`
 
-### 1) Policy ownership
-- Maintain policy set versions and approval requirements.
-- Define trust/risk/cost/compliance thresholds by environment.
+## 3) Grant and identity hygiene
+- enforce short-lived authority grants
+- require explicit scope for secrets and infra mutation
+- disable standing broad production grants
+- use workload identity for service-to-service authorization
 
-### 2) Identity and grant hygiene
-- Rotate and expire authority grants.
-- Disallow standing broad grants in production.
-- Require explicit grants for secrets access and infrastructure mutation.
+## 4) Step-up and escalation operations
 
-### 3) Receipt governance
-- Retain receipts according to control and jurisdiction obligations.
-- Verify receipt integrity fields (`hash`, `chainHash`) in audit workflows.
-- Correlate receipt IDs with execution IDs and change records.
+### STEP_UP runbook
+1. Validate request context and attestation freshness.
+2. Re-run authorization with updated evidence.
+3. Record all evidence links in receipt trails.
 
-### 4) Step-up and escalation controls
-- Ensure `STEP_UP` paths require stronger attestation.
-- Ensure `ESCALATE` paths bind to documented approver roles.
-- Require explicit evidence for any production mutation approvals.
+### ESCALATE runbook
+1. Route to authorized approver role.
+2. Capture decision rationale and approver identity.
+3. Re-authorize with approval context.
 
-## Control mapping readiness
+## 5) Receipt governance and retention
 
-The repository includes framework-aware compliance structures for governance workflows, including support for mapping to NIST, SOC2, PCI_DSS, SOX, FFIEC, CMMC, ISO27001, and EU_AI_ACT contexts.
+### Minimum retained fields
+- `receiptId`
+- `execution.executionId`
+- `decision.outcome`, `decision.mode`
+- `integrity.hash`, `integrity.chainHash`
+- `compliance.retentionClass`
 
-## Recommended operating checks
+### Retention recommendation
+- `STANDARD`: 12 months minimum
+- `REGULATED` / `FINANCIAL_RECORD` / `PAYMENT_RECORD`: follow legal & framework-specific controls
 
-- Run CI health checks (`.github/workflows/ci.yml`).
-- Run governed-execution checks (`.github/workflows/governed_execution.yml`).
-- Periodically validate that constrained permits are not treated as full permits in downstream execution surfaces.
+## 6) Compliance mapping readiness
+
+Use structured mappings for NIST, FFIEC, SOX, PCI_DSS, CMMC, SOC2, ISO27001, EU_AI_ACT. Mark uncertain applicability as conditional and track residual gaps explicitly.
+
+## 7) Operational KPIs
+Track:
+- authorization latency (p50/p95)
+- decision distribution (`PERMIT`, `STEP_UP`, `ESCALATE`, `DENY`)
+- constrained-permit rate
+- escalation turnaround time
+- receipt integrity verification success rate
+
+## 8) Administration checklist
+- [ ] Fail-closed behavior verified in each environment.
+- [ ] Approval paths tested quarterly.
+- [ ] Receipt retention and integrity verification scheduled.
+- [ ] Policy versions and exceptions reviewed monthly.
+- [ ] High-risk production mutation paths require human approval.
diff --git a/docs/repo-completeness-assessment.md b/docs/repo-completeness-assessment.md
@@ -0,0 +1,26 @@
+# Repository Completeness Assessment
+
+## Scope assessed
+- Core protocol specs
+- API contract completeness
+- SDK usability
+- Reference implementation behavior
+- User/Admin documentation
+- CI and governance workflows
+
+## Current status (as of 2026-04-25)
+
+| Area | Status | Notes |
+|---|---|---|
+| Runtime authority decision model | Complete baseline | 4 outcomes + mode semantics implemented. |
+| Receipt model | Complete baseline | Structured receipt sections + integrity hash/chain. |
+| API contract | Improved | Added status codes, required fields, response structure, caller rules. |
+| User guide | Improved | Includes quickstart, enforcement matrix, checklist, troubleshooting. |
+| Admin guide | Improved | Includes governance model, runbooks, retention, KPIs. |
+| CI health checks | Complete baseline | Tests + smoke checks in `.github/workflows/ci.yml`. |
+
+## Remaining production hardening recommendations
+1. Add OpenAPI/JSON Schema artifacts for `POST /re/authorize` and receipt schema.
+2. Add signed-receipt verification utility and key-rotation documentation.
+3. Add persistence backend abstraction for receipts (currently in-memory in reference gate).
+4. Add formal SLO targets and synthetic health checks for production FrontDesk deployments.
diff --git a/docs/user-guide.md b/docs/user-guide.md
@@ -1,46 +1,73 @@
 # User Guide (Integrators)
 
-## Who this is for
+## Audience
+Application teams, CI/CD owners, platform engineering, and agent-runtime integrators.
 
-This guide is for teams integrating governed execution into CI/CD, APIs, and agent runtimes.
+## Outcome
+By the end of this guide, you should be able to:
+1. call `POST /re/authorize` before protected execution,
+2. enforce decision + mode correctly,
+3. persist `ExecutionReceipt` evidence for audit.
 
-## What you get
+## Quick start (15 minutes)
 
-- Runtime authorization via `POST /re/authorize`
-- Deterministic decision outcomes (`PERMIT`, `STEP_UP`, `ESCALATE`, `DENY`)
-- Decision modes (`FULL`, `CONSTRAINED`, etc.)
-- Portable `ExecutionReceipt` evidence
+### Step 1: Run FrontDesk locally
+```bash
+node reference-implementations/runtime-authority-gate/server.mjs
+```
 
-## Integration path
+### Step 2: Health check
+```bash
+curl -sS http://127.0.0.1:8080/healthz | jq .
+```
 
-1. **Read protocol contracts**
-   - `specs/scim-re.md`
-   - `specs/scim-re-authorize-api.md`
-   - `specs/execution-receipt.md`
+### Step 3: Authorize a governed action
+```bash
+curl -sS -X POST http://127.0.0.1:8080/re/authorize \
+  -H 'content-type: application/json' \
+  -d '{
+    "requestId":"demo-1",
+    "subject":"agent-42",
+    "action":"pipeline.deploy",
+    "resource":{"type":"environment","id":"prod"},
+    "context":{"environment":"prod","agentType":"advanced","trustScore":0.82,"costCenter":"platform"},
+    "authorityGrant":{"grantId":"grant-local-001","expiresAt":"2030-01-01T00:00:00Z","scope":["pipeline.deploy:prod"]}
+  }' | jq .
+```
 
-2. **Stand up FrontDesk locally**
-   - `reference-implementations/runtime-authority-gate/`
-   - Run `node server.mjs`
+## Decision enforcement matrix
 
-3. **Integrate clients**
-   - Node SDK: `sdk/node`
-   - Python SDK: `sdk/python`
+| Decision | Mode | Caller action |
+|---|---|---|
+| PERMIT | FULL | Execute as requested. |
+| PERMIT | CONSTRAINED | Execute with constraints (reduced scope/capability). |
+| STEP_UP | REQUIRES_REATTESTATION | Pause and require fresh attestation/stronger proof. |
+| ESCALATE | REQUIRES_HUMAN_APPROVAL | Route to privileged human approval workflow. |
+| DENY | FAILED_CLOSED (or other) | Block execution; record receipt. |
 
-4. **Apply enforcement patterns**
-   - CI/CD examples: `examples/governed-ci/`
-   - API example: `examples/api-gateway/`
-   - Agent/tool example: `examples/copilot-tool-gate/`
+## SDK usage
+- Node SDK: `sdk/node`
+- Python SDK: `sdk/python`
 
-## Decision handling contract
+Both SDKs return decision and mode. Integrations MUST evaluate both values.
 
-- `PERMIT` + `FULL`: allow intended execution.
-- `PERMIT` + `CONSTRAINED`: allow with narrowed capability.
-- `STEP_UP`: pause execution and request stronger proof/fresher attestation.
-- `ESCALATE`: route to human/privileged approval path.
-- `DENY`: block execution.
+## Required logging and audit fields
+At minimum, store:
+- `requestId`
+- `decision`
+- `mode`
+- `receiptId`
+- `receipt.integrity.hash`
+- `receipt.integrity.chainHash`
 
-## Non-negotiable integration rules
+## Integration checklist
+- [ ] Every protected action calls `POST /re/authorize`.
+- [ ] Caller blocks on missing response/receipt.
+- [ ] `PERMIT+CONSTRAINED` is handled as constrained, not full permit.
+- [ ] `STEP_UP` and `ESCALATE` route to explicit control paths.
+- [ ] Receipt IDs are linked to runtime execution logs.
 
-- No execution without authorization response.
-- No authorization response without receipt.
-- Persist receipt IDs with execution logs for audit traceability.
+## Troubleshooting
+- **400 invalid_request**: verify required fields (`requestId`, `action`, `resource.id`).
+- **Unexpected DENY**: validate grant scope/expiry and trust inputs.
+- **Frequent ESCALATE in prod**: review risk triggers and mythos/advanced-agent policies.
diff --git a/examples/README.md b/examples/README.md
@@ -1,6 +1,15 @@
 # Examples
 
+This section contains practical integration patterns for governed execution.
+
+## CI/CD
 - `governed-ci/github-actions-governed-step.md`
 - `governed-ci/azure-devops-governed-pipeline.md`
+
+## Runtime/API enforcement
 - `api-gateway/api-gateway-enforcement.md`
 - `copilot-tool-gate/copilot-tool-call-gate.md`
+- `github-app-self-governance.md`
+
+## Usage note
+Treat examples as reference patterns. Production deployments should adapt policies, approval paths, and receipt retention to organizational controls.
diff --git a/examples/api-gateway/api-gateway-enforcement.md b/examples/api-gateway/api-gateway-enforcement.md
@@ -6,7 +6,7 @@ Pseudo-flow for gateway middleware:
 2. Gateway builds TTP context and calls `POST /re/authorize`.
 3. Decision drives enforcement:
    - `PERMIT`: forward request.
-   - `CONSTRAIN`: strip privileged operation headers.
+   - `PERMIT` + `mode=CONSTRAINED`: strip privileged operation headers.
    - `STEP_UP` / `ESCALATE`: require stronger auth or manual review.
    - `DENY`: return 403.
 4. Persist returned `ExecutionReceipt` with request logs.
@@ -16,6 +16,6 @@ Node middleware skeleton:
 ```js
 const auth = await fetch('http://localhost:8080/re/authorize', { method: 'POST', body: JSON.stringify(payload) }).then(r => r.json());
 if (auth.decision === 'DENY') return res.status(403).json(auth.receipt);
-if (auth.decision === 'CONSTRAIN') req.headers['x-scope-mode'] = 'constrained';
+if (auth.decision === 'PERMIT' && auth.mode === 'CONSTRAINED') req.headers['x-scope-mode'] = 'constrained';
 next();
 ```
diff --git a/reference-implementations/runtime-authority-gate/README.md b/reference-implementations/runtime-authority-gate/README.md
@@ -7,14 +7,31 @@ Minimal local service implementing runtime authority for governed actions.
 - `POST /re/authorize`
 
 ## Features
-- Local trust evaluation (`trustScore` thresholding).
+- Local trust/risk/cost/compliance evaluation.
+- Runtime decision outcomes: `PERMIT|STEP_UP|ESCALATE|DENY`.
+- Decision modes: `FULL|CONSTRAINED|REQUIRES_REATTESTATION|REQUIRES_HUMAN_APPROVAL|FAILED_CLOSED`.
 - In-memory `AuthorityGrant` validation.
-- `ExecutionReceipt` generation for every decision.
-- `chainHash` linking for tamper-evident local audit chain.
+- Structured `ExecutionReceipt` generation for every decision (`execution`, `decision`, `trust`, `risk`, `cost`, `compliance`, `evidence`, `integrity`).
+- `chainHash` linking for tamper-evident local audit chains.
 
 ## Run
 ```bash
 node server.mjs
 ```
 
 Default URL: `http://localhost:8080`
+
+## API usage
+See canonical contract: `specs/scim-re-authorize-api.md`.
+
+Quick request:
+```bash
+curl -sS -X POST http://127.0.0.1:8080/re/authorize \
+  -H 'content-type: application/json' \
+  -d '{"requestId":"demo-1","action":"pipeline.deploy","resource":{"type":"environment","id":"prod"},"context":{"environment":"prod","trustScore":0.9},"authorityGrant":{"grantId":"grant-local-001"}}' | jq .
+```
+
+## Test
+```bash
+npm run test:runtime-authority-gate
+```