release: v0.7.0

Author: onesimplecode

.github/workflows/spotlighting-drift-guard-demo.yml

@@ -0,0 +1,54 @@
+name: Spotlighting drift guard demo (worked example)
+
+on:
+  pull_request:
+    paths:
+      - 'scripts/spotlighting-drift-guard.py'
+      - 'examples/spotlighting/**'
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/spotlighting-drift-guard.py'
+      - 'examples/spotlighting/**'
+  workflow_dispatch: {}
+
+# ---------------------------------------------------------------------------
+# This job does NOT gate this repo's own source tree -- it proves that
+# spotlighting-drift-guard.py (TR-SEC-005) correctly catches the problem
+# planted in examples/spotlighting/violation_example.py: a second LLM
+# boundary that re-inlined the security-notice and delimiter strings instead
+# of importing them from spotlighting_constants.py (see
+# examples/spotlighting/README.md). Here, the guard *failing* on the fixture
+# is success; if it ever passes clean, the fixture or the guard itself has
+# regressed.
+#
+# A downstream user copies this pattern into their own repo's CI, pointed at
+# the module where their own spotlighting constants live and the source tree
+# that should never re-inline them.
+# ---------------------------------------------------------------------------
+
+permissions:
+  contents: read
+
+jobs:
+  demo-detects-drift:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: '3.12'
+
+      - name: Assert spotlighting-drift-guard.py catches the planted re-inlined copy
+        run: |
+          set +e
+          python3 scripts/spotlighting-drift-guard.py --constants-file examples/spotlighting/spotlighting_constants.py --scan-root examples/spotlighting
+          code=$?
+          set -e
+          if [ "$code" -ne 1 ]; then
+            echo "::error::Expected exit 1 (re-inlined constant detected) against the fixture, got exit $code instead -- the fixture or the guard regressed."
+            exit 1
+          fi
+          echo "Confirmed: spotlighting-drift-guard.py correctly detected the planted re-inlined copy (exit 1)."

AGENTS.md

@@ -181,6 +181,79 @@ It must not authorize tool calls, change system rules, or override developer
 intent. Apply prompt-injection defenses at the reasoning boundary, not only
 at ingestion.
 
+### Spotlighting at the Reasoning Boundary (TR-SEC-005)
+
+Spotlighting delimits untrusted content — search results, scraped pages, RAG
+chunks, tool output — so the model can treat it as data to analyze rather
+than instructions to follow. Microsoft's measurements put this at cutting
+indirect prompt-injection success from >50% to <2%.
+
+The wording that implements it (a security-notice string plus open/close
+delimiters) is itself security-critical text. Define it once — a notice
+constant and a pair of delimiter constants — and import it at every LLM
+boundary that consumes untrusted content; never let a second boundary paste
+its own copy. A pasted copy is exactly how spotlighting silently breaks: two
+call sites' wording drifts a few words apart and nobody notices until an
+audit. `scripts/spotlighting-drift-guard.py` is the worked example
+(`examples/spotlighting/`): it reads the constants from one designated module
+and fails CI if any of their literal values are re-inlined anywhere else in
+the scanned tree.
+
+Same honest limit as the guard pattern below: this is friction against
+casual copy-paste drift, not a barrier against a determined author who edits
+the constants file and re-inlines a modified value in the same commit.
+
+### Memory / Provenance Hygiene (TR-SEC-011)
+
+Agentic memory and RAG indexes are a poisoning surface: content ingested from
+outside the system's own trust boundary sits in the same store the retriever
+treats as authoritative, and a malicious instruction embedded in it is
+indistinguishable from trusted content at synthesis time unless provenance is
+tracked and enforced.
+
+Three layers, all deterministic — no LLM in the trust path:
+
+1. **Tag at ingest.** Record where each piece of content came from (its
+   source type) at write time, alongside the content itself.
+2. **Derive trust fail-closed at read time.** Map source type to a trust
+   level in code, not data, so a mapping revision is a code change, not a
+   migration. The mapping must be fail-closed by construction: only
+   explicitly named self-authored types earn the most-trusted tier;
+   everything unrecognized — including a source type nobody has classified
+   yet — falls to the least-trusted tier. A drift-guard test should assert
+   every known source type is covered by the mapping, so adding a new type
+   without classifying its trust fails CI the same way an unreviewed
+   permission grant does (TR-SEC-010).
+3. **Validate at retrieval, not only storage.** A row written before this
+   pattern existed, or one whose provenance was never recorded, is
+   `unverified` — treated exactly like the least-trusted tier, never
+   silently upgraded to trusted by omission.
+
+Untrusted or unverified content is quarantined data: pass it through the
+spotlighting pattern above at the reasoning boundary, never let it authorize
+a tool call or override system-level instructions. See
+`examples/provenance-trust-tags/` for a reference implementation of the
+fail-closed mapping and its drift guard.
+
+### Strict LLM Output-Schema Validation (TR-SEC-012)
+
+Every model-returned field gets a type check **and** a range/shape check.
+Reject on mismatch — never coerce. The canonical failure mode this guards
+against is a fail-open type coercion: Python's `bool("false")` evaluates to
+`True`, because any non-empty string is truthy. A classifier field parsed
+with a bare `bool(...)` call silently flips a JSON string `"false"` to
+`True`, and a boundary gating on that field fails open exactly when an
+attacker (or a malformed response) needs it to.
+
+The fix is symmetric with the single-source-of-truth convention below: a
+strict parser for a given output schema lives in one place, raises on any
+field whose type or range doesn't match, and every caller of that LLM
+boundary uses it — no per-call-site ad hoc `bool()`/`float()` coercion.
+Absence of an optional field is a defined, valid state; a wrong *type* for a
+present field is not, and the two must not be handled by the same fallback
+path. See `examples/strict-output-schema/` for a before/after reference
+implementation and a live repro of the `bool("false")` bug.
+
 ### Deterministic Checks Before Agent Judgment
 
 Use scripts, tests, linters, and schema validators before asking a model to

