Milestone 8: documentation reconciliation and clean-user testing

.github/workflows/f7las-ci.yml

@@ -35,6 +35,9 @@ jobs:
       - name: Validate supply-chain invariants
         run: python scripts/validate-supply-chain.py
 
+      - name: Validate documentation
+        run: python scripts/validate-documentation.py
+
       - name: Audit dependencies and generate CycloneDX SBOM
         run: |
           mkdir -p "$RUNNER_TEMP/f7las-sbom"
@@ -88,6 +91,12 @@ jobs:
           echo "OPA_BIN=$RUNNER_TEMP/f7las-bin/opa" >> "$GITHUB_ENV"
           "$RUNNER_TEMP/f7las-bin/opa" version
 
+      - name: Run clean-user acceptance
+        env:
+          OPA_BIN: ${{ runner.temp }}/f7las-bin/opa
+          PYTHON_BIN: python
+        run: scripts/run-clean-user-acceptance.sh
+
       - name: Verify src.policy package imports
         run: python -c "import src.policy"
 
@@ -110,7 +119,7 @@ jobs:
         run: opa check --strict config/policies/canonical-workflow.rego
 
       - name: Run behavioral scenarios
-        run: pytest -q tests/test_behavioral_scenarios.py
+        run: python -m pytest -q tests/test_behavioral_scenarios.py
 
       - name: Generate canonical evidence
         run: |
@@ -133,7 +142,7 @@ jobs:
             --opa-binary "$OPA_BIN"
 
       - name: Run unit tests
-        run: pytest -q --ignore=tests/test_behavioral_scenarios.py
+        run: python -m pytest -q --ignore=tests/test_behavioral_scenarios.py
 
       - name: Run golden dataset evaluation
         run: |

README.md

@@ -32,9 +32,10 @@ Software supply-chain security is a cross-cutting supplemental domain, **Layer S
 - Architecture diagrams and engineering review material
 - Canonical v1.0.0 data contracts and one synthetic, offline Python + OPA workflow
 - Illustrative prompts, additional policies, validators, and runtime stubs
-- Structural CI checks and prototype tests
+- Supply-chain CI, behavioral tests, evidence verification, deterministic replay,
+  and a clean-user acceptance gate for the canonical path
 
-The canonical workflow provides one deliberately constrained executable Layers 1–7 path. It does not make the other examples executable or production-ready. The existing golden-dataset runner validates scenario structure; it does not prove the described allow/deny behavior. Placeholder tests and incomplete examples are being replaced as part of the [overhaul roadmap](ROADMAP.md).
+The canonical workflow provides one deliberately constrained executable Layers 1–7 path. It does not make the other examples executable or production-ready. The behavioral scenario matrix exercises the canonical enforcement path; the separate golden-dataset runner validates scenario structure and does not prove the described allow/deny behavior. Non-canonical examples remain illustrative unless they are explicitly reclassified and tested.
 
 ## Executable versus illustrative
 
@@ -45,7 +46,7 @@ The canonical workflow provides one deliberately constrained executable Layers 1
 | Other OPA/PDP/PEP code | Partial prototype |
 | Planner, tools, sandbox, telemetry | Illustrative prototypes |
 | Other policy-engine examples | Illustrative, non-canonical patterns |
-| Other end-to-end workflows | Planned; not yet implemented |
+| Other end-to-end workflows | Not provided |
 | Production integrations or actions | Not provided |
 
 Nothing in this repository should be connected to production data, identities, cloud resources, security platforms, or remediation systems without independent engineering and security review.
@@ -61,12 +62,14 @@ python -m venv .venv
 source .venv/bin/activate
 python -m pip install --require-hashes -r requirements-ci.lock
 python scripts/validate-supply-chain.py
+python scripts/validate-documentation.py
 python scripts/validate-prompts.py
 python scripts/validate-policies.py
+python scripts/allowlist-validator.py
 python scripts/validate-settings.py config/settings.yaml
 python scripts/validate-contracts.py
 opa check --strict config/policies/canonical-workflow.rego
