pi-gauntlet 5.23.0 → 6.0.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## v6.0.0 - 2026-09-30
+
+### Changed
+
+- **Breaking:** `skills/forge-skill/` replaces the former skill-authoring skill: one 68-line rules-first `SKILL.md` (pi and Claude Code conventions table, eleven authoring rules, a five-step edit procedure, an optional two-worker A/B test) and no `reference/` files; the three reference documents (Anthropic best-practices copy, persuasion research, subagent testing recipes) are removed. Consumers invoking the old `/skill:` name switch to `/skill:forge-skill`; AGENTS core `v8` routes skill, persona, and prompt edits to it. `forge-skill` is exposed to Claude Code as the sixth marketplace skill (`/gauntlet:forge-skill`). `scripts/model-literal-lint.mjs` drops its only path exclusion (`EXCLUDED_PREFIXES = []`).
+
+## v5.23.1 - 2026-09-27
+
+### Changed
+
+- `gauntlet-spec-index` prints a one-line stderr note (`<corpus> corpus has <n> documents - too small for the confidence rule; no rows returned`) when a query returns no rows on a corpus under 10 documents; stdout and exit code are unchanged. The brainstorming scout carries the reason as `Predecessor: none (specs corpus too small: <n> documents)` / `Docs touched: none (docs corpus too small: <n> documents)`.
+
 ## v5.23.0 - 2026-09-27
 
 ### Added
@@ -110,7 +122,7 @@
 
 ## v5.16.0 - 2026-09-20
 