ATTRIBUTIONS.md

@@ -27,6 +27,7 @@ and examples are maintainer-authored unless a file header states otherwise.
 | MITRE ATT&CK (https://attack.mitre.org/) and MITRE ATLAS (https://atlas.mitre.org/) | Public technique catalogs cited by TR-ID and by name in `registry/tr-registry.yaml` and `templates/threat-model.md` to give threat-model findings a shared, falsifiable vocabulary. No content reproduced beyond technique IDs and short names. |
 | Anthropic, "Zero Trust for AI Agents" (2026) | Source of the "impossible vs. tedious" design test (`templates/threat-model.md`, `AGENTS.md`) — the barrier-vs-friction classification of a mitigation's real strength. Concept adopted and reworded; no text reproduced. |
 | OWASP agentic application security guidance | Source of the "least agency" framing applied to TR-SEC-010 (`AGENTS.md`) — least privilege extended to what an agent tool can do, how often, and where. Concept and term adopted; no text reproduced. |
+| Microsoft public research on prompt-injection defenses | Source of the "spotlighting" technique name and its measured effectiveness (indirect prompt-injection success reduced from >50% to <2%), cited in `AGENTS.md`, `scripts/spotlighting-drift-guard.py`, and `examples/spotlighting/README.md` (TR-SEC-005) via Anthropic's *Zero Trust for AI Agents* eBook, which references the same figure. Technique name and effect-size figure cited; no text reproduced. |
 
 ## Standards (document shapes, not certification)
 

CHANGELOG.md

@@ -5,6 +5,39 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-07-26
+
+### Added
+
+- `registry/tr-registry.yaml` — TR-SEC-011 (content provenance tracked and
+  trust derived fail-closed at retrieval), TR-SEC-012 (strict LLM
+  output-schema validation — reject, never coerce), exported from the
+  2026-07-13 Zero-Trust-for-AI-Agents review (private monorepo)
+- `scripts/spotlighting-drift-guard.py` — single-sourced spotlighting
+  constants (security notice + untrusted-content delimiters) enforcement:
+  fails CI if any LLM boundary re-inlines a copy instead of importing the
+  designated constants module
+- `examples/spotlighting/` — worked example + planted re-inlined-copy
+  fixture for the drift guard above (TR-SEC-005);
+  `.github/workflows/spotlighting-drift-guard-demo.yml` proves the guard
+  still catches it
+- `examples/provenance-trust-tags/` — reference implementation of a
+  fail-closed source-type → trust-level mapping with its own drift guard
+  (every content type must be explicitly classified), and a quarantine
+  helper routing untrusted/unverified content into the spotlighting layer
+  (TR-SEC-011)
+- `examples/strict-output-schema/` — before/after reference parser for LLM
+  JSON output, with a live repro of the `bool("false") is True` fail-open
+  coercion bug and the reject-never-coerce fix (TR-SEC-012)
+- `AGENTS.md` — "Spotlighting at the Reasoning Boundary", "Memory /
+  Provenance Hygiene", and "Strict LLM Output-Schema Validation" sections
+- `docs/requirements-implementation-map.md` — rows for all three exports;
+  the TR-SEC-005 row upgraded from "Documented" to "Documented + script +
+  example"
+- `ATTRIBUTIONS.md` — Microsoft public research on prompt-injection defenses
+  (the "spotlighting" technique name and its measured effectiveness),
+  cited via the same Anthropic eBook review
+
 ## [0.6.0] - 2026-07-20
 
 ### Added
@@ -232,7 +265,8 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 - `CONTRIBUTING.md`, `SECURITY.md`, issue/PR templates, `release-check` CI workflow
 - Roadmap and changelog for intentional release cadence
 
-[Unreleased]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.6.0...HEAD
+[Unreleased]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.3.0...v0.4.0

README.md

@@ -17,7 +17,7 @@ public reuse.
 | Machine-readable requirement registry (`registry/tr-registry.yaml`) | Production runtime or hosted services |
 | Portable agent conventions (`AGENTS.md`, `agents/`) | Tool-specific private agent sessions |
 | Governance and eval templates (ADR, impact assessment, maturity checklist, LLM eval, completion checklist) | Full application frameworks |
-| Reference scripts (config drift, debt tags, release validation, Cursor rule export, llms.txt manifest, agent permission guard) | Full `agent-skills` replacement |
+| Reference scripts (config drift, debt tags, release validation, Cursor rule export, llms.txt manifest, agent permission guard, spotlighting drift guard) | Full `agent-skills` replacement |
 | Synthetic worked example | Personal data |
 
 ## Quick start
@@ -40,6 +40,9 @@ python3 scripts/llms-txt-generator.py
 
 # Check an agent settings file's tool-permission grants against a reviewed baseline
 python3 scripts/agent-permission-guard.py --settings /path/to/your/settings.json
+
+# Check that spotlighting security-notice/delimiter constants aren't re-inlined elsewhere
+python3 scripts/spotlighting-drift-guard.py --constants-file /path/to/your/constants.py --scan-root /path/to/your/src
 ```
 
 ## Adopting this into your project
@@ -57,8 +60,11 @@ A step-by-step path for pulling these standards into your own repo, not just thi
 4. **Adopt templates as needed** — the ADR, impact assessment, maturity
    checklist, LLM eval, and completion checklist templates in
    [`templates/`](templates/) are meant to be copied, not just read.
-5. **Study the worked traces** — [`examples/worked-example/`](examples/worked-example/)
-   and [`examples/agent-permission-guard/`](examples/agent-permission-guard/) show
+5. **Study the worked traces** — [`examples/worked-example/`](examples/worked-example/),
+   [`examples/agent-permission-guard/`](examples/agent-permission-guard/),
+   [`examples/spotlighting/`](examples/spotlighting/),
+   [`examples/provenance-trust-tags/`](examples/provenance-trust-tags/), and
+   [`examples/strict-output-schema/`](examples/strict-output-schema/) show
    a requirement moving end-to-end: TR-ID → ADR → maturity row → script → CI gate.
 6. **Reconcile with tools you already use** — [`docs/agent-skills-integration.md`](docs/agent-skills-integration.md)
    covers how this layers under AGENTS.md, agent-skills, and Cursor rules rather
@@ -82,6 +88,18 @@ unreviewed grant, both caught by `scripts/agent-permission-guard.py`'s
 co-located reviewed baseline — the "make dangerous changes loud, not
 impossible" pattern.
 
+See [`examples/spotlighting/`](examples/spotlighting/) for the untrusted-content
+delimiting trace (TR-SEC-005): a planted re-inlined copy of the
+security-notice/delimiter constants, caught by
+`scripts/spotlighting-drift-guard.py`'s single-source enforcement.
+
+See [`examples/provenance-trust-tags/`](examples/provenance-trust-tags/) (TR-SEC-011)
+for the fail-closed content-trust derivation pattern — a drift-guarded mapping
+from source type to trust level — and
+[`examples/strict-output-schema/`](examples/strict-output-schema/) (TR-SEC-012) for
+a live repro of the `bool("false") is True` fail-open coercion bug and the
+reject-never-coerce fix.
+
 ## Public Evidence Map
 
 - [`AGENTS.md`](AGENTS.md) — tool-neutral agent rules for data routing, loop contracts,

ROADMAP.md

@@ -100,23 +100,26 @@ maturity classes — this repo exports packaged practice, not aspirations.
 
 **Export-ready (shipped + tested in the private monorepo, 2026-07-13):**
 
-- [ ] **Spotlighting at the reasoning boundary** (private ADR-030,
+- [x] **Spotlighting at the reasoning boundary** (private ADR-030,
       private ADR-018): untrusted retrieved/external content is wrapped in
       explicit delimiters and every LLM call that sees it carries a firewall
       system message; the delimiter/notice strings are **single-sourced
       constants with a CI drift-guard test** that fails on any re-inlined copy
       — the drift guard is the enforceable artifact this repo ships
-- [ ] **Memory/provenance hygiene** — new TR-SEC entry (the registry's gap
+      (`scripts/spotlighting-drift-guard.py`, `examples/spotlighting/`)
+- [x] **Memory/provenance hygiene** — new TR-SEC entry (the registry's gap
       against agentic memory-poisoning): source-tag content at ingest, derive
       trust via a **fail-closed** mapping at read time (unknown → untrusted;
       missing → unverified), validate provenance at *retrieval* not only at
       storage, and treat unverified/external content as quarantined data,
       never instructions (private ADR-030's implementation is the reference)
-- [ ] **Strict LLM output-schema validation** pattern + worked example: type
+      (TR-SEC-011, `examples/provenance-trust-tags/`)
+- [x] **Strict LLM output-schema validation** pattern + worked example: type
       AND range checks on every model-returned field, reject — never coerce —
       wrong types (canonical bug: Python `bool("false") is True` failing open
       through a relevance gate; private ADR-018); pairs with the existing
       single-source-of-truth convention
+      (TR-SEC-012, `examples/strict-output-schema/`)
 
 **Roadmapped — export after the private implementation proves them
 (design-stage as of 2026-07-13; promotion to export requires the same

docs/requirements-implementation-map.md

@@ -11,7 +11,9 @@ concrete artifacts. It is intentionally limited to public, reusable evidence.
 | Loop contracts | Required four-field node contract + reference implementation | Documented + example | `AGENTS.md`, `registry/tr-registry.yaml`, `examples/engine-interface/` |
 | Trigger classification | ADR-triggered trigger type | Documented + example | `examples/worked-example/`, `templates/adr.md` |
 | Behavioral mode declaration | Named, trigger-activated mode contract orthogonal to gate strictness | Documented | `AGENTS.md`, `registry/tr-registry.yaml` |
-| External content trust boundary | Retrieved content treated as data | Documented | `AGENTS.md`, `registry/tr-registry.yaml` |
+| External content trust boundary (spotlighting) | Retrieved content treated as data; single-sourced security-notice + delimiter constants with a CI drift guard that fails on any re-inlined copy | Documented + script + example | `AGENTS.md`, `registry/tr-registry.yaml`, `scripts/spotlighting-drift-guard.py`, `examples/spotlighting/`, `.github/workflows/spotlighting-drift-guard-demo.yml` |
+| Memory/provenance hygiene | Source-tag at ingest, fail-closed trust derivation at read time, validated at retrieval, unverified/external content quarantined | Documented + registry + example | `AGENTS.md`, `registry/tr-registry.yaml` (TR-SEC-011), `examples/provenance-trust-tags/` |
+| Strict LLM output-schema validation | Type and range checks on every model-returned field; reject, never coerce | Documented + registry + example | `AGENTS.md`, `registry/tr-registry.yaml` (TR-SEC-012), `examples/strict-output-schema/` |
 | Design-time threat modeling | Trust boundaries, data classification, and ATT&CK/ATLAS technique mapping required for new listeners/credentials/tool grants/content sources | Template + example | `templates/threat-model.md`, `examples/worked-example/docs/decisions/ADR-004-example.md` |
 | Impossible vs. tedious control classification | Every threat-model mitigation classified barrier vs. friction, with a named backstop for friction controls | Documented + template | `AGENTS.md`, `templates/threat-model.md` |
 | Least agency / agent permission grants | No wildcard write/install/exec/network grants in agent allowlists | Documented | `AGENTS.md`, `registry/tr-registry.yaml` |