-pytest -q
+python -m pytest -q
 ```
 
 These commands validate the **current prototype and repository structure**. They are not evidence of production readiness or full behavioral enforcement.
@@ -82,6 +85,7 @@ These commands validate the **current prototype and repository structure**. They
 - [Canonical data contracts v1.0.0](schemas/contracts/README.md)
 - [Canonical offline workflow](examples/canonical-workflow/README.md)
 - [Supply-chain and CI controls](docs/supply-chain-and-ci.md)
+- [Clean-user acceptance](docs/clean-user-acceptance.md)
 - [Roadmap](ROADMAP.md)
 - [Security policy](SECURITY.md)
 

ROADMAP.md

@@ -17,7 +17,7 @@ The target is an **Executable Reference Implementation**: one offline, determini
 5. **Behavioral scenarios** — an executable canonical matrix tests permitted, denied, malformed, unauthorized, unavailable, timed-out, tampered, expired, obligation, and recovery paths.
 6. **Evidence and replay** — canonical evidence can be independently verified for complete correlation and tampering, then replayed from the admitted input to reproduce the exact canonical outcome.
 7. **Supply chain and CI** — implement pinned and hashed dependencies, immutable action references, verified tool downloads, known-vulnerability and Git-history secret gates, and a retained CI SBOM.
-8. **Documentation reconciliation** — execute every documented command in a clean environment.
+8. **Documentation reconciliation** — execute every supported user command in a clean environment; classify maintainer-only and illustrative material explicitly.
 9. **F7-LAS-specific diagrams** — replace diagrams only after execution semantics are frozen.
 10. **Independent review** — review the complete branch diff and CI evidence before any merge, release, or Zenodo update.
 

docs/F7-LAS-QA.md

@@ -17,7 +17,8 @@ executable or production-ready. The existing golden-dataset evaluator validates
 scenario and rubric structure; it does not execute or prove the stated security
 behavior.
 
-The canonical path has automated behavioral checks, but repository-wide control
+The canonical path has automated behavioral checks, evidence verification,
+deterministic replay, and a clean-user acceptance gate. Repository-wide control
 status is not yet machine-readable or evidence-linked.
 
 ## Is the code production-ready?
@@ -86,6 +87,16 @@ prove that dependencies are non-malicious, guarantee that no secret exists, or
 create a signed release SBOM or provenance attestation. See
 [Supply-chain and CI controls](supply-chain-and-ci.md) for the exact boundary.
 
+## Has the documented canonical path been tested as a clean user?
+
+Yes, within a deliberately narrow boundary. The
+[clean-user acceptance gate](clean-user-acceptance.md) copies the repository
+without Git metadata, removes inherited Python import settings, creates a new
+Python 3.12.14 virtual environment, performs a hash-locked installation, and
+runs the supported validation and canonical walkthrough commands with the
+checksum-verified OPA 1.20.2 binary. It does not test the illustrative layer
+examples or establish production readiness.
+
 ## How should practitioners use the repository today?
 
 Use it as a design-review lens, threat-modeling aid, draft control catalog, and source of clearly labeled examples. Verify each claimed outcome independently before adapting any pattern.

docs/README.md

@@ -14,13 +14,14 @@ This directory contains the governed documentation for the F7-LAS seven-layer re
 - [Canonical data contracts v1.0.0](../schemas/contracts/README.md) — machine-validated request-through-audit definitions used by the canonical executable path.
 - [Canonical offline workflow](../examples/canonical-workflow/README.md) — the bounded synthetic Python + OPA Layers 1–7 demonstration.
 - [Supply-chain and CI controls](supply-chain-and-ci.md) — implemented dependency, action, download, vulnerability, secret, and SBOM checks and their limits.
+- [Clean-user acceptance](clean-user-acceptance.md) — the exact supported environment, complete walkthrough, command inventory, and assurance boundary.
 
 ## Architecture graphics
 
 Existing diagrams remain under `docs/` and `docs/images/` while their references and semantics are inventoried. They are historical/current draft visuals, not evidence of implemented behavior. Purpose-built replacement diagrams will be created only after the canonical execution semantics are approved.
 
 ## Status and use
 
-The model is established; the repository implementation is a prototype. Documentation may specify desired controls that are not yet implemented. Consult the control catalog status and future traceability matrix before treating a control as verified.
+The model is established; the repository implementation is a prototype. Documentation may specify desired controls that are not implemented. Treat only the canonical behavior covered by tests and correlated evidence as verified; control-to-evidence traceability remains a separate release gate.
 
 See the root [license map](../LICENSE.md) and [security policy](../SECURITY.md).

docs/clean-user-acceptance.md

@@ -0,0 +1,54 @@
+# Clean-user acceptance
+
+Milestone 8 defines one supported clean-user path for the bounded F7-LAS
+reference implementation. It starts from repository files without Git metadata,
+creates a new virtual environment, installs only the reviewed hash-locked graph,
+and runs the documented validators, tests, canonical walkthrough, evidence
+verification, deterministic replay, golden structural evaluation, vulnerability
+audit, and SBOM generation.
+
+## Exact prerequisites
+
+- A clean checkout of this repository on Linux x86_64.
+- Python **3.12.14**.
+- The OPA **1.20.2** Linux x86_64 static binary with SHA-256
+  `69da5179ee403d10fa11bab6cfb4ffb0d23dba5f9b682fa977db772a1da5670f`.
+- Network access to the configured Python package index and vulnerability
+  service during dependency installation and `pip-audit`.
+
+The repository's canonical code supports Python 3.10 or later, but the
+acceptance environment is intentionally narrower and matches CI exactly.
+
+## Run the complete gate
+
+From the repository root, point `OPA_BIN` at the checksum-verified binary:
+
+```bash
+OPA_BIN=/absolute/path/to/opa scripts/run-clean-user-acceptance.sh
+```
+
+The script rejects a different Python patch release, OPA version, or OPA binary
+digest. It removes inherited `PYTHONPATH`, copies the working tree without Git
+metadata or local environments, and performs the acceptance run in a temporary
+directory. Set `KEEP_CLEAN_USER_WORKDIR=1` only when the temporary evidence and
+SBOM are needed for diagnosis.
+
+Success ends with `Clean-user acceptance PASSED`. A nonzero status means the
+repository has not passed this gate.
+
+## Command inventory
+
+| Documentation | Classification | Clean-user evidence |
+|---|---|---|
+| Root validation commands | Supported | Validators and complete tests run in the isolated environment |
+| Canonical workflow commands | Supported | Execution, evidence verification, and replay all run |
+| Contract validation commands | Supported | Contract validator and complete tests run |
+| Supply-chain reproduction commands | Supported | Locked installation, invariant validation, audit, SBOM, and supply-chain tests run |
+| Non-canonical layer examples | Illustrative only | No runnable walkthrough is claimed or accepted |
+| Dependency-lock regeneration | Maintainer operation | Not represented as a clean-user command; any update requires separate dependency-diff review |
+| Full-history Gitleaks scan | CI-only | Requires Git history and remains enforced by the normal GitHub Actions job |
+
+This gate proves reproducibility for one synthetic, offline workflow on the
+specified platform. It does not prove production readiness, external-system
+behavior, OS/container isolation, artifact provenance, or trustworthiness of
+the audited dependencies.

docs/supply-chain-and-ci.md

@@ -28,12 +28,13 @@ python -m venv .venv
 source .venv/bin/activate
 python -m pip install --require-hashes -r requirements-ci.lock
 python scripts/validate-supply-chain.py
+python scripts/validate-documentation.py
 pip-audit --require-hashes --disable-pip --strict \
   --progress-spinner off \
   --requirement requirements-ci.lock \
   --format cyclonedx-json \
   --output f7las-python.cdx.json
-pytest -q tests/test_supply_chain.py
+python -m pytest -q tests/test_supply_chain.py
 ```
 
 Gitleaks and OPA are installed in CI from the exact versioned URLs and digests
