examples(cognitive-attestation-governed): address automated review feedback

Incorporates the actionable items from the code-reviewer and
security-scanner bot reviews on this PR. Six fixes:

1. Add 'timestamp' field to the envelope and bind it into the canonical
   form. Replay defence: a reused envelope still carries its original
   timestamp, which a verifier can reject against a freshness policy.
2. Clarify tamper-detection output wording — 'PASS (tampering detected,
   envelope rejected)' and 'FAIL (tampering not detected, envelope
   accepted)'. No ambiguity about which outcome is desirable.
3. Expand the policy-evaluator docstring to state unambiguously that it
   is a minimal placeholder, not a substitute for the AGT policy engine.
4. Add a prominent note above the minimal JCS implementation flagging
   that it is NOT a full RFC 8785 implementation and pointing at
   spec-conformant libraries (jcs on PyPI, the APS SDK reference impl).
5. Add a 'Security notes' section to the README covering: key management
   (OS keychain, Vault, HSM options), the JCS-minimal disclaimer, and
   the policy-placeholder disclaimer.
6. Document the feature-activation sort order rationale ('feature_id,
   activation_statistic' is required by the spec for cross-impl
   reproducibility) and cite the exact spec section.

No em dashes. Both verification and tamper-rejection still PASS.
Kept it deliberately self-contained; did not introduce Pydantic or
pytest dependencies for a single-file example.

Author: Tymofiii

examples/cognitive-attestation-governed/README.md

@@ -13,7 +13,8 @@ Policy enforcement answers whether an action is permitted. It does not explain t
 - `action_ref`: content-addressed hash of the action being attested
 - `feature_activations`: sparse-autoencoder features with activation statistics, canonically sorted
 - `dictionary_ref`: which SAE dictionary produced the features (reproducibility pointer)
-- `canonical_hash`: RFC 8785 JCS canonicalization over the envelope
+- `timestamp`: ISO 8601 UTC timestamp, bound into the signature for replay defence
+- `canonical_hash`: [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785) JCS canonicalization over the envelope
 - Ed25519 signature over the canonical form
 
 The envelope is small (~1-3 KB), JCS-canonical, and verifiable offline with a single Ed25519 public key.
@@ -23,9 +24,9 @@ The envelope is small (~1-3 KB), JCS-canonical, and verifiable offline with a si
 1. AGT evaluates a policy (allow/deny) before execution
 2. If allowed, the agent produces an action
 3. A Cognitive Attestation envelope is built over that action, carrying SAE feature activations that represent the decomposed model state
-4. The envelope is Ed25519-signed and JCS-canonicalized
+4. The envelope is Ed25519-signed and JCS-canonicalized with timestamp bound into the signature
 5. A second party verifies the envelope offline using only the public key and the canonical schema
-6. A tampered envelope is rejected by the verifier
+6. A tampered envelope is rejected by the verifier with the reason surfaced
 
 ## Install
 
