release: v0.3.0

Author: onesimplecode

.github/workflows/config-drift-demo.yml

@@ -0,0 +1,51 @@
+name: Config drift demo (worked example)
+
+on:
+  pull_request:
+    paths:
+      - 'scripts/check-config-consistency.py'
+      - 'examples/worked-example/**'
+  push:
+    branches: [main]
+    paths:
+      - 'scripts/check-config-consistency.py'
+      - 'examples/worked-example/**'
+  workflow_dispatch: {}
+
+# ---------------------------------------------------------------------------
+# This job does NOT gate this repo's own config -- it proves that
+# check-config-consistency.py (TR-GOV-001) correctly detects the drift
+# planted in examples/worked-example/sample-app (gemma4:31b in CLAUDE.md
+# vs gemma4:26b in config/search_config.yaml.example -- see
+# examples/worked-example/README.md). Here, the detector *failing* on the
+# fixture is success; if it ever passes clean, the fixture or the detector
+# itself has regressed.
+#
+# A downstream user copies this pattern into their own app's CI, pointed at
+# their own --root, where a real drift SHOULD fail the build (see
+# docs/releasing.md and the sample release-check.yml in this repo for what
+# a real, blocking gate looks like).
+# ---------------------------------------------------------------------------
+
+jobs:
+  demo-detects-drift:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v7.0.0
+
+      - uses: actions/setup-python@v6.3.0
+        with:
+          python-version: '3.12'
+
+      - name: Assert check-config-consistency.py catches the planted drift
+        run: |
+          set +e
+          python3 scripts/check-config-consistency.py --root examples/worked-example
+          code=$?
+          set -e
+          if [ "$code" -ne 1 ]; then
+            echo "::error::Expected exit 1 (DRIFT detected) against examples/worked-example/sample-app, got exit $code instead -- the fixture or detector regressed."
+            exit 1
+          fi
+          echo "Confirmed: check-config-consistency.py correctly detected the planted local-gemma-model drift (exit 1)."

.gitignore

@@ -1,5 +1,3 @@
 __pycache__/
 *.pyc
 .pytest_cache/
-.venv/
-venv/

AGENTS.md

@@ -37,17 +37,35 @@ Every multi-step agent node declares four fields before implementation:
 
 Missing any field means the design is incomplete.
 
-**Reference implementation:** `examples/engine-interface/` shows this pattern
-applied to a multi-source polling pipeline (inspired by the SearXNG engine
-interface). Key properties: `source_name` (identity), `default_timeout`
-(budget), `fetch()` that never raises (exit condition = always returns),
-`list[Result]` output (normalized schema). These four map directly to the
-four TR-AGT-003 fields.
-
 The exit condition must be verified by deterministic evidence when the agent
 changes persistent state, writes files, sends messages, or calls tools with side
 effects (TR-TEST-006).
 
+See `examples/engine-interface/` for a concrete reference implementation: a
+SearXNG-inspired multi-source polling pattern where `source_name` (identity),
+`default_timeout` (budget), a never-raising `fetch()` (exit condition), and a
+normalized `list[Result]` (output schema) map directly onto the four fields above.
+
+### MCP Tool Annotations (TR-AGT-003, field 5)
+
+When a node is exposed as an MCP tool, declare four hint flags describing its blast
+radius. These are advisory hints to MCP clients (Claude Code, Cursor, opencode) — the
+MCP protocol does not enforce them, so declare them accurately regardless.
+
+| Annotation | Meaning | Intended client behaviour |
+|---|---|---|
+| `readOnlyHint: true` | Tool never writes to external state | Act freely, safe to parallelize |
+| `destructiveHint: true` | Tool deletes or irreversibly mutates data | Always confirm, no exceptions |
+| `idempotentHint: true` | Safe to re-run after a retry or exhausted budget | Affects retry policy (field 4) |
+| `openWorldHint: true` | Tool reaches external systems (web, APIs, services) | Treat output as untrusted (TR-SEC-005) |
+
+All four are required when registering an MCP tool (using MCP SDK `ToolAnnotations`
+keyword names); nodes not exposed as MCP tools are exempt. Example: `search_notes` is
+`readOnlyHint=True, destructiveHint=False, idempotentHint=True, openWorldHint=False`;
+`fetch_url` is `readOnlyHint=True, destructiveHint=False, idempotentHint=True,
+openWorldHint=True` (external fetch triggers TR-SEC-005 on its output); `delete_document`
+is `readOnlyHint=False, destructiveHint=True, idempotentHint=True, openWorldHint=False`.
+
 ### Trigger Classification (TR-AGT-004)
 
 Classify every agent invocation at design time:

