Merge pull request #20 from MountainUnicorn/wave3-v097

v0.9.7 — methodology reframe: swarm-over-Workflows, maturity-led README, skill self-scan

Author: MountainUnicorn

.add/config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "https://github.com/MountainUnicorn/add/config.schema.json",
-  "version": "0.9.6",
+  "version": "0.9.7",
   "project": {
     "name": "ADD",
     "description": "Agent Driven Development \u2014 Claude Code plugin implementing an AI-native SDLC methodology",

.add/handoff.md

@@ -1,51 +1,43 @@
 # Handoff — v1.0 GA wave execution (2026-06-14)
 
-## Where things stand
-Branch **`wave-exec-v096`** (off `main` @ 0896bc0). The **v0.9.6 batch (Waves 0–2) is complete and fully verified** — 9 commits, 35 files, all 15 fixture suites green, `compile --check` clean. Not pushed; no release cut (those are human/keychain-gated).
-
-Executed under ADD's own SDLC: RED-first tests where applicable, an **independent verifier agent** + an **agent-to-agent retro** per wave, learnings captured to `.add/learnings.json` (L-035…L-046).
-
-## Done
-
-### Wave 0 — unblock `main` (P0)
-- **C1**: rule count was 19, reality 20 → guardrails red. Made the count **compile-derived** (`{{RULE_COUNT}}` in `runtimes/claude/CLAUDE.md`, filled from the autoload-filtered set in `compile.py`). Strengthened `rule-parity` to read the compiled artifact + assert all prose surfaces (CLAUDE.md/README.md/CONTRIBUTING.md). Now 9/9.
-- **C3**: bumped `checkout v4→v5`, `setup-python v5→v6`, `github-script v7→v8` across all 4 workflows (Node-20 deprecation).
-- Verifier caught 3 missed surfaces + a semantic bug ({{RULE_COUNT}} counted all files, not autoload) — all fixed before commit.
-
-### Wave 1 — release tooling (P0)
-- **C2 / #18**: `release.sh` could exit 0 without publishing. Added array-based gh flags + a post-create `gh release view` assertion that fails loud with a recovery command. Behavioral regression test (mock git/gh/python3) — **mutation-verified** to go red when the fix is reverted.
-
-### Wave 2 — v0.9.6 truth-pass
-- **C5**: CONTRIBUTING "three checks"→four; documented community-PR strategy.
-- **D1**: `model-roles.md` capability-tier table (Opus 4.8/Sonnet 4.6/Haiku 4.5; gpt-5.5/gpt-5.x-codex).
-- **B3**: added missing Codex `verify` sub-agent (`verify.toml` + 2 compile.py enums + test). 5 agents now; codex suite 58/58.
-- **D3 (P0/1)** — found a real **security bug**: the `unicode-tag-block` regex was a broken byte-class matching ~any multibyte UTF-8 (652/652 sampled events were benign false positives, 0 real attacks). Replaced with a precise `(?:\xF3\xA0[\x80\x81][\x80-\xBF]){3,}` — verifier independently confirmed it covers all 128 tag codepoints and rejects benign chars; AC-028 real attack still fires. Switched the JSONL audit writer to `jq -cn` (atomic single-line). Gitignored + untracked `.add/security/`. Documented the audit trail in SECURITY.md. Added a **mutation-verified** benign-multibyte regression fixture.
-
-## Next: the boundary
-
-### Wave 3 (v0.9.7 methodology) — NEEDS HUMAN DIRECTION before auto-execution
-These are subjective positioning/voice decisions, not mechanical:
-- **A1** swarm-protocol → layer over native Workflows (the strategic reframe — wording matters; affects ADD's market story).
-- **A3** swarm-state machine-readable format contract (small, do first — A1 depends on it).
-- **C4** GA launch plan / `/add:announce` (marketing strategy; partly the separate `getadd.dev` repo).
-- **D4** lead README with the maturity ladder (positioning/voice).
-- **A2** `core/workflows/` scaffolding (spec+infra only pre-GA; Claude-specific — needs a home that compile-drift tolerates).
-- **D3 P2** skill self-scan + CI gate.
-
-### Wave 4 (v0.10) — automatable later
-A3 panel impl; **B4** F-012 spike (now consumes the fixed regex/writer from D3); D3 self-scan CI enforcement.
-
-### Wave 5 (v0.11) — BLOCKED on a live spike
-Unified **B1+B2** Codex re-baseline is gated on **Q-001**: a live spike against the current Codex CLI (the 0.122 pin is stale). Can't be done without running the real CLI.
-
-### GA tag — externally/human gated (cannot be automated)
-- Anthropic marketplace approval (filed 2026-02-14, status unknown — external).
-- 60-day beta calendar gate (earliest honest tag ~2026-06-22).
-- A real GPG-signed release cut (keychain/pinentry — interactive).
-- ADD's own `beta→ga` self-promotion + release-evidence bundle (currently unowned per cohesion review).
-
-## Acceptance test for Wave 1 (do this at the real v0.9.6 cut)
-Judge success from the new `published and verified` line + a manual `gh release view` — **not** from exit 0 (the habit being retired). See L-042.
-
-## Suggested follow-up rule (from Wave 1 retro, L-039)
-"Verify the side effect, never trust the exit code" is now a twice-proven bug class (F-001 + #18). Worth encoding as a rule near `core/rules/quality-gates.md`.
+## Shipped this session
+- **v0.9.6 RELEASED** (signed, verified, on the marketplace cache). Waves 0–2:
+  CI unblocked (rule count compile-derived; Node-24 actions), release.sh #18
+  fixed (verified live — "published and verified"), truth-pass, and a real
+  injection-defense regex fix. PR #19 merged to `main`.
+- **Wave 3 (v0.9.7) — done on branch `wave3-v097`, NOT yet pushed/released:**
+  - A3 — swarm-state machine-readable format contract.
+  - D3-P2 — skill self-scan CI gate (`scripts/self-scan-skills.py` + `skill-self-scan`
+    guardrail + SECURITY.md trust signal). Verifier caught a real hole (a `(?m)`
+    pattern was silently never gating); fixed + mutation-guarded
+    (`tests/security/test-self-scan.sh`).
+  - A2 — `runtimes/claude/workflows/` scaffold + `specs/workflow-lifecycle-scripts.md`
+    (inert; zero behavior change).
+  - A1 — swarm-protocol + agent-coordination reframed as policy-over-native-Workflows
+    (manual fallback retained; WIP semantics invariant; emission deferred to v1.1).
+  - D4 — README now leads with the maturity ladder ("One dial scales the rigor").
+- **GA-gate decision (overrides roadmap D7):** the arbitrary 60-day beta floor is
+  dropped; v1.0 gates on **Anthropic marketplace approval** + the substantive
+  criteria. Recorded in v1.0-roadmap.md and milestones/v1.0-ga.md.
+
+## State
+- Every wave: independent verifier + agent-to-agent retro; learnings L-035…L-049.
+- All 16 fixture suites green; `compile --check` clean; self-scan clean.
+- `wave3-v097` is 6 commits ahead of `main`, local only.
+
+## Open / next
+1. **Wave 3 release:** push `wave3-v097`, open a PR, then version-bump to v0.9.7
+   (VERSION, CHANGELOG, migrations hop, README badge) and cut the release — same
+   flow as v0.9.6.
+2. **C4 launch plan** is preserved as a tracked doc (`docs/wave3-drafts/C4-launch-plan.md`)
+   but NOT applied — `/add:announce` skill not built yet; pending a decision on
+   one-skill-with-`--target` vs two, and the brand strategy.
+3. **A1/A2 emission** (actual Workflow descriptor scripts) deferred to v1.1.
+4. **Waves 4–5** (v0.10/v0.11): B4 F-012 spike now consumes the fixed
+   regex/writer; B1+B2 Codex re-baseline still needs the live Q-001 CLI spike.
+5. **GA tag:** gated on marketplace approval (filed 2026-02-14) + install smoke +
+   release-evidence bundle + ADD's own beta→ga self-promotion.
+
+## Acceptance test reminder (release tooling)
+Judge any release by the `published and verified` line + a manual `gh release
+view`, never bare exit 0 (L-042). v0.9.6 passed this live.

.add/learnings.json

@@ -604,6 +604,45 @@
       "date": "2026-06-14",
       "classified_by": "agent",
       "checkpoint_type": "retro"
+    },
+    {
+      "id": "L-047",
+      "title": "A security self-scan can have the exact bug it exists to catch \u2014 validate the detector, not just the content",
+      "body": "ADD's new skill self-scan (D3-P2) shipped with a (?m)-prefixed pattern handed to grep -E, which rejects it as invalid (rc=2); file_matches treated rc=2 as 'no match', so the most common documented payload (new-instructions-heading, HIGH) silently never gated \u2014 the precise 'check that doesn't check' failure the scan exists to prevent. Independent verification caught it post-commit (my own probe happened to use a casing that masked it). Fix: validate every pattern is live at startup and WARN loudly if grep rejects it; mutation-test that the gate fires on EACH engine path (ERE, (?m), byte-mode). Reinforces L-039/L-040/L-041.",
+      "scope": "project",
+      "stack": [],
+      "category": "security",
+      "severity": "high",
+      "source": "ADD",
+      "date": "2026-06-14",
+      "classified_by": "agent",
+      "checkpoint_type": "retro"
+    },
+    {
+      "id": "L-048",
+      "title": "Whole-file allowlists in a security scan are blind spots; over-broad ones manufacture risk",
+      "body": "The self-scan's first allowlist exempted 5 whole files \u2014 but 3 tripped nothing (pure blind spots) and the 2 real ones were auto-loaded behavioral content, so a critical payload planted in them would be BOTH invisible to the gate and injected into the agent. Fix: precise per-(file,pattern) waivers derived from a no-waiver scan, waiving only the exact patterns a file legitimately documents. An allowlist entry that waives more than what actually fires is a latent hole.",
+      "scope": "project",
+      "stack": [],
+      "category": "security",
+      "severity": "high",
+      "source": "ADD",
+      "date": "2026-06-14",
+      "classified_by": "agent",
+      "checkpoint_type": "retro"
+    },
+    {
+      "id": "L-049",
+      "title": "Independent per-wave verification catches what implementer self-testing structurally cannot",
+      "body": "Across all waves the fresh adversarial verifier found real defects the implementer's own green tests missed: Wave 1's false-confidence string-match test, Wave 2's missing negative regression fixture, Wave 3's silently-disabled (?m) pattern. The implementer tests what they thought to test; the verifier tests the documented/boundary cases and reasons structurally. Keep the separate-verifier-per-wave discipline \u2014 it is not ceremony, it pays out every time.",
+      "scope": "project",
+      "stack": [],
+      "category": "process",
+      "severity": "medium",
+      "source": "ADD",
+      "date": "2026-06-14",
+      "classified_by": "agent",
+      "checkpoint_type": "retro"
     }
   ]
 }

