From 5ef6633babd68258883b956124e5fc53b29883f7 Mon Sep 17 00:00:00 2001
From: Imran Siddique <imran.siddique@opaque.co>
Date: Sun, 21 Jun 2026 13:54:41 -0700
Subject: [PATCH] docs: fix package name, enforcement mode values, add pos/neg
 test columns
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- quickstart.md: fix pip install agentrust-trace-tests → trace-tests
  (matches README); add Next steps table
- tr-pol.md: fix enforcement_mode valid values — enforce/advisory/silent
  not enforce/monitor (confirmed against tutorial test at line 142)
- error-codes.md: same TR-POL-002 fix; add missing TR-RTE-003
- tr-sig.md, tr-rte.md, tr-pol.md, tr-txn.md, tr-anc.md, tr-sca.md:
  add Positive Case / Negative Case columns to match tr-env.md format

Signed-off-by: Imran Siddique <imran.siddique@opaque.co>
---
 docs/error-codes.md    |  3 ++-
 docs/modules/tr-anc.md |  8 ++++----
 docs/modules/tr-pol.md |  8 ++++----
 docs/modules/tr-rte.md | 10 +++++-----
 docs/modules/tr-sca.md |  8 ++++----
 docs/modules/tr-sig.md | 12 ++++++------
 docs/modules/tr-txn.md |  8 ++++----
 docs/quickstart.md     | 11 ++++++++++-
 8 files changed, 39 insertions(+), 29 deletions(-)

diff --git a/docs/error-codes.md b/docs/error-codes.md
index 9376f01..df96587 100644
--- a/docs/error-codes.md
+++ b/docs/error-codes.md
@@ -26,13 +26,14 @@ All TRACE test failures emit a structured error code of the form `TR-<MODULE>-<N
 |------|-------------|
 | TR-RTE-001 | `runtime.platform` is not a recognised TEE enum value |
 | TR-RTE-002 | `runtime.measurement` is not a valid `sha256:` digest |
+| TR-RTE-003 | RIM URI present but does not resolve to a valid reference image |
 
 ## TR-POL — Policy
 
 | Code | Description |
 |------|-------------|
 | TR-POL-001 | `policy.bundle_hash` is not a valid `sha256:` digest |
-| TR-POL-002 | `policy.enforcement_mode` is not `enforce` or `monitor` |
+| TR-POL-002 | `policy.enforcement_mode` is not `enforce`, `advisory`, or `silent` |
 
 ## TR-TXN — Transcript
 
diff --git a/docs/modules/tr-anc.md b/docs/modules/tr-anc.md
index 7695ef8..ac9782e 100644
--- a/docs/modules/tr-anc.md
+++ b/docs/modules/tr-anc.md
@@ -4,7 +4,7 @@ Tests transparency anchoring via SCITT.
 
 ## Required at Level 2+
 
-| Test ID | Description |
-|---------|-------------|
-| TR-ANC-001 | `transparency` is a non-empty URI |
-| TR-ANC-002 | URI scheme is `https://` |
+| Test ID | Description | Positive Case | Negative Case |
+|---------|-------------|---------------|---------------|
+| TR-ANC-001 | `transparency` is a non-empty URI | `https://transparency.example/entries/abc123` | missing field, empty string |
+| TR-ANC-002 | URI scheme is `https://` | `https://` prefix | `http://`, bare path, `ipfs://` |
diff --git a/docs/modules/tr-pol.md b/docs/modules/tr-pol.md
index 60559eb..a321402 100644
--- a/docs/modules/tr-pol.md
+++ b/docs/modules/tr-pol.md
@@ -4,7 +4,7 @@ Tests Cedar policy bundle binding.
 
 ## Required at Level 0+
 
-| Test ID | Description |
-|---------|-------------|
-| TR-POL-001 | `policy.bundle_hash` is a valid `sha256:` digest |
-| TR-POL-002 | `policy.enforcement_mode` is `enforce` or `monitor` |
+| Test ID | Description | Positive Case | Negative Case |
+|---------|-------------|---------------|---------------|
+| TR-POL-001 | `policy.bundle_hash` is a valid `sha256:` digest | `sha256:` followed by 64 hex chars | missing, wrong prefix, wrong length |
+| TR-POL-002 | `policy.enforcement_mode` is `enforce`, `advisory`, or `silent` | `enforce` | `strict`, `monitor`, absent |
diff --git a/docs/modules/tr-rte.md b/docs/modules/tr-rte.md
index 8475bd1..de398c8 100644
--- a/docs/modules/tr-rte.md
+++ b/docs/modules/tr-rte.md
@@ -4,8 +4,8 @@ Tests TEE platform attestation in the `runtime` field.
 
 ## Required at Level 1+
 
