Clarify README and release metadata

Author: screenleon

.github/workflows/rule-governance.yml

@@ -16,6 +16,7 @@ on:
       - "prompt-budget.local.example.yml"
       - "CHANGELOG.md"
       - "MIGRATION.md"
+      - "VERSION"
       - "scripts/*.sh"
       - "scripts/*.py"
   pull_request:
@@ -32,6 +33,7 @@ on:
       - "prompt-budget.local.example.yml"
       - "CHANGELOG.md"
       - "MIGRATION.md"
+      - "VERSION"
       - "scripts/*.sh"
       - "scripts/*.py"
   workflow_dispatch:

CHANGELOG.md

@@ -6,6 +6,59 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 
 ---
 
+## [0.20.0] - 2026-04-30
+
+### Added
+
+- **`VERSION`** — new release metadata file tracking the current template
+  version. The template now declares `0.20.0` in a small machine-readable file
+  instead of relying only on changelog headings.
+
+### Changed
+
+- **`README.md`** — rewritten project introduction so first-time readers can
+  immediately understand the repository's purpose: a portable governance layer
+  for AI coding agents, not an app runtime. Added a concrete inventory covering
+  rules, skills, adapter harnesses, scripts, GitHub workflows, evals, context
+  packs, and release metadata.
+
+- **Decision policy guidance** — README, reusable templates, and documentation
+  skills now describe decision capture in terms of `prompt-budget.yml` →
+  `decision_log.policy`. Adopted projects normally write `DECISIONS.md`; this
+  template repo keeps `DECISIONS.md` example-only and records task decisions in
+  summaries, handoffs, or traces.
+
+- **Rule contract governance** — domain rule templates now use the canonical
+  rule-entry contract (`Directive`, `Rationale`, `Conflict handling`, `Example`,
+  `Non-example`). `scripts/lint-layered-rules.sh` now rejects active rules that
+  omit required canonical fields or leave whole-field placeholders behind.
+
+- **Budget reporting** — `scripts/budget-report.sh` now checks the actual
+  `skills.always_load` set against `layer2_max_tokens` and reports the full
+  skill catalog as informational. The tracked `prompt-budget.yml` targets were
+  updated to match the current standard-profile baseline while the optimization
+  roadmap continues to track future slimming.
+
+### Fixed
+
+- **Context-pack decision parsing** — `scripts/build-context-pack.py` and
+  `scripts/decisions-conflict-check.py` now ignore HTML comment blocks in
+  `DECISIONS.md`, preventing the example decision template from being treated
+  as a real decision entry.
+
+- **Trace review alignment** — `docs/schemas/trace.schema.yaml` and the bundled
+  medium trace example now agree that Medium/Large traces include
+  `task_summary`; `scripts/agent-review.sh` no longer reports a finding on the
+  checked-in example trace.
+
+### Tooling
+
+- **`evals/tooling/context-pack-determinism/expected.json`** — refreshed after
+  the context-pack parser and rule/budget metadata changes so deterministic
+  tooling tests reflect the current contract.
+
+---
+
 ## [0.19.0] - 2026-04-29
 
 ### Added
@@ -663,6 +716,7 @@ Initial release of the agent playbook template.
 
 ---
 
+[0.20.0]: https://github.com/screenleon/agent-playbook-template/compare/v0.19.0...v0.20.0
 [0.19.0]: https://github.com/screenleon/agent-playbook-template/compare/v0.18.0...v0.19.0
 [0.3.0]: https://github.com/screenleon/agent-playbook-template/compare/v0.2.0...v0.3.0
 [0.5.0]: https://github.com/screenleon/agent-playbook-template/compare/v0.4.0...v0.5.0

README.md

@@ -1,5 +1,28 @@
 # Agent Playbook Template
 
+Agent Playbook Template is a portable governance framework for AI coding agents.
+It gives a repository a version-controlled source of truth for how agents load
+context, route work by role, handle approval gates, validate changes, record
+decisions, and hand off structured context across tools.
+
+Use this template when you want repeatable agent behavior across Codex, Claude,
+Copilot, Cursor, OpenCode, Windsurf, or a generic CLI workflow. It is not an app
+runtime or product framework; it is the operating layer around agent-assisted
+software work.
+
+## What This Repository Contains
+
+- Root agent instructions through `AGENTS.md`
+- Source-of-truth operating and routing docs in `docs/`
+- Layered reusable rules in `rules/global/`, `rules/domain/`, and `project/`
+- Reusable skills in `skills/*/SKILL.md`
+- Tool-specific agent surfaces for Claude and GitHub Copilot
+- Adapter harnesses for Claude Code, Copilot, Cursor, OpenCode, Windsurf, and generic CLI use
+- Governance scripts for linting, budget reporting, trace review, context-pack generation, and eval scoring
+- GitHub Actions workflows for markdown lint, rule governance, and trace review
+- Evals and deterministic tooling fixtures for checking governance behavior
+- Release metadata in `VERSION` and `CHANGELOG.md`
+
 ## Quick-start onboarding paths
 
 Choose the path that fits your situation — all three lead to the same governance model.
@@ -59,15 +82,15 @@ The table below shows how each governance gate behaves across the three trust le
 
 Legend: **STOP** = agent pauses and waits for human input. **Advisory** = agent logs the event and continues. Gate behavior is defined in `docs/operating-rules.md` → Trust level.
 