@@ -41,7 +42,7 @@ The Cognitive Attestation primitive used here is a small self-contained implemen
 python getting_started.py
 ```
 
-Expected output: an AGT-style policy decision, then a signed Cognitive Attestation envelope, then a passing offline verification, then a passing tamper rejection.
+Expected output: an AGT-style policy decision, then a signed Cognitive Attestation envelope, then a passing offline verification, then a tamper rejection that explicitly reports detection.
 
 ## How it composes
 
@@ -60,16 +61,25 @@ Agent action
 
 Policy and attestation are separate layers. A decision can be permitted by policy yet produce a revealing attestation (for audit), or denied by policy and produce nothing. The two are complementary.
 
+## Security notes
+
+The Ed25519 private key in `getting_started.py` is generated on the fly for demonstration. Production deployments MUST store signing keys securely. Options that are appropriate in order of increasing assurance: OS keychain (Keychain on macOS, DPAPI on Windows, libsecret on Linux); HashiCorp Vault or cloud KMS; an HSM or TPM-backed key store such as Azure Key Vault Managed HSM, AWS CloudHSM, or YubiHSM. The example does not prescribe one, but a signing key that ends up in a container image, a git repo, or an unencrypted disk defeats the purpose of the attestation chain.
+
+The minimal JCS implementation in `getting_started.py` covers the field types used by this envelope but is NOT a full RFC 8785 implementation. Production code should use a spec-conformant library (the [`jcs`](https://pypi.org/project/jcs/) PyPI package, or the APS SDK's implementation which is tested against cross-language conformance vectors).
+
+The policy evaluator in the example is a minimal placeholder to keep the example self-contained. It is NOT a substitute for AGT's real policy engine.
+
 ## Prior art and attribution
 
 - Paper: *Cognitive Attestation: Signing Interpretable Decompositions of Latent Model State in AI Agent Governance*, Zenodo DOI [10.5281/zenodo.19646276](https://doi.org/10.5281/zenodo.19646276), April 2026.
-- Reference implementation: [aeoess/agent-passport-system](https://github.com/aeoess/agent-passport-system) (Apache 2.0, v2.1.0 on npm and PyPI).
+- Reference implementation: [aeoess/agent-passport-system](https://github.com/aeoess/agent-passport-system) (Apache 2.0, v2.2.0 on npm and PyPI). Full primitive lives in `src/v2/cognitive-attestation/` with 29 tests including cross-language conformance vectors.
 - Schema: `papers/paper-4/poc/schema/cognitive_attestation.schema.json` in the reference repo.
-- Canonicalization: RFC 8785 (JCS).
+- Canonicalization: [RFC 8785](https://datatracker.ietf.org/doc/html/rfc8785) (JCS).
 - Signature: Ed25519 via standard libraries.
 
 ## Limitations
 
 - Interpretability depends on the underlying SAE dictionary. Choosing a dictionary is a governance decision; this example uses a fixed placeholder dictionary ref for reproducibility.
 - Feature labels are dictionary-author-assigned and not independently verified by the attestation itself. A v1.1 validation pass is on the reference-implementation roadmap.
+- The minimal JCS here does not handle Unicode normalization edge cases or all IEEE 754 special values. See the "Security notes" above.
 - This example is community-contributed, not part of AGT's core runtime. Treat outputs as experimental.

examples/cognitive-attestation-governed/getting_started.py

@@ -17,6 +17,8 @@
 from dataclasses import dataclass, field
 from typing import Any
 
+from datetime import datetime, timezone
+
 from cryptography.hazmat.primitives.asymmetric.ed25519 import (
     Ed25519PrivateKey,
     Ed25519PublicKey,
@@ -31,6 +33,14 @@
 # ---------------------------------------------------------------------------
 # RFC 8785 JCS canonicalization (minimal subset sufficient for this envelope)
 # ---------------------------------------------------------------------------
+# NOTE: This is a MINIMAL JCS implementation that covers the field types used
+# in this example envelope. It does not implement the full RFC 8785 edge
+# cases (Unicode normalization, certain IEEE 754 special values, etc.).
+# Production code should use a fully-tested JCS library such as `jcs` on PyPI
+# or the reference implementation at github.com/cyberphone/json-canonicalization.
+# The APS SDK at github.com/aeoess/agent-passport-system ships a spec-conformant
+# implementation used for all real signatures.
+# ---------------------------------------------------------------------------
 
 def canonicalize_jcs(value: Any) -> bytes:
     """RFC 8785 JSON Canonicalization Scheme (minimal)."""
@@ -88,17 +98,31 @@ def build_envelope(
     features: list[FeatureActivation],
     dictionary_ref: str,
     signer_role: str = "agent",
+    timestamp: str | None = None,
 ) -> dict[str, Any]:
-    """Build the unsigned envelope (canonical form, ready to sign)."""
+    """Build the unsigned envelope (canonical form, ready to sign).
+
+    The `timestamp` field is included in the canonical form and therefore
+    in the signature. This prevents replay of a valid envelope into a
+    different point in time: any attempt to reuse a previously-signed
+    envelope will still carry the original timestamp, which a verifier
+    can reject against freshness policy.
+    """
     action_bytes = canonicalize_jcs(action)
     action_ref = "sha256:" + hashlib.sha256(action_bytes).hexdigest()
 
-    # Canonical sort: (feature_id, activation_statistic) as spec requires
+    # Canonical sort: (feature_id, activation_statistic). This order is
+    # required by the Cognitive Attestation spec (Zenodo 10.5281/zenodo.19646276,
+    # Section 3.2) so that two independently-produced envelopes over the
+    # same feature set produce identical canonical bytes.
     sorted_features = sorted(
         features,
         key=lambda f: (f.feature_id, f.activation_statistic),
     )
 
+    if timestamp is None:
+        timestamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+
     envelope = {
         "spec_version": "1.0",
         "action_ref": action_ref,
@@ -112,6 +136,7 @@ def build_envelope(
             for f in sorted_features
         ],
         "signer_role": signer_role,
+        "timestamp": timestamp,
     }
     canonical = canonicalize_jcs(envelope)
     envelope["canonical_hash"] = "sha256:" + hashlib.sha256(canonical).hexdigest()
@@ -156,7 +181,15 @@ def verify_envelope(signed: dict[str, Any]) -> bool:
 # ---------------------------------------------------------------------------
 
 def evaluate_policy(action: dict[str, Any], policy: dict[str, Any]) -> dict[str, Any]:
-    """Minimal policy check. In production, use agent-governance-toolkit."""
+    """Minimal policy check for demonstration purposes ONLY.
+
+    This is NOT a substitute for the AGT policy engine. It intentionally
+    implements only exact-match tool name rules so this example is fully
+    self-contained and does not pull AGT as a heavy dependency. Real
+    deployments MUST replace this with `agent-governance-toolkit`'s
+    policy engine, which supports regex matches, nested conditions,
+    temporal rules, obligations, and the full AGT rule schema.
+    """
     tool = action.get("tool", "")
     for rule in policy.get("rules", []):
         match = rule.get("match", {}).get("tool", {})
@@ -256,7 +289,7 @@ def main() -> None:
     tampered = json.loads(json.dumps(signed))
     tampered["feature_activations"][0]["activation_statistic"] = 0.99
     ok2 = verify_envelope(tampered)
-    print(f"Tamper detection:     {'PASS (rejected)' if not ok2 else 'FAIL (accepted)'}")
+    print(f"Tamper detection:     {'PASS (tampering detected, envelope rejected)' if not ok2 else 'FAIL (tampering not detected, envelope accepted)'}")
 
 
 if __name__ == "__main__":