ElvinMorales · ElvinMorales · Jun 15, 2026 · Jun 15, 2026
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -41,6 +41,17 @@ jobs:
       - name: Validate generated catalog
         run: agent-librarian validate examples/generated-catalog
 
+      - name: Check runtime wrapper proposals
+        run: |
+          python -m agent_librarian.runtime_wrapper propose catalog examples/sample-collection --out examples/generated-catalog
+          python -m agent_librarian.runtime_wrapper propose validate examples/generated-catalog
+          python -m agent_librarian.runtime_wrapper propose report examples/generated-catalog
+
+      - name: Check review summary JSON syntax
+        run: |
+          python -m json.tool agent/schemas/review-summary.schema.json
+          python -m json.tool agent/schemas/review-summary.example.json
+
       - name: Check generated catalog is current
         run: git diff --exit-code -- examples/generated-catalog
 

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,52 @@
 
 All notable changes to this project are documented here.
 
+## [0.4.0] - 2026-06-15
+
+### Added
+
+- Added a two-layer architecture model for a planned LLM interaction layer,
+  with the deterministic CLI backend remaining the source of truth.
+- Added agent-layer design artifacts covering identity, operating boundaries,
+  prompts, capabilities, governance, memory, state, tools, policies, evals,
+  runtime state, and schemas.
+- Added a documented CLI tool contract and an approval-gated catalog-review
+  workflow for scoped proposals, exact approval, deterministic execution,
+  validation, reporting, and human-review handoff.
+- Added an LLM-layer public-safety policy and safe-scan eval cases.
+- Added runtime state and approval-log artifact designs.
+- Added a review-summary JSON Schema and synthetic example.
+- Added an optional local runtime wrapper prototype for proposing and
+  exact-approval execution of documented `catalog`, `validate`, and `report`
+  actions.
+- Added runtime-wrapper tests for proposals, approval, execution, sensitivity,
+  records, and safety boundaries.
+
+### Changed
+
+- Updated roadmap, taxonomy architecture, and README references for the v0.4
+  LLM-layer and runtime-prototype artifact set.
+- Clarified that the stable CLI remains deterministic and that the optional
+  runtime wrapper does not call an LLM provider, use network access, or expose
+  arbitrary shell execution.
+
+### Safety
+
+- The runtime wrapper supports only documented `catalog`, `validate`, and
+  `report` actions and requires exact command approval before execution.
+- `unclear` and `work-internal` execution are blocked by the prototype.
+- Runtime records are written only when explicitly requested, and generated
+  outputs and records inherit source sensitivity.
+- Validation, reports, and review summaries remain review aids, not safety,
+  correctness, completeness, approval, or publication certification.
+
+### Not included
+
+- No LLM provider integration, network calls, or arbitrary shell execution.
+- No autonomous publication, approval, deletion, merge, or source-editing
+  behavior.
+- No PyPI publishing or release artifact upload in this repository change.
+
 ## [0.3.0] - 2026-06-14
 
 ### Added

diff --git a/README.md b/README.md
@@ -68,8 +68,9 @@ generated outputs.
 
 The LLM layer should orchestrate the workflow, not replace deterministic
 cataloging logic or invent results. CLI-generated files remain the source of
-truth and explicit review artifacts. Current v0.3 behavior does not call an
-LLM.
+truth and explicit review artifacts. The stable CLI remains deterministic and
+does not call an LLM. The optional runtime wrapper prototype also does not call
+an LLM provider or network service.
 
 ## Quickstart
 

diff --git a/docs/forum-demo-runbook.md b/docs/forum-demo-runbook.md
@@ -20,10 +20,10 @@ The demo should emphasize inspectable artifacts and bounded behavior rather
 than model autonomy.
 
 The current forum demo shows the deterministic CLI backend. The project
-direction adds a future LLM interaction layer in front of this workflow to
+direction adds a planned LLM interaction layer in front of this workflow to
 scope user intent, explain safety boundaries, propose documented CLI commands,
 request approval before execution, and summarize generated outputs. Do not
-claim that this LLM behavior exists in v0.3.
+claim that the optional local runtime wrapper calls an LLM provider.
 
 ## What this demo is
 
@@ -36,8 +36,9 @@ claim that this LLM behavior exists in v0.3.
 
 ## What this demo is not
 
-Current v0.3 is not an autonomous LLM agent. It does not call an LLM, use the
-network, execute scanned files, or make artifact-management decisions.
+The stable CLI and optional local runtime wrapper are not autonomous LLM
+agents. They do not call an LLM provider, use the network, execute scanned
+files, or make artifact-management decisions.
 
 It is also not a hosted registry, semantic search system, automatic
 deduplication engine, safety certification, or replacement for human review.
@@ -144,10 +145,10 @@ A practical five-minute sequence is:
 
 ## If someone asks "is this really an agent?"
 