@@ -42,19 +43,12 @@ running the corresponding workflow commands on Linux x64.
 
 ## Updating the Python lock
 
-Change exact top-level pins deliberately, then regenerate the lock with the
-same resolver command and review all transitive changes:
-
-```bash
-python -m pip install pip-tools==7.6.1
-pip-compile --allow-unsafe --generate-hashes --resolver=backtracking \
-  --strip-extras --output-file requirements-ci.lock requirements-ci.in
-python scripts/validate-supply-chain.py
-```
-
-An update is incomplete until the known-vulnerability audit, full tests, and
-the complete dependency diff have been reviewed. Dependabot proposals are not
-auto-merged.
+Dependency-lock regeneration is a maintainer operation, not a supported
+clean-user command. Change exact top-level pins deliberately, regenerate the
+lock in a separately reviewed maintenance environment, and review every
+transitive version and hash change. An update is incomplete until the
+known-vulnerability audit, full tests, and complete dependency diff have been
+reviewed. Dependabot proposals are not auto-merged.
 
 ## Assurance boundary
 

examples/README.md

@@ -34,4 +34,6 @@ A minimal simulated execution wrapper and container example. Containment is not
 ### Layer 7 — Monitoring & Telemetry  
 A simple event schema + Python logger for auditability.
 
-Each layer folder contains its own README with instructions.
+Each layer folder contains its own README with its classification and
+limitations. Only [`canonical-workflow/`](canonical-workflow/README.md) provides
+a supported runnable walkthrough.

examples/canonical-workflow/README.md

