docs: refresh AGENTS.md + PLAN.md; codify test-floor, full-suite-gate, and baseline-before-closeout lessons

AGENTS.md

@@ -5,7 +5,7 @@
 This is **claude-mods** - a collection of custom extensions for Claude Code:
 - **3 expert agents** for pure context-isolation/worker roles (git-agent, firecrawl-expert, project-organizer) - every domain-knowledge agent became an `-ops` skill (v3.0, skills-first)
 - **3 commands** for session management and git orchestration (/sync, /save, /git-ops)
-- **102 skills** for CLI tools, patterns, workflows, and development tasks (incl. `parallel-ops` for routing across the parallel/recurring-agent-work skill family, `fleetflow` for heterogeneous GLM/Codex/Anthropic worker fleets, `repo-doctor` for agentic-quality repo audits, `svg-brand-tint-ops` for zero-dep in-browser SVG brand-recolour + Potrace-stage raster vectorising, `r-ops` for tidyverse-first modern R / data analysis, `loop-ops` for outer-loop design discipline, `ffmpeg-ops` for probe-first media processing and EDL-driven editing, `supply-chain-defense` for behavioural-first dependency security, `prompt-injection-defense` for instruction-integrity scanning, `pypi-ops` for OIDC Trusted Publishing to PyPI, `net-ops` for network troubleshooting, `windows-ops` / `mac-ops` for workstation diagnostics, `fleet-worker` for cheap parallel worker delegation)
+- **102 skills** for CLI tools, patterns, workflows, and development tasks (incl. `parallel-ops` as the router for the parallel/recurring-agent-work family — fleet-ops, fleet-worker, fleetflow, loop-ops, iterate, spawn — read it first when that family is ambiguous; `fleetflow` for heterogeneous GLM/Codex/Anthropic worker fleets; `repo-doctor` for agentic-quality repo audits; `svg-brand-tint-ops` for zero-dep in-browser SVG brand-recolour + Potrace-stage raster vectorising; `r-ops` for tidyverse-first modern R / data analysis; `loop-ops` for outer-loop design discipline; `ffmpeg-ops` for probe-first media processing and EDL-driven editing; `supply-chain-defense` for behavioural-first dependency security; `prompt-injection-defense` for instruction-integrity scanning; `pypi-ops` for OIDC Trusted Publishing to PyPI; `net-ops` for network troubleshooting; `windows-ops` / `mac-ops` for workstation diagnostics; `fleet-worker` for cheap parallel worker delegation)
 - **13 output styles** for response personality (Vesper, Spartan, Mentor, Executive, Pair, Atlas, Coach, Harbour, Meridian, Noir, Roast, Sage, Scout)
 - **13 hooks** for pre-commit linting, post-edit formatting, dangerous command warnings, uv enforcement, dependency-install + manifest-edit supply-chain advisories, hidden-Unicode scanning (session-start + pre-commit), live config-change + worktree guards, mid-session peer-writer guard + touched-files ledger, and pmail notifications - security set auto-wired via plugin hooks.json
 - **Pigeon** inter-session messaging (`pigeon send/read/reply`) - SQLite-backed pmail at `~/.claude/pmail.db`
@@ -60,6 +60,10 @@ On "INIT:" message at session start:
 | `skills/auto-skill/` | Auto-detect skill-worthy workflows; Stop hook suggests after complex sessions. `/auto-skill on/off/status` to toggle |
 | `skills/supply-chain-defense/` | Behavioural-first dependency security - Socket.dev depscore MCP, exposure-check (IOC match across npm/pnpm/yarn/bun/PyPI/Composer/Cargo/Go/RubyGems + extensions), integrity-audit (persistence), scan-extensions, install/manifest hooks. Paired with `rules/supply-chain.md` |
 | `skills/repo-doctor/` | Agentic-quality auditor - scores any repo (entry docs, comments, structure, gates, doc-pairing) with --json + --strict CI gate; monorepo-structure + comment-doctrine references. Paired with `rules/agentic-quality.md` |
+| `skills/parallel-ops/` | Router for the parallel/recurring-agent-work family (fleet-ops, fleet-worker, fleetflow, loop-ops, iterate, spawn) - read first when it's unclear which one owns a fan-out/schedule/delegation ask |
+| `skills/fleetflow/` | Heterogeneous GLM/Codex/Anthropic worker fleets from one session; escape guard + baseline-before-closeout discipline documented in-skill |
+| `tests/validate.sh` | Frontmatter + naming gate; enforces the description-budget cap (combined description+when_to_use, hard-fails over budget) |
+| `tests/doc-drift.sh` | Counts-on-disk vs docs gate; also checks section-map markers and skill-frontmatter ghost references (related-skills/depends-on naming a skill not on disk) |
 
 ## Quick Reference
 
