chore: initialize marketplace scaffold - #1
Merged
Conversation
Fresh public marketplace skeleton: marketplace.json catalog, README, CLAUDE.md fresh-docs mandate, migration playbook, plugins/ dir. Co-Authored-By: Claude <noreply@anthropic.com>
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5a7469e640
ℹ️ 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".
Comment on lines
+54
to
+55
| - **Namespacing.** An in-repo `/foo` becomes `/melodic-software:foo` (plugin-namespaced). Internal | ||
| cross-references to the bare name break — update them. |
There was a problem hiding this comment.
When this playbook is used to migrate a skill whose plugin name is not exactly melodic-software, it tells maintainers to rewrite slash-command references to the marketplace name. I checked the current Claude Code plugin marketplace docs, and installed plugin skills are namespaced by the plugin name (for example /quality-review-plugin:quality-review after installing quality-review-plugin@my-plugins), so references like /melodic-software:foo will not resolve for plugins published under this marketplace. Please make the example use the actual plugin name, e.g. /<plugin-name>:foo.
Useful? React with 👍 / 👎.
This was referenced Jun 28, 2026
This was referenced Jul 4, 2026
This was referenced Jul 11, 2026
Merged
This was referenced Jul 11, 2026
feat: add review-toolkit plugin (6 reviewer agents + quality-gate and code-review-fanout skills)
#71
Merged
This was referenced Jul 12, 2026
kyle-sexton
added a commit
that referenced
this pull request
Jul 12, 2026
…r self-contained Address three more Codex P2 findings: - teach topic case (#1): topic is start-or-resume, so a fresh-workspace expectation flakes on a machine with prior data. Assert the start-or-resume contract — mission interview for a new workspace, resume for an existing one. - teach primer case (#3): the primer intakes the user's starting point with one question before building the ladder, so a single-turn run may correctly open with the intake. Make the expectation intake-first. - diagnose cleanup case (#6): a broad grep -r "[DEBUG-" already matches the diagnose docs and this fixture in the checkout. Scope the assertion to the specific [DEBUG-a4f2] tag across the changed source.
This was referenced Jul 12, 2026
kyle-sexton
added a commit
that referenced
this pull request
Jul 13, 2026
… hardening (#138) Applies the resolved `planning/setup` hardening to `knowledge/setup`'s `library_dir` seam (same single-directory `userConfig` shape, same latent issues). ## Changes **`plugins/knowledge/skills/setup/SKILL.md`** - **Precedence** — step 1 now resolves the full documented order (Managed > `--settings` > Local > Project > User), warns when higher layers are unreadable instead of declaring a lower value authoritative, and surfaces layer shadowing before the project write. - **Portability** — step 5 guards the tracked project write: never propagate a machine-specific personal-layer value into team settings; route personal-only overrides to `.claude/settings.local.json` (portability required only for the shared project write). - **Declared-convention alignment** — inspect the repo's declared working-notes/artifacts convention even when a value is set; surface divergence and offer to reconcile. **`plugins/codebase-audit/skills/setup/SKILL.md`** (partial match — writes a tracked `.md`, not settings) - Applied only the precedence/shadowing subset: step 1 reports the *effective additively-merged* config across user-global → team → local layers (and warns on unreadable layers), instead of summarizing the team file alone. Settings-write portability specifics do not apply. ## Deviations (own-flagged) 1. **Fix #3 premise softened for knowledge.** The issue's fix #3 parenthetical assumed knowledge "honors that convention over the config at write time" (true for planning). Verified via `skills/youtube/extraction/lib/work-root.js` and the youtube pipeline that **knowledge resolves `library_dir` directly at write time — no skill overrides it with a repo convention at runtime.** Documenting that behavior would be false, so I softened the imported write-time-override claim: `library_dir` is runtime-authoritative, and setup's job is to keep it *aligned* with any declared convention. Fixes #1 and #2 are unaffected. 2. **`codebase-audit` version bump not in issue scope.** Patch-bumped `0.1.0 → 0.1.1` because its SKILL behavior changed; the issue only specified the `knowledge` minor bump. ## Verification - `knowledge` `plugin.json` minor bump `0.2.0 → 0.3.0`; `codebase-audit` `0.1.0 → 0.1.1`. - `claude plugin validate` clean on both plugins. - markdownlint clean on both edited files. Refs melodic-software/medley#1463 <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Changes are limited to plugin skill documentation and version metadata; no application runtime or security-sensitive code paths are modified. > > **Overview** > **Hardens setup skills** for the `knowledge` and `codebase-audit` plugins so interactive setup reflects layered config reality instead of treating a single team file as authoritative. > > For **`knowledge/setup`**, step 1 now follows the full Claude Code precedence chain (Managed → `--settings` → Local → Project → User), warns when higher layers are unreadable, and calls out when a project write would stay shadowed. A new step reconciles `library_dir` with repo-declared working-notes conventions even when a value is already set. Persistence (step 5) blocks copying machine-specific personal paths into tracked project settings, routes personal-only overrides to `.claude/settings.local.json`, and the output section documents honest pipeline behavior (`book-distill` ignores `library_dir`; YouTube does not yet honor it). **`knowledge`** bumps **0.2.0 → 0.3.0**. > > For **`codebase-audit/setup`**, step 1 is expanded to summarize the **effective merged** config across user-global → team → local layers (including dimension opt-outs via empty source lists), explain that only the team file is written, and warn when overlays block re-enabling dimensions. **`codebase-audit`** patch-bumps **0.1.0 → 0.1.1**. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit f13139a. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
kyle-sexton
added a commit
that referenced
this pull request
Jul 14, 2026
…ntion (#175) ## What Adds a durable guardrail against fragile Claude Code permission grants, in two parts: - **(a) Enforceable check** — a new `permission-hygiene` skill in the `claude-config-audit` plugin, matching the plugin's established idiom (deterministic detector script + `.test.sh` contract test + `reference/criteria.md` + `evals/evals.json`). A `permission-rule-check.sh` detector scans skill/command/agent frontmatter `allowed-tools` and `settings.json` / `settings.local.json` `permissions.allow`, and flags three anti-patterns. - **(b) Convention doc** — `docs/conventions/permission-rule-hygiene/` (README + CHANGELOG), matching the existing `hook-telemetry` / `ecosystem-commands` convention-directory house style, stating the principle, the three anti-patterns, the correct pattern, and the operator-setup boundary — each with official-doc citations. The skill's criteria link to it (reference, don't restate). ## The three anti-patterns → the correct pattern All three make a grant silently do nothing. Verified against current official docs (URLs below): 1. **Interpreter-wildcard / blanket allow rules are dropped in auto mode.** Per permission-modes: "On entering auto mode, broad allow rules that grant arbitrary code execution are dropped: Blanket `Bash(*)` or `PowerShell(*)`; Wildcarded interpreters like `Bash(python*)`; Package-manager run commands; `Agent` allow rules. Narrow rules like `Bash(npm test)` carry over." So a frontmatter grant such as `Bash(python "*helper.py":*)` grants nothing under auto mode. Empirically, a guarded merge helper granted this way was denied even when invoked bare. 2. **Hardcoded absolute machine/user paths.** Bash rules match the command string literally — no `~`/`$HOME`/env expansion — so `Bash(/c/Users/<name>/.../x.sh:*)` breaks on other machines/usernames and leaks a username into source control. 3. **Assuming a skill or plugin can self-grant.** Skill `allowed-tools` is skill-scoped and (per #1) ineffective for auto-mode-gated actions; a plugin `settings.json` supports only the `agent` and `subagentStatusLine` keys, so a `permissions` block there is inert; and an agent editing its own settings to self-grant is blocked (`.claude/` is a protected path; `defaultMode: auto` is ignored from project/local settings so a repo can't grant itself auto mode). **Correct pattern:** expose the guarded helper as a stable bare command on the Bash tool PATH (pre-plugin: a PATH shim in a dir already on PATH; post-migration: the plugin's `bin/`), allow the bare name narrowly (`Bash(babysit_merge.sh:*)` — carries over into auto mode like `Bash(npm test)`, machine -independent, identical before/after migration), and have the **operator** add that bare-name rule once to user-global `~/.claude/settings.json`. ## The check (detector → criteria → evals) `permission-rule-check.sh` (advisory, exits 0; `--count` for a count; requires `jq`) flags: - **P1** interpreter-wildcard / blanket rules (`Bash(*)`, `Bash(python*)`, `Bash(bash <path>*)`, `Bash(sh -c*)`, package-manager runners, `Bash(*.py:*)`). Narrow rules (`Bash(npm test)`, `Bash(babysit_merge.sh:*)`) are NOT flagged — a negative fixture proves this. - **P2** hardcoded machine/user paths (`/c/Users/…`, `/home/…`, `/Users/…`, `C:\Users\…`); `${CLAUDE_PROJECT_DIR}`/`~/` forms are exempt. - **P3** a plugin `settings.json` that declares an inert `permissions` block. `settings.local.json` is parsed for its `permissions.allow` array only — never read or echoed wholesale (matching the sibling `settings-audit` secret-handling posture). Scope vs `settings-audit` is explicit: this skill owns grant portability + auto-mode durability + who adds the operative rule; file correctness (baseline deny/ask, deprecated `:*`, drift) routes to `settings-audit`. Detector and test fixtures assemble machine-path strings from fragments (and the docs use `<name>` placeholders) so no contiguous machine-path literal sits in a committed file — the repo's own machine-specific-path CI lane stays clean without a CI exclude. ## Empirical evidence the guardrail is needed Running the new detector against this marketplace surfaced **six pre-existing interpreter/runner-led frontmatter grants** across unrelated plugins (shapes like `Bash(bash <script>:*)`, `Bash(bash <dir>/*)`, and `Bash(npx:*)`) — none of them the portable bare-name pattern, and the broad forms among them (a globbed script target, a package runner) are exactly what auto mode drops. (For a grant that invokes one fixed script through an interpreter, the detector flags the same authoring anti-pattern without asserting the drop; the bare-name fix is identical.) Those live in other contributors' plugins and are left for a separate follow-up (out of this PR's lane). ## Tests - `permission-rule-check.test.sh`: 27 checks pass (positive + negative fixtures for all three checks, `--count`, `--help`, jq-missing → exit 2, and the narrow-rule-not-flagged negative case). - Full `scripts/run-plugin-tests.sh` suite green; `shellcheck -x` and `shfmt -ci -i 2` clean; markdownlint clean; scripts carry the executable bit. ## Sources (verified this session) - Auto-mode drop / decision order — https://code.claude.com/docs/en/permission-modes - `classifyAllShell`, narrow-rule carryover — https://code.claude.com/docs/en/auto-mode-config - Literal matching, wildcard / `:*` semantics — https://code.claude.com/docs/en/permissions - `allowed-tools` scope, `${CLAUDE_PROJECT_DIR}` substitution — https://code.claude.com/docs/en/skills - Plugin `bin/` on PATH + `agent`/`subagentStatusLine`-only `settings.json` — https://code.claude.com/docs/en/plugins-reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) https://claude.ai/code/session_013gKgRoW8zkFadbE2hE4r4b <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Changes are documentation plus read-only local scanning scripts; they do not alter Claude Code behavior or auto-modify user settings. > > **Overview** > Adds a **permission-rule-hygiene** marketplace convention (`docs/conventions/permission-rule-hygiene/`) and a fourth **`claude-config-audit`** skill, **`permission-hygiene`**, that audits whether `allowed-tools` and `permissions.allow` grants are portable and still effective in auto mode. > > The skill runs a deterministic **`permission-rule-check.sh`** detector (plus **`permission-rule-check.test.sh`**, **`reference/criteria.md`**, and **`evals/evals.json`**) that flags **P1** interpreter/blanket/`Agent` grants auto mode drops, **P2** hardcoded user-home paths, and **P3** inert `permissions` blocks in plugin `settings.json`. It is **report-only** (remediation is operator manual: bare command on PATH + user-global allow rule), with scope filters and explicit routing of file-correctness work to **`settings-audit`**. > > Plugin manifest and docs move **`claude-config-audit`** to **0.3.0** and update the root catalog to describe four audit skills. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 867e5f2. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY --> --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This was referenced Aug 10, 2026
This was referenced Aug 11, 2026
Merged
kyle-sexton
added a commit
that referenced
this pull request
Aug 15, 2026
Fills PLAN.md's empty `## Plan` with an eight-phase sequence and records the Tier B design early-exit that gates it. The spine is ordered by two constraints that are easy to miss. Fanout is findings producer #1, so the first detector of any kind makes producer #2 and the single-file consumer becomes a silent-shadowing bug -- coexistence is strictly phase 1, not merely early. And the owner doc precedes the *second* adopter, so the Pattern-C proof slice runs before the detector contract is written rather than after it. Draft only: the fresh-context stress-test has not been applied yet. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 15, 2026
Closed
Merged
kyle-sexton
added a commit
that referenced
this pull request
Aug 15, 2026
…sues, contract-slice prune (#2686) 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: ```bash git show 5341117:docs/topics/boris-routines-adoption/PLAN.md git show 5341117: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. <details> <summary><b>What the review passes caught</b></summary> 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. </details> <details> <summary><b>The locked Brief (the contract this plan was built to)</b></summary> ## 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](#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. </details> ## 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: ```text 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 #1, so the first detector of any kind makes producer #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 (#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 #2678, #2679, #2680, #2681, #2682, #2683, #2684, #2685 — the eight phase issues this PR files - Refs #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 #2649, #2650 — mutator-gating defects found during the research sweep - ADR 0010 — `docs/adr/0010-merge-findings-across-producers-and-mark-consumption-explicitly.md` --------- Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
This was referenced Aug 17, 2026
Merged
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Initialize the fresh public marketplace.
Scaffold only; plugins migrated one at a time.