docs: generalize the maintenance-routine pattern — ADR 0010, eight phase issues, slice pruned

[kyle-sexton]

No linked issue

Summary

Answers "what can we do with the maintenance-routine pattern" for this marketplace, and lands the answer as durable artifacts rather than a document. Eight research lanes and three verification passes ran to completion; this PR graduates what they settled and prunes the working slice.

The research inverted the original framing three times, and the plan encodes the inverted shape:

1. The apply machinery already exists and is reachable by file format alone. What is missing, class after class, is a detector to feed it. Validated empirically, not inferred: a hand-written conforming file from a non-fanout producer passed the fix action's locator, frontmatter gate, exact-branch check, and table parse.
2. Merge rate cannot justify any of this. Peer-reviewed observational work, a large-N regression, and a randomized trial all find artifact quality weakly-to-not coupled to acceptance. The verification contract is justified on defect escape and reviewer burden, never acceptance. Nothing here cites the source's 388/180 figures as evidence of efficacy — a single self-report with no independent corroboration and no published methodology.
3. Class-level beats instance-level. Three lanes converged from different literatures: durable wins come from policy and mechanism, not from better per-instance agent judgement.

Fix

ADR 0010 — merge findings across producers, and mark consumption explicitly. The correctness gate the whole effort turns on. review:fanout's fix action consumes exactly one findings file and merges nothing (context/fix-pass-mode.md:3,7), which is safe only while fanout is the sole producer. The first detector of any kind makes producer #2, at which point the later timestamp silently wins and the earlier producer's findings are never applied — no error, no warning, run reports success. Three decisions, each with a rejected alternative that had a real case:

• The consumer merges the conforming set instead of picking the newest, and unions the coverage fields rather than reporting one producer's.
• Cross-producer dedup is presence-only. The existing ±3-line key sits behind a Sonnet semantic stage the fix action does not have, and adopting the bucket without the semantics would invert the pipeline's own minimise-false-merge rule and silently discard a remediation.
• The applied-plan record becomes a consumption ledger written on every apply path. It is currently written only under --yes in a non-interactive session, so any bound anchored on it is a no-op on the path most runs take.

Eight phase issues, each carrying its own ADR-0004 incumbent evidence inlined as path:line — deliberately not a pointer into the gitignored .work/ tree, which no delegated worker, fresh session, or second machine can read:

Issue	Phase
#2678	feat(review): merge findings across producers (implements ADR 0010)
#2679	docs(conventions): detector-findings owner doc (stub)
#2680	feat(mutation-testing): persist survivors as a conforming findings file
#2681	docs(conventions): harden detector-findings with the rule-id to severity crosswalk
#2682	feat(autonomy): catalog rows for every routine class considered
#2683	feat(autonomy): reviewer-burden promotion term, recorded as deferred
#2684	feat(testing): can't-fail test audit plus fail-closed --check mode
#2685	spike: per-repo routine capability detection, promoted to its own topic

The contract slice is pruned in this PR's final commit, per docs/conventions/topic-docs/README.md:43. Recover the full PLAN.md and the design resolution from the commit before the prune:

git show 5341117c:docs/topics/boris-routines-adoption/PLAN.md
git show 5341117c:docs/topics/boris-routines-adoption/design/design-resolution.md

Verification

• bash scripts/check-contract-slice-prune.sh --check-diff origin/main — exits 1 before the prune commit (it named both slice paths), exits 0 after. That transition is the point of the final commit.
• npx markdownlint-cli2 — 0 issues across ADR 0010, PLAN.md, and design-resolution.md.
• Per-phase sanity-check invariant, measured rather than asserted: awk '/^### Phase [0-9]/{p=$0;c[p]=0} /Sanity Check/{if(p!="")c[p]++} END{for (k in c) if (c[k]==0) print k}' printed nothing — all ten numbered phases carried at least one mechanically verifiable check.
• Two independent fresh-context review passes ran against the plan with the authoring rationale withheld: an adversarial pass (2 CRITICAL, 8 HIGH) and a mechanics pass (1 CRITICAL, 7 IMPORTANT). Every finding acted on was re-verified against the file before the plan was changed. Details in the collapsed section below.