@@ -96,6 +100,27 @@ On "INIT:" message at session start:
 
 Requires Sonnet 4+ or Opus 4+.
 
+## Landmines
+
+- **A skill's own test suite can assert on its own frontmatter shape** (e.g.
+  `r-ops/tests/run.sh` requires `when_to_use:` to exist). A trim/edit pass
+  touching only the SKILL.md body can still break CI if it drops a field a
+  sibling suite polices — read the skill's `tests/run.sh` before removing any
+  frontmatter field, not just the SKILL.md itself.
+- **The landing gate must run the FULL per-skill suite sweep** (`skills/*/tests/run.sh`,
+  all of them), never just the touched lanes' — suites assert on shared/sibling
+  files, so a change in one skill can silently break another's gate.
+- **Executable bit on commit**: scripts under `skills/*/scripts/` and `hooks/*.sh`
+  must be tracked `100755`. Git on Windows won't set this for you — `tests/check-exec-bits.sh`
+  gates it; a script that "works locally" but fails `bash foo.sh` for another
+  contributor is almost always a missing exec bit, not a logic bug.
+- **Coupled golden fixtures**: some skill tests compare output against a fixture
+  file colocated in the same `tests/` dir — editing the skill's output format
+  without regenerating the fixture is a silent, not loud, break (diff the fixture,
+  don't just eyeball the code change).
+- Never touch `.claude/worktrees/` or any repo's git worktree state (see
+  `rules/worktree-boundaries.md`) — it looks orphaned and isn't.
+
 ## Testing
 
 ```bash

docs/PLAN.md

@@ -3,7 +3,7 @@
 **Goal**: A centralized repository of custom Claude Code commands, agents, and skills that enhance Claude Code's native capabilities with persistent session state, specialized expert agents, and streamlined workflows.
 
 **Created**: 2025-11-27
-**Last Updated**: 2026-07-05
+**Last Updated**: 2026-07-09
 **Status**: Active Development
 
 > Historical record of what shipped lives in [CHANGELOG.md](../CHANGELOG.md) and the
@@ -39,7 +39,7 @@ One line per canonical doc; update in the same commit as any docs/ change.
 | [RESERVED-COMMANDS.md](RESERVED-COMMANDS.md) | Command names that collide with Claude Code built-ins |
 | [AUTO-MODE-CLASSIFIER.md](AUTO-MODE-CLASSIFIER.md) | The two-gate auto-mode permission model behind loop-engineering |
 
-Subdirs: `archive/` (completed-migration records, retired) · `references/` (vendored guides).
+Subdirs: `archive/` (completed-migration records, retired) · `references/` (vendored guides) · `plans/` (dated build specs for named execution waves, e.g. QUALITY-2026-07.md).
 
 ---
 
@@ -81,6 +81,31 @@ Subdirs: `archive/` (completed-migration records, retired) · `references/` (ven
       scrub, revert) on top of native agent teams / background agents; new
       `fleet track` registers natively-spawned branches
 
+### Phase 4 — Fleetflow quality wave (2026-07)
+
+Full build spec: [docs/plans/QUALITY-2026-07.md](plans/QUALITY-2026-07.md).
+Theme: subtraction and enforcement, not addition.
+
+- [x] Phase 0 — closed the loop (README count fixes, plan committed, CI green)
+- [x] Phase 1 — enforcement gates: description-budget gate (700 hard cap),
+      section-map drift gates (summon, svg-brand-tint-ops), doc-drift
+      extensions (prose counts, frontmatter ghost refs), repo-doctor
+      guard-comment recognition, hook wiring on script installs
+- [x] Phase 2 — consolidation: `parallel-ops` router shipped, 22-skill
+      description trim, portability sanitization (process-compose-ops,
+      portless-ops, shell-preference.md), dsp-launch retirement,
+      description-budget gate flipped WARN→FAIL
+- [ ] Phase 3 — robustness floor: push-gate test suite, verifier-wrap suites,
+      security-sensitive suites (security-ops, pigeon, leveldb-ops),
+      remaining test backlog, protocol backfill on 2025-12-21 scaffold batch
+      (R6 within Phase 3 is done — see below)
+- [x] R6 — docs truth pass: AGENTS.md refresh, this inventory update,
+      test-floor policy in SKILL-CREATION-PROTOCOL.md, full-suite-gate note
+      in fleet-ops, baseline-before-closeout note in fleetflow
+- [ ] Deferred follow-ons — skill-telemetry, marketplace submission,
+      claude-mods-local formalization, push-cadence advisory (wave's Phase 4,
+      not this repo's Phase 4 heading)
+
 ---
 
 ## Open Questions

docs/SKILL-CREATION-PROTOCOL.md

@@ -89,6 +89,20 @@ Add `tests/run.sh` — an **offline, self-contained** behavioural suite that exi
 on any failure and prints a skip message (exit 0) on unsupported platforms. Pattern after
 [`skills/supply-chain-defense/tests/run.sh`](../skills/supply-chain-defense/tests/run.sh).
 
+**Test floor (non-negotiable):** every NEW skill ships **at least one** smoke assertion
+in `tests/run.sh` — structure/frontmatter checks alone (already required by Step 6's
+gate) don't count. If nothing else, assert the skill's primary script runs and exits 0
+on its documented happy path.
+
+**If your suite asserts on the skill's own frontmatter shape** (e.g. requiring
+`when_to_use:` to exist, or a specific `metadata` key), **say so in a comment right next
+to that assertion**. A later trim/cleanup lane edits SKILL.md bodies and frontmatter
+without necessarily reading every skill's test suite — an unstated contract is what let
+a 2026-07 description-trim pass delete `r-ops`'s `when_to_use` field and break CI, because
+the field's own suite required it and nothing at the edit site said so (fixed in
+17c8a3a). The comment is the fix: state the contract where the assertion lives, not just
+in the trim commit that later re-discovers it.
+
 No registration needed: [`tests/run-skill-tests.sh`](../tests/run-skill-tests.sh) globs
 `skills/*/tests/run.sh` and runs them all in CI. If the skill ships a verifier script,
 also add an offline-mode assertion to [`tests/check-resources.sh`](../tests/check-resources.sh)

skills/fleet-ops/SKILL.md

@@ -74,7 +74,7 @@ N > 1 on one shared working tree           → REFUSE. Worktrees or separate clo
 1. **Scrub** — `git diff main...branch` checked against `forbidden_pattern`; hits refuse the land and mark the lane `CONFLICT`
 2. **Clean-base check** — refuses if `main` has uncommitted tracked changes
 3. **Merge** — `--no-ff` with message `merge: <branch>` (this message is what `fleet revert` finds later)
-4. **Test gate** — runs `test_cmd` if set; on failure, hard-resets the merge and marks the lane `FAILED`. If unset, trusts `signal.sh`'s log gate (refused READY on failing logs)
+4. **Test gate** — runs `test_cmd` if set; on failure, hard-resets the merge and marks the lane `FAILED`. If unset, trusts `signal.sh`'s log gate (refused READY on failing logs). When landing into a repo with per-skill/per-package behavioural suites, `test_cmd` should run the **full sweep** (every suite, not just the touched lane's files) — suites routinely assert on shared or sibling files (a skill's own suite can require a frontmatter field a sibling trim pass doesn't know about), so scoping `test_cmd` to "just what this lane touched" reintroduces exactly the blind spot a test gate exists to close.
 5. **Rebase others** — every still-active lane is rebased onto the new `main` (in its own worktree if it has one); a rebase conflict marks that lane `CONFLICT`
 
 `fleet revert <branch>` finds the `merge: <branch>` commit on `main` and runs `git revert -m 1` — one command to back out a bad landing.

skills/fleetflow/SKILL.md

@@ -223,6 +223,14 @@ default the script-author follows, not an option — and real runs routinely hit
   both defaults: the guard preamble's *relative-paths-only* clause, and
   `ff-collect.sh --check-main-clean` after every run (exit 12 = escape
   detected; stop, `git stash push -u` to salvage, investigate).
+- **Baseline-before-closeout (learned 2026-07-08, exit 12 false positive):**
+  `--check-main-clean` compares `main` against whatever it was when the check
+  runs — if the orchestrator makes its own edits to `main` (docs, PLAN.md,
+  closeout commits) between spawning lanes and running the check, those
+  self-made edits look identical to an escaped worker's writes. Snapshot a
+  clean-`main` baseline (`git status --short` / a commit sha) **before** any
+  orchestrator-authored closeout edit, so the check compares against the
+  pre-spawn state, not a moving target the orchestrator itself just moved.
 - **Permission posture:** workers run non-interactive
   (`bypassPermissions` default; `FLEETFLOW_PERMISSION_MODE=dontAsk` + allowlist
   when the orchestrator session is in auto mode — a `bypassPermissions` child