-I would not call the current v0.3 runtime an autonomous LLM agent. I would call
-it the deterministic backend of an evolving artifact-librarian agent or an
-agentic infrastructure component. It has a bounded role, explicit inputs and
-outputs, operating constraints, tool surfaces, validation, diagnostics, and
+I would not call the current runtime an autonomous LLM agent. I would call it
+the deterministic backend and optional approval-gated wrapper of an evolving
+artifact-librarian design. It has a bounded role, explicit inputs and outputs,
+operating constraints, tool surfaces, validation, diagnostics, and
 governance boundaries. A future LLM interaction layer can provide the
 user-facing identity and orchestration while preserving this backend as the
 source of truth.

diff --git a/docs/release-checklist.md b/docs/release-checklist.md
@@ -1,21 +1,104 @@
-# Release Checklist
-
-## v0.3.0 manual release steps
-
-1. Confirm `main` is clean and up to date.
-2. Confirm package metadata reports `0.3.0`.
-3. Run local validation.
-4. Confirm CI passes on the release PR.
-5. Merge the release PR.
-6. Pull latest `main`.
-7. Create an annotated tag:
-
-   ```bash
-   git tag -a v0.3.0 -m "v0.3.0"
-   git push origin v0.3.0
-   ```
-
-8. Create a GitHub release from the tag using the `CHANGELOG.md` `0.3.0`
-   section.
-9. Do not publish to PyPI unless a separate package distribution issue
-   explicitly adds that scope.
+# v0.4.0 Release Checklist
+
+The maintainer performs tag creation and GitHub release publication manually
+after this checklist passes. This release does not include PyPI publishing.
+
+## Pre-release checks
+
+- Confirm the release branch starts from an updated, clean `main`.
+- Confirm the change set contains release metadata, documentation, and CI
+  hygiene only.
+- Confirm the stable deterministic CLI remains the source of truth.
+- Confirm the optional runtime wrapper remains local-only, approval-gated, and
+  bounded to documented `catalog`, `validate`, and `report` actions.
+- Confirm generated examples remain synthetic and unchanged.
+- Open external PR #62 is outside the v0.4 release scope and should be reviewed
+  separately after the release, or closed as not planned if it does not fit
+  the project's contribution or safety standards.
+
+## Version and changelog
+
+- Confirm `pyproject.toml` reports `0.4.0`.
+- Confirm `src/agent_librarian/__init__.py` reports `0.4.0`.
+- Confirm `agent-librarian --version` prints `0.4.0`.
+- Confirm `CHANGELOG.md` contains the dated `0.4.0` release entry.
+- Confirm current-version documentation does not describe v0.3 as current.
+
+## Validation commands
+
+Run from the repository root:
+
+```bash
+python -m pip install -e ".[dev]"
+agent-librarian --version
+agent-librarian --help
+agent-librarian catalog --help
+agent-librarian catalog examples/sample-collection --out examples/generated-catalog
+agent-librarian validate examples/generated-catalog
+agent-librarian report examples/generated-catalog
+python -m json.tool agent/schemas/review-summary.schema.json
+python -m json.tool agent/schemas/review-summary.example.json
+pytest
+git diff --check
+git diff --exit-code -- examples/generated-catalog
+```
+
+Also parse the tool manifest:
+
+```bash
+python -c "from pathlib import Path; import yaml; yaml.safe_load(Path('agent/tools/tools.yaml').read_text(encoding='utf-8')); print('tools yaml: valid')"
+```
+
+If normal catalog regeneration creates timestamp-only noise, rerun the
+deterministic check in PowerShell:
+
+```powershell
+$env:SOURCE_DATE_EPOCH = "1781481600"
+agent-librarian catalog examples/sample-collection --out examples/generated-catalog
+agent-librarian validate examples/generated-catalog
+git diff --exit-code -- examples/generated-catalog
+agent-librarian report examples/generated-catalog
+```
+
+## Runtime-wrapper smoke checks
+
+```bash
+python -m agent_librarian.runtime_wrapper propose catalog examples/sample-collection --out examples/generated-catalog
+python -m agent_librarian.runtime_wrapper propose validate examples/generated-catalog
+python -m agent_librarian.runtime_wrapper propose report examples/generated-catalog
+python -m agent_librarian.runtime_wrapper run report examples/generated-catalog --approve-exact "wrong command"
+```
+
+The wrong-command approval check is expected to fail with a nonzero exit
+status. It must report an approval mismatch and must not execute the
+deterministic backend.
+
+## Public-safety checks
+
+- No private paths.
+- No employer-specific examples.
+- No secrets or credentials.
+- No private prompts, traces, logs, memory snapshots, or state snapshots.
+- No generated private catalogs.
+- No claims of employer endorsement.
+- External PR #62 is not included in v0.4 unless separately reviewed.
+- Validation, reports, and review summaries are not described as safety,
+  correctness, completeness, approval, or publication certification.
+
+## GitHub release steps
+
+After local validation and release-branch CI pass, the maintainer:
+
+1. Reviews and merges the release change through the normal repository process.
+2. Pulls the merged `main` branch.
+3. Creates and pushes the annotated `v0.4.0` tag.
+4. Publishes the GitHub release using the `CHANGELOG.md` `0.4.0` section.
+5. Leaves package registry publishing out of scope unless separately approved.
+
+## Post-release checks
+
+- Confirm the GitHub release points to the intended `v0.4.0` tag.
+- Confirm the release text preserves the runtime and public-safety boundaries.
+- Confirm no package registry artifact was published.
+- Confirm PR #62 remains separate from the v0.4 release and has not been
+  implicitly accepted by the release.
diff --git a/docs/roadmap-v0.4.md b/docs/roadmap-v0.4.md
@@ -23,9 +23,9 @@ operations**.
 The LLM layer should orchestrate the workflow, not invent catalog results.
 CLI-generated files remain the source of truth for review.
 