@@ -57,7 +57,7 @@ effects. Admission refusals must emit no workflow records.
 Run the matrix with the pinned OPA CLI available:
 
 ```bash
-OPA_BIN=opa pytest -q tests/test_behavioral_scenarios.py
+OPA_BIN=opa python -m pytest -q tests/test_behavioral_scenarios.py
 ```
 
 These are deterministic reference-workflow scenarios, not claims of production

examples/layer5-policy-engines/opa-rego/README.md

@@ -1,124 +1,21 @@
-# OPA Rego PDP Demo (Layer 5)
+# Illustrative OPA/Rego Pattern (Layer 5)
 
-This folder provides a runnable demonstration of the **F7-LAS Layer 5 Policy Decision Point (PDP)** using **Open Policy Agent (OPA)** and the Rego policy located at:
+This directory is **illustrative, non-canonical, and unsupported as a runnable walkthrough**.
+It preserves an early HTTP-based PDP/PEP pattern for design comparison only.
 
-```
-config/policies/l5/opa/agent_security_enforcement.rego
-```
+The local files are not a coherent supported deployment:
 
-The demo shows how the PDP evaluates agent actions such as:
+- `policy.rego` uses an older Rego style and is not the policy executed by the
+  canonical workflow.
+- `pep_opa.py` targets a service hostname and package path that require external
+  orchestration and configuration.
+- `docker-compose.yml` is retained as historical prototype material; it uses a
+  mutable image reference and does not mount the policy from this directory.
 
-- `terminate_instance`
-- `describe_instance`
-- `list_instances`
+Do not infer execution, security, or compatibility from these files and do not
+connect them to production tools or data. The only supported OPA execution path
+is the checksum-verified CLI workflow documented in the
+[canonical workflow](../../canonical-workflow/README.md). Its executable policy
+is [`config/policies/canonical-workflow.rego`](../../../config/policies/canonical-workflow.rego).
 
-…and how the **PEP (Policy Enforcement Point)** queries the PDP before tools are executed.
-
----
-
-## Run the OPA PDP Locally
-
-From the **repo root**, start the OPA container using:
-
-```bash
-docker compose -f examples/layer5-policy-engines/opa-rego/docker-compose.yml up
-```
-
-This will:
-
-- Start OPA on `http://localhost:8181`
-- Load the Layer-5 Rego policy automatically
-- Watch policy files for changes
-
----
-
-## Test the Policy Manually
-
-### 1. Check the `allow` rule
-
-```bash
-curl -s -X POST   http://localhost:8181/v1/data/f7las/l5/enforcement/allow   -H 'Content-Type: application/json'   -d '{
-        "input": {
-          "action": "terminate_instance",
-          "environment": "production",
-          "current_time_ok_for_change": false
-        }
-      }'
-```
-
-**Expected Output:**
-
-```json
-{"result": false}
-```
-
----
-
-### 2. Retrieve the denial reason
-
-```bash
-curl -s -X POST   http://localhost:8181/v1/data/f7las/l5/enforcement/deny_message   -H 'Content-Type: application/json'   -d '{
-        "input": {
-          "action": "terminate_instance",
-          "environment": "production",
-          "current_time_ok_for_change": false
-        }
-      }'
-```
-
-**Example Output:**
-
-```json
-{"result": "Agent action denied by L5 Policy: Production modification outside of approved maintenance window or environment."}
-```
-
----
-
-## Using the PDP from the Python PEP
-
-If you are using the OPA-backed PEP module located at:
-
-```
-src/policy/pep_opa.py
-```
-
-Example wiring:
-
-```python
-from src.policy.pep_opa import OPAPEP
-
-pep = OPAPEP()
-
-tool_call = {
-    "tool_name": "aws_ec2_client",
-    "action": "terminate_instance",
-    "arguments": {"instance_id": "i-prod-1234"},
-}
-
-context = {
-    "agent_id": "OpsAgent-v1",
-    "target_environment": "production",
-    "initiating_user_role": "devops_engineer",
-}
-
-decision = pep.authorize(tool_call, context)
-
-if decision.is_allowed:
-    print("L5: ALLOW → call tool")
-else:
-    print(f"L5: DENY → {decision.reason}")
-```
-
----
-
-## Notes
-
-This is a **Stage‑1 demo PDP**, not a production deployment.
-
-Future stages will add:
-
-- Input validation  
-- Authenticated PDP queries  
-- Layer‑7 telemetry integration  
-- Structured logs for every authorization request  
-- Secure bundle mounting  
+This example may be removed or rebuilt in a later, separately reviewed change.