-- Skills never name a provider or model: `subagent-driven-development` drops its `## Model Selection` tier table for a one-place `## Model` rule (a dispatch's `model:` is omitted, or carries a `gauntlet_setting` value, a user-named model, or the main loop's own string); `doc/configuration.md` gains `### Dispatch model precedence`; `scripts/model-literal-lint.mjs` bans provider/model literals in `skills/`, `agents/`, `extensions/` from `scripts/ci.mjs`. `writing-skills` widens its trigger to personas and prompt templates and adds `## Authoring rules` (imperative voice, low conditionality, minimal diff, oversized-skill extraction); AGENTS core `v6` makes it binding for every skill, persona, and prompt edit. `shape-ticket` and `conformance-check.md` name the main-loop-string provenance explicitly. (#42)
+- Skills never name a provider or model: `subagent-driven-development` drops its `## Model Selection` tier table for a one-place `## Model` rule (a dispatch's `model:` is omitted, or carries a `gauntlet_setting` value, a user-named model, or the main loop's own string); `doc/configuration.md` gains `### Dispatch model precedence`; `scripts/model-literal-lint.mjs` bans provider/model literals in `skills/`, `agents/`, `extensions/` from `scripts/ci.mjs`. `forge-skill` widens its trigger to personas and prompt templates and adds `## Authoring rules` (imperative voice, low conditionality, minimal diff, oversized-skill extraction); AGENTS core `v6` makes it binding for every skill, persona, and prompt edit. `shape-ticket` and `conformance-check.md` name the main-loop-string provenance explicitly. (#42)
 
 ## v5.15.0 - 2026-09-20
 
@@ -328,7 +340,7 @@
 
 ## v5.0.0 - 2026-08-23
 
-- **Breaking:** `skills/systematic-debugging/` removed (7 files) with active references cleaned (`dispatching-parallel-agents`, `writing-skills`, README); historical `doc/specs/**` and CHANGELOG references retained. Consumers referencing `/skill:systematic-debugging` must migrate to `/skill:chase-bug` for triage.
+- **Breaking:** `skills/systematic-debugging/` removed (7 files) with active references cleaned (`dispatching-parallel-agents`, `forge-skill`, README); historical `doc/specs/**` and CHANGELOG references retained. Consumers referencing `/skill:systematic-debugging` must migrate to `/skill:chase-bug` for triage.
 - New skill `chase-bug` (explicit-invocation-only): human-driven bug triage - origin intake, prior-report search (open + closed, own resolution ladder), three-phase read-only root-cause discovery with a run-falsification evidence bar, an evidenced verdict menu (real bug: file ticket / brainstorm now / respond-only, exactly one `[recommended]`; five negative verdicts with named citation sources), then a gated response-to-origin (exact `send it` confirmation). Baseline-relative zero-mutation invariant (`git status --porcelain --untracked-files=no` at invocation / pre-menu / end); origin text fenced as untrusted data; exactly two human gates. Exposed via the Claude Code marketplace (4-skill allowlist).
 - AGENTS.md gold rule: agent-initiated writes to human-readable channels are gated on exact-text confirmation; obra coverage 12-of-14 -> 11-of-14 (total stays 16).
 
@@ -710,7 +722,7 @@ is deduplicated, and this repo now dogfoods its own workflow (GitHub #1 + folded
 - **Part D - self-hosting mandate.** `AGENTS.md` mandates the full gauntlet for this
   repo's own non-trivial changes and reframes the direct-edit recipes as implement-phase
   mechanics.
-- **Part E - file-placement convention.** `writing-skills` codifies dispatch-payload
+- **Part E - file-placement convention.** `forge-skill` codifies dispatch-payload
   templates as `SKILL.md` siblings vs deep guidance in `reference/` (destination, not format).
 
 ## v4.1.0 - 2026-07-02
@@ -1012,7 +1024,7 @@ Root cause: `plan_tracker` is execution-only by intent, but nothing enforced it.
 - **writing-plans:** drop `plan-document-reviewer-prompt.md` subagent dispatch from the Self-Review step. Align with obra v5.0.6 — inline self-review only. The dispatch added ~25 min/run with no measured quality gain and contradicted the repo's no-belt-and-suspenders rule.
 - **using-git-worktrees:** port obra v5.1.0 Step 0 improvements — robust path resolution via `cd && pwd -P` wrapping, submodule guard via `git rev-parse --show-superproject-working-tree` (replaces fragile `.git is a file` heuristic), branch-state reporting after detection.
 - **using-git-worktrees:** port obra v5.1.0 Step 1a improvements — explicit native-tool name anchors (`EnterWorktree`, `WorktreeCreate`, `/worktree`, `--worktree`). Upstream TDD showed compliance jumped from 2/6 to 50/50 with explicit names.
-- **writing-skills:** fix dead reference to `examples/CLAUDE_MD_TESTING.md` in `reference/testing-skills-with-subagents.md`. File was never ported; replaced with pointer to upstream `obra/superpowers` repo.
+- **forge-skill:** fix dead reference to `examples/CLAUDE_MD_TESTING.md` in `reference/testing-skills-with-subagents.md`. File was never ported; replaced with pointer to upstream `obra/superpowers` repo.
 - **README:** fix broken link — `mariozechner/pi` → `badlogic/pi-mono` (was 404).
 - **AGENTS.md:** improve verification grep example — replace meaningless `specific.company.name` placeholder with realistic patterns (`jjuraszek`, `/Users/[^/]+`, `<your-org-name>`).
 - **extensions:** add `phase-tracker.ts` — tracks workflow phase (brainstorm → plan → implement → verify → ship) with a TUI widget. Session-state only, no disk persistence.
@@ -1023,7 +1035,7 @@ Root cause: `plan_tracker` is execution-only by intent, but nothing enforced it.
 - **Agents:** add `thinking`, `defaultContext`, `inheritSkills` frontmatter to all three personas. Previously these knobs were documented in `AGENTS.md` but missing from the agent files, so dispatch fell back to pi-cohort defaults (typically `thinking: high`, no defaultContext override). Now: reviewers use `thinking: high` + `defaultContext: fresh`; implementer uses `thinking: medium` + `defaultContext: fork`. All three use `inheritSkills: false` to prevent recursive skill discovery in dispatched children.
 - **AGENTS.md:** correct false claim that `plan-tracker.ts` accepts settings — it has no configurable knobs. Tighten the package-conventions section. Document the divergence from `obra/superpowers` v5.1.0 (they dropped `agents/`, we keep them as pi-cohort profiles) and explain why `using-superpowers` is intentionally absent.
 - **README.md:** rewrite for human readability, expand the project-overrides section with a concrete example, fix the version pin from `v0.1.0` to `v0.1.1`.
-- **skills/writing-skills/SKILL.md:** drop project-specific references; broaden the "Where Skills Live in Pi" table to include the package-distributed path; update extension references to reflect package distribution.
+- **skills/forge-skill/SKILL.md:** drop project-specific references; broaden the "Where Skills Live in Pi" table to include the package-distributed path; update extension references to reflect package distribution.
 
 ## v0.1.1 — 2026-05-28
 

package/README.md

@@ -69,7 +69,7 @@ Everything between gate 1 and gate 2 - task breakdown, implementation, both revi
 
 pi-gauntlet ships three kinds of pieces, layered on top of pi-cohort's dispatch:
 
-- **20 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `writing-skills`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Seven more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
+- **20 skills** - the workflow logic. Thirteen activate automatically when pi sees the matching kind of task, and each one gates the next: `brainstorming`, `writing-plans`, `roasting-the-spec`, `test-driven-development`, `subagent-driven-development`, `dispatching-parallel-agents`, `verification-before-completion`, `requesting-code-review`, `receiving-code-review`, `using-git-worktrees`, `finishing-a-development-branch`, `forge-skill`, `linear` (reads/searches/comments on/manages Linear tickets via the `linearis` CLI; owns all linearis mechanics and the `## Issue tracker` overrides schema; tracker-facing skills route to it). Seven more are explicit-invocation-only (`disable-model-invocation: true`): `shape-ticket` creates or repairs one tracker issue per run against a Context/Problem/Idea/Acceptance-Criteria template, gated by an AC integrity check, a cheap council roast, and a single human-confirmed write - run it with `/skill:shape-ticket`. `gatekeep-pr` is consent-gated pre-merge verification of a PR against its issue - read-only gathering, verification evidence resolved CI-first (green checks on the exact assessed head count as evidence; the project's verification command runs only as fallback), a rubric-based review, then a deterministic authorship-aware menu with stable finding IDs (P#/L#/C#/F#) and numbered pre-composed courses (fixes execute as a single parallel-safe wave: one gate run, one re-review, one push); nothing mutates (fixes, pushes, reviews, merges) until you pick a row - run it with `/skill:gatekeep-pr <pr>`. `check-delivery` is a post-merge detective control: proves an issue actually shipped (default-branch landing, delivery target, per-AC evidence) before its tracker status advances; it never writes a terminal status - run it with `/skill:check-delivery <ref>`. `chase-bug` is human-only bug triage: read-only root-cause discovery to an evidenced verdict menu (real bug -> ticket/brainstorm/hotfix/respond; five negative verdicts), then a gated response to the reporter for addressable origins (GitHub issue / tracker ticket) and a rendered verdict summary otherwise - it never fixes during triage; the hotfix row hands off to `skills/chase-bug/hotfix.md` after the menu - run it with `/skill:chase-bug`. `gauntlet-performance` reads the committed run telemetry (current repo by default, `--dir <path>` adds others) through the parse-only `gauntlet-performance` CLI and answers with one example-led recommendation, 3-5 cornerstone numbers, a council assessment when available, and a menu of at most three actions (render a report file, open the recommendation as a ticket via `shape-ticket`, drill into one run); it writes nothing unless you pick render - run it with `/skill:gauntlet-performance [--dir <path>]... [--since <version>]`. `gauntlet-handoff` ends a session whose flow a fresh session will continue: it invokes pi-cohort's `handoff` skill (`--out <path>` or `--key <name>`, default key = the run worktree's branch with `/` flattened to `-`, default file `<tmpdir>/pi-handoff/<key>.md`), then appends the gauntlet process-state section (phase/plan tracker status) per the shared contract `skills/gauntlet-resume/reference/brief-contract.md` - run it with `/skill:gauntlet-handoff [--out <path> | --key <name>]`. `gauntlet-resume` is the only way back into an interrupted flow from a fresh session: it takes a `gauntlet-handoff` brief (a file path, pasted text, or - with no arguments - a pick from the briefs under `<tmpdir>/pi-handoff/`), a bare worktree that already holds a spec, or a spec tracked on main under a configured spec dir (a spec seed: it creates or reuses the worktree through `using-git-worktrees` and pins the spec), restores phase/plan tracker state through the legal arming sequence (`start brainstorm`, `skip` with `resume:` reasons, `plan_check` before implement-or-later), and never infers approval from artifacts - run it with `/skill:gauntlet-resume [<brief-file> | <spec>.md | <worktree-name-or-path>]`.
 - **7 subagent personas** - the specialized child agents the skills dispatch via pi-cohort: `implementer`, `code-reviewer`, `spec-reviewer`, `conformance-reviewer`, `spec-summarizer`, `spec-council-member`, `spec-council-synthesizer`. See [doc/personas.md](./doc/personas.md) for what each one does and why its permissions are scoped the way they are.
 - **4 runtime extensions** - the enforcement layer. `plan-tracker` and `phase-tracker` are tools skills call to track progress (with a TUI widget); `verify-before-ship` is a hook that warns if you push or open a PR without a passing test run since your last edit; a phase-tracker flow guard reminds on implement-phase commits missing spec/code review. In a brainstorming-entered flow, phase-tracker rejects `implement` or `verify` completion while tracker tasks remain pending or in progress; see [its configuration reference](./doc/configuration.md#phase-tracker). phase-tracker also registers `plan_check`, which verifies a plan against its spec and against the grammar in [skills/writing-plans/reference/plan-contract.md](./skills/writing-plans/reference/plan-contract.md), including that each task's `Tests:` commands are selective and never the full suite; a pass stamps the plan for implementation. `telemetry` records one YAML record per gauntlet run (phase timing, models, personas, gate/fix rounds, diff at ship) that ships in the squash beside the spec - it is written only inside a brainstorming-entered flow, kept untracked and git-excluded until `finishing-a-development-branch` seals and commits it once with `gauntlet-telemetry-seal` - and blocks a brainstorm `write` into an already-shipped spec; see [its configuration reference](./doc/configuration.md#telemetry). See [doc/configuration.md](./doc/configuration.md) for the settings each one reads.
 
@@ -113,7 +113,7 @@ Run by a human against pi-cohort >= 7.1.0, before a pi-gauntlet release claims t
 ## Requirements
 
 - [pi-coding-agent](https://github.com/earendil-works/pi) ≥ 0.85.1 - tested minimum for sequential `phase_tracker` tool execution, which persists a tracker update before a later tool call in the same model message.
-- [pi-cohort](https://github.com/jjuraszek/pi-cohort) ≥ 1.4.5 - required peer package. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `writing-skills`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics.
+- [pi-cohort](https://github.com/jjuraszek/pi-cohort) ≥ 1.4.5 - required peer package. Skills that dispatch agents (`requesting-code-review`, `subagent-driven-development`, `dispatching-parallel-agents`, `writing-plans`, `forge-skill`, `shape-ticket`, `roasting-the-spec`) call `subagent({})`, which pi-cohort provides. pi-gauntlet does not vendor the dispatch tool; without pi-cohort those skills have nothing to call. Gauntlet execution dispatches explicitly use `async: false`; do not enable pi-cohort's incompatible `forceTopLevelAsync` setting. See pi-cohort's [dispatch configuration](https://github.com/jjuraszek/pi-cohort/blob/main/doc/configuration.md) for that setting's owner and semantics.
 
 Both packages must be listed in your `.pi/settings.json#packages` array (pi adds them automatically when you `pi install`). pi-gauntlet and pi-cohort are versioned independently but release together whenever dispatch semantics change - pin compatible versions of both.
 
@@ -137,7 +137,7 @@ Pin an exact release with `npm:pi-gauntlet@X.Y.Z`. See [doc/install-internals.md
 
 ## Spec search index
 
-`gauntlet-spec-index` provides lexical search over two corpora in one per-worktree cache. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--corpus specs|docs] [--limit N] [--exclude <repo-relative path>]...`; it requires Node >=24.15.0 and refreshes its FTS5 index on every query. `--corpus specs` (the default) searches `doc/specs/*.md` at the repository root and one service level down and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `state`, `files`, and `snippet` columns. `--corpus docs` searches project documentation and prints `score`, `path`, `title`, and `snippet`; the snippet is the matched `##`/`###` heading line when one holds a query term, else a body fragment. Docs candidates are the tracked and untracked, non-gitignored `*.md` files (`git ls-files -co --exclude-standard`, so nested repositories and submodules are not indexed) matching an include list - default `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`, where a slash-free entry also matches one service level down - minus the fixed exclusions `**/doc/specs/**`, `**/docs/specs/**`, `**/doc/plans/**`, `**/docs/plans/**`, `**/node_modules/**`, `.pi/gauntlet/**`, `.worktrees/**`, symlinks, and files whose first line is the context-draft marker; `**` never matches a dot directory, so `.pi/*.md` or `.github/*.md` is indexed only through an explicit include. A project replaces the include list with `- docs: <glob>` bullets under a `## Spec index` heading in its gauntlet overrides file (see [Project-specific overrides](#project-specific-overrides)); the exclusions are not configurable. Both corpora pass the same confidence rule before `--limit` applies: a query term is evidence when it occurs in fewer than half the rows of the queried table (stem variants of one word count once); query tokens split on word boundaries, so `gauntlet-spec-index` searches as three words; a row is returned only when it matches at least two distinct evidence terms in the corpus's strong fields - `title` or `goal` for specs, `title` or `headings` for docs - and rows scoring below half the best live row's score are dropped (every docs row is live). A query with no real match therefore prints the header only and exits 0, and a corpus of two or fewer files never returns rows. `--exclude` (repeatable) removes a path before the rule runs, so the spec under review never sets the bar. `state` is `superseded` when a `> **Superseded by:** ... - fully` banner sits in the block directly under the title and `live` otherwise; named-section banners and consumer-defined banner syntaxes both read as `live`. Live rows sort before superseded rows, then by score. The `files` column is a `;`-separated list of repo-relative paths the spec's shipped change modified and that still exist in the repository, the literal `missing` when the spec's telemetry record has no `derived.modified_files` list, or blank when there is no readable record or no recorded path remains. The cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`. `/skill:brainstorming` queries the specs corpus twice - the scout at gather time from the request, and the main loop at spec-writing from the finished spec's title, goal, and headings, surfacing new `live` candidates at the review gate - and the scout queries the docs corpus once to render `Docs touched:` lines that round 2 weighs as documentation-impact candidates.
+`gauntlet-spec-index` provides lexical search over two corpora in one per-worktree cache. From a repository worktree, run `node <pi-gauntlet-package>/bin/gauntlet-spec-index.mjs --query "<text>" [--corpus specs|docs] [--limit N] [--exclude <repo-relative path>]...`; it requires Node >=24.15.0 and refreshes its FTS5 index on every query. `--corpus specs` (the default) searches `doc/specs/*.md` at the repository root and one service level down and prints tab-separated `score`, `path`, `service`, `title`, `status`, `shipped_at`, `state`, `files`, and `snippet` columns. `--corpus docs` searches project documentation and prints `score`, `path`, `title`, and `snippet`; the snippet is the matched `##`/`###` heading line when one holds a query term, else a body fragment. Docs candidates are the tracked and untracked, non-gitignored `*.md` files (`git ls-files -co --exclude-standard`, so nested repositories and submodules are not indexed) matching an include list - default `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`, where a slash-free entry also matches one service level down - minus the fixed exclusions `**/doc/specs/**`, `**/docs/specs/**`, `**/doc/plans/**`, `**/docs/plans/**`, `**/node_modules/**`, `.pi/gauntlet/**`, `.worktrees/**`, symlinks, and files whose first line is the context-draft marker; `**` never matches a dot directory, so `.pi/*.md` or `.github/*.md` is indexed only through an explicit include. A project replaces the include list with `- docs: <glob>` bullets under a `## Spec index` heading in its gauntlet overrides file (see [Project-specific overrides](#project-specific-overrides)); the exclusions are not configurable. Both corpora pass the same confidence rule before `--limit` applies: a query term is evidence when it occurs in fewer than half the rows of the queried table (stem variants of one word count once); query tokens split on word boundaries, so `gauntlet-spec-index` searches as three words; a row is returned only when it matches at least two distinct evidence terms in the corpus's strong fields - `title` or `goal` for specs, `title` or `headings` for docs - and rows scoring below half the best live row's score are dropped (every docs row is live). A query with no real match therefore prints the header only and exits 0 - and when the queried corpus has fewer than 10 documents, also writes one stderr line naming the corpus and its size (`gauntlet-spec-index: docs corpus has 5 documents - too small for the confidence rule; no rows returned`), so a small corpus and a genuine miss stay distinguishable; a corpus of two or fewer files never returns rows. `--exclude` (repeatable) removes a path before the rule runs, so the spec under review never sets the bar. `state` is `superseded` when a `> **Superseded by:** ... - fully` banner sits in the block directly under the title and `live` otherwise; named-section banners and consumer-defined banner syntaxes both read as `live`. Live rows sort before superseded rows, then by score. The `files` column is a `;`-separated list of repo-relative paths the spec's shipped change modified and that still exist in the repository, the literal `missing` when the spec's telemetry record has no `derived.modified_files` list, or blank when there is no readable record or no recorded path remains. The cache lives at `.pi/gauntlet/index.sqlite`, and its first creation adds `/.pi/gauntlet/index.sqlite*` to Git's `info/exclude` so the database and SQLite sidecars stay out of `git status`. `/skill:brainstorming` queries the specs corpus twice - the scout at gather time from the request, and the main loop at spec-writing from the finished spec's title, goal, and headings, surfacing new `live` candidates at the review gate - and the scout queries the docs corpus once to render `Docs touched:` lines that round 2 weighs as documentation-impact candidates.
 
 ## Performance digest
 
@@ -154,20 +154,27 @@ pi install -l ~/repos/pi-gauntlet
 
 ## Use from Claude Code
 
-Five skills are exposed to Claude Code via the plugin marketplace at
+Six skills are exposed to Claude Code via the plugin marketplace at
 `.claude-plugin/marketplace.json`: **shape-ticket**, **gatekeep-pr**,
-**check-delivery**, **chase-bug**, and **linear**. They are harness-portable by design - every pi-specific
-mechanic they touch (`plan_tracker`, `gauntlet_setting`, `subagent()`) carries
-an inline fallback, so they run on Claude Code's native facilities. This is the
-supported set. Not exposed, in two classes: (a) genuinely pi-bound surface -
-the full gated pipeline (brainstorming -> writing-plans ->
-subagent-driven-development -> verify -> finish), the spec council, the
-conformance gate, flow guards, verify-before-ship, and all `piGauntlet.*`
-settings, which depend on pi extensions; (b) runtime-neutral skills
-(e.g. `receiving-code-review`, `using-git-worktrees`) that
-are simply out of scope for this channel, not incompatible - re-adding one is a
-one-line allowlist append. For Claude-Code-native equivalents of the
-methodology skills, see [obra/superpowers](https://github.com/obra/superpowers).
+**check-delivery**, **chase-bug**, **linear**, and **forge-skill**. They are
+harness-portable by design - every pi-specific mechanic they touch
+(`plan_tracker`, `gauntlet_setting`, `subagent()`) carries an inline fallback,
+so they run on Claude Code's native facilities. `forge-skill` is the authoring
+skill for skills, personas, prompt templates, and slash commands under
+gauntlet's conventions (imperative voice, minimal diff, low conditionality,
+extraction over 500 lines); Claude Code namespaces plugin skills, so it lists
+as `/gauntlet:forge-skill` and coexists with the skill-authoring skill of
+[obra/superpowers](https://github.com/obra/superpowers) - invoke the one
+whose conventions the repo follows. This is the supported set. Not exposed,
+in two classes: (a) genuinely pi-bound surface - the full gated pipeline
+(brainstorming -> writing-plans -> subagent-driven-development -> verify ->
+finish), the spec council, the conformance gate, flow guards,
+verify-before-ship, and all `piGauntlet.*` settings, which depend on pi
+extensions; (b) runtime-neutral skills (e.g. `receiving-code-review`,
+`using-git-worktrees`) that are simply out of scope for this channel, not
+incompatible - re-adding one is a one-line allowlist append. For
+Claude-Code-native equivalents of the methodology skills, see
+[obra/superpowers](https://github.com/obra/superpowers).
 
 ### Setup
 
@@ -230,9 +237,9 @@ exact repo folder* in interactive Claude Code. Trusting a parent folder,
 4. Run `/plugin` and confirm: marketplace `pi-gauntlet` is listed, plugin
    `gauntlet` is enabled. If it shows as known but not installed, run
    `/plugin install gauntlet@pi-gauntlet` and re-check.
-5. Confirm exactly five skills are registered under the plugin (via the
+5. Confirm exactly six skills are registered under the plugin (via the
    `/plugin` details view): shape-ticket, gatekeep-pr, check-delivery, chase-bug,
-   linear.
+   linear, forge-skill.
 6. Invoke `/gauntlet:shape-ticket` with a deliberately two-concern ask (e.g.
    "shape a ticket: CSV import for operators, plus a partner-facing status
    API") so the skill deterministically consults its

package/bin/gauntlet-spec-index.mjs

@@ -10,6 +10,8 @@ const SCHEMA_VERSION = 3;
 const EVIDENCE_DF_FRACTION = 0.5;
 const MIN_EVIDENCE_TOKENS = 2;
 const SCORE_RATIO = 0.5;
+// Policy floor, not derived from the rule: below it an empty result says little about coverage.
+const MIN_CORPUS = 10;
 // Default banner grammar of skills/brainstorming/reference/superseding.md; a named-section
 // scope or anything after `- fully` keeps the spec live.
 const FULLY_BANNER = /^> \*\*Superseded by:\*\* \[.*\]\(.*\) - fully$/;
@@ -307,7 +309,7 @@ function query(db, corpus, toks, { limit, exclude }) {
     if (all.size === 0 || all.size >= n * EVIDENCE_DF_FRACTION) continue;
     evidence.push({ all, strong: rowids(corpus.strong.map((f) => `${f}:${quote(tok)}`).join(" OR ")) });
   }
-  if (evidence.length < MIN_EVIDENCE_TOKENS) return [];
+  if (evidence.length < MIN_EVIDENCE_TOKENS) return { rows: [], n };
   const rows = db.prepare(
     `SELECT rowid, ${corpus.select}, bm25(${table}, ${corpus.weights.map((w) => w.toFixed(1)).join(", ")}) AS score
      FROM ${table} WHERE ${table} MATCH ?`,
@@ -317,7 +319,7 @@ function query(db, corpus, toks, { limit, exclude }) {
   kept.sort((a, b) => Number(!live(a)) - Number(!live(b)) || a.score - b.score);
   const best = kept.find(live);
   const cut = best ? kept.filter((r) => Math.abs(r.score) >= SCORE_RATIO * Math.abs(best.score)) : kept;
-  return cut.slice(0, limit);
+  return { rows: cut.slice(0, limit), n };
 }
 
 function telemetry(root, specPath) {
@@ -394,10 +396,13 @@ async function main() {
   const corpus = CORPORA[name];
   const db = await openDb(root);
   refresh(db, root, corpus);
-  const rows = query(db, corpus, toks, { limit, exclude });
+  const { rows, n } = query(db, corpus, toks, { limit, exclude });
   const out = [corpus.header.join("\t")];
   for (const r of rows) out.push(corpus.format(root, r).join("\t"));
   process.stdout.write(out.join("\n") + "\n");
+  if (rows.length === 0 && n < MIN_CORPUS) {
+    process.stderr.write(`gauntlet-spec-index: ${name} corpus has ${n} documents - too small for the confidence rule; no rows returned\n`);
+  }
   db.close();
 }
 

package/bin/gauntlet-spec-index.test.mjs

@@ -43,6 +43,16 @@ const commit = (root) => {
 };
 // Fillers keep the corpus large enough that two-document probe terms stay below N/2.
 const filler = (n) => `# Filler ${n}\n\n**Goal:** filler goal ${n}.\n\n## Design\n\nnothing of note here\n`;
+const boundaryRepo = (fillers) => {
+  const root = gitRepo();
+  const common = (n) => `# Plain spec ${n}\n\n**Goal:** plain goal ${n}.\n\nThe body mentions the common shared vocabulary.\n`;
+  write(root, "doc/specs/strong.md", "# Strong heron ibis\n\n**Goal:** heron ibis jackal.\n\nbody\n");
+  for (let n = 1; n <= 5; n++) write(root, `doc/specs/p${n}.md`, common(n));
+  for (const f of fillers) write(root, `doc/specs/filler-${f}.md`, filler(f));
+  commit(root);
+  return root;
+};
+const NOTE = "too small for the confidence rule; no rows returned";
 
 const repo = () => {
   const root = gitRepo();
@@ -357,6 +367,50 @@ test("16: punctuation splits into distinct evidence terms and query order does n
   assert.deepEqual(paths(run(root, ["--query", "config config-file"])), paths(run(root, ["--query", "config-file config"])));
 });
 
+test("21: three-spec corpus, no match - header only plus the small-corpus note", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  for (const n of ["one", "two", "three"]) write(root, `doc/specs/filler-${n}.md`, filler(n));
+  commit(root);
+  const r = run(root, ["--query", "yeti unicorn"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.header, HEADER);
+  assert.deepEqual(r.rows, []);
+  assert.equal(r.stderr, `gauntlet-spec-index: specs corpus has 3 documents - ${NOTE}\n`);
+});
+
+test("22: MIN_CORPUS boundary - note at N = 9, silent at N = 10, rows unaffected", (t) => {
+  const root = boundaryRepo(["one", "two", "three"]);
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const nine = run(root, ["--query", "yeti unicorn"]);
+  assert.equal(nine.status, 0, nine.stderr);
+  assert.deepEqual(nine.rows, []);
+  assert.equal(nine.stderr, `gauntlet-spec-index: specs corpus has 9 documents - ${NOTE}\n`);
+  write(root, "doc/specs/filler-four.md", filler("four"));
+  commit(root);
+  for (const q of ["yeti unicorn", "common shared"]) {
+    const r = run(root, ["--query", q]);
+    assert.equal(r.status, 0, r.stderr);
+    assert.deepEqual(r.header, HEADER);
+    assert.deepEqual(r.rows, []);
+    assert.equal(r.stderr, "");
+  }
+  const strong = run(root, ["--query", "heron ibis jackal common", "--limit", "10"]);
+  assert.equal(strong.status, 0, strong.stderr);
+  assert.deepEqual(paths(strong), ["doc/specs/strong.md"]);
+  assert.equal(strong.stderr, "");
+});
+
+test("23: n is the table count before --exclude", (t) => {
+  const root = boundaryRepo(["one", "two", "three", "four"]);
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  const r = run(root, ["--query", "yeti unicorn", "--exclude", "doc/specs/p1.md"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(r.header, HEADER);
+  assert.deepEqual(r.rows, []);
+  assert.equal(r.stderr, "");
+});
+
 test("D1: --corpus specs and omitted --corpus are byte-identical; nine columns", (t) => {
   const root = repo();
   t.after(() => rmSync(root, { recursive: true, force: true }));
@@ -420,6 +474,7 @@ test("D2: docs include defaults and fixed exclusions", (t) => {
   assert.equal(tiny.status, 0, tiny.stderr);
   assert.deepEqual(tiny.header, DOCS_HEADER);
   assert.deepEqual(tiny.rows, []);
+  assert.equal(tiny.stderr, `gauntlet-spec-index: docs corpus has 2 documents - ${NOTE}\n`);
 });
 
 test("D3: shared confidence rejects common body-only hits", (t) => {
@@ -558,3 +613,15 @@ test("D10: fenced headings and shorter nested fences are ignored", (t) => {
   run(root, ["--corpus", "docs", "--query", "ptarmigan gannet"]);
   for (const p of ["doc/f.md", "doc/nested.md"]) assert.equal(withDb(root, (db) => db.prepare("SELECT headings FROM docs WHERE path = ?").get(p).headings), "");
 });
+
+test("D13: five-document docs corpus with rare heading terms returns rows and no note", (t) => {
+  const root = gitRepo();
+  t.after(() => rmSync(root, { recursive: true, force: true }));
+  write(root, "doc/strong.md", "# Strong doc\n\n## heron ibis\n\n## jackal\n\nbody\n");
+  for (let n = 1; n <= 4; n++) write(root, `doc/p${n}.md`, `# Plain doc ${n}\n\nThe body mentions the common shared vocabulary.\n`);
+  commit(root);
+  const r = run(root, ["--corpus", "docs", "--query", "heron ibis jackal common", "--limit", "10"]);
+  assert.equal(r.status, 0, r.stderr);
+  assert.deepEqual(paths(r), ["doc/strong.md"]);
+  assert.equal(r.stderr, "");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-gauntlet",
-  "version": "5.23.0",
+  "version": "6.0.0",
   "description": "Opinionated, gated workflow skills, subagent personas, and runtime extensions for the pi coding agent.",
   "author": "Jacek Juraszek",
   "type": "module",

package/skills/brainstorming/gatherer.md

@@ -58,7 +58,11 @@ Scout (always dispatched):
 > `node <SPEC_INDEX> --query '<keywords>' --limit 10` from the worktree root,
 > keeping the keywords inside single quotes, and treat its rows as the candidate
 > list; zero rows means the index found no evidence, not that no predecessor exists -
-> judge `Predecessor: none` from the code recon. If the command fails, fall back to
+> judge `Predecessor: none` from the code recon. When the command output contains a line
+> ending "too small for the confidence rule; no rows returned" (a diagnostic, not a row) and
+> the code recon names no predecessor, write
+> `Predecessor: none (specs corpus too small: <n> documents)`, copying <n> from that
+> line. If the command fails, fall back to
 > listing the project's spec directory
 > and reading titles and `**Goal:**` lines, and write
 > `Spec index unavailable - predecessor check used directory listing.` in your
@@ -96,7 +100,10 @@ Scout (always dispatched):
 > document (the row's `snippet` column is a hint to it), or the document title when no single
 > section applies; or `Docs touched: none`. Judge by topic; a lexical hit alone is not
 > coverage. Zero rows means the index found no evidence, not that no document covers the
-> topic. This query supplements the code and documentation recon you already perform; it
+> topic. When the docs command output contains that same diagnostic line and the recon
+> found no covering document, write
+> `Docs touched: none (docs corpus too small: <n> documents)` instead. This query
+> supplements the code and documentation recon you already perform; it
 > never replaces it - keep reading the files the request touches. End with an
 > "Open questions that matter for the spec"
 > section. Compact handoff, not a dump.

package/skills/forge-skill/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: forge-skill
+description: Use when creating or editing a SKILL.md, a skill's reference file, an agent persona, a prompt template, or a slash command in pi or Claude Code - including one-line edits - or when such a file exceeds 500 lines, gains if/else branching, or drifts from imperative voice; the authoring skill for repos that follow gauntlet's conventions.
+---
+
+# Forge Skill
+
+## Overview
+
+This skill governs every file a model reads as instructions: `SKILL.md` and its reference files, agent personas, prompt templates, and slash commands, in pi and in Claude Code. Every sentence below is a rule to apply or a fact to check.
+
+## Conventions
+
+Sources: pi - `docs/skills` in `@earendil-works/pi-coding-agent`; Claude Code - `code.claude.com/docs/en/skills`.
+
+| Item | pi | Claude Code |
+|---|---|---|
+| Frontmatter | `---` on line 1, `name` and `description`, closing `---` | Same; an unknown field is ignored silently; unparseable YAML loads the skill with no fields |
+| `name` | Lowercase letters, digits, hyphens; no leading, trailing, or doubled hyphen; at most 64 chars; match the directory name (Agent Skills standard; pi does not enforce it) | Display label for a personal or project skill (the command is the directory name); the last command segment for a plugin skill |
+| `description` | At most 1024 chars; a skill without one is not loaded | Recommended; `description` plus `when_to_use` is cut at 1536 chars in the listing |
+| Harness-only fields | `license`, `compatibility`, `metadata`, `allowed-tools` (spec-listed, not enforced) | `when_to_use`, `argument-hint`, `arguments`, `user-invocable`, `allowed-tools` (enforced) |
+| `disable-model-invocation: true` | Command-only skill | Same; also excluded from subagent preload |
+| Invocation | `/skill:name [args]` | `/name [args]`, or `/plugin:name` for a plugin skill |
+| Supporting files | `reference/<topic>.md` (gauntlet convention; pi docs show `references/`), read at the step that names it; dispatch payloads sit beside `SKILL.md` | Any file linked by relative path; `references/`, `scripts/`, `assets/` by convention; `scripts/` files are executed, not loaded |
+| Substitutions | None; the body is read as written | Argument tokens and `CLAUDE_*` variables in the dollar form expand before the model reads the body. In prose, prefix an argument token with one backslash (backslash, dollar, ARGUMENTS) and name a variable bare (`CLAUDE_SKILL_DIR`) |
+| Locations | `.pi/skills/`, `~/.pi/agent/skills/`, `.agents/skills/`, `~/.agents/skills/`, a package's `skills/` dir | `.claude/skills/`, `~/.claude/skills/`, a plugin's `skills/` dir; `.agents/skills/` is not read |
+| Reload after edit | `/reload` | Watched for `.claude/skills/` and `~/.claude/skills/`; a plugin skill needs a new session |
+
+## Authoring rules
+
+These rules bind the lines an edit adds or changes. Leave other lines alone.
+
+- Imperative voice. Write instructions as commands. Never "should", "consider", "you may want to", "it is recommended".
+- Low conditionality. One path per step: branch only on a runtime fact the model can observe - a tool result, a file's presence, a settings value - never on the reader's judgment. Two branches is the ceiling; a third goes into a table or a `reference/` file.
+- Minimal diff. A rule change touches the sentence that owns the rule, not the section. Never restate a rule in a second place; link the owner.
+- Oversized file. A change touching a file over 500 lines extracts the concern it touches - or the largest self-contained `##` section - into `reference/<topic>.md` in the same change, and leaves a one-line "read X now" pointer at the step that needs it.
+- Recipe over prohibition. A shape or quality problem gets a statement of what the output is; a discipline problem gets one explicit rule. Never a list of things to avoid.
+- No nuance clauses. "Unless it matters", "when appropriate", "if needed" reopen the decision; delete them or name the observable condition.
+- Description is a trigger. State when to load the skill (symptoms, file types, situations); never summarize its steps.
+- One example. One concrete example per rule, never three.
+- Skip what the model knows. No explanations of git, shell, or the harness.
+- Never force-load. Cross-reference a skill by its invocation name (pi `/skill:name`, Claude Code `/name` or `/plugin:name`); never with `@`.
+- ASCII punctuation, compact `|---|` table separators, present tense.
+
+## Edit procedure
+
+1. Read the whole file.
+2. Locate and edit the sentence that owns the rule you are changing (see Minimal diff).
+3. Read the changed lines back against `## Authoring rules`.
+4. Run `wc -l` on the file; over 500 lines, extract per the oversized-file rule.
+5. pi: run `/reload`. Claude Code: start a new session.
+
+## Test (optional)
+
+Run after adding a rule or rewording a discipline rule.
+
+1. Write one scenario prompt the rule governs.
+2. In one turn dispatch two fresh workers: the loaded worker's task is the scenario plus the full `SKILL.md` body; the baseline worker's task is the scenario alone.
+3. Compare the two outputs. Fold every excuse the baseline gives into the rule sentence it evades.
+
+| Harness | Dispatch |
+|---|---|
+| pi | `subagent({ agent: "worker", context: "fresh", task })` twice, one task with the body appended |
+| Claude Code | The harness's subagent dispatch tool, twice, same split |
+
+## Project overrides
+
+If a gauntlet overrides file exists - checked in order: `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins - read it. Read and apply `## conventions` whenever present, without a relevance judgment. Give this skill's named section precedence over conflicting `## conventions` rules. Use other relevant sections - by name match, by topic (routing, verification, worktrees, etc.), or by workflow convention - to override or extend the instructions above. Project-local `AGENTS.md` is already in context - check it for project-specific routing tables, service paths, and verification commands.