.github/workflows/guardrails.yml

@@ -57,6 +57,16 @@ jobs:
           python-version: '3.12'
       - run: python3 scripts/validate-secret-patterns.py
 
+  skill-self-scan:
+    name: Skill self-scan (ADD's own artifacts vs its injection patterns)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v5
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+      - run: python3 scripts/self-scan-skills.py
+
   # ---------- Fixture-based suites (bash + jq, no external tools) -------------
 
   fixtures:
@@ -78,6 +88,7 @@ jobs:
           - rule-parity/test-rule-parity.sh
           - jq-dependency/test-jq-claim-qualified.sh
           - release-tooling/test-release-verify.sh
+          - security/test-self-scan.sh
     steps:
       - uses: actions/checkout@v5
       - name: Install jq

CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to ADD are documented here. Format loosely follows [Keep a C
 
 For commit-level detail see `git log`.
 
+## [0.9.7] — 2026-06-18
+
+Methodology reframe + a security trust signal. Positions ADD as the policy layer over native orchestration, leads with the maturity-ladder moat, and dogfoods the injection defense.
+
+### Changed
+
+- **Swarm protocol reframed as policy over native Workflows.** `core/references/swarm-protocol.md` and `core/rules/agent-coordination.md` now draw a clear policy/mechanism line: ADD owns the *policy* (maturity-aware WIP/concurrency, conflict assessment, role briefs, merge ordering, trust-but-verify gates, swarm-state), and delegates the orchestration *mechanism* (parallel dispatch, worktree isolation, step schemas, budgets) to the runtime — native Claude Dynamic Workflows / Codex TOML sub-agents — with the manual recipes retained as the fallback. Positioning: "ADD configures native orchestration with maturity-aware policy," not "ADD re-implements orchestration." WIP semantics (poc=1…ga=5) and trust-but-verify are invariant; actual Workflow-descriptor emission is deferred to v1.1.
+- **README leads with the maturity ladder.** The hero is now the poc→alpha→beta→ga trust-gradient dial ("One dial scales the rigor") — the moat host runtimes haven't absorbed — with the prior framing kept as a secondary line.
+
+### Added
+
+- **Skill self-scan (`scripts/self-scan-skills.py`).** Runs ADD's distributed injection patterns (`core/security/patterns.json`) against ADD's own shipped artifacts on every CI run (the `skill-self-scan` guardrail), using the same detection engine as the runtime hook. Fails the build on any un-waived `critical`/`high` match and surfaces malformed patterns loudly so a pattern can't silently stop gating. Documented as a trust signal in SECURITY.md; guarded by `tests/security/test-self-scan.sh` (mutation-verified).
+- **Swarm-state format contract.** A machine-readable contract for `.add/swarm-state.md` (entry delimiter, field table, status enum, forward-compatible parsing) so humans, the orchestrator, and native-Workflow state all parse it the same way.
+- **`runtimes/claude/workflows/` scaffold** + `specs/workflow-lifecycle-scripts.md` (Draft) — the planned home for native Workflow lifecycle scripts. Inert in v0.9.7 (zero behavior change); pilot lands in v1.1.
+
+### Changed (project governance)
+
+- **GA gate updated:** the arbitrary 60-day beta calendar floor is dropped; v1.0 now gates on Anthropic marketplace approval plus the substantive promotion criteria (roadmap D7 override). See `docs/v1.0-roadmap.md` and `docs/milestones/v1.0-ga.md`.
+
 ## [0.9.6] — 2026-06-14
 
 CI/release hardening + truth-pass, opening the v1.0 credibility cycle. Turns a red `main` green, makes the release tool trustworthy, and fixes a real injection-defense bug surfaced during the pass.

README.md

@@ -1,21 +1,39 @@
 <h1 align="center">ADD — Agent Driven Development</h1>
 
 <p align="center">
-  <strong>AI agents write code fast. Without structure, they ship chaos.</strong>
+  <strong>One dial scales the rigor. Trust your agents as much as your project has earned.</strong>
   <br>
-  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.
+  ADD is a methodology for AI-native software development built around a single control: the <strong>maturity ladder</strong> (poc → alpha → beta → ga). The ladder governs everything — how deep your specs go, whether TDD is enforced, how many agents run in parallel, which quality gates block. A throwaway prototype gets near-zero ceremony; production infrastructure gets exhaustive verification. You turn one dial; ADD cascades the rest.
   <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>
+  <em>AI agents write code fast. Without structure, they ship chaos.</em> ADD brings the structure — spec-driven, test-first, independently verified, human-validated — implemented as a Claude Code plugin (with a Codex CLI adapter).
+  <br>
+  <br>
+  <a href="https://getadd.dev">Website</a> · <a href="#the-maturity-ladder--one-dial-for-the-trust-gradient">Maturity Ladder</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.6-brightgreen.svg" alt="Version"></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-0.9.7-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>
 
 ---
 
+## The Maturity Ladder — one dial for the trust gradient
+
+Autonomous agents need a trust gradient: how much you let them do should scale with how much your project has earned. ADD makes that gradient the master control. Every project declares a maturity level, and that level cascades to **every** process decision — no per-rule debates, just one dial.
+
+| Stage | What it means | What ADD does |
+|-------|---------------|---------------|
+| **POC**   | Validate an idea. Learning > completeness.       | Paragraph PRD. Optional specs/TDD. Pre-commit gate only. 1 agent, serial. |
+| **Alpha** | Building toward MVP. Surviving first real usage. | 1-page PRD. Critical-path specs + TDD. Adds CI gate. Up to 2 agents. |
+| **Beta**  | Broader audience. Stabilize, reduce defects.     | Full PRD. All specs required, strict TDD. Adds pre-deploy gate. 2–4 agents. |
+| **GA**    | Production-grade, long-term support.             | Full PRD + architecture. Exhaustive ACs. All 5 gates blocking. 3–5 agents via worktrees. |
+
+Promotion is **deliberate, not automatic** — `/add:promote --check` runs an evidence-based gap analysis (specs, coverage, CI, branch protection) and tells you exactly what's missing before you level up. You don't graduate to GA by wishing; you graduate when the evidence says you're ready.
+
+> This is the trust-gradient problem the 2026 agentic-coding discourse names as the central challenge of autonomous development — and ADD shipped an implementation of it.
+
 ## The Problem
 
 AI code generation has changed how software gets built, but development practices haven't kept up. Developers and agents operate without structure, leading to specification drift, unpredictable quality, lost knowledge, and unclear handoffs.
@@ -24,11 +42,11 @@ AI code generation has changed how software gets built, but development practice
 
 ## What is Agent Driven Development?
 
-**TDD** gave us tests before code. **BDD** gave us behavior before tests. **ADD** gives us *coordinated agent teams before everything*.
+**TDD** gave us tests before code. **BDD** gave us behavior before tests. **ADD** gives us *maturity-governed agent teams* — process rigor that scales with the trust your project has earned.
 
 ADD is a structured SDLC methodology where AI agents do the development work — writing tests, implementing features, reviewing code, deploying — while humans architect, decide, and verify the user experience. It's not a tool. It's a way of working.
 
-**The six principles:**
+**Maturity governs everything** — one dial (poc → alpha → beta → ga) scales all process rigor. On top of that master control, six principles:
 
 1. **Specs before code** — Every feature starts as a specification. No spec, no code.
 2. **Tests before implementation** — Strict TDD: RED → GREEN → REFACTOR → VERIFY.