chore: v0.9.5 hygiene + truth pass before v1.0 credibility cycle

Doc-only release. Removes drift between docs and what shipped through v0.9.4 so the v1.0 credibility cycle (v0.9.6 → v1.0.0) starts from honest ground.

Spec/plan frontmatter sweep: 10 specs flipped Draft/Implementing → Complete with Shipped-In recorded; 18 plan files got close-out headers; specs/timeline-events.md superseded by telemetry-jsonl + dashboard.

PRD § 4 reframed to point at docs/milestones/v1.0-ga.md (canonical) and docs/v1.0-roadmap.md (synthesis); § 3 telemetry metrics qualified pending v0.9.7 dog-food verification. README rules count corrected (11 → 19); methodology-led intro seeded for D5; CLAUDE.md / runtimes/claude/CLAUDE.md / CONTRIBUTING.md repository-structure blocks updated for core/lib/, core/security/, core/references/, core/schemas/.

maturity-loader cascade matrix completed for the four v0.9.0 rules (cache-discipline, injection-defense, secrets-handling, telemetry). plugin-family-release-hardening F-006/F-007 + AC-010/AC-011/AC-012 retargeted to v1.1.0 per D2 lock — full host-neutral kernel and adapter contracts are M4 architectural work; v0.9.7 ships Tier 1 substitution-only fix for v1.0 GA.

next_promotion_criteria reworded per D1 lock: 60-day calendar floor replaced with engineering evidence (≥3 minor/patch releases past v0.9.0, ≥1 community PR merged, AC-025 release-evidence bundle); criterion 6 reworded from unmeasurable "20+ projects" to maintainer attestation via private signal. See docs/v1.0-roadmap.md § D1.

Added: core/rules/model-roles.md (Architect/Editor guidance, M3 deferral closed); docs/milestones/v1.0-ga.md (canonical v1.0 milestone); docs/v1.0-roadmap.md (synthesis of three parallel research swarms with D1–D7 decisions locked).

migrations.json hop 0.9.4 → 0.9.5 added (no-op, doc-only).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: MountainUnicorn