-## Quick Start (3 steps)
+## Adopter Quick Start
 
 1. Copy this template into your repository (or create a repo from this template).
 2. Edit the two source-of-truth docs first: `docs/operating-rules.md` and `docs/agent-playbook.md`. Update `AGENTS.md` after them as the root entrypoint.
-3. Run your first task with the required workflow: discover -> triage -> plan (if needed) -> implement -> validate -> record decisions.
+3. Run your first task with the required workflow: discover -> triage -> plan (if needed) -> implement -> validate -> record decisions according to `prompt-budget.yml` -> `decision_log.policy`.
 
 For first entry into a new repository, use the profile-aware initialization path: at `minimal`, follow the manual scan path in `docs/rules-quickstart.md`; at `standard`/`full`, run `skills/on-project-start/SKILL.md` before implementation.
 
-If you only do one thing on day one: keep `DECISIONS.md` updated so future agent runs can perform contradiction checks.
+If you only do one thing on day one after adopting this template: switch `decision_log.policy` to `normal` and keep `DECISIONS.md` updated so future agent runs can perform contradiction checks.
 
 ## Mental model
 
@@ -141,7 +164,7 @@ flowchart LR
     D --> E[Role Selection]
     E --> F[skills/*/SKILL.md]
     F --> G[Implementation + Validation Loop]
-    G --> H[DECISIONS.md Update]
+    G --> H[Decision Record<br/>per decision_log.policy]
     H --> I[Future Contradiction Checks]
 ```
 
@@ -167,7 +190,7 @@ For staged simplification and automation steps, see `docs/rule-optimization-plan
 4. Plan path: Small uses the simplified path; bounded Medium work may go directly to implementation; ambiguous, high-risk, or cross-module Medium/Large work uses the full planning path.
 5. Implement safely: keep scope tight and follow repository patterns.
 6. Validate: run targeted checks/tests, fix, and repeat until stable.
-7. Record durable state: update `DECISIONS.md` when behavior or architecture choices are made.
+7. Record durable state according to `prompt-budget.yml` -> `decision_log.policy`: adopted projects usually update `DECISIONS.md`; this template repo records task decisions in summaries, handoffs, or traces.
 
 This flow is what makes the template useful in real teams: predictable output quality, lower drift, and faster onboarding.
 
@@ -192,13 +215,19 @@ If you maintain a fork, keep these phrases in your repository description and RE
 - a machine-readable context-pack contract for multi-tool orchestration
 - a canonical trace schema (`docs/schemas/trace.schema.yaml`) usable by any adapter
 - an adapter-neutral evals framework (`evals/`) that verifies governance rules across tools
+- harness adapters and shell-first governance scripts for local and CI validation
 - reusable skills you can adapt into your own agent ecosystem
 - repo-wide Copilot instructions
 
 ## Current asset inventory
 
+- Version: 0.20.0 (`VERSION`)
 - Claude subagents: 8 (`.claude/agents/*.md`)
 - Reusable skills: 18 (`skills/*/SKILL.md`)
+- Governance scripts: 14 (`scripts/*`)
+- GitHub workflows: 3 (`.github/workflows/*.yml`)
+- Adapter harnesses: 6 (`harness/adapters/*`)
+- Example profiles and notes: 4 (`examples/*.md`)
 - Source-of-truth docs: `docs/operating-rules.md`, `docs/agent-playbook.md` (`AGENTS.md` is the root entrypoint that should stay aligned with them)
 
 ## Example gallery
@@ -208,6 +237,7 @@ Use `examples/` for ready-to-adapt constraint profiles:
 - `examples/high-security-mode.md`
 - `examples/mvp-rapid-mode.md`
 - `examples/legacy-maintenance.md`
+- `examples/anti-patterns.md`
 
 ## Required vs optional files
 
@@ -234,6 +264,8 @@ Use `examples/` for ready-to-adapt constraint profiles:
 - `docs/example-task-walkthrough.md` — reference for expected output formats
 - `docs/external-practices-notes.md`
 - `docs/adoption-guide.md`
+- `harness/` — adapter hooks and wrapper scripts for tools that support or emulate governance hooks
+- `evals/` — adapter-neutral behavior fixtures and scoring helpers
 
 ## Adoption path
 

VERSION

@@ -0,0 +1 @@
+0.20.0

evals/tooling/context-pack-determinism/expected.json

@@ -38,18 +38,18 @@
   "orchestration": {
     "budget": {
       "allocated": {
-        "entrypoint": 3970,
+        "entrypoint": 4338,
         "reserve": 1200,
-        "rules": 6830
+        "rules": 6462
       },
       "estimate_method": "word_count*1.35",
       "profile": "standard",
       "target_total_tokens": 12000
     },
     "determinism": {
       "builder_version": "1.0.0",
-      "input_hash": "sha256:baf218e89141bbd6900ef6b09b12ccb6d14d7971ed8eb744d8eae8fb3cbf2565",
-      "output_hash": "sha256:8dad16c4d5d3113a98a3b45265f13a278a18d403599a001c283ffaf5cc304305"
+      "input_hash": "sha256:12c89274afa60281d42317847967718c1f27b5b26013d7430db17597f2ac43a2",
+      "output_hash": "sha256:ed00d4ccbd0dca37799cc214308e73e3e157d6b580606447a80f036738558c25"
     },
     "dropped": [
       {