docs(repo-fleet-hygiene): restore the documented argument grammar

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

plugins/repo-fleet-hygiene/.claude-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "$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.",
+  "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",
     "email": "info@melodicsoftware.com"

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

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 — 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 |
@@ -56,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 <checkout>
 ```
 
+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

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'."
+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 <dir>]... [--repo <dir>]... [--config <file>] [--canonical <github.com/owner/repo=path>]... [--max-depth <1..12>] [--detail] [--plan-file <path>] | --apply-plan <path>"
+argument-hint: "[<dir>]... [--root <dir>]... [--repo <dir>]... [--config <file>] [--canonical <github.com/owner/repo=path>]... [--max-depth <1..12>] [--detail] [--plan-file <path>] | --apply-plan <path>"
 allowed-tools:
   - Bash(${CLAUDE_SKILL_DIR}/scripts/audit-fleet.sh:*)
 metadata:
@@ -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`.
@@ -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:
 
+- `<dir>`: 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 <dir>`: bounded recursive repository discovery (repeatable).
 - `--repo <dir>`: exact repository/worktree target (repeatable).
 - `--config <file>`: explicit Git-format config (at most one).
 - `--canonical <github.com/owner/repo=path>`: invocation-specific canonical checkout override
   (repeatable; explicit wins over config).
 - `--max-depth <1..12>`: discovery bound; explicit wins over config/default `5`.
-- `--project-dir <dir>`: the session's project directory, used for the project-scoped config rung
-  and the no-scope fallback target.
+- `--project-dir <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 <path>`: 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
 `<project-dir>/.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