.add/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://github.com/MountainUnicorn/add/config.schema.json",
-  "version": "0.9.4",
+  "version": "0.9.5",
   "project": {
     "name": "ADD",
     "description": "Agent Driven Development \u2014 Claude Code plugin implementing an AI-native SDLC methodology",
@@ -11,7 +11,7 @@
     "level": "beta",
     "promoted_from": "alpha",
     "promoted_date": "2026-04-23",
-    "next_promotion_criteria": "Guardrail suite running in CI and release-blocking; real Claude + Codex install smoke in CI; per-runtime capability matrix in release notes; 60-day stability at beta; marketplace submission approved; 20+ projects using ADD.",
+    "next_promotion_criteria": "1. Guardrail suite running in CI and release-blocking. 2. Real Claude + Codex install smoke in CI. 3. Per-runtime capability matrix in release notes. 4. Beta exercise evidence: \u22653 minor or patch releases past v0.9.0 shipped with no post-tag rollback; \u22651 community PR merged during the beta cycle; AC-025 release-evidence bundle generated for the v1.0 candidate release. 5. Marketplace submission approved. 6. ADD verified in active use beyond the maintainer's solo work: maintainer attests via private signal (direct contact, observed adoption, adopter feedback) that ADD methodology is in production on multiple external projects. Adopter naming only with explicit consent.",
     "exemptions": []
   },
   "planning": {

AGENTS.md

@@ -1,4 +1,4 @@
-<!-- ADD:MANAGED:START version=0.9.1 maturity=beta generated=2026-04-23T14:35:33Z -->
+<!-- ADD:MANAGED:START version=0.9.4 maturity=beta generated=2026-04-30T17:34:32Z -->
 
 # ADD
 

CHANGELOG.md

@@ -27,6 +27,33 @@ Hotfix. Fixes three findings from the plugin-family release-hardening review bef
 
 _(Nothing yet — tracking items go here between releases.)_
 
+## [0.9.5] — 2026-04-22
+
+**Hygiene + truth pass.** Doc-only release. Removes the smokescreen between what the docs claim and what's actually shipped, so the v1.0 credibility cycle (v0.9.6 → v1.0.0) starts from honest ground. No consumer config or plugin-runtime changes.
+
+### Changed
+
+- **Spec/plan frontmatter sweep.** Ten specs flipped from `Draft`/`Implementing` to `Complete` with `Shipped-In: vX.Y.Z` recorded: `agents-md-sync`, `cache-discipline`, `prompt-injection-defense`, `secrets-handling`, `telemetry-jsonl`, `test-deletion-guardrail`, `codex-native-skills` (all v0.9.0); `jq-dependency-declaration`, `secrets-scanner-executable` (v0.9.3); `project-dashboard` (v0.3.0). Eighteen plan files in `docs/plans/` got `> Status: Complete (vX.Y.Z) — superseded by shipped feature.` close-out headers. `specs/timeline-events.md` marked `Superseded` (replaced by telemetry-jsonl + dashboard).
+- **PRD refresh.** `docs/prd.md` header bumped to v0.9.5 / 2026-04-22. § 4 v1.0 reframed to point at `docs/milestones/v1.0-ga.md` (canonical) and `docs/v1.0-roadmap.md` (synthesis), with the 6 reworded GA criteria from `.add/config.json:next_promotion_criteria` listed inline. § 3 metrics qualified — telemetry-derived measurements depend on dog-food emission verification (v0.9.7 milestone).
+- **Maturity cascade matrix.** `core/rules/maturity-loader.md` updated for the four v0.9.0-shipped rules: `secrets-handling` (alpha+ active), `cache-discipline`, `injection-defense`, `telemetry` (beta+ active).
+- **README + CLAUDE.md counts.** README rules count corrected to 19 (was 11). CLAUDE.md, runtimes/claude/CLAUDE.md, CONTRIBUTING.md repository-structure blocks updated to include `core/lib/`, `core/security/`, `core/references/`, `core/schemas/` and current template/knowledge counts.
+- **README intro.** Lead paragraph reframed methodology-first ("ADD is a methodology"); the Claude/Codex plugin is the canonical implementation. Seed for the D5 brand-split direction (methodology authoritative at `docs/methodology.md` mirror, plugin as one runtime).
+- **Roadmap section.** README's stale "v0.4.0 — Next" historic block replaced with a one-line pointer to `docs/v1.0-roadmap.md` and `CHANGELOG.md`.
+
+### Added
+
+- **`core/rules/model-roles.md`** — Architect / Editor model-role guidance. One-paragraph rule distinguishing planning-shaped work (Opus, spec authoring, decision walkthroughs) from mechanical-shaped work (Sonnet/Haiku, file rewrites, frontmatter sweeps). Guidance, not enforcement; ties back to `agent-coordination.md` for swarm dispatch. M3 deferral closed.
+- **`docs/milestones/v1.0-ga.md`** — Canonical v1.0 milestone document. Goal, driving context, the 6 reworded success criteria, 8–10 week appetite, hill chart, per-release feature detail (v0.9.5 → v1.0.0), parallelism analysis, risks register, out-of-scope list, open questions, validation gates per release.
+- **`docs/v1.0-roadmap.md`** — Synthesis of three parallel v1.0 research swarms (current state, unimplemented inventory, market review). Six-release path, capability-family architecture, four moats, four abandon recommendations, eight risks, decisions D1–D7 locked.
+
+### Retargeted
+
+- **`specs/plugin-family-release-hardening.md`** — F-006 (host-neutral kernel) and F-007 (adapter contracts) target moved from `v1.0.0` to `v1.1.0`. Acceptance criteria AC-010/AC-011/AC-012 retagged to `v1.1.0` to match. Per D2 lock in `docs/v1.0-roadmap.md`: full architectural close is M4 work; v0.9.7 will ship Tier 1 substitution-only fix (~80% of leak) for v1.0 GA.
+
+### Maturity criteria reworded
+
+- `.add/config.json:next_promotion_criteria` updated per D1 lock. The 60-day calendar floor — generic, not project-shaped — is replaced by engineering evidence: ≥3 minor/patch releases past v0.9.0 with no post-tag rollback, ≥1 community PR merged during the beta cycle, AC-025 release-evidence bundle generated for the v1.0 candidate. Criterion 6 ("verified in active use") rewords the unmeasurable "20+ projects" claim to maintainer attestation via private signal — adopter naming only with explicit consent. See `docs/v1.0-roadmap.md` § D1 for rationale.
+
 ## [0.9.4] — 2026-04-27
 
 **Hotfix.** Completes the migration chain from v0.8.0 onward. Surfaced when a project at v0.5.0 updated to v0.9.3 and Claude Code reported: _"Plugin manifest covers up to 0.8.0; plugin is now 0.9.3 … no 0.8 → 0.9 hop exists."_ The version field on the consumer's `.add/config.json` was bumping past 0.8.0 without any migration hop being traversed — a silent gap that's harmless today (v0.8 → v0.9.x had no required config-schema changes) but would silently skip future migrations that DO have steps.

CLAUDE.md

@@ -53,8 +53,11 @@ Cut a signed release:
 core/                  # Source of truth (runtime-neutral)
   skills/              #   27 skills — all slash commands
   rules/               #   19 auto-loading behavioral rules
-  templates/           #   21 document templates
-  knowledge/           #   2 Tier-1 knowledge files
+  references/          #   non-autoloaded reference rules (loaded on-demand)
+  templates/           #   23 document templates
+  knowledge/           #   4 Tier-1 knowledge files
+  lib/                 #   shared library functions used by hooks/skills
+  security/            #   security-related artifacts (threat model, redaction)
   schemas/             #   2 JSON Schema validators
   VERSION              #   Canonical version string
 

CONTRIBUTING.md

@@ -17,8 +17,11 @@ That's it. There's nothing to build or install. The plugin is entirely markdown
 core/                   # Source of truth (v0.7+ restructure)
 ├── skills/             # 27 skills — all slash commands (/add:init, /add:spec, /add:tdd-cycle, ...)
 ├── rules/              # 19 auto-loading behavioral rules
-├── templates/          # 21 document templates (PRD, spec, plan, config, etc.)
-├── knowledge/          # 2 Tier-1 knowledge files (global, image-gen-detection)
+├── references/         # Non-autoloaded reference rules (loaded on-demand)
+├── templates/          # 23 document templates (PRD, spec, plan, config, etc.)
+├── knowledge/          # 4 Tier-1 knowledge files (global, image-gen-detection, secret-patterns, threat-model)
+├── lib/                # Shared library functions used by hooks/skills
+├── security/           # Security-related artifacts (threat model, redaction)
 ├── schemas/            # 2 JSON Schema validators (rule + skill frontmatter)
 └── VERSION             # Canonical version string
 

README.md

@@ -3,14 +3,14 @@
 <p align="center">
   <strong>AI agents write code fast. Without structure, they ship chaos.</strong>
   <br>
-  ADD is coordinated agent swarms — test-writers, implementers, reviewers, deployers — that ship verified software as a team. Spec-driven. Test-first. Independently verified. Human-validated.
+  ADD is a methodology for AI-native software development — spec-driven, test-first, independently verified, human-validated — implemented as a Claude Code plugin (with a Codex CLI adapter) that coordinates specialized agent swarms.
   <br>
   <br>
   <a href="https://getadd.dev">Website</a> · <a href="#install">Install</a> · <a href="#quick-start">Quick Start</a> · <a href="#coordinated-agent-teams">Agent Teams</a> · <a href="#human-in-the-loop">Human-in-the-Loop</a> · <a href="#for-product-managers">For PMs</a> · <a href="#cross-project-learning">Learning</a>
   <br>
   <br>
   <a href="https://github.com/MountainUnicorn/add/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
-  <a href="#"><img src="https://img.shields.io/badge/version-0.9.4-brightgreen.svg" alt="Version"></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-0.9.5-brightgreen.svg" alt="Version"></a>
   <a href="#"><img src="https://img.shields.io/badge/Claude_Code-plugin-blueviolet.svg" alt="Claude Code Plugin"></a>
 </p>
 
@@ -449,7 +449,7 @@ Quality gates, deployment skills, and test matrices all adjust based on your tie
 ---
 
 <details>
-<summary><strong>Commands &amp; Skills</strong> — 27 total (v0.9.1)</summary>
+<summary><strong>Commands &amp; Skills</strong> — 27 total</summary>
 
 **Core workflow:**
 
@@ -498,7 +498,7 @@ Quality gates, deployment skills, and test matrices all adjust based on your tie
 </details>
 
 <details>
-<summary><strong>Rules</strong> — 11 auto-loaded behavioral rules</summary>
+<summary><strong>Rules</strong> — 19 auto-loaded behavioral rules</summary>
 
 | Rule | What it enforces |
 |------|-----------------|
@@ -512,7 +512,15 @@ Quality gates, deployment skills, and test matrices all adjust based on your tie
 | `learning` | Automatic checkpoints, knowledge persistence, retro integration |
 | `project-structure` | Standard `.add/` layout, cross-project persistence paths |
 | `maturity-lifecycle` | **Master dial** — governs ALL ADD behavior per maturity level |
+| `maturity-loader` | Loads the per-maturity preset that gates other rules |
 | `design-system` | Silicon Valley Unicorn aesthetic for all generated visuals |
+| `add-compliance` | ADD methodology compliance checks |
+| `cache-discipline` | Marketplace/cache hygiene and stale-cache recovery |
+| `injection-defense` | Prompt-injection defense for untrusted content |
+| `registry-sync` | Keep manifests/registries in sync after edits |
+| `secrets-handling` | Never commit secrets; redaction patterns |
+| `telemetry` | Structured telemetry events from skills/hooks |
+| `version-migration` | Multi-hop version migration ladder |
 
 </details>
 
@@ -554,10 +562,7 @@ Cross-project persistence (machine-local, not committed):
 
 ## Roadmap
 
-- **v0.1.0** — Complete. Core infrastructure — 6 commands, 8 skills, 10 rules, 10 templates.
-- **v0.2.0** — Complete. Branding system, image gen detection, auto-changelog, infographic generation.
-- **v0.4.0** — Next. Adoption & polish — `/add:init --adopt`, enhanced interviews, cross-project sync.
-- **v1.0.0** — Planned. Marketplace ready — CI/CD hooks, advanced learnings, team profiles.
+See [docs/v1.0-roadmap.md](docs/v1.0-roadmap.md) for the current path to v1.0 (GA). Release history lives in [CHANGELOG.md](CHANGELOG.md).
 
 ---
 

core/VERSION

@@ -1 +1 @@
-0.9.4
+0.9.5

core/rules/maturity-loader.md

@@ -38,10 +38,14 @@ A project at `alpha` loads `poc` + `alpha` rules. A project at `beta` loads `poc
 | `quality-gates` | dormant | **active** | active | active |
 | `human-collaboration` | dormant | **active** | active | active |
 | `add-compliance` | dormant | **active** | active | active |
+| `secrets-handling` | dormant | **active** | active | active |
 | `tdd-enforcement` | dormant | dormant | **active** | active |
 | `agent-coordination` | dormant | dormant | **active** | active |
 | `environment-awareness` | dormant | dormant | **active** | active |
 | `maturity-lifecycle` | dormant | dormant | **active** | active |
+| `cache-discipline` | dormant | dormant | **active** | active |
+| `injection-defense` | dormant | dormant | **active** | active |
+| `telemetry` | dormant | dormant | **active** | active |
 | `design-system` | dormant | dormant | dormant | **active** |
 
 ## Agent Instructions
@@ -52,7 +56,7 @@ A project at `alpha` loads `poc` + `alpha` rules. A project at `beta` loads `poc
 2. If a rule's `maturity:` level is ABOVE the project's level, **treat that rule as non-existent** — do not follow its instructions, do not reference it, do not enforce it
 3. If no `.add/config.json` exists, assume `alpha` maturity (reasonable default)
 
-**Example:** A project at `alpha` maturity has 6 active rules (project-structure, learning, source-control, maturity-loader, spec-driven, quality-gates, human-collaboration). The agent should NOT enforce TDD cycles, agent coordination protocols, environment-awareness tiers, or design system rules — those are dormant until the project promotes to beta or ga.
+**Example:** A project at `alpha` maturity loads its 6 poc rules plus 5 alpha rules (spec-driven, quality-gates, human-collaboration, add-compliance, secrets-handling). The agent should NOT enforce TDD cycles, agent coordination protocols, environment-awareness tiers, cache-discipline, injection-defense, telemetry, or design-system rules — those are dormant until the project promotes to beta or ga.
 
 ## Why This Matters
 

core/rules/model-roles.md

@@ -0,0 +1,9 @@
+---
+autoload: true
+maturity: beta
+description: "Architect vs Editor model-role guidance — match agent capability to task shape across `/add:cycle`, `/add:spec`, `/add:plan` and downstream sub-agent dispatches."
+---
+
+# ADD Rule: Architect vs Editor Model Roles
+
+ADD's methodology splits agentic work into two role shapes: the **Architect** — planning, spec authoring, decision walkthroughs, parallelism analysis, retro synthesis — which benefits from a larger reasoning model (Opus / equivalent), e.g. drafting a new milestone doc that weighs D1–D7 trade-offs against six-release sequencing; and the **Editor** — mechanical edits, file rewrites, frontmatter sweeps, formatting, table reflows, generated-output regen — which is Sonnet/Haiku-shaped, e.g. flipping `Status: Draft` to `Status: Complete (v0.9.5)` across nine specs in parallel. This is **guidance, not enforcement**: ADD does not prescribe a model per skill, and any model can perform either role. But when a user dispatches `/add:cycle`, `/add:spec`, `/add:plan`, or a swarm of editor-style sub-agents, picking the role-appropriate model materially affects cost, latency, and output quality — and the swarm-orchestration pattern in `rules/agent-coordination.md` is most effective when an Architect orchestrator delegates Editor-shaped work to parallel Sonnet sub-agents rather than running every dispatch on the largest available model.

core/templates/migrations.json

@@ -1,6 +1,6 @@
 {
   "schema_version": "1.0.0",
-  "plugin_version": "0.9.4",
+  "plugin_version": "0.9.5",
   "migrations": [
     {
       "from": "0.1.0",
@@ -242,6 +242,12 @@
       "to": "0.9.4",
       "steps": [],
       "description": "v0.9.4 hotfix \u2014 completes the migration chain from v0.8.0 onward. Adds the missing hops 0.8.0 \u2192 0.8.1 \u2192 0.9.0 \u2192 0.9.1 \u2192 0.9.2 \u2192 0.9.3 plus the 0.8.0 \u2192 0.9.3 skip hop, so projects that updated the plugin without traversing each intermediate release reach 0.9.3 cleanly. No consumer config changes."
+    },
+    {
+      "from": "0.9.4",
+      "to": "0.9.5",
+      "steps": [],
+      "description": "v0.9.5 hygiene \u2014 doc-only truth pass before the v1.0 credibility cycle. Spec/plan frontmatter flipped from Draft/Implementing to Complete for already-shipped work; PRD reframed to reference docs/milestones/v1.0-ga.md and docs/v1.0-roadmap.md as canonical v1.0 sources; maturity-loader cascade matrix completed for the four v0.9.0 rules (cache-discipline, injection-defense, secrets-handling, telemetry); plugin-family-release-hardening F-006/F-007 retargeted to v1.1.0 (architectural, post-GA). New core/rules/model-roles.md adds Architect/Editor guidance. No consumer config changes."
     }
   ]
 }