-## Current baseline
+## Historical baseline
 
-Version 0.3.0 already includes:
+Version 0.3.0 established:
 
 - a deterministic local CLI
 - catalog generation
@@ -39,9 +39,10 @@ Version 0.3.0 already includes:
 - warning-code documentation and a synchronization check
 - release hygiene
 
-The current v0.3 runtime does not call an LLM, execute scanned artifacts,
-maintain hidden memory or session state, or make artifact-management
-decisions.
+The stable CLI remains deterministic and does not call an LLM. The optional
+runtime wrapper prototype also does not call an LLM provider or network
+service, execute scanned artifacts, maintain hidden memory, or make
+artifact-management decisions.
 
 ## Target architecture
 

diff --git a/docs/showcase-brief.md b/docs/showcase-brief.md
@@ -20,8 +20,8 @@ boundaries are all visible in the repository.
 
 ## Architecture direction
 
-The current v0.3 showcase is CLI-first: it demonstrates the deterministic
-backend that performs `catalog`, `validate`, and `report` actions. A future LLM
+The showcase is CLI-first: it demonstrates the deterministic backend that
+performs `catalog`, `validate`, and `report` actions. A planned LLM
 interaction layer can sit in front of this same backend to scope intent,
 explain safety boundaries, propose bounded commands, ask for approval before
 execution, and summarize the generated outputs.
@@ -97,11 +97,12 @@ It is:
 - not a tool that executes scanned artifacts
 - not a replacement for human review
 
-Current v0.3 behavior does not use an LLM and is not an LLM-powered autonomous
-agent. It is the deterministic backend for a planned two-layer architecture,
-not an autonomous agent runtime. Warnings and overlap candidates are review
-prompts, not decisions, and a future model summary must not present them as
-safety, completeness, approval, or publication-readiness certifications.
+The stable CLI and optional runtime wrapper do not use an LLM provider and are
+not an LLM-powered autonomous agent. They support a planned two-layer
+architecture, not an autonomous agent runtime. Warnings and overlap candidates
+are review prompts, not decisions, and a future model summary must not present
+them as safety, completeness, approval, or publication-readiness
+certifications.
 
 ## Why it matters for agentic AI artifacts
 

diff --git a/docs/taxonomy-architecture-map.md b/docs/taxonomy-architecture-map.md
@@ -27,7 +27,7 @@ overlap candidates, and validation results remain inputs to human review.
 
 ## Current and future layers
 
-The current v0.3 repository implements the deterministic CLI backend. Its
+The stable repository runtime implements the deterministic CLI backend. Its
 commands, parsers, schemas, diagnostics, generated catalogs, and reports are
 the current runtime and review artifacts.
 

diff --git a/docs/two-layer-artifact-catalog.md b/docs/two-layer-artifact-catalog.md
@@ -19,9 +19,9 @@ The LLM layer should orchestrate the workflow, not replace deterministic
 cataloging logic or invent catalog results. CLI-generated files remain the
 source of truth for review.
 
-This catalog makes the v0.4 direction inspectable before runtime work begins.
-It does not claim that the planned LLM layer is part of current v0.3 runtime
-behavior.
+This catalog makes the v0.4 direction inspectable. It does not claim that the
+planned LLM layer is part of the stable CLI or the optional local runtime
+wrapper prototype.
 
 ## Architecture summary
 
@@ -58,8 +58,8 @@ generated outputs, and the identity, prompt, capability, tool-boundary, and
 policy documents under `agent/`.
 
 Files under `agent/` describe planned behavior and are not loaded as runtime
-LLM instructions. Their presence does not mean the current v0.3 or v0.4 CLI
-has an LLM wrapper.
+LLM instructions. Their presence does not mean the stable CLI or optional
+runtime wrapper calls an LLM provider.
 
 Entries that still name future issue artifacts are directional, not runtime
 behavior implemented by this documentation issue. Public/private notes apply

diff --git a/pyproject.toml b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-librarian"
-version = "0.3.0"
+version = "0.4.0"
 description = "Catalog and compare local collections of agentic AI artifacts."
 readme = "README.md"
 requires-python = ">=3.10"

diff --git a/src/agent_librarian/__init__.py b/src/agent_librarian/__init__.py
@@ -1,3 +1,3 @@
 """Local catalog generation for agentic AI artifacts."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"