-| Test ID | Description |
-|---------|-------------|
-| TR-RTE-001 | `runtime.platform` is a known TEE enum value |
-| TR-RTE-002 | `runtime.measurement` is a valid `sha256:` digest |
-| TR-RTE-003 | RIM URI (if present) resolves to a valid reference image |
+| Test ID | Description | Positive Case | Negative Case |
+|---------|-------------|---------------|---------------|
+| TR-RTE-001 | `runtime.platform` is a known TEE enum value | `tpm2`, `sev-snp`, `tdx`, `opaque` | `"software"`, `"cloud"`, absent |
+| TR-RTE-002 | `runtime.measurement` is a valid `sha256:` digest | `sha256:` followed by 64 hex chars | missing, wrong prefix, all zeros |
+| TR-RTE-003 | RIM URI (if present) resolves to a valid reference image | valid `https://` URI returning a reference manifest | non-HTTPS URI, 404 response |
diff --git a/docs/modules/tr-sca.md b/docs/modules/tr-sca.md
index 437b48d..52a7aeb 100644
--- a/docs/modules/tr-sca.md
+++ b/docs/modules/tr-sca.md
@@ -4,7 +4,7 @@ Tests SLSA build provenance.
 
 ## Required at Level 1+
 
-| Test ID | Description |
-|---------|-------------|
-| TR-SCA-001 | `build_provenance.slsa_level` is 0–4 |
-| TR-SCA-002 | `build_provenance.digest` is a valid `sha256:` digest |
+| Test ID | Description | Positive Case | Negative Case |
+|---------|-------------|---------------|---------------|
+| TR-SCA-001 | `build_provenance.slsa_level` is 0–4 | `0`, `1`, `2`, `3`, `4` | `5`, `-1`, `"high"`, absent |
+| TR-SCA-002 | `build_provenance.digest` is a valid `sha256:` digest | `sha256:` followed by 64 hex chars | missing, wrong prefix, wrong length |
diff --git a/docs/modules/tr-sig.md b/docs/modules/tr-sig.md
index 890b004..0523f1f 100644
--- a/docs/modules/tr-sig.md
+++ b/docs/modules/tr-sig.md
@@ -4,9 +4,9 @@ Tests Ed25519 signature binding on the TRACE Trust Record.
 
 ## Required at Level 0+
 
-| Test ID | Description |
-|---------|-------------|
-| TR-SIG-001 | Signature algorithm is Ed25519 (OKP crv=Ed25519) |
-| TR-SIG-002 | `cnf.jwk` present and carries the public key |
-| TR-SIG-003 | Signature verifies over the canonical record bytes (RFC 8785 JCS) |
-| TR-SIG-004 | `cnf.jwk` does not contain private key material (`d` member absent) |
+| Test ID | Description | Positive Case | Negative Case |
+|---------|-------------|---------------|---------------|
+| TR-SIG-001 | Signature algorithm is Ed25519 (OKP crv=Ed25519) | `{"kty":"OKP","crv":"Ed25519"}` | ES256, RS256, missing `alg` |
+| TR-SIG-002 | `cnf.jwk` present and carries the public key | JWK with `x` member set | missing `cnf`, missing `jwk`, missing `x` |
+| TR-SIG-003 | Signature verifies over the canonical record bytes (RFC 8785 JCS) | valid Ed25519 signature | bit-flipped signature, wrong key |
+| TR-SIG-004 | `cnf.jwk` does not contain private key material (`d` member absent) | JWK with only `x` | JWK with `d` present |
diff --git a/docs/modules/tr-txn.md b/docs/modules/tr-txn.md
index 4c658a4..d39e7b0 100644
--- a/docs/modules/tr-txn.md
+++ b/docs/modules/tr-txn.md
@@ -4,7 +4,7 @@ Tests tool-call transcript binding.
 
 ## Required at Level 2+
 
-| Test ID | Description |
-|---------|-------------|
-| TR-TXN-001 | `tool_transcript.hash` is a valid `sha256:` digest |
-| TR-TXN-002 | `tool_transcript.call_count` is a non-negative integer |
+| Test ID | Description | Positive Case | Negative Case |
+|---------|-------------|---------------|---------------|
+| TR-TXN-001 | `tool_transcript.hash` is a valid `sha256:` digest | `sha256:` followed by 64 hex chars | missing, wrong prefix, wrong length |
+| TR-TXN-002 | `tool_transcript.call_count` is a non-negative integer | `0`, `1`, `42` | `-1`, `"three"`, absent |
diff --git a/docs/quickstart.md b/docs/quickstart.md
index 686328b..9e2b071 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -3,7 +3,7 @@
 ## Install
 
 ```bash
-pip install agentrust-trace-tests
+pip install trace-tests
 ```
 
 ## Run against a Trust Record
@@ -41,3 +41,12 @@ TR-RTE-001  FAIL  Runtime: TEE measurement missing (required at level 1)
 ```
 
 Error codes follow the form `TR-<MODULE>-<NNN>`.
+
+## Next steps
+
+| What | Where |
+|------|-------|
+| Understand what each test checks | [Test Modules](../modules.md) |
+| Look up a specific error code | [Error Codes](../error-codes.md) |
+| Write your own conformance tests | [Tutorial: Writing conformance tests](tutorials/writing-conformance-tests.md) |
+| Set up CI | [Tutorial: CI integration](tutorials/ci-integration.md) |