From f4a27b5a01f9735c466f40a079c2a9f02acabecb Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 15 Aug 2026 00:26:59 -0400 Subject: [PATCH 1/2] docs(repo-fleet-hygiene): restore the documented argument grammar The skill body told an agent to reject `audit D:` while the bundled script accepted it. #2638 shipped bare positional paths and drive roots and replaced the project-directory fallback with a hard scope failure; #2646 landed eight minutes later from a branch cut before it, and its rebase carried the pre-#2638 prose forward as a revert. Restores, against the script as it actually behaves on main: - the bare positional `` form, in the argument list and the hint - `--project-dir` as a config rung only, not a scope fallback - the no-scope paragraph, which now describes the hard failure and its remedies instead of the removed project-directory target - the reject-outside-this-grammar clause, which now says plainly that a bare path IS in the grammar and only unknown flags are refused Also documents `bare-repo-with-working-tree` (#2633/#2602), whose handoff row was dropped by the same revert, and corrects the machine-wide-discovery claim in the README and plugin description: the ladder is not built, a no-scope run fails, and #2599 tracks it. Catalog regenerated from the manifest. Co-authored-by: Kyle Sexton --- docs/CATALOG.md | 2 +- .../.claude-plugin/plugin.json | 2 +- plugins/repo-fleet-hygiene/README.md | 3 +- .../repo-fleet-hygiene/skills/audit/SKILL.md | 29 ++++++++++++------- 4 files changed, 22 insertions(+), 14 deletions(-) diff --git a/docs/CATALOG.md b/docs/CATALOG.md index 3aec963fdf..6ab738a758 100644 --- a/docs/CATALOG.md +++ b/docs/CATALOG.md @@ -67,7 +67,7 @@ plugin manifests and kept in sync by CI — never hand-edit it; the category voc - [`docs-hygiene`](../plugins/docs-hygiene) — Documentation-hygiene toolkit of six skills: compress (flavor-trim markdown with a semantic-diff safety net), audit-noise (classify markdown noise), extract-ssot (deduplicate repeated content into a single source of truth), audit-encapsulation (detect citations into skill-private surfaces), rename-references (sweep stale references after renames), and audit-derivability (classify whether a whole document earns its existence — could a fresh agent re-derive it from the code?). - [`code-tidying`](../plugins/code-tidying) — Code tidying and comment hygiene: /code-tidying:tidy proactively hunts a rotated, glob-scoped lane for Beck-style tidyings under a research-backed scope budget and ships one tight PR; /code-tidying:batch-simplify sweeps recently changed files through grouped, dependency-ordered simplification waves with a never-drop deferred-items contract; /code-tidying:audit-comment-residue is a read-only classifier that flags history, plan, conversational, and ticket/PR residue in code comments for author-applied deletion. Project-specific tidy lanes are scaffolded into a tracked .claude/tidy-lanes/ config folder by a re-runnable setup skill. - [`repo-hygiene`](../plugins/repo-hygiene) — Repo hygiene action-router: /repo-hygiene:clean sweeps reclaimable caches, build artifacts, and stale git metadata, and can realign the working tree to a fresh-pull state — dry-run-first, with destructive tiers gated behind explicit confirmation and a session-scoped destructive-command guard. Ecosystem targets are detected at runtime; secrets, runtime dependencies, and skill data are preserved by default. -- [`repo-fleet-hygiene`](../plugins/repo-fleet-hygiene) — Machine-wide Git/GitHub repository discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes. +- [`repo-fleet-hygiene`](../plugins/repo-fleet-hygiene) — Cross-repository Git/GitHub fleet discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes. - [`disk-hygiene`](../plugins/disk-hygiene) — Context-aware disk hygiene for arbitrary directory trees: inventories orphaned and temporary artifacts, classifies evidence into review tiers, and offers exact-path cleanup only after a fresh safety preview and explicit per-tier approval. The target is read-only by default; OS-managed paths, links and mount points, VCS-tracked content without the complete checkout evidence bundle, changed entries, and live-handle uncertainty fail closed. ## Claude Code diff --git a/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json b/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json index 21bfea5df9..2a216a0e43 100644 --- a/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json +++ b/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json @@ -2,7 +2,7 @@ "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "repo-fleet-hygiene", "version": "0.22.0", - "description": "Machine-wide Git/GitHub repository discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes.", + "description": "Cross-repository Git/GitHub fleet discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes.", "author": { "name": "Melodic Software", "email": "info@melodicsoftware.com" diff --git a/plugins/repo-fleet-hygiene/README.md b/plugins/repo-fleet-hygiene/README.md index 6b69034da5..fb92c47aef 100644 --- a/plugins/repo-fleet-hygiene/README.md +++ b/plugins/repo-fleet-hygiene/README.md @@ -32,7 +32,8 @@ The epic's fleet architecture is intentionally split from the current implementa | Capability | Owner | Availability in this release | |---|---|---| -| Machine-wide repository discovery and canonical-checkout resolution | `repo-fleet-hygiene` | Shipped | +| Bounded repository discovery (bare path, drive root, `--root`, `--repo`, config rungs) and canonical-checkout resolution | `repo-fleet-hygiene` | Shipped | +| Machine-wide discovery with no argument (ghq / configured roots / agent state / bounded sweep ladder) | `repo-fleet-hygiene` | Not shipped — tracked by [#2599](https://github.com/melodic-software/claude-code-plugins/issues/2599); a no-scope run fails with remedies rather than guessing a root | | Cross-repository GitHub merge and repository-identity evidence | `repo-fleet-hygiene` | Shipped | | Per-repository worktree status, stranded-work classification, and cleanup | `/source-control:worktree` | Delegated; fleet-local reclaimability was retired in [#2605](https://github.com/melodic-software/claude-code-plugins/issues/2605) | | Per-repository branch, cache, build, and deletion triage | `/repo-hygiene:clean` | Delegated | diff --git a/plugins/repo-fleet-hygiene/skills/audit/SKILL.md b/plugins/repo-fleet-hygiene/skills/audit/SKILL.md index c770bf1b99..7f9eab52d3 100644 --- a/plugins/repo-fleet-hygiene/skills/audit/SKILL.md +++ b/plugins/repo-fleet-hygiene/skills/audit/SKILL.md @@ -1,7 +1,7 @@ --- description: "Coordinate Git/GitHub hygiene across a machine-wide fleet: discover canonical repositories, collect and roll up cross-repository evidence (including merged remote-tracking heads still on origin), and hand an action plan to repo-hygiene/source-control, which own per-repository cleanup. The current collector is read-only and emits detailed exact handoffs; it never deletes, prunes, repairs, fetches, checks out, or rewrites. Use when: 'audit repositories', 'repo fleet hygiene', 'stale branches across repos', 'orphaned worktrees across repos', 'merged remote branches', 'moved repos', 'renamed GitHub owner', 'cross-repo git cleanup report'." user-invocable: true -argument-hint: "[--root ]... [--repo ]... [--config ] [--canonical ]... [--max-depth <1..12>] [--detail] [--plan-file ] | --apply-plan " +argument-hint: "[]... [--root ]... [--repo ]... [--config ] [--canonical ]... [--max-depth <1..12>] [--detail] [--plan-file ] | --apply-plan " allowed-tools: - Bash(${CLAUDE_SKILL_DIR}/scripts/audit-fleet.sh:*) metadata: @@ -37,14 +37,16 @@ gate. Actual fleet mutation belongs to `/repo-fleet-hygiene:apply`, not this ski Parse `$ARGUMENTS` as opaque arguments for the bundled script. Supported flags: +- ``: a bare positional path, treated as `--root`. A drive root (`D:`, `D:/`) is a legitimate + discovery root and normalizes to `D:/`. This is the form `/repo-fleet-hygiene:audit D:` uses. - `--root `: bounded recursive repository discovery (repeatable). - `--repo `: exact repository/worktree target (repeatable). - `--config `: explicit Git-format config (at most one). - `--canonical `: invocation-specific canonical checkout override (repeatable; explicit wins over config). - `--max-depth <1..12>`: discovery bound; explicit wins over config/default `5`. -- `--project-dir `: the session's project directory, used for the project-scoped config rung - and the no-scope fallback target. +- `--project-dir `: the session's project directory, used for the project-scoped config rung. + It is **not** a scope fallback — a run with no scope fails rather than auditing it. - `--detail`: emit collapsed per-target evidence after the rollup (default is rollup + action plan only). - `--plan-file `: write the machine-readable action-plan JSON to this path (otherwise a temp @@ -57,12 +59,12 @@ variable is substituted in this markdown content and in `allowed-tools` Bash rul **not** present in the Bash tool's environment, so the script cannot read it for itself — passing it in is what makes the project rung below reachable at all. -If neither `--root` nor `--repo` is present, the script uses the project directory as an exact -`--repo` target — not as a discovery root, so nothing beneath it is searched. A project directory -that is not a Git working tree is therefore rejected, and the rejection names the three ways to -supply scope plus `/repo-fleet-hygiene:setup apply`; pass that guidance through rather than -re-deriving a root yourself. If no project directory resolves either, the run stops with the same -remedies rather than auditing the shell's incidental working directory. Config +If no scope resolves — no bare path, no `--root`, no `--repo`, and no config-supplied +`fleet.root`/`fleet.repo` — the run **stops** and names the ways to supply scope plus +`/repo-fleet-hygiene:setup apply`. Pass that guidance through rather than re-deriving a root +yourself. The project directory is **not** a fallback scope: auditing the session's incidental +working directory was removed because it silently audited whatever tree the shell happened to sit +in. Config resolution is the script's own ladder — do not pre-resolve or pass a probed path yourself: explicit `--config` wins, else the script probes `/.claude/repo-fleet-hygiene.conf` (project-scoped), else @@ -75,8 +77,12 @@ Config-supplied scope is **additive** to CLI-supplied scope: a `--repo X` run st configured root. The header's `Scope:` line names each contributing rung and its entry count, so report that line rather than assuming the arguments were the whole scope. -Before execution, reject any arguments outside this grammar. Pass every path/override as a quoted -argument; never assemble a shell fragment from config, repository, remote, or branch text. +Before execution, reject any arguments outside this grammar — noting that a bare positional path +**is** in the grammar, so `/repo-fleet-hygiene:audit D:` and +`/repo-fleet-hygiene:audit /path/to/tree` are valid invocations to pass through, not arguments to +refuse. What stays rejected is an unrecognized flag: anything beginning with `-` that is not listed +above. Pass every path/override as a quoted argument; never assemble a shell fragment from config, +repository, remote, or branch text. Run exactly once: @@ -275,6 +281,7 @@ Related fleet contracts that remain separate: | `worktree-root-unconfigured` | Set `melodic.worktreeroot` (git config) or source-control `worktree_root`, then rerun | | `worktree-root-pluginconfigs-unreadable` | Install `jq`, or set `melodic.worktreeroot`; do not treat the fleet as unconfigured | | `worktree-placement-unverifiable` | Inspect the canonical checkout; placement was not checked for any of its worktrees, so their placement is unknown rather than confirmed | +| `bare-repo-with-working-tree` | Manual review. `core.bare=true` coincides with working-tree content or registered linked worktrees, so the main worktree is disabled while linked worktrees keep working. Nothing is lost; the documented remedy is `git config --local core.bare false` in the named checkout | | `github-remote-moved` | Human-reviewed `git remote set-url`; this plugin never changes remotes | This plugin remains useful if those optional collaborators are absent: the report names the local From fd4168cfc1cb4a96d463cf2f3750748903833c43 Mon Sep 17 00:00:00 2001 From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com> Date: Sat, 15 Aug 2026 04:40:14 +0000 Subject: [PATCH 2/2] fix(repo-fleet-hygiene): changelog parity and doc review follow-ups Bump to 0.22.1 with a CHANGELOG entry so plugin-file edits clear changelog-parity. Align the audit skill description/Purpose with the cross-repository wording already used in README and plugin.json, replace the stale no-argument Quick start with an explicit --repo example, and stop naming closed #2599 as the tracker for the still-unshipped machine-wide discovery ladder. Co-authored-by: Kyle Sexton --- plugins/repo-fleet-hygiene/.claude-plugin/plugin.json | 2 +- plugins/repo-fleet-hygiene/CHANGELOG.md | 10 ++++++++++ plugins/repo-fleet-hygiene/README.md | 9 ++++++--- plugins/repo-fleet-hygiene/skills/audit/SKILL.md | 4 ++-- 4 files changed, 19 insertions(+), 6 deletions(-) diff --git a/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json b/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json index 2a216a0e43..bdee0494bb 100644 --- a/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json +++ b/plugins/repo-fleet-hygiene/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json", "name": "repo-fleet-hygiene", - "version": "0.22.0", + "version": "0.22.1", "description": "Cross-repository Git/GitHub fleet discovery, evidence rollup, and a gated apply verb that executes a prior fleet action plan behind one confirmation. Audit stays read-only and confidence-tiered; apply mutates only with --apply plus interactive confirmation or --yes.", "author": { "name": "Melodic Software", diff --git a/plugins/repo-fleet-hygiene/CHANGELOG.md b/plugins/repo-fleet-hygiene/CHANGELOG.md index 8c1b9e5a10..e6967d327f 100644 --- a/plugins/repo-fleet-hygiene/CHANGELOG.md +++ b/plugins/repo-fleet-hygiene/CHANGELOG.md @@ -3,6 +3,16 @@ All notable changes to `repo-fleet-hygiene` are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this plugin uses semantic versioning. +## [0.22.1] + +### Fixed + +- **Documented audit argument grammar restored after a silent prose revert (#2599).** Bare + positional paths and drive roots, `--project-dir` as a config rung only, the hard no-scope + failure, and the `bare-repo-with-working-tree` handoff row again match `audit-fleet.sh` (the + #2646 rebase had carried pre-#2638 skill prose forward). README / plugin / skill copy no longer + claim machine-wide no-argument discovery as shipped; Quick start uses an explicit `--repo`. + ## [0.22.0] ### Added diff --git a/plugins/repo-fleet-hygiene/README.md b/plugins/repo-fleet-hygiene/README.md index fb92c47aef..9dd3477901 100644 --- a/plugins/repo-fleet-hygiene/README.md +++ b/plugins/repo-fleet-hygiene/README.md @@ -33,7 +33,7 @@ The epic's fleet architecture is intentionally split from the current implementa | Capability | Owner | Availability in this release | |---|---|---| | Bounded repository discovery (bare path, drive root, `--root`, `--repo`, config rungs) and canonical-checkout resolution | `repo-fleet-hygiene` | Shipped | -| Machine-wide discovery with no argument (ghq / configured roots / agent state / bounded sweep ladder) | `repo-fleet-hygiene` | Not shipped — tracked by [#2599](https://github.com/melodic-software/claude-code-plugins/issues/2599); a no-scope run fails with remedies rather than guessing a root | +| Machine-wide discovery with no argument (ghq / configured roots / agent state / bounded sweep ladder) | `repo-fleet-hygiene` | Not shipped — remaining contract work (not an open issue); a no-scope run fails with remedies rather than guessing a root | | Cross-repository GitHub merge and repository-identity evidence | `repo-fleet-hygiene` | Shipped | | Per-repository worktree status, stranded-work classification, and cleanup | `/source-control:worktree` | Delegated; fleet-local reclaimability was retired in [#2605](https://github.com/melodic-software/claude-code-plugins/issues/2605) | | Per-repository branch, cache, build, and deletion triage | `/repo-hygiene:clean` | Delegated | @@ -57,12 +57,15 @@ report and exact per-repository handoffs. ## Quick start -Audit the current project repository (zero configuration): +Audit the current project repository explicitly (no fleet config required): ```text -/repo-fleet-hygiene:audit +/repo-fleet-hygiene:audit --repo ``` +A bare `/repo-fleet-hygiene:audit` with neither CLI scope nor `fleet.root` / `fleet.repo` in a +resolved config hard-fails and names remedies — it does not audit the session project directory. + Audit one or more repository-tree roots: ```text diff --git a/plugins/repo-fleet-hygiene/skills/audit/SKILL.md b/plugins/repo-fleet-hygiene/skills/audit/SKILL.md index 7f9eab52d3..7019d8213f 100644 --- a/plugins/repo-fleet-hygiene/skills/audit/SKILL.md +++ b/plugins/repo-fleet-hygiene/skills/audit/SKILL.md @@ -1,5 +1,5 @@ --- -description: "Coordinate Git/GitHub hygiene across a machine-wide fleet: discover canonical repositories, collect and roll up cross-repository evidence (including merged remote-tracking heads still on origin), and hand an action plan to repo-hygiene/source-control, which own per-repository cleanup. The current collector is read-only and emits detailed exact handoffs; it never deletes, prunes, repairs, fetches, checks out, or rewrites. Use when: 'audit repositories', 'repo fleet hygiene', 'stale branches across repos', 'orphaned worktrees across repos', 'merged remote branches', 'moved repos', 'renamed GitHub owner', 'cross-repo git cleanup report'." +description: "Coordinate Git/GitHub hygiene across a cross-repository fleet: discover canonical repositories, collect and roll up cross-repository evidence (including merged remote-tracking heads still on origin), and hand an action plan to repo-hygiene/source-control, which own per-repository cleanup. The current collector is read-only and emits detailed exact handoffs; it never deletes, prunes, repairs, fetches, checks out, or rewrites. Use when: 'audit repositories', 'repo fleet hygiene', 'stale branches across repos', 'orphaned worktrees across repos', 'merged remote branches', 'moved repos', 'renamed GitHub owner', 'cross-repo git cleanup report'." user-invocable: true argument-hint: "[]... [--root ]... [--repo ]... [--config ] [--canonical ]... [--max-depth <1..12>] [--detail] [--plan-file ] | --apply-plan " allowed-tools: @@ -12,7 +12,7 @@ metadata: ## Purpose -Coordinate machine-wide repository hygiene. This skill owns cross-repository discovery, canonical +Coordinate cross-repository hygiene. This skill owns bounded fleet discovery, canonical checkout resolution, fleet-scale evidence collection, rollup, and action-plan routing. It does **not** own per-repository cleanup decisions or execution; those belong to `repo-hygiene` and `source-control`.