What the review passes caught

Both CRITICALs from the adversarial pass landed on the coexistence design and both held:

• The staleness bound could not exist on the path the plan runs. fix-pass-mode.md:76 — "Interactive and headless-stop paths write no record". The solo shape is the interactive path, so the merge set would have grown without limit, re-injecting findings that :95's required post-fix re-review had already resolved. The draft would have regressed a documented loop while claiming to close a correctness gate.
• The dedup key was not mechanically available. findings-normalization.md:77 places dedup at "Stage 3 Sonnet (semantic merge)"; :66 orders "Minimize FALSE-MERGE over FALSE-SPLIT — a false merge silently drops a real issue". The fix action runs no LLM stage.

The mechanics pass then executed rather than argued its CRITICAL: check-contract-slice-prune.sh --check-diff origin/main exits 1 on this branch, which is what produced the prune commit and the branch-shape decision. It also repaired five sanity checks that could not pass as written — a bare check-changelog-parity.sh exits 2 on usage; a grep -c … returns 0 check inverts its own exit code, so the success case failed and a wrongly staged file passed; a forbidden-metric grep passed vacuously on zero matches; two checks named a state with no command.

Other corrections worth recording: docs/PLUGIN-PHILOSOPHY.md:471 is a deadline ("before a second plugin adopts it"), not a licence to author an owner doc late — and the pilot phase is itself the second adopter, hence the stub-then-harden split. routines.md:192,195 already carry dead-code-sweep and coverage-mutation-watch, so the catalog phase gained an existing-row sweep as its first work item. The new skill takes the audit leaf and joins the registered owner set rather than picking scan to sidestep the argument the registry asks for. And the routine-delivery gap is bound to liveness-assertion's two-limb Core contract instead of being deferred by scope, which was not one of the permitted answers.

The locked Brief (the contract this plan was built to)

Brief

TLDR

Generalize the maintenance-routine pattern reported by @bcherny (2026-08-13) into tool-, org-, and
product-agnostic capability for this marketplace: detectors that emit conforming findings, plus
catalog rows governing them, plus the substrate both need. Not a port of his eleven routines,
and not a new plugin.

The research inverted the original framing three times, and the Brief encodes the inverted shape:

1. The apply machinery already exists and is reachable by file format alone (validated, below).
   What is missing, class after class, is a detector to feed it.
2. Merge rate cannot justify any of this. Three independent lines — peer-reviewed observational,
   large-N regression, randomized trial — find artifact quality weakly-to-not coupled to acceptance.
   The verification contract is justified on defect escape and reviewer burden, never on
   acceptance.
3. Class-level beats instance-level. Three lanes converged from different literatures: durable
   wins come from policy and mechanism, not from better per-instance agent judgement.

Goal

Ship, in dependency order:

• Tier 0 substrate — the four items below, which every candidate class depends on.
• Tier 1 detectors — three classes with the strongest evidence and a real local surface.
• Catalog rows for every class considered, including the ones deliberately not built, so the
  reasoning is recorded rather than re-litigated.

Constraints

Binding repository rules (verified, path:line in the research record):

• ADR 0005 — a new class extends the existing catalog: a reference/ edit plus a CHANGELOG.md
  entry plus a version bump. Not a new catalog, not a new skill, not a new plugin. This closed
  the original "where does it land" question; it is not reopened here.
• ADR 0004 incumbent-first gate is binding — no remediation ships until it proves no existing
  skill covers it, with path:line evidence. Satisfied for all eight classes by
  research/V1-coverage-negatives.md; each issue carries its own evidence.
• ADR 0008 — a row is admitted only when its observable is anchored to text that is present. An
  obligation a surface should satisfy, anchored to nothing, does not become a row however well
  sourced.
