fix(docs-review): accept any file type in docs-review/docs-loop slash grammar, not just .md

Author: zeikar

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperclaude",
-  "version": "1.9.1",
+  "version": "1.9.2",
   "description": "Push Claude Code beyond stock. Skills, agents, Codex collab — opinionated and personal.",
   "author": {
     "name": "zeikar",

docs/decisions.md

@@ -323,6 +323,8 @@ Rules live in `references/review-brief.md`; the four caller skills (`hyper-plan-
 
 `docs-target` frontmatter now encodes as a JSON array in `--docs-path` list mode (vs. the pre-existing JSON string in `--docs-dir` mode); `resume.mjs`'s identity check normalizes both shapes — a legacy scalar string is wrapped to a 1-element array before the set comparison — so pre-existing single-string artifacts remain resumable without a migration.
 
+**Follow-up 2026-07-16 — skill grammar relaxed from `.md`-only to any file.** The `hyper-docs-review` / `hyper-docs-loop` slash grammars initially accepted only `.md` file tokens, which couldn't express the motivating `site/index.html` target above even though the bridge itself never restricted extension. Relaxed to discriminate file-vs-directory by an existence check (`[ -f ]` / `[ -d ]`) rather than the `.md` extension, so the skills accept any existing file and match the bridge's capability. `--docs-dir` is still non-recursive and still top-level `.md`-only inside a directory (unchanged) — the relaxation is only about which explicit file tokens the `--docs-path` path accepts.
+
 ---
 
 ## Pointers (decisions documented elsewhere)

docs/gates-and-agents.md

@@ -141,7 +141,7 @@ A gate skill mediates a step in the cycle that produces a canonical `.hyperclaud
 - **Slash:** `/hyperclaude:hyper-docs-review [path...] [--diff-base <ref>] [--resume [<artifact>]]` — argument order is `path → --diff-base → --resume`. `path` defaults to `docs/` when omitted, so `/hyperclaude:hyper-docs-review --diff-base main` is valid (reviews `docs/` against the diff).
   - Empty → top-level `.md` files in `docs/` (commentarium convention).
   - Single file → reviews that file.
-  - Multiple `.md` files (space-separated) → each maps to its own `--docs-path` flag (repeatable; appends).
+  - Multiple files (space-separated, any type — e.g. `README.md` + `site/index.html`) → each maps to its own `--docs-path` flag (repeatable; appends).
   - Directory → reviews top-level `.md` files in that dir (recursion deferred — see [decisions.md](decisions.md)).
   - `--resume` — resume the most recent matching prior review (auto-discovers newest artifact in `.hyperclaude/docs-reviews/` matching on the docs-target SET — order-insensitive — plus diff-base and current `template-version`; falls back to fresh run if none found, records `codex-resume-status: fallback`).
   - `--resume <prev-artifact-path>` — resume from an explicit prior review; validation fail → `ok:false`, no fresh run. If docs payload exceeds 200KB on a resume run, bridge returns `ok:false` (no fallback — user must narrow scope).
@@ -153,7 +153,7 @@ A gate skill mediates a step in the cycle that produces a canonical `.hyperclaud
 
 ### `hyper-docs-loop` — autonomous docs-hardening loop
 
-- **Slash:** `/hyperclaude:hyper-docs-loop [target]` — same target grammar as `hyper-docs-review` (empty → `docs/` directory; `.md` file → single-file mode; multiple `.md` files → repeated `--docs-path`; existing directory → directory mode).
+- **Slash:** `/hyperclaude:hyper-docs-loop [target]` — same target grammar as `hyper-docs-review` (empty → `docs/` directory; a file → single-file mode; multiple files → repeated `--docs-path`; existing directory → directory mode).
 - **Mechanics:** team-based docs-hardening loop. The skill confirms agent-teams availability via an env probe (`[ "$CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS" = "1" ]`; a missing env var stops as a clean no-op before any tree mutation), then spawns the [`documenter`](#documenter) agent once as a persistent teammate — same agent the `hyper-docs-sync` flow uses, dispatched in this loop with a structured-findings reply contract (the agent stays loop-agnostic; the per-finding schema and `request-id: <id>` prefix live ONLY in the SKILL.md spawn-prompt, not in the agent file); every lead→teammate SendMessage (findings, corrective, shutdown) runs the §A send-resolution procedure (bare `teammate_name` on the main path; `agent_id` fallback + notification-reply driving on degraded hosts via the removable `§A-DEGRADE` override). Then it invokes Codex `docs-review` directly via the bridge for that first review, sends blocking `### Findings` bullets to the still-live documenter via SendMessage, and repeats until no blocking findings remain (judged semantically — accuracy / drift / actively misleading claims block; pure prose-polish nits and redundancy-only findings do not) or a 6-review cap is reached. Only the `### Findings` section is gating; `### Gaps`, `### Broken Or Suspect Links`, and `### Cross-Doc Inconsistencies` are reported in the final Step 9 summary but never auto-fixed (those sections need human judgment). The reviewer is always the Codex bridge — NOT a team agent — preserving the "Claude builds, Codex reviews" invariant. (At Step 0 the lead Reads both the shared `${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md` — agent-teams contract, unsolicited-message protocol, teardown, abstract request-id state machine, AND the shared **§F loop skeleton** (Step 0/2/4a/8 boilerplate + degrade-condition pointers) that this SKILL binds to by pointing at the named §F sub-blocks — and the loop-specific `skills/hyper-docs-loop/references/failure-protocol.md` — structured-schema reply with `request-id: <id>` prefix, semantic finding-map validation, docs-loop-specific anti-patterns.)
 - **Writes:** the doc edits themselves (uncommitted), plus one `.hyperclaude/docs-reviews/<timestamp>-<slug>.md` per Codex review iteration.
 - **No baseline sync:** docs-loop is review ↔ fix only. If you want code-change-driven syncing first, run `/hyperclaude:hyper-docs-sync` separately before invoking this skill (keeping the two flows separate avoids conflating the code-diff-driven sync with the docs-target-driven review).

docs/workflow.md

@@ -153,7 +153,7 @@ Default: top-level `.md` files in `docs/`. Variants:
 /hyperclaude:hyper-docs-review README.md                       # single file
 /hyperclaude:hyper-docs-review docs/api/                       # specific subdir
 /hyperclaude:hyper-docs-review README.md --diff-base main      # with code-diff context
-/hyperclaude:hyper-docs-review README.md docs/workflow.md      # multiple named files (each maps to its own --docs-path)
+/hyperclaude:hyper-docs-review README.md docs/workflow.md site/index.html  # multiple named files, any type (each maps to its own --docs-path)
 ```
 
 Writes `.hyperclaude/docs-reviews/<timestamp>-<slug>.md`. Scope is strict: accuracy / drift / completeness / broken links / cross-doc inconsistencies / redundancy (in-doc duplicated claims, reported Minor; deliberate cross-doc propagation exempt). NOT prose or style — the documenter agent owns those.

skills/hyper-docs-loop/SKILL.md

@@ -42,7 +42,7 @@ The lead must also retain the following handle-resolution run-state across turns
 `$ARGUMENTS` is a **docs target** (optional path tokens; the loop mirrors `hyper-docs-review`'s target grammar). Resolution:
 
 - `$ARGUMENTS` empty → default to `docs/` (directory mode).
-- `$ARGUMENTS` is one or more existing `.md` file paths → multi-file mode (each maps to its own `--docs-path`).
+- `$ARGUMENTS` is one or more existing file paths (any type) → multi-file mode (each maps to its own `--docs-path`).
 - `$ARGUMENTS` is a single existing directory path → directory mode.
 - Anything else → ask the user to clarify and STOP.
 
@@ -54,18 +54,18 @@ See `${CLAUDE_PLUGIN_ROOT}/references/loop-protocol.md` §F2 for the two-file re
 
 ### Step 1 — Resolve the docs target
 
-Apply the resolution table above to `$ARGUMENTS`. Verify each path exists via Bash (`[ -e "<path>" ]`). Record `docs_target` as the bridge argv tokens:
+Apply the resolution table above to `$ARGUMENTS`. Classify each token via Bash — `[ -f "<path>" ]` (existing file → `--docs-path`) vs `[ -d "<path>" ]` (existing directory → `--docs-dir`); a token that is neither → STOP. Record `docs_target` as the bridge argv tokens:
 
 | Argument | `docs_target` argv |
 |---|---|
 | Empty | `['--docs-dir', 'docs/']` |
-| One or more `.md` files that exist | `['--docs-path', '<path1>', '--docs-path', '<path2>', ...]` (one flag per file, in order) |
+| One or more existing files (each `[ -f ]`, any type) | `['--docs-path', '<path1>', '--docs-path', '<path2>', ...]` (one flag per file, in order) |
 | Single existing directory | `['--docs-dir', '<path>']` |
 | Anything else | Ask the user to clarify, STOP. |
 
 `docs_target` is reused **verbatim** on every iteration in Step 5 and Step 7 — never change it mid-run.
 
-**Directory-target note.** Per `docs-review`'s established contract, `--docs-dir <p>` reviews only the top-level `.md` files directly under `<p>` (not recursive). This is intentional. The loop inherits that scope; if the user wants nested docs reviewed, they invoke the loop once per subdirectory or against a single `.md` path.
+**Directory-target note.** Per `docs-review`'s established contract, `--docs-dir <p>` reviews only the top-level `.md` files directly under `<p>` (not recursive). This is intentional. The loop inherits that scope; if the user wants nested docs reviewed, they invoke the loop once per subdirectory or against an explicit file path of any type.
 
 ### Step 2 — Confirm agent-teams availability
 

skills/hyper-docs-review/SKILL.md

@@ -31,7 +31,7 @@ Apply this regex to the trimmed `$ARGUMENTS`:
 ^((?:(?!--)\S+\s*)*)(?:--diff-base\s+(\S+))?(?:\s*(--resume)(?:\s+(\S+))?)?\s*$
 ```
 
-- Group 1 = zero or more space-separated leading path tokens (split on whitespace in Step 1); each is either an existing `.md` file or, if it's the sole token, an existing directory; empty defaults to `docs/`. Negative lookahead per-token prevents matching `--diff-base` or `--resume` as a path. Many `.md` files OR one directory — never both.
+- Group 1 = zero or more space-separated leading path tokens (split on whitespace in Step 1); each is either an existing file (any type — not just `.md`) or, if it's the sole token, an existing directory; empty defaults to `docs/`. Negative lookahead per-token prevents matching `--diff-base` or `--resume` as a path. Many files OR one directory — never both.
 - Group 2 = optional `--diff-base <ref>` value
 - Group 3 = literal `"--resume"` token (truthy when present, undefined when not)
 - Group 4 = optional resume artifact path
@@ -42,6 +42,7 @@ When Group 3 is `'--resume'` (truthy) and Group 4 is undefined, treat as `--resu
 - `/hyperclaude:hyper-docs-review` — reviews `docs/`, fresh run
 - `/hyperclaude:hyper-docs-review docs/api.md` — reviews single file, fresh run
 - `/hyperclaude:hyper-docs-review README.md docs/workflow.md docs/architecture.md` — reviews three files, fresh run
+- `/hyperclaude:hyper-docs-review README.md site/index.html` — mixed file types (`.md` + `.html`), fresh run
 - `/hyperclaude:hyper-docs-review --resume` — reviews `docs/`, resumes from latest artifact
 - `/hyperclaude:hyper-docs-review --resume <prev-artifact-path>` — resumes from explicit artifact
 - `/hyperclaude:hyper-docs-review docs/api.md --diff-base main` — single file with diff context
@@ -58,14 +59,14 @@ See `${CLAUDE_PLUGIN_ROOT}/references/bridge-review-calls.md` for the shared `--
 
 ### Step 1 — Resolve target
 
-Split Group 1 on whitespace into tokens (or default to `docs/` when empty). Verify each path exists first via Bash (`[ -e "<path>" ]`).
+Split Group 1 on whitespace into tokens (or default to `docs/` when empty). Classify each token via Bash — `[ -f "<path>" ]` (existing file → `--docs-path`) vs `[ -d "<path>" ]` (existing directory → `--docs-dir`); a token that is neither → STOP.
 
 | Group 1 tokens | Bridge argv |
 |---|---|
 | Empty | `['docs-review', '--docs-dir', 'docs/']` |
-| One or more `.md` paths that exist | `['docs-review', '--docs-path', '<path1>', '--docs-path', '<path2>', ...]` (one flag per file, in order) |
+| One or more existing files (each `[ -f ]`, any type) | `['docs-review', '--docs-path', '<path1>', '--docs-path', '<path2>', ...]` (one flag per file, in order) |
 | Single existing directory path | `['docs-review', '--docs-dir', '<path>']` |
-| Anything else (mix of files and a dir, non-`.md` path, or a path that doesn't exist) | Tell user the contract, ask to clarify, STOP. |
+| Anything else (mix of files and a dir, more than one directory, or a path that doesn't exist) | Tell user the contract, ask to clarify, STOP. |
 
 ### Step 2 — Run the bridge