ATTRIBUTIONS.md

@@ -14,6 +14,7 @@ and examples are maintainer-authored unless a file header states otherwise.
 | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | MIT | Debt-tag convention, config consistency checking concept; adapted as `LUMIA-DEBT:` / `POC-EXCEPTION:` and `check-config-consistency.py`. |
 | [MODSetter/SurfSense](https://github.com/MODSetter/SurfSense) | Apache-2.0 | Comparative analysis only; selective pattern adoption (RRF, automations) documented in private app ADRs — not shipped as SurfSense code. |
 | Karpathy LLM Wiki (public write-ups) | N/A (ideas) | Three-layer vault structure, file-based session state, ingest queue patterns — described and reimplemented independently. |
+| [SearXNG](https://github.com/searxng/searxng) | AGPL-3.0 | Comparative pattern reference only for `examples/engine-interface/` (TR-AGT-003 loop contract demo). No code copied — verified directly against `searx/engines/demo_online.py`, which uses a module-level `setup()`/`init()`/`request()`/`response()` plugin API, structurally unrelated to this example's synthetic ABC-based `source_name`/`fetch()`/`default_timeout` pattern. The per-engine declared-timeout *idea* is the only thing carried over. |
 | AGENTS.md ecosystem | Open standard | Complementary positioning; this repo focuses on governance/traceability, not replacing AGENTS.md. |
 | [Microsoft Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit) | (see upstream) | Comparative positioning only; this repo focuses on design-time and repo-time standards, not runtime agent governance. |
 | Dify and similar RAG/agent platforms | (varies by project) | Comparative positioning only; no code, docs, or implementation copied. |

CHANGELOG.md

@@ -5,7 +5,60 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
-No unreleased changes.
+## [0.3.0] - 2026-07-04
+
+### Added
+
+- `examples/engine-interface/` — reference implementation of the TR-AGT-003 loop-contract
+  pattern (SearXNG-inspired multi-source polling engine interface), plus a Loop Contracts
+  pointer in `AGENTS.md` and a `requirements-implementation-map.md` row update. This was
+  published directly to the public repo (commit `c20c72d`) without a corresponding private-repo
+  change; pulled back into the private source here so the next `publish-public-standards.yml`
+  run (which mirrors private → public via `rsync --delete`) does not silently delete it.
+- `AGENTS.md` — new "MCP Tool Annotations (TR-AGT-003, field 5)" section: the
+  `readOnlyHint`/`destructiveHint`/`idempotentHint`/`openWorldHint` convention for MCP-exposed
+  nodes, ported from the private operating conventions (v0.3 roadmap item 1).
+  `registry/tr-registry.yaml`'s `TR-AGT-003` entry extended to reference field 5.
+- `examples/worked-example/` — the TR-AGT-004 trace now runs to completion: step 5 shows real
+  `check-config-consistency.py` output (previously only described hypothetically) and a new
+  step 6, `.github/workflows/config-drift-demo.yml`, is a CI job whose success condition is
+  that the example's planted `local-gemma-model` drift is still detected — the "TR-ID → ADR →
+  maturity row → script output → CI gate" full path the v0.3 roadmap asked for. Corrected the
+  maturity-checklist's Annex A mapping in the process: the CI-gate evidence now lives on a new
+  A.10 row (third-party/supplier relationships, matching the template's own mapping for
+  `check-config-consistency.py`) instead of conflated into A.9 (human oversight); the now-closed
+  `LUMIA-DEBT` tag was removed from `sample-app/CLAUDE.md`.
+- `scripts/check-config-consistency.py` — new `--root PATH` flag (default: the script's own
+  repo root), so it can scan any app monorepo, not just the one it lives in (P2). `README.md`'s
+  usage example updated to show `--root /path/to/your/repo --app YourApp`.
+- `registry/tr-registry.yaml` — `TR-PUB-006`: agent persona drift check between the private
+  operating-persona tree and its public-standards rewrite. Compares last-changed time for each
+  pair and fails on drift, forcing a human reconciliation decision instead of silent staleness.
+- `.gitignore` — `__pycache__/`, `*.pyc`, `.pytest_cache/` (P3); nothing previously kept these
+  out of a future `git add -A` in the public repo. Added to `docs/public-export-manifest.yaml`'s
+  `generated:` list.
+
+### Fixed
+
+- `scripts/check-config-consistency.py` — an unknown `--app` name or a nonexistent `--root`
+  previously printed a false "OK" (or crashed) instead of failing; now exits 2 with an
+  explicit "Unknown app(s): ... . Known: ..." message (P1, P2).
+- `ATTRIBUTIONS.md` — added the `detect-secrets` (Yelp, Apache-2.0) entry that should have
+  shipped alongside v0.2.0's secret-scanning CI step but was missed.
+- `ATTRIBUTIONS.md` — added a SearXNG (AGPL-3.0) entry for `examples/engine-interface/`'s
+  cited pattern source, found during v0.3 release-readiness review; verified no code was
+  copied (SearXNG's actual `searx/engines/demo_online.py` uses an unrelated module-level
+  plugin API) before writing the entry.
+
+### Changed
+
+- `templates/completion-checklist.md` strengthened to match the private template's rigor:
+  file:line evidence citation per acceptance criterion, an explicit anti-mock-masking clause
+  on test completeness, and a "Reviewer scope complete" item (docs/ADRs, not just code, must
+  be in a reviewer's stated scope). The public copy's own "Post-write verification" item is
+  kept (P4) — nothing here required staying private.
+- `.github/workflows/release-check.yml` — `actions/checkout`/`actions/setup-python` bumped to
+  Node.js 24-compatible versions, clearing the Node 20 deprecation warning.
 
 ## [0.2.0] - 2026-06-26
 
@@ -36,6 +89,7 @@ No unreleased changes.
 - `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.2.0...HEAD
+[Unreleased]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/onesimplecode/ai-engineering-standards/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/onesimplecode/ai-engineering-standards/releases/tag/v0.1.0

README.md

@@ -27,7 +27,7 @@ public reuse.
 python3 scripts/public-export-check.py .
 
 # Scan for config/model-string drift (point at your app monorepo)
-python3 scripts/check-config-consistency.py --app YourApp
+python3 scripts/check-config-consistency.py --root /path/to/your/repo --app YourApp
 
 # Report deferred-work tags
 python3 scripts/debt-report.py --path /path/to/your/repo

examples/worked-example/README.md

@@ -9,19 +9,40 @@ artifacts. **All content is fictional** — no private data or real application
 |------|----------|----------|
 | 1 | `registry-snippet.yaml` | TR-AGT-004 defined as active |
 | 2 | `docs/decisions/ADR-001-example.md` | Trigger type classified: user-initiated |
-| 3 | `docs/maturity-checklist.md` | A.9 human oversight row = Partial |
-| 4 | `sample-app/CLAUDE.md` | Documents trigger + debt tag |
-| 5 | `check-config-consistency.py` | Would catch model-string drift in real app |
+| 3 | `docs/maturity-checklist.md` | A.9 human oversight row = Partial (trigger classified, no further action needed at POC) |
+| 4 | `sample-app/CLAUDE.md` | Documents trigger classification |
+| 5 | `check-config-consistency.py` | Real output below — catches the planted `local-gemma-model` drift (TR-GOV-001) |
+| 6 | `.github/workflows/config-drift-demo.yml` | CI gate: fails the job if the drift is ever *not* detected (see `docs/maturity-checklist.md` A.10) |
 
 ## Run (from public repo root)
 
 ```bash
 python3 scripts/public-export-check.py .
 python3 scripts/debt-report.py --path examples/worked-example
+python3 scripts/check-config-consistency.py --root examples/worked-example
 ```
 
 ## Deliberate drift example
 
 `sample-app/CLAUDE.md` references `gemma4:31b` while `config/search_config.yaml.example`
-uses `gemma4:26b`. In a real app at repo root, `check-config-consistency.py` would
-report **DRIFT** for the `local-gemma-model` family.
+uses `gemma4:26b`. Real output from the command above:
+
+```
+sample-app:
+  DRIFT    local-gemma-model: 2 distinct values found
+             'gemma4:31b' <- sample-app/CLAUDE.md:8
+             'gemma4:26b' <- sample-app/config/search_config.yaml.example:5, sample-app/config/search_config.yaml.example:5
+
+See TR-GOV-001 (docs/tr-registry.yaml) for the convention this enforces.
+```
+
+(the duplicated location on the last line is a cosmetic quirk in the script itself:
+`SCAN_GLOBS` includes both `config/*.yaml.example` and `config/*.example`, and
+`search_config.yaml.example` matches both patterns with no dedup, so the file is scanned
+twice. Harmless — it doesn't cause a false positive or negative — but worth knowing if
+you copy this script into your own repo.)
+
+(exit code 1). `.github/workflows/config-drift-demo.yml` runs this exact command in CI
+on every change to this example or the script — the job's *success* condition is that
+the drift is still caught. If a future change to the fixture or the detector makes this
+pass clean, the job fails loudly instead of silently losing the example's teaching value.

examples/worked-example/docs/maturity-checklist.md

@@ -1,14 +1,15 @@
 # Maturity Checklist: Sample App (Synthetic)
 
-**Last updated:** 2026-06-17
+**Last updated:** 2026-07-04
 **Current tier:** POC
 **Operationalizes:** TR-GOV-004
 
 | # | Objective | Mechanism | Applicable | Status | Evidence |
 |---|-----------|-----------|------------|--------|----------|
 | A.5 | AI impact assessment | templates/ai-impact-assessment.md | Yes | N/A | No user-facing AI output in this example |
-| A.9 | Human oversight | Tiered Autonomy | Yes | Partial | ADR-001 documents user-initiated trigger; no CI gate yet |
+| A.9 | Human oversight | Tiered Autonomy | Yes | Partial | ADR-001 documents user-initiated trigger classification (TR-AGT-004) |
+| A.10 | Third-party / supplier relationships | `scripts/check-config-consistency.py` (TR-GOV-001) | Yes | Met | `.github/workflows/config-drift-demo.yml` runs the script against this example on every change and fails if the planted `local-gemma-model` drift is ever not detected |
 
 ## Open items
 
-- `sample-app/CLAUDE.md` — LUMIA-DEBT: add CI gate for config drift (TR-GOV-001)
+None currently open for this example.

examples/worked-example/sample-app/CLAUDE.md

@@ -10,7 +10,8 @@
 
 ## Known debt
 
-LUMIA-DEBT: wire check-config-consistency.py into CI (TR-GOV-001)
+None currently open. `check-config-consistency.py` runs against this app in
+`.github/workflows/config-drift-demo.yml` (TR-GOV-001).
 
 ## Privacy (TR-SEC-003)
 

registry/tr-registry.yaml

@@ -76,7 +76,9 @@ requirements:
     section: "Agent Spawning"
     text: >
       Every agent pipeline node declares input schema, output schema, exit condition,
-      and resource budget before implementation.
+      and resource budget before implementation. Nodes exposed as MCP tools additionally
+      declare four tool annotation hints (readOnlyHint, destructiveHint, idempotentHint,
+      openWorldHint) describing blast radius — required only for MCP-exposed nodes.
 
   - id: TR-AGT-002
     title: Deterministic operations use scripts not agents
@@ -205,3 +207,13 @@ requirements:
     text: >
       Public repo maintains ROADMAP.md and CHANGELOG.md with periodic curated releases,
       not continuous private-repo mirroring.
+
+  - id: TR-PUB-006
+    title: Agent persona drift check between private and public trees
+    status: active
+    section: "Public Release"
+    text: >
+      A drift check compares the last-changed time of each private operating persona
+      against its public-standards rewrite and fails if the private side changed more
+      recently. This does not auto-sync content — the public rewrite stays hand-curated
+      — it only forces a human reconciliation decision instead of silent drift.