• Version bump and matching CHANGELOG entry in the same PR (CI-enforced, zero exemptions);
  metadata.workflow-stage required; regenerate docs/CATALOG.md and docs/SKILL-CHEAT-SHEET.md;
  SKILL.md under 500 lines; evals required for any new skill; only docs/topics/ is
  docs-only-allowlisted, so anything under plugins/** runs the full CI suite.

Product constraints (verified at primary, code.claude.com/docs/en/routines.md, 2026-08-14):

• Routines are available on Pro, Max, Team, and Enterprise — the mechanism is reachable on this
  account. Claude Tag (the Slack surface the source used) is Team/Enterprise-only and is out of
  reach; only that delivery surface is unavailable, not the capability.
• Minimum schedule interval is one hour. Runs count against a per-account daily allowance;
  one-off runs do not, which is the pilot lever.
• No permission containment during a run — "no permission-mode picker and no approval prompts".
  Containment is repo selection, environment, connector list, and the claude/-branch push rule.
• Repo .claude/ loads; user-scope ~/.claude does not. pluginConfigs is ignored at project
  scope by design, so any plugin taking userConfig has no cloud-run way to receive values.
• Green status ≠ success — "It does not mean the task in your prompt succeeded." Efficacy reads
  logs, never statuses.
• Workflows do not travel into scheduled runs; custom slash commands do.

Evidentiary constraint: the source is a single self-report with zero independent corroboration
and no published methodology. Nothing in this plan may cite 388/180 as evidence of efficacy.

Acceptance criteria

Per-unit close-out loop — one class at a time: incumbent evidence recorded → row derived through the
catalog's own mapping rules → detector or deferral shipped → CI green → CHANGELOG + version bump in
the same PR. A class is closed when its row exists with a derived guardrail class and either a
shipped detector or a join: trigger naming what would unblock it.

1. Findings-file coexistence is settled before a second producer ships. The fix action consumes
   exactly one file and merges nothing; two producers in one branch directory means the later
   timestamp silently wins. Green run, hidden findings. This is a correctness gate, not a nicety.
2. Every detector emits machine-computed severity, not prose routed through an LLM crosswalk. No
   crosswalk row exists for a deterministic surface today; that is contract work, not a detail.
3. Every class-level gate satisfies items 1-2 of the trust-path definition (below). Items 3-5 are
   org-scale and explicitly deferred at solo volume.
4. No acceptance-rate metric anywhere — not as a promotion input, not as an efficacy signal.
5. Each shipped detector carries evals, per the CI gate.

Captured assumptions

• The format-only path stays supported. Validated 2026-08-14, not assumed: a hand-written
  conforming file from a non-fanout producer passed the fix action's locator, frontmatter gate,
  exact-branch check, and table parse, including the cell-escaping rule. Probe deleted afterward —
  while it existed it was the newest file in that directory and would have shadowed a real review.
• Detectors are scripts unless a named agent is earned. The repo's own philosophy prefers one script
  "wherever the judgment is mechanical", and fanout can dispatch agents only — which is why
  mutation-testing:audit, the best deterministic detector in the fleet, reaches no relay today.
• Catalog rows derive their guardrail class through the existing mapping rules, never by hand.

The class-level trust path (the operative definition)

An instance-level path asks a judge to evaluate each change on its merits. A class-level path
decides once, for a category, what condition makes any member acceptable — so the per-instance
question collapses from a judgement to a check. The mechanism: per-instance persuasion is subject to
habituation; a standing class rule is not.

#	Requirement	Portable?
1	Class definition narrow enough that membership is decidable without judgement	yes
2	Machine-checkable gate that fails closed	yes
3	A denominator — enough instances to compute a rate	org-scale
4	An outcome signal that is not the merge decision	org-scale
5	A lookback window and a demotion rule	org-scale

"Dead-code removal where the code is provably unreachable" is a class. "Code quality improvements"
is not. If deciding membership needs the judgement you were eliminating, it is an instance-level path
wearing a class-level label.

Solo shape: the gate without the statistics — narrow class, machine-checkable gate, run it
before the PR opens, human on the merge. The earned auto-merge tier is deferred with a trigger.

Scope — tiers

Tier 0 — substrate. Blocks everything.

Item	Why
Findings-file coexistence	Silent-shadowing correctness bug the moment a second producer exists
Detector contract	Machine-computed severity, rule/threshold vocabulary, suppression; owner doc must precede the second adopter
Per-repo capability detection	The agnostic core: which classes bind, resolved from repo state (build files, language, test framework, flag system, architecture config, MCP servers, CLI tools)
Repo-scope plugin declaration	User-scope does not load in cloud; gated on the cloud probe (below)

Tier 1 — build. Formal-logic modeling (decision tables + property-based testing; strongest
evidence, and its mechanical artifacts are the verification payload) · useless-test repair
queue (genuinely uncovered; the fleet names the capability it lacks) · layering enforcement, inform-human posture (most mechanical once rules exist; propose-and-baseline, never impose-and-fail).

Tier 2 — rows now, build later. Dead code, both postures, with a 30-90 day window floor and
staged quarantine — never the source's one-day window · clone detection + trend gating (the unify
decision has no automation precedent in twenty years) · stale-flag removal (strong prior art;
consumer-facing, no local surface).

Tier 3 — rows recording why not. Logic simplification above expression level (no published
effectiveness evidence; excluded by name in tidyings.md) · abstraction flattening (no validated
detector exists, and the fault data runs backwards — Speculative Generality and Middle Man sometimes
reduce faults) · ant-only shipper (the decision is a human product call) · GUI crash fuzzing (no
local surface; 36.6% crash-replay reproducibility).

Out of scope

• A new plugin, a new catalog, or a parallel governance surface (ADR 0005).
• A self-tuning routine class. Across 22 verified papers, none tunes from deployed production
  outcomes with a human gate; the famous citations are within-episode and do not persist. The
  existing promotion apparatus is the better-grounded shape and already avoids the merge-rate
  confound by keying on completions, gate passes, and reverts.
• Auto-merge without human review at solo volume — requirements 3-5 above are unmeetable here.
• Porting the source's prompts. They are a meta-prompt (instructions to create routines), one
  layer above any stored prompt.

Deferred questions

• Q12 (arbiter: USER-RESERVED) — repo-scope plugin declaration in cloud. Filed as
  #2660 (needs-human).
  Two official pages contradict each other on whether repo-declared marketplace plugins install;
  workspace trust for a cloud clone is undocumented, and if untrusted the declaration is ignored
  silently; private-marketplace auth in cloud is undocumented. One probe settles all three, and
  it cannot run unattended — browser selection, account mutation, and metered usage all require the
  human. Tier 0's fourth item is blocked on it; the documented alternative (components committed
  directly to .claude/) is the fallback and needs no marketplace fetch, trust step, or credentials.
• Q4 follow-on (arbiter: /planning:plan) — add a reviewer-burden term to the existing promotion
  predicate, and keep any future tuner's signal set disjoint from promotion evidence. Composition
  hazard if not: a tuner could raise the metric that promotes the cell that reduces scrutiny of the
  tuner's own output.
• Q2 (resolved, recorded) — join: proven recurring manual pattern stays our-own-proven. The
  source's run is named-product evidence and belongs in the routine-catalog research record, not the
  non-normative precedent-pointers section, whose own scope line routes it elsewhere.
• Live daily run-cap numbers (arbiter: USER-RESERVED) — the docs direct readers to
  claude.ai/code/routines; published figures trace to a stale April blog post. Needs an
  authenticated session.

The plan's shape

Ten phases, sequential. Blast radius HIGH. Full bodies, work items, and sanity checks live in the eight issues above; the spine is:

P1 coexistence ──> P2 convention stub ──> P3 Pattern-C pilot ──> P4 harden ──> P7 detector
                        (must merge to main)                                      ^
P5 catalog rows ──> P6 predicate term ────────────────────────────────────────────┘

P8 capability detection ── promoted to its own topic
P9 repo-scope declaration ── blocked on #2660
P10 graduate + prune ── this PR

Three ordering constraints, none obvious:

• P1 before any detector — fanout is producer chore: initialize marketplace scaffold #1, so the first detector of any kind makes producer fix: correct plugin-system inaccuracies and harden references #2.
• P2 before P3 — a new cross-plugin convention lands in an owner doc before a second plugin adopts it, and P3 is that second adopter.
• P2 merged to main before P3 — a plugin cannot cite a repo-relative docs/conventions/ path, because it installs standalone. The established form is a raw URL to main, which only resolves once the convention is merged.

Approved reductions against the Brief

Both were surfaced as scope cuts rather than absorbed, and accepted:

• Tier 1: three detectors to one. Ships can't-fail tests (feat(testing): can't-fail test audit — detector plus fail-closed --check mode #2684); formal-logic modeling and layering enforcement become catalog rows with named triggers.
• Detection, not repair. The Brief names a repair queue; a judgment-shaped finding is surfaced rather than auto-applied, so the queue-and-apply half needs its own decision.
• One deviation: the Brief's per-unit close-out loop is batched stage-at-a-time, because the substrate phases are shared by every class and a per-class loop would re-pay them N times.

Follow-up outside this PR

AGENTS.md is 28 lines at HEAD and no longer carries the exec-bit or Windows-filemode guidance — commit e22190e's managed sync deleted the 34 lines 7c2a9b3 had added four commits earlier. It is a managed materialization, so a local patch is removed by the next sync; the fix belongs upstream in melodic-software/standards. The exec-bit CI gate still runs and is ungated by the docs-only allowlist, so the constraint is live while its documentation is not.

Related

• Refs feat(review): merge findings across producers and mark consumption explicitly (ADR 0010) #2678, docs(conventions): add the detector-findings owner doc (stub) #2679, feat(mutation-testing): persist survivors as a conforming findings file behind a flag #2680, docs(conventions): harden detector-findings with the rule-id to severity crosswalk #2681, feat(autonomy): catalog rows for every routine class considered #2682, feat(autonomy): record the reviewer-burden promotion term as deferred #2683, feat(testing): can't-fail test audit — detector plus fail-closed --check mode #2684, spike: per-repo routine capability detection — promote to its own topic #2685 — the eight phase issues this PR files
• Refs spike: does a repo-declared marketplace plugin load in a Claude Code cloud routine run? #2660 — repo-scope plugin declaration in a cloud run (needs-human spike); Tier 0's fourth item is blocked on it, and the documented fallback proceeds regardless
• Refs fix(toolchain): lint --fix ships code-changing defaults behind a single flag, no dry-run, no scope fence #2649, fix(typos-format): --write-changes runs with no extension filter #2650 — mutator-gating defects found during the research sweep
• ADR 0010 — docs/adr/0010-merge-findings-across-producers-and-mark-consumption-explicitly.md

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[claude]

Claude finished @kyle-sexton's task in 1m 58s —— View job

---

Code review — /review:code-review

• Gather context (PR body, gh pr diff, skill instructions)
• Read changed file(s)
• Apply code-review criteria (correctness, CLAUDE.md alignment, maintainability)
• Post findings

Scope: this PR's only change is docs/adr/0010-merge-findings-across-producers-and-mark-consumption-explicitly.md (+99/-0, new file). No code paths are touched in this PR — the ADR is a design record; its implementation is deferred to issue #2678.

What I checked

Since the diff is pure prose with no logic to exercise, "correctness" here means: do the ~10 path:line evidence citations the ADR's argument depends on actually say what it claims, and is the decision internally consistent. I independently re-read every cited source line rather than trusting the PR body's claimed verification:

• fanout/context/default-mode.md:48,77 — findings-file contract shape and the "required to keep the report honest" language. Matches.
• fanout/context/fix-pass-mode.md:3,7,56,76,95 — "newest persisted findings file", the load-bearing branch check, the scope-fenced fix, "Interactive and headless-stop paths write no record", and the required post-fix re-review. All match verbatim or in substance.
• fanout/context/findings-normalization.md:66,77 — the ±3-line dedup bucket, "Stage 3 Sonnet (semantic merge)", and the false-merge-over-false-split rule. Matches.
• docs/conventions/liveness-assertion/README.md:58 — the green-with-hidden-findings framing. Matches the Core Contract section it points to.

I also confirmed ADR numbering has no gap (0001–0010, all present) and the frontmatter/heading shape matches the existing ADRs (e.g. 0009) exactly.

Findings

None at the code-review high-signal bar. The document's citations are accurate, the three decisions each carry a rejected alternative with a real reason (not a strawman), and the "Consequences" section's claims (byte-for-byte-unchanged single-producer case vs. "interactive applies now write a record") are two distinct, non-contradictory properties rather than an inconsistency once read against Decision 3's actual scope.

I did not independently run markdownlint-cli2 (no shell access to npx in this sandbox) — the PR's markdownlint claim is author-reported and unverified by me.

[github-actions]

Claude has reviewed this PR 1 time. The lane skips further automatic reviews after 5; deleting this comment resets the count.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5341117ca0

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[claude]

Claude encountered an error after 0s —— View job

---

I'll analyze this and get back to you.

[github-actions]

Warning

Automated review did not complete — this is an infrastructure failure, not a review verdict.

Treat any Claude comment on this PR (including a placeholder like "I'll analyze this and get back to you") as incomplete, not "no findings."

• Run: https://github.com/melodic-software/claude-code-plugins/actions/runs/31872041579
• Failure class: rate-limit
• Last SDK result: {"subtype":"success","is_error":true,"num_turns":1,"duration_ms":300,"total_cost_usd":0,"api_error_status":429,"class":"rate-limit"}

Re-run the job, or workflow_dispatch this workflow with the PR number, to retry the review. A new push re-triggers this lane only if the caller's pull_request triggers include synchronize (the canonical caller omits it).
An automatic retry may already have run — it is skipped when a partial review could duplicate comments, or when the failure class needs an operator (auth).

[kyle-sexton]

Correction — the recovery pointer in this PR's body does not survive the merge

Raised by an independent review of the ADR edit, verified after merge. Recording it here rather than
silently editing the body, because the body is the artifact that was wrong.

The body says (still, unedited):

git show 5341117c:docs/topics/boris-routines-adoption/PLAN.md
git show 5341117c:docs/topics/boris-routines-adoption/design/design-resolution.md

Why that no longer works. This repository squash-merges and deletes the head branch on merge.
5341117c was a commit on feat/boris-routines-adoption, which no longer exists —
gh api repos/melodic-software/claude-code-plugins/branches/feat/boris-routines-adoption returns
404 Branch not found. A squash merge does not carry branch commits into main's history, so a
fresh clone has never fetched that object and git show fails against it. The command only works in
a checkout that fetched the branch before it was deleted — which is to say, on the machine that
wrote it.

What does work today, because GitHub still retains the unreachable commit object:

gh api "repos/melodic-software/claude-code-plugins/contents/docs/topics/boris-routines-adoption/PLAN.md?ref=5341117c" \
  --jq '.content' | base64 -d
gh api "repos/melodic-software/claude-code-plugins/contents/docs/topics/boris-routines-adoption/design/design-resolution.md?ref=5341117c" \
  --jq '.content' | base64 -d

Verified after the merge: the first returns a 67,690-byte blob. Treat this as convenience, not a
guarantee — retention of an unreachable object is a GitHub implementation detail with no promised
lifetime, and nothing in this repository keeps it alive.

The durable record was never those two files, and that was the design. The whole point of
graduating before pruning is that everything load-bearing left the slice before it was deleted:

• ADR 0010 — docs/adr/0010-merge-findings-across-producers-and-mark-consumption-explicitly.md,
  now on main. Carries the three decisions, their rejected alternatives, and the consequences.
• Issues feat(review): merge findings across producers and mark consumption explicitly (ADR 0010) #2678–spike: per-repo routine capability detection — promote to its own topic #2685 — one per phase, each carrying its own work items, sanity checks, and
  inlined path:line incumbent evidence. The evidence was deliberately inlined rather than cited
  into .work/, which is gitignored and unreadable to a delegated worker or a second machine.
• This PR body — the plan summary and the Brief.

So the correct reading of the prune is that the PLAN was a working artifact whose durable content had
already been moved. The pointer was offered as a convenience and was written in a form that outlives
neither the branch nor a fresh clone.

Convention follow-up. docs/conventions/topic-docs/README.md prescribes naming the pruning
commit and reading its parent (?ref=<pruning-commit>^). That form has the same defect under
squash-merge for the same reason: the pruning commit is a branch commit too, and the squash commit on
main has no parent containing the slice. A slice pruned on a squash-merging repository is
recoverable only through the API-by-SHA form above, or not at all once the object is collected.
Worth fixing in the convention rather than repeating per slice — filed separately rather than
patched into this merged PR.