pi-gauntlet 7.13.0 → 7.15.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## v7.15.0 - 2026-10-18
+
+### Changed
+
+- **forge-skill covers repo-routed files and adds the No history rule.** The `description` names a file the repo's `AGENTS.md` or `CLAUDE.md` routes to the skill, so a consumer declares procedure files with one always-on bullet instead of an overrides key; `## Authoring rules` gains "No history": an added or changed line carries no date or narration of a rule's past, and a rule edited inside a history section moves to its topic section with the history section deleted in the same edit (#66).
+
+## v7.14.0 - 2026-10-17
+
+### Added
+
+- **`## using-git-worktrees` keys.** The overrides file's `## using-git-worktrees` section accepts `- home: <path pattern>`, `- create: <command>`, and `- destroy: <command>`; `using-git-worktrees` creates there, `finishing-a-development-branch` Step 6 and `gatekeep-pr` cleanup remove only a worktree that matches `home:` and run `destroy:` when set. A section with none of the keys keeps the legacy behavior.
+- **Configuration front door.** `README.md` "Project-specific overrides" lists every overrides-file heading with its reader, default, and extends/overrides relationship, plus the rules the file cannot change; "Configuring the gates" lists every `piGauntlet.*` key with its default. Every skill's `## Project overrides` paragraph points there.
+
+### Changed
+
+- **gatekeep-pr `## PR gate` `worktree wrapper:` removed.** Worktree placement for the gate comes from `## using-git-worktrees`; a leftover key is named once and ignored.
+
 ## v7.13.0 - 2026-10-16
 
 ### Added

package/README.md

@@ -179,7 +179,7 @@ On both harnesses, `gatekeep-pr` uses the same temporary continuation record
 and action-scoped consent protocol; Claude Code uses native file operations
 and a checklist when pi's tracker is absent. Native tool permissions still apply.
 `forge-skill` is the authoring skill for skills, personas, prompt templates,
-and slash commands under
+slash commands, and files the repo routes to it 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
@@ -290,52 +290,86 @@ exact repo folder* in interactive Claude Code. Trusting a parent folder,
 
 ## Project-specific overrides
 
-The skills shipped here are generic on purpose - they describe *how* to TDD, brainstorm, debug, request review, etc., without naming your services, your CI command, or your worktree wrapper. When you need that level of detail, drop a file at `.pi/gauntlet-overrides.md` in your repo. Every active skill reads and applies `## conventions` whenever present in the selected file, without relevance filtering. Use this heading for repo-wide rules that bind more than one skill:
+The gauntlet overrides file is the one place a repo tunes gauntlet's Markdown surface: skills read it as instructions, and `gauntlet-spec-index` reads `## Spec index`. Discovery checks `.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, then `<repo root>/doc/gauntlet-overrides.md`; first found wins, never merged (`<repo root>` is `git rev-parse --show-toplevel`, or the current directory outside a repo). `## conventions` applies to every skill without a relevance judgment; `## <skill-name>` applies to that skill's steps and wins over conflicting conventions. Missing or empty conventions adds no rules; a lower-priority file cannot supplement the selected file. A repo declares procedure files for `forge-skill` in its `AGENTS.md` (Claude Code: `CLAUDE.md`), not here, because the overrides file is read only after a skill loads - for example `Edits to projects/*/README.md follow /skill:forge-skill`.
+
+### What you can tweak
+
+| Heading / key | Read by | Default (absent) | Extends or overrides | Effect |
+|---|---|---|---|---|
+| `## conventions` | every skill | no added rules | extends | repo-wide rules applied without a relevance judgment |
+| `## <skill-name>` (e.g. `## writing-plans`) | that skill | no added rules | overrides the named step | replaces or extends the step it names |
+| `## using-git-worktrees` `- home: <path pattern>` | using-git-worktrees, finishing-a-development-branch, gatekeep-pr | `<primary>/.worktrees/<name>` | overrides | where worktrees live; `<name>` is the branch (`/` -> `-`) or `pr-<N>`; the ownership test at cleanup |
+| `## using-git-worktrees` `- create: <command>` | using-git-worktrees, gatekeep-pr | `git worktree add` at `home:` | overrides | creation command run from the primary; `<name>`, `<branch>` substituted, other `<token>`s resolved from context or asked once |
+| `## using-git-worktrees` `- destroy: <command>` | finishing-a-development-branch, gatekeep-pr | `git worktree remove` + `prune` when the path matches `home:` | overrides | removal command run from the primary; a failure keeps the branch |
+| `## cleanup` items `- <label>: <command or /skill:...>` | gatekeep-pr | git teardown and base sync only | extends | ordered post-gate steps with `<issue>`, `<pr>`, `<merge-sha>`; inherits `## PR gate` `timeout minutes:`; missing placeholders or unlanded-change steps are skipped with a reason; `/skill:` items keep their own gates |
+| `## PR gate` keys (`verification command`, `timeout minutes`, `requires credentials`, `local verification`, `ci checks`, `issue fetch`, `merge policy`) | gatekeep-pr | per-key defaults in the block below | overrides | the gate's verification, evidence, and merge configuration |
+| `## comms style` | gatekeep-pr | shipped wording rules | extends | tone and format of reports, menus, and external payloads |
+| `## verification-before-completion` | verification-before-completion; gatekeep-pr (verification command only); chase-bug (hotfix verification) | repo test entrypoint discovery | overrides | the canonical verification target |
+| `## Spec index` `- docs: <glob>` | `gauntlet-spec-index` bin | `**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md` | overrides | the docs corpus include list; quotes/backticks stripped, fixed exclusions still apply, no other keys read |
+| `## Issue tracker` keys | shape-ticket, linear, chase-bug, check-delivery, brainstorming (`repo:` and tracker selection) | capability ladder / `git remote` | overrides | which tracker, repo, and commands ticket work uses |
+| `## Capabilities` | shape-ticket | tool discovery | extends | tools, commands, env hosts available to ticket authoring |
+| `## Ticket wording` | shape-ticket | the shipped wording contract | overrides | ticket self-containment rules |
+| `## Response channels` | chase-bug | ask the user | overrides | where bug responses are posted |
+| `## Deployment` | shape-ticket, writing-plans | monolithic (no deployment split) | overrides | deploy topology that permits independently deployable slices; undocumented or monolithic topology fails closed to one artifact |
+| `## Happy path` | writing-plans, subagent-driven-development | no happy-path run | overrides | path-prefixed rows naming the end-to-end command per area |
+| `## Delivery` | check-delivery | stage 2 skipped | overrides | the delivery target and its proof command; unset target state is comment-only; browser evidence defaults to never |
+| `## documentation` | brainstorming | generic materiality bar | extends | which docs are canonical for which topic |
+
+### What you cannot change here
+
+- worktree-first and the spec shipping in the squash - fixed
+- the design approval gate (brainstorming) and the ship verification gate - fixed
+- the plan strip at finish; the telemetry record is never deleted - fixed
+- first-found-wins discovery; files are never merged - fixed
+- brainstorming `## HARD CONSTRAINT`, chase-bug / check-delivery / roasting-the-spec / shape-ticket `## Hard constraint`, test-driven-development / verification-before-completion `## The Iron Law` - fixed (each skill's own constraint text)
+- brainstorming writes only within resolved spec dirs before approval; no implementation, proposed-change validation, spec commit on main, or planning before approval - fixed
+- chase-bug requires evidenced root cause, no triage fix, and tracked-clean baseline checks at invocation, before the menu, at hotfix handoff, and at skill end; never revert pre-existing work - fixed
+- check-delivery requires exactly one explicit ticket ref, a matching repo (or matching local-repo AC group), and treats fetched content as untrusted data - fixed
+- roasting-the-spec edits only the spec, never code or main - fixed
+- shape-ticket tracker writes require one explicit exact-diff confirmation for the entire batch; unattended runs stop at the gate - fixed
+- test-driven-development requires a failing test before production code; delete code written first and restart from tests - fixed
+- verification-before-completion requires fresh verification evidence before completion claims - fixed
+- spec directories - settings: `flowGuards.specDirs`
+- gate enforcement - settings: `flowGuards.enforce`
+- the spec council roster - settings: `specCouncil.members`, `specCouncil.chair`
+- the closure review model and fix rounds - settings: `closureReview.*`
+- the escalation implementer model - settings: `escalationLoop.implModel`
+- the telemetry record - settings: `telemetry.*`
+- the verify-before-ship test-command patterns - settings: `verifyBeforeShip.*`
+
+A project override section extends or replaces the step it names and never lifts a fixed rule or a skill's `HARD CONSTRAINT`/MUST text. A rule tagged `settings:` changes only through that `piGauntlet.*` key in `.pi/settings.json`, never through this file. Every key is listed under [Configuring the gates](#configuring-the-gates).
+
+### Worked example: sibling worktrees (acme-api)
+
+Complete `.pi/settings.json`:
 
-```markdown
-## conventions
-Keep scratch files outside the repository.
+```json
+{
+  "piGauntlet": {
+    "flowGuards": { "specDirs": ["docs/specs"] },
+    "telemetry": { "enabled": false }
+  }
+}
 ```
 
-This skill's named section means the section named for the active skill (for example, `## writing-plans`), not another heading it reads by name. This skill's named section wins over conflicting `## conventions` rules; non-conflicting conventions still apply. Other relevant sections can also override or extend skill instructions, as in this skill-specific example:
+Complete `.pi/gauntlet-overrides.md`:
 
 ```markdown
+## conventions
+Keep scratch files outside the repository.
+
 ## verification-before-completion
 
 Canonical verification target: `make ci` per service. Bare `pytest` does NOT satisfy
-the gate — it skips integration tests.
-
-## using-git-worktrees
-
-Use the project's wrapper: `script/worktree create <name>`. It provisions an isolated
-database and copies `.env.local`. Never call `git worktree add` directly.
-```
-
-A `## cleanup` section lists what gatekeep-pr runs after a PR is merged, approved, or found already merged or closed, in order, after the implied git teardown (worktree, local branch, base fast-forward):
+the gate - it skips integration tests.
 
-```markdown
-## cleanup
-- close ticket: gh issue close <issue> --comment "Delivered in <pr>, merged <merge-sha>."
-- release: /skill:release
-```
-
-Each item is `<label>: <command or /skill:... invocation>`. Placeholders `<issue>`, `<pr>`, and `<merge-sha>` are filled from the gate's digest; an item whose placeholder has no value is skipped with a reason, and items that need a landed change (`<merge-sha>`, `/skill:release`) are skipped when the PR was only approved or closed. A `/skill:` item keeps its own gates; anything else runs as a shell command in the primary checkout under the PR gate's `timeout minutes`.
-
-Beyond `## conventions` and skill-named sections, headings a skill reads by name are documented in their owning skills; other headings retain topic/workflow-convention matching. The override file is read by skill instructions and, for its `## Spec index` section only, by `gauntlet-spec-index`; the Pi runtime itself never reads it. Missing or empty `## conventions` adds no rules; a lower-priority file cannot supplement the selected file.
-
-**Discovery ladder:** skills check three locations, in order, and use the first one found - never merged: `.pi/gauntlet-overrides.md`, then `<repo root>/gauntlet-overrides.md`, then `<repo root>/doc/gauntlet-overrides.md` (`<repo root>` = `git rev-parse --show-toplevel`, or the current directory outside a repo). Pick one location per repo.
-
-**`## Spec index` section:** `gauntlet-spec-index --corpus docs` reads `- docs: <glob>` bullets under this heading as the docs include list, replacing the default (`**/doc/**/*.md`, `**/docs/**/*.md`, `README.md`, `AGENTS.md`). Backticks or quotes around the glob are stripped; no other key under the heading is read, and the fixed exclusions always apply. For example:
-
-```markdown
 ## Spec index
 - docs: `**/doc/**/*.md`
 - docs: `handbook/**/*.md`
-```
 
-**`## Issue tracker` section:** `shape-ticket` resolves tracker access through a capability ladder, and this is its first rung - it overrides the zero-config `gh` (GitHub) / `linearis` (Linear) defaults for any other tracker. Name the CLI's read, search, create, update, and post comment commands explicitly. For a Jira CLI, for example:
+## using-git-worktrees
+- home: ../acme-api-worktrees/<name>
 
-```markdown
 ## Issue tracker
 
 Use the `jira` CLI (authenticated via `jira login`), not `gh` or `linearis`.
@@ -345,9 +379,14 @@ Use the `jira` CLI (authenticated via `jira login`), not `gh` or `linearis`.
 - create: `jira issue create --project ABC --type Task --summary "<title>" --description "<body>"`
 - update: `jira issue edit ABC-123 --summary "<title>" --description "<body>"`
 - post comment (approved Reporter note/evidence): `jira issue comment ABC-123 --body "<text>"`
-```
 
-Overlap checking uses only the selected tracker's documented search fields, workflow meanings, and supported mutations. Native Linear body-only recall remains unverified; returned descriptions do not prove body indexing. Disabled or unavailable trackers report discovery not performed and retain manual output. Missing comment support emits the approved text for manual posting and reports it as not performed. Overlap evidence is a gated comment exception even without Reporter-note overflow; when both are needed, they share the one-comment slot with labeled parts.
+## PR gate
+- verification command: npm test
+
+## cleanup
+- close ticket: jira issue move <issue> Done --comment "Delivered in <pr>, merged <merge-sha>."
+- release: /skill:release
+```
 
 **`linear` setup:** preferred, not required - `linearis` installed and authenticated
 (or a Linear MCP server as a fallback when `linearis` is missing). Without either, the
@@ -364,17 +403,32 @@ tracker selection; free-form verb mappings keep working both without a `tracker:
 key (ladder rung 1, as today) and as the mechanics source when `tracker:` names an
 unknown value.
 
-**`## Deployment` section:** `shape-ticket` (split rule), `writing-plans` (scope check), and `brainstorming` (scope check) read deploy topology from this section: what ships together, what ships independently, and the mechanism. It is a fact to look up, never to infer - when the section is absent, or when it documents a monolithic topology (like the example below), the "separable release timing" split axis is unavailable and splits fail closed to one artifact.
+### Worked example: wrapper-managed worktrees (acme-mono)
 
-```markdown
-## Deployment
+Complete `.pi/settings.json`:
 
-One deploy workflow ships the whole system at once - nothing ships independently.
+```json
+{
+  "piGauntlet": {
+    "flowGuards": { "specDirs": ["doc/specs"] }
+  }
+}
 ```
 
-**`## Happy path` section:** `writing-plans` selects the row whose `Paths` cover the plan's files and copies it into the plan header's `**Happy path:**` line; `subagent-driven-development` runs it once in the verify phase - after full verification and code review, before the conformance audit - and hands a bounded transcript to the conformance reviewer as runtime evidence. Optional: without the section, or with no matching row, nothing downstream changes.
+Complete `.pi/gauntlet-overrides.md`:
 
 ```markdown
+## using-git-worktrees
+- home: ../acme-mono-<name>
+- create: script/worktree create <name> <subproject> --branch <branch>
+- destroy: script/worktree destroy <name>
+
+The wrapper symlinks build/ into the tree; never replace it with a directory.
+
+## Deployment
+
+One deploy workflow ships the whole system at once - nothing ships independently.
+
 ## Happy path
 
 | Row | Paths | Command | Timeout |
@@ -382,39 +436,7 @@ One deploy workflow ships the whole system at once - nothing ships independently
 | dashboard | `dashboard/` | `script/e2e-dashboard` | 3m |
 | excavation | `excavation/` | `cd excavation && make e2e` | 2m |
 | cross-cutting | `dashboard/`, `excavation/`, `docker-compose.yml`, `Makefile` | `script/e2e-stack` | 5m |
-```
 
-- `Row` is a free label; `cross-cutting` is reserved: it applies when the change matches two or more non-`cross-cutting` rows, or when a path is inside its own `Paths` and inside no other row's `Paths`, and it takes precedence over a single matched row (so root compose files, Makefiles, and lockfiles a stack run depends on select it on their own, while a change inside one project row alone selects that row).
-- `Paths` is a comma-separated list of repo-relative prefixes; a path is inside a row when it starts with one of them. Paths matching no row are ignored, both for selection and for the fix-loop re-run test.
-- `Command` is repo-relative and runs through `bash -c`, so `cd`, `&&`, and env assignments work. It must be self-contained and worktree-safe: boot what it needs, drive one flow, exit, trap `TERM`/`INT` to tear down (containers are not in the process group, so the script owns their teardown), and write only to gitignored paths or outside the worktree. Two worktrees may run it at the same time; pi-gauntlet does not serialize, and knows nothing about brokers, compose files, or ports.
-- `Timeout` is optional, grammar `\d+(s|m|h)`, default `10m`. The parent runs the command under `timeout -k 30s <Timeout>`: `TERM`, then `KILL` after 30s. A malformed cell falls back to the default and the plan header omits the suffix.
-- Exit code contract: `0` = passed; `75` (`EX_TEMPFAIL`) = environment unavailable, reported as `not run`; `126` = not executable, reported as `not run`; any other non-zero = failed. A timeout is failed, not `not run`. Residue left in the worktree is failed regardless of exit code.
-- Host dependency: GNU `timeout` (`timeout` or `gtimeout` on PATH); absent -> `not run - no timeout binary`.
-
-**`## Delivery` section:** `check-delivery` resolves its overrides through the same discovery ladder. Defaults are pessimistic where it matters: an unset `target state` keeps the write comment-only; unset `deploy watch`/`delivery target` skip stage 2 (reported, never silently passed); `browser evidence` defaults to never. `check-delivery` is single-ticket by design - sweep/reconciliation passes over many tickets stay consumer territory, invoking the skill once per ticket. The remaining slots have working defaults shown below:
-
-| Slot | Meaning | Default (unset) |
-|---|---|---|
-| `target state` | Non-terminal tracker state to advance to on success | none - comment only |
-| `deploy watch` | Workflow/command to await before the target check | none |
-| `delivery target` | URL / health endpoint / registry query / command + success predicate reflecting the shipped SHA (`<sha>` substituted) | none - stage 2 skipped, reported |
-| `timeout` | Upper bound on stage 2 (watch + target check) | 10 minutes when stage 2 runs at all |
-| `browser evidence` | When/how to capture UI evidence (requires a browser tool) | never |
-| `ref convention` | How commits/PRs reference tickets (e.g. `(ref ABC-123)`) | tracker-native forms (`#N`, `Fixes #N`, bare `ABC-123`) |
-| `AC location` | Where ACs live if not the ticket body | ticket body |
-| `synthesized AC gaps` | `block` or `soft` - whether an unmet synthesized AC produces a blocking `unexplained gap` or a non-blocking proposal | `soft` |
-| `descope edits` | `strikethrough` - on gate approval, strike ratified `proposed descope` AC lines in the ticket body | none - no body edits ever |
-
-Malformed slot values fail safe, with one warning per invocation naming the
-bad value: `synthesized AC gaps` treats anything other than `block`/`soft`
-as `soft`; `descope edits` treats anything other than `strikethrough` as
-unset (no body edits). `descope edits` also requires a resolved edit-body
-write verb: when the slot is active and the approval ratifies a `proposed
-descope` but no edit-body verb resolves, the whole batched write (body
-edit, evidence comment, status advance) degrades to manual - none
-auto-posted.
-
-```markdown
 ## Delivery
 - target state: Ready
 - deploy watch: gh run watch --workflow deploy.yml (run for <sha>)
@@ -425,6 +447,10 @@ auto-posted.
 - descope edits: strikethrough
 ```
 
+The Happy path table selects a row by repo-relative path prefix. `cross-cutting` takes precedence when multiple project rows match or only its own paths match. No matching row means no run. Commands run through `bash -c` and must be self-contained, worktree-safe, tear down on `TERM`/`INT`, and leave no residue. Timeout accepts `s`, `m`, or `h` (default `10m`, malformed values fall back); GNU `timeout` or `gtimeout` is required, with `TERM` then `KILL` after 30 seconds. Exit `0` passes; `75` or `126` reports not run; other nonzero exits, timeout, or residue fail.
+
+Delivery is single-ticket. `timeout` defaults to 10 minutes when stage 2 runs, `ref convention` to tracker-native forms, `AC location` to the ticket body, `synthesized AC gaps` to `soft`, and `descope edits` to unset. Malformed synthesized-gap values fall back to `soft`; malformed descope values remain unset, with one warning. `descope edits: strikethrough` needs an edit-body verb and gate approval; without the verb, the entire batched write degrades to manual output.
+
 ## REVIEW.md convention
 
 `/skill:gatekeep-pr` (the pre-merge gate) reads an optional root-level `REVIEW.md` -
@@ -479,7 +505,6 @@ customization lives in three places, never in the wrapper itself:
 - requires credentials: false                # optional; true => skill reports "not run" as missing evidence
 - local verification: always                 # optional; default (absent) = CI-first; "always" forces the local run even when exact-head CI is green
 - ci checks: <comma-separated check names>   # optional; narrows which checks count as evidence; absent = all checks on the assessed head
-- worktree wrapper: <command>                # optional
 - issue fetch: <command with <ref> placeholder>   # optional, replaces gh issue view
 - merge policy: squash | merge-commit | rebase   # optional; default squash
 ```
@@ -490,14 +515,32 @@ An existing `## verification-before-completion` overrides section is an accepted
 equivalent source for the verification command only; all other PR-gate keys
 still live under `## PR gate`. A `## comms style` section in the same overrides
 file extends gatekeep-pr's wording rules - the rendered report and menu, and every
-external payload (review bodies, replies, tracker comments, commit subjects) alike.
+external payload (review bodies, replies, tracker comments, commit subjects) alike. Worktree placement for the gate is the `## using-git-worktrees` contract above.
 
 Anything a wrapper skill contains beyond trigger phrases is misplaced - move it to
 `REVIEW.md` or the overrides file instead.
 
 ## Configuring the gates
 
-The conformance gate's model, the spec council's roster, and the phase-tracker's flow guards are all configured per pi preset (or per repo, via `.pi/settings.json`). See [doc/configuration.md](./doc/configuration.md) for every setting, its default, and how repo-local config overrides a preset.
+The conformance gate's model, the spec council's roster, and the phase-tracker's flow guards are all configured per pi preset (or per repo, via `.pi/settings.json`). Keys below are relative to `piGauntlet`.
+
+| Key | Owner (extension) | Default | Effect |
+|---|---|---|---|
+| `specCouncil.members` | phase-tracker (`gauntlet_setting`), roasting-the-spec | `[]` (worker critique) | council models for the spec critique - [detail](./doc/configuration.md#spec-council) |
+| `specCouncil.chair` | same | unset (inherits the main loop) | chair model - [detail](./doc/configuration.md#spec-council) |
+| `closureReview.enforce` | phase-tracker | `true` | conformance gate on/off - [detail](./doc/configuration.md#conformance-gate-model) |
+| `closureReview.model` | phase-tracker | unset (inherits) | conformance reviewer model - [detail](./doc/configuration.md#conformance-gate-model) |
+| `closureReview.maxFixRounds` | phase-tracker | `3` | fix rounds before escalation - [detail](./doc/configuration.md#conformance-gate-model) |
+| `escalationLoop.implModel` | phase-tracker | unset (main loop) | implementer model on escalation - [detail](./doc/configuration.md#escalation-loop) |
+| `flowGuards.enforce` | phase-tracker | `true` | phase gates on/off - [detail](./doc/configuration.md#phase-tracker) |
+| `flowGuards.specDirs` | phase-tracker, plan-tracker; telemetry and spec-index consumers | `["doc/specs", "docs/specs"]` | where specs and sibling plans live - [detail](./doc/configuration.md#phase-tracker) |
+| `verifyBeforeShip.testCommands` | verify-before-ship | the `DEFAULT_TEST_COMMANDS` patterns in `extensions/lib/gauntlet-settings.ts` (make, npm, pnpm, yarn, pytest, rspec, cargo, go) | patterns that count as a test run - [detail](./doc/configuration.md#verify-before-ship) |
+| `verifyBeforeShip.warningReference` | verify-before-ship | unset | pointer shown with the warning - [detail](./doc/configuration.md#verify-before-ship) |
+| `telemetry.enabled` | telemetry | `true` | record each flow - [detail](./doc/configuration.md#telemetry) |
+| `telemetry.dir` | telemetry | `.pi/gauntlet/telemetry` | record location - [detail](./doc/configuration.md#telemetry) |
+| `telemetry.buckets` | telemetry | test / docs / config globs (`DEFAULT_TELEMETRY_BUCKETS`) | file classification - [detail](./doc/configuration.md#telemetry) |
+
+For Markdown instructions rather than runtime settings, use [Project-specific overrides](#project-specific-overrides). Repo-local settings replace each configured second-level object wholesale; see the [deep reference](./doc/configuration.md).
 
 ## Relationship to the other repos
 

package/package.json

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

package/skills/brainstorming/SKILL.md

@@ -183,3 +183,5 @@ Redraw: keep the worktree and the approved spec file. `plan_tracker({ action: "c
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/chase-bug/SKILL.md

@@ -441,3 +441,5 @@ nested resources" (the decision that made it so).
 ## 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. `## Response channels` and `## Issue tracker` are the named extension points for this skill.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/check-delivery/SKILL.md

@@ -418,3 +418,5 @@ 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/dispatching-parallel-agents/SKILL.md

@@ -219,3 +219,5 @@ After agents return:
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/finishing-a-development-branch/SKILL.md

@@ -320,6 +320,18 @@ If confirmed: Cleanup worktree (Step 6), then, if Step 6 removed the worktree, `
 
 **Only runs for the Squash-merge and Discard options (3 and 5).** The PR, draft PR, and Keep options always preserve the worktree.
 
+Read the gauntlet overrides file now (ladder in Project overrides) and its `## using-git-worktrees` section; nothing from creation time is carried - the file is the contract (keys written like `## cleanup` items: `using-git-worktrees/SKILL.md` Step 1a).
+
+**Keyed contract** - the section has at least one of `- home:`, `- create:`, `- destroy:`:
+
+1. Resolve `home:` against `$PRIMARY` (absent -> `$PRIMARY/.worktrees/<name>`; an absolute value is used as-is). `<name>` must appear exactly once, inside one path segment that may carry a literal prefix or suffix; otherwise stop and name the line.
+2. Ownership match: canonicalize both sides (`realpath`) and compare `$WORKTREE` to the resolved pattern, treating the `<name>` segment as `<prefix>*<suffix>` where `*` matches the remainder of that one segment. The text `*` matched is `NAME` - the creation identifier (`jacek/fix-x` was created as `jacek-fix-x`; `home: ../acme-mono-<name>` recovers `fix-x` from `acme-mono-fix-x`). A pattern that cannot isolate one segment -> stop and report.
+3. Match and `destroy:` set -> run it from `$PRIMARY` with `<name>` -> `'NAME'` and `<branch>` -> `'$FEATURE'`, each value one single-quoted shell word (`'...'`, an embedded `'` escaped), any other `<token>` resolved from context or asked once, never executed raw. Non-zero exit -> print its output, keep the branch, end this step; never fall back to `git worktree remove --force`. On success, run no `git worktree remove` or `prune`; continue to `git -C "$PRIMARY" branch -D "$FEATURE"`.
+4. Match and no `destroy:` -> `git -C "$PRIMARY" worktree remove "$WORKTREE"` then `git -C "$PRIMARY" worktree prune`; after success, continue to `git -C "$PRIMARY" branch -D "$FEATURE"`.
+5. No match -> the host environment owns this workspace: remove nothing, skip the branch deletion that follows, report that the host-owned worktree still holds `$FEATURE`.
+
+**Legacy path** - no overrides file, no section, or a keyless section:
+
 **If the worktree was created by a project-native script** (e.g. `script/worktree create`, `bin/worktree`): defer to its destroy command, run against the primary: `"$PRIMARY/script/worktree" destroy "${WORKTREE##*/}"`.
 
 **If `$WORKTREE` is under `$PRIMARY/.worktrees/` or `~/.worktrees/<project>/`:** gauntlet created it - we own cleanup:
@@ -343,7 +355,7 @@ Removal precedes branch deletion in both options; `git branch -d`/`-D` fails whi
 | 4. Keep as-is | - | - | yes | - | - |
 | 5. Discard | - | - | - | yes (force, after Step 6 removal) | - |
 
-A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branch.
+A host-owned worktree (Step 6: no `home:` match, or the legacy "Otherwise") keeps both the worktree and the branch.
 
 ## Common Mistakes
 
@@ -369,7 +381,7 @@ A host-owned worktree (Step 6 "Otherwise") keeps both the worktree and the branc
 
 **Cleaning up harness-owned worktrees**
 - **Problem:** Removing a worktree the harness created causes phantom state
-- **Fix:** Only clean up worktrees under `.worktrees/`, `~/.worktrees/<project>/`, or paths produced by a project-native worktree script
+- **Fix:** Only clean up worktrees that match the `home:` pattern of `## using-git-worktrees`, or - on the legacy path - under `.worktrees/`, `~/.worktrees/<project>/`, or paths produced by a project-native worktree script
 
 **No confirmation for discard**
 - **Problem:** Accidentally delete work
@@ -402,6 +414,7 @@ Once the merge (and any deploy) has landed, `/skill:check-delivery <ticket-ref>`
 - Force-push without explicit request
 - Remove a worktree before confirming merge success
 - Clean up worktrees you didn't create (provenance check)
+- Retry a failed `destroy:` with `git worktree remove --force`
 - Run any step without the `<worktree-path>` argument
 - Auto-proceed past an undispositioned carried-open gap
 - Skip the strip-and-seal block before the Option 3 squash or the Option 1/2 push
@@ -416,8 +429,11 @@ Once the merge (and any deploy) has landed, `/skill:check-delivery <ticket-ref>`
 - Clean up worktree for Options 3 & 5 (Squash-merge, Discard) only
 - Target `$PRIMARY` with `git -C` for merge, worktree removal, and branch deletion
 - Run `git -C "$PRIMARY" worktree prune` after removal
+- Match `$WORKTREE` against the `home:` pattern of `## using-git-worktrees` before removing anything when the keyed contract is active
 - Surface the closure / conformance verdict as its own section before the options menu
 
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/forge-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use when creating or editing a SKILL.md, a skill's reference file, an agent persona, a prompt template, a slash command, or a file the repo's AGENTS.md or CLAUDE.md routes here, 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
@@ -35,6 +35,7 @@ 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 for a skill 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.
+- No history. An instruction file states current rules only: an added or changed line carries no date, no "previously"/"formerly"/"as of" clause, and no narration of a rule's past - that goes to the commit body, the ticket, or the spec; a one-clause operational reason stays, and a date that is itself a rule (a freeze window) stays. The one exception to Minimal diff and to "Leave other lines alone": an edit that changes a rule inside a changelog, a dated-entry list, or a "previously" section moves that section's surviving rules into the section that owns their topic and deletes the history section in the same edit; a history section the edit does not touch stays. Example: `2025-03-02: builds now use the release profile because debug ran out of memory` under `## History` becomes `Build with the release profile (debug runs out of memory)` under `## Deploy`, and `## History` is deleted.
 - Skills only: 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.
@@ -59,7 +60,7 @@ A persona is an `agents/<name>.md` file dispatched by name (pi-cohort `subagent(
 ## Edit procedure
 
 1. Read the whole file.
-2. Locate and edit the sentence that owns the rule you are changing (see Minimal diff).
+2. Locate and edit the sentence that owns the rule you are changing (see Minimal diff; under No history, the history section it sits in).
 3. Read the changed lines back against `## Authoring rules`.
 4. Run wc -l; over 500 lines, a skill extracts per the oversized-file rule, a persona splits by job.
 5. Skill, pi: run /reload. Persona, pi: nothing. Claude Code: start a new session.
@@ -81,3 +82,5 @@ Run after adding a rule or rewording a discipline rule.
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/gatekeep-pr/SKILL.md

@@ -76,3 +76,5 @@ These bind every rendered report, menu, and external payload (review bodies, rep
 ## 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. `## PR gate` keys are read in step 2 (`reference/assessment.md`); `## comms style` extends the wording rules. `## cleanup` steps run on the `cleanup` pick (`reference/cleanup.md`).
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/gatekeep-pr/reference/assessment.md

@@ -8,9 +8,11 @@ Read from SKILL.md step 2. Input: the step-1 digest. Output: a provisioned workt
 |---|---|---|---|
 | A worktree exists on the expected branch (`headRefName` for in-repo PRs, a fork-local `pr-<N>` branch for fork PRs), at any path | Reuse unconditionally; sync with `git fetch origin` + `git pull --ff-only` (the local branch tracks `origin/<headRefName>`) | Reuse unconditionally; the local `pr-<N>` branch has no upstream - sync with `git fetch origin pull/<N>/head` + `git merge --ff-only FETCH_HEAD` | STOP and surface on divergence, dirt, or local-only commits; never force, never create a duplicate |
 | The default path `.worktrees/pr-<N>` exists but holds a different branch | STOP and surface; never repurpose | STOP and surface; never repurpose | - |
-| Nothing exists (an overrides worktree wrapper can relocate it, following `using-git-worktrees` conventions, gitignore-first) | Create at `.worktrees/pr-<N>`; `git fetch origin` + `git worktree add .worktrees/pr-<N> <headRefName>`; verify post-checkout that HEAD == the digest's `headRefOid` | Create at `.worktrees/pr-<N>`; `git fetch origin pull/<N>/head:pr-<N>` first, then add on that local branch; verify post-checkout that HEAD == the digest's `headRefOid` | - |
+| Nothing exists | `git fetch origin`, then create on `headRefName`: keyed contract -> `create:` when set with `<name>` = `pr-<N>`, `<branch>` = `headRefName`, never `-b`, else `git worktree add "<home>" <headRefName>`; no section or keyless -> `git worktree add .worktrees/pr-<N> <headRefName>`; verify post-checkout that HEAD == the digest's `headRefOid` | `git fetch origin pull/<N>/head:pr-<N>` first, then create on the local `pr-<N>` branch: keyed contract -> `create:` when set with `<name>` = `<branch>` = `pr-<N>`, else `git worktree add "<home>" pr-<N>`; no section or keyless -> `git worktree add .worktrees/pr-<N> pr-<N>`; verify post-checkout that HEAD == the digest's `headRefOid` | - |
 
-Record the digest's `worktree` block (`../verification-brief.md`): `path`, `branch` (the actual local branch - `headRefName`, `pr-<N>`, or whatever a wrapper created), `created` (true when this run created it), and `destroy` (the exact destroy invocation when a `worktree wrapper` created it, else null). `cleanup.md` reads it; `post-selection-loop.md` `### Teardown` points there.
+**Keyed contract.** The merge-base overrides file's `## using-git-worktrees` section (read like `## PR gate`, `## Configuration` below) with at least one of `- home:`, `- create:`, `- destroy:` is the keyed contract; its grammar is `using-git-worktrees/SKILL.md` Step 1a. The worktree path is `home:` resolved against the primary with `<name>` -> `pr-<N>` (absent -> `.worktrees/pr-<N>`). `create:` runs from the primary with every resolved token one single-quoted shell word (`'...'`, an embedded `'` escaped; an unresolved `<token>` is never executed) and replaces only the add command above; the fetch, the unconditional reuse row, the divergence stops, and the HEAD check are unchanged. A `create:` that exits non-zero STOPs with the command's output; never fall back to `git worktree add`. A `create:` with a `<token>` the PR context cannot resolve (the one top-level directory the PR's files touch, for `<subproject>`) asks once. Before the built-in add (keyed with `home:` only, or the legacy `.worktrees/pr-<N>` fallback), gitignore the home's parent directory first when the resolved home is inside the primary, following `using-git-worktrees/SKILL.md` Step 2b; a sibling home needs no gitignore edit. After creation, `git worktree list --porcelain` must list the resolved path; otherwise STOP and surface the mismatch. A legacy `worktree wrapper:` line under `## PR gate` is named once in the report as unrecognized and ignored. No section or a keyless section: the legacy behavior above, including a wrapper `## Configuration` rung 3 discovers from `AGENTS.md`.
+
+Record the digest's `worktree` block (`../verification-brief.md`): `path` (the worktree actually selected - the resolved `home:` when this run created it, a reused tree's real path otherwise), `branch` (the actual local branch - `headRefName`, `pr-<N>`, or whatever a wrapper created), `created` (true when this run created it), and `destroy` (under the keyed contract, `destroy:` substituted with the identifier the ownership match in `../../finishing-a-development-branch/SKILL.md` Step 6 recovers from `path`, null when there is no `destroy:` or no match; under the legacy path, the wrapper's exact destroy invocation when one created it, else null). `cleanup.md` reads it; `post-selection-loop.md` `### Teardown` points there.
 
 Then set the digest's `permissions.head_pushable` (`../verification-brief.md` Section A): `git -C <worktree> push --dry-run --no-verify --no-follow-tags <head_url> HEAD:refs/heads/<head_ref>` exit 0 is `true`, a non-zero exit is `false`, when `head_url` is `unreadable`, `head_pushable` is `unreadable` and the probe does not run. The probe records observed authorization; a real push the server rejects (branch protection) is reported as that push's failure.
 
@@ -21,8 +23,8 @@ When the digest reported `mergeable: UNKNOWN` or `mergeStateStatus: UNKNOWN`, re
 Resolve per concern, first match wins, evaluated unconditionally - never delegated to a wrapper skill:
 
 1. **Repo root `REVIEW.md`** (rubric concerns only). Wins over the shipped baseline and reviewer-persona defaults on any conflict.
-2. **Gauntlet overrides file** (`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins): the `## PR gate` section below. The same file's `## cleanup` section is the second gatekeep-read section: an ordered list of `<label>: <command or /skill:... invocation>` items with placeholders `<issue>`, `<pr>`, `<merge-sha>`, read from the merge-base like `## PR gate` and consumed by `cleanup.md`; a PR that edits it is review subject matter, never this run's config. Git teardown and base sync are implied and never listed; the release skill's own propose step supplies the recommended level and pauses for the pick, and a repo that wants no pause writes the level in the item. An existing `## verification-before-completion` section is an accepted equivalent source for the verification command.
-3. **Repo documentation** - an explicitly documented command or tool (`AGENTS.md`'s canonical test entrypoint, a documented worktree wrapper, a documented tracker CLI, documented merge policy or branch rules). Reading documentation is not inference. Discovery-only: never tell consumers to add gatekeep-pr configuration here.
+2. **Gauntlet overrides file** (`.pi/gauntlet-overrides.md`, `<repo root>/gauntlet-overrides.md`, `<repo root>/doc/gauntlet-overrides.md`; first found wins): the `## PR gate` section below. The same file's `## using-git-worktrees` section is the worktree contract (`## Provision the worktree`). The same file's `## cleanup` section is the second gatekeep-read section: an ordered list of `<label>: <command or /skill:... invocation>` items with placeholders `<issue>`, `<pr>`, `<merge-sha>`, read from the merge-base like `## PR gate` and consumed by `cleanup.md`; a PR that edits it is review subject matter, never this run's config. Git teardown and base sync are implied and never listed; the release skill's own propose step supplies the recommended level and pauses for the pick, and a repo that wants no pause writes the level in the item. An existing `## verification-before-completion` section is an accepted equivalent source for the verification command.
+3. **Repo documentation** - an explicitly documented command or tool (`AGENTS.md`'s canonical test entrypoint, a documented worktree wrapper (legacy path only), a documented tracker CLI, documented merge policy or branch rules). Reading documentation is not inference. Discovery-only: never tell consumers to add gatekeep-pr configuration here.
 4. **Ask the user.** Never guess from lockfiles, file heuristics, or vibes.
 
 ```markdown
@@ -32,7 +34,6 @@ Resolve per concern, first match wins, evaluated unconditionally - never delegat
 - requires credentials: false                # optional; true => the gate reports "not run" as missing evidence
 - local verification: always                 # optional; default (absent) = CI-first; "always" forces the local run even when exact-head CI is green
 - ci checks: <comma-separated check names>   # optional; narrows which checks count as evidence; absent = all checks on the assessed head
-- worktree wrapper: <command>                # optional
 - issue fetch: <command with <ref> placeholder>   # optional, replaces gh issue view
 - merge policy: squash | merge-commit | rebase   # optional; default squash
 ```

package/skills/gatekeep-pr/reference/cleanup.md

@@ -6,8 +6,8 @@ Read from `decision-menu.md` when `cleanup` is picked on a terminal overlay. Inp
 
 Run the steps in order; a failing step prints its first error line and the loop continues; retry nothing.
 
-1. **Worktree.** Eligible when `worktree.path` is not the primary, `git -C <worktree.path> status --porcelain --untracked-files=no` is empty (tracked-clean; untracked files never block removal), and - when landed - `git -C <worktree.path> log origin/<baseRefName>..HEAD` shows no commit outside the assessed head's history (`git -C <worktree.path> merge-base --is-ancestor HEAD <headRefOid>` succeeds). Eligible and (`worktree.created` or landed) -> run `worktree.destroy` when recorded, else `git worktree remove --force <worktree.path>` (the single `--force` removes a tree whose only dirt is untracked files; those files are deleted); then `git worktree prune`; print `worktree: done`. Reused and not landed -> `worktree: skipped - reused, left at <path>`. Dirty -> `worktree: skipped - uncommitted changes at <path>`. Commits beyond the assessed head -> `worktree: skipped - unmerged commits <shas> at <path>`. Under `approved` on a `rebased locally` head this step reports `unmerged commits` and leaves the tree, and `stop` leaves the rewritten local head in place and names it.
-2. **Branch.** Landed, the branch exists locally, and no worktree holds it (`git worktree list --porcelain` lists no `branch refs/heads/<worktree.branch>`) -> `git branch -D <worktree.branch>`; print `branch: done`. Not landed -> `branch: skipped - PR not merged`. Still checked out -> `branch: skipped - checked out at <path>`. Never delete a remote branch.
+1. **Worktree.** Eligible when `worktree.path` is not the primary, `git -C <worktree.path> status --porcelain --untracked-files=no` is empty (tracked-clean; untracked files never block removal), and - when landed - `git -C <worktree.path> log origin/<baseRefName>..HEAD` shows no commit outside the assessed head's history (`git -C <worktree.path> merge-base --is-ancestor HEAD <headRefOid>` succeeds). When the merge-base `## using-git-worktrees` section has at least one of `- home:`, `- create:`, `- destroy:` (the keyed contract), eligibility also requires the ownership match of `../../finishing-a-development-branch/SKILL.md` Step 6 (the recorded `worktree.destroy` already carries the recovered identifier): `home:` resolved against `$PRIMARY` (absent -> `.worktrees/<name>`), the `<name>` segment matched as `<prefix>*<suffix>` within one segment (`../acme-mono-<name>` against `/work/acme-mono-fix-x` recovers `fix-x`), `$WORKTREE` (the digest `worktree.path`) and the pattern both through `realpath`; an ambiguous match stops; no match -> `worktree: skipped - outside configured home, left at <path>` and the branch step reports it still checked out. Eligible and (`worktree.created` or landed) -> run `worktree.destroy` when recorded (from the primary; a non-zero exit prints `worktree: failed - <its output>`, keeps the branch (the branch step reports it still checked out), and never falls back to a forced removal), else `git worktree remove --force <worktree.path>` (the single `--force` removes a tree whose only dirt is untracked files; those files are deleted); then `git worktree prune`; print `worktree: done`. Reused and not landed -> `worktree: skipped - reused, left at <path>`. Dirty -> `worktree: skipped - uncommitted changes at <path>`. Commits beyond the assessed head -> `worktree: skipped - unmerged commits <shas> at <path>`. Under `approved` on a `rebased locally` head this step reports `unmerged commits` and leaves the tree, and `stop` leaves the rewritten local head in place and names it.
+2. **Branch.** A non-zero `worktree.destroy` exit in step 1 -> `branch: skipped - worktree destroy failed`, whatever `git worktree list` shows. Landed, the branch exists locally, and no worktree holds it (`git worktree list --porcelain` lists no `branch refs/heads/<worktree.branch>`) -> `git branch -D <worktree.branch>`; print `branch: done`. Not landed -> `branch: skipped - PR not merged`. Still checked out -> `branch: skipped - checked out at <path>`. Never delete a remote branch.
 3. **Base.** Landed, the primary is on `<baseRefName>`, and its tree is tracked-clean -> `git fetch origin` then `git pull --ff-only`; print `base: synced <sha>` when `git merge-base --is-ancestor <pr.merge_commit> HEAD` succeeds, else `base: failed - merge commit not on local <baseRefName>`. Primary on another branch -> `base: skipped - primary on <branch>`; dirty -> `base: skipped - uncommitted changes`; not landed -> `base: skipped - PR not merged`. Never switch the primary's branch.
 4. **Override steps**, one per `## cleanup` item in list order. An item is `<label>: <text>`; any other shape -> `skipped - malformed item: <text>`.
    - Landed-change guard first: not landed and the text contains `<merge-sha>` or `/skill:release` -> `skipped - needs a landed change`. The guard decides before any placeholder is read, so an item it skips never prints a `no <name> resolved` line, whatever its placeholders hold. A `/skill:release` item when step 3 did not print `synced` -> `skipped - base not synced`.

package/skills/gatekeep-pr/verification-brief.md

@@ -81,7 +81,7 @@ provisioning, so it never re-reads; step 2 re-reads once after provisioning (`re
 - issue_ref: <ref> | null
 - issue: null   # shape and fill: step 2, reference/assessment.md ## Fetch the ticket
 - worktree_discovery: { expected_path, exists, branch, dirty, ahead, behind }
-- worktree: { path, branch, created, destroy }   # filled in step 2, reference/assessment.md: worktree.path; worktree.branch is the actual local branch (headRefName, pr-<N>, or whatever a worktree wrapper created); worktree.created is true when this run created it; worktree.destroy is the wrapper's exact destroy invocation, else null
+- worktree: { path, branch, created, destroy }   # filled in step 2, reference/assessment.md: worktree.path; worktree.branch is the actual local branch (headRefName, pr-<N>, or whatever a worktree wrapper created); worktree.created is true when this run created it; worktree.destroy is the substituted ## using-git-worktrees destroy: command, else a legacy wrapper's exact destroy invocation, else null
 - sync: <record>   # only with --rebase; grammar: reference/sync.md ## Sync record
 - truncation_notes: []
 ```

package/skills/gauntlet-handoff/SKILL.md

@@ -115,3 +115,5 @@ 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/gauntlet-performance/SKILL.md

@@ -46,3 +46,5 @@ 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/gauntlet-resume/SKILL.md

@@ -166,3 +166,5 @@ 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/linear/SKILL.md

@@ -259,3 +259,5 @@ for product behavior the CLI doesn't expose.
 ## 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. `## Issue tracker` is the named extension point for this skill.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/receiving-code-review/SKILL.md

@@ -178,3 +178,5 @@ No performative agreement. Technical rigor always.
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/requesting-code-review/SKILL.md

@@ -81,3 +81,5 @@ See template at: `code-reviewer.md` in this skill directory
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/roasting-the-spec/SKILL.md

@@ -160,3 +160,5 @@ Single pass — no automatic re-roast loop. The user can invoke this skill again
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/shape-ticket/SKILL.md

@@ -325,3 +325,5 @@ Read this when applying the AC integrity gate (drafting, repairing, or adjudicat
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/subagent-driven-development/SKILL.md

@@ -319,3 +319,5 @@ For the fan-out + worktree + patch-integration + conflict mechanics, see `dispat
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/test-driven-development/SKILL.md

@@ -237,3 +237,5 @@ phase_tracker({ action: "complete", phase: "implement" })
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/using-git-worktrees/SKILL.md

@@ -55,7 +55,30 @@ Pause for explicit consent **only** when one of these holds:
 
 Otherwise create it. The gate is "is this real work?", not "did the user approve this worktree?"
 
-## Step 1a — Prefer Native Worktree Tools
+## Step 1a - Read the `## using-git-worktrees` contract
+
+Read the gauntlet overrides file (ladder in Project overrides) before any tool or wrapper discovery. Its `## using-git-worktrees` section carries up to three key lines, written like `## cleanup` items; prose before, between, or after them is instruction too:
+
+| Key | Meaning | Absent (keyed contract active) |
+|---|---|---|
+| `- home: <path pattern>` | Where this repo's worktrees live, relative to the primary checkout (an absolute path is used as-is). `<name>` substitutes and must appear exactly once, inside one path segment that may carry a literal prefix or suffix (`../acme-mono-<name>`). Ownership test for finishing Step 6 and gatekeep cleanup. | `<primary>/.worktrees/<name>` |
+| `- create: <command>` | Shell command run from the primary with `<name>` and `<branch>` substituted. Any other `<token>` stays literal: resolve it from the task context when the plan, ticket, or prompt names exactly one value for it (`<subproject>`: the one top-level directory the change touches); zero or several candidates -> ask once. | Built-in: `git worktree add "<home>" -b "<branch>"`, gitignore-first only when the home is inside the primary |
+| `- destroy: <command>` | Removal command run from the primary, same substitution; read by `finishing-a-development-branch` Step 6 and gatekeep-pr cleanup. | `git worktree remove "<path>" && git worktree prune` when the path matches `home:`; host-owned, keep, when it does not |
+
+The **keyed contract is active** when at least one key is present. A duplicate key: the first wins; name the duplicate. `home:` without a `<name>` segment, or with it twice: stop and name the line.
+
+Keyed contract active:
+
+1. Run the Step 3 clean-base check in the source checkout.
+2. `NAME` is the branch name with every `/` replaced by `-` (`jacek/fix-x` -> `jacek-fix-x`). `HOME` is `home:` resolved against `$ROOT` with `<name>` -> `NAME`.
+3. `create:` set -> run it from `$ROOT` with each resolved token inserted as one single-quoted shell word (`'...'`, an embedded `'` escaped), including when the template already quotes it; a `<token>` the context rule cannot resolve is never executed - ask once for its value. A non-zero exit stops this skill with the command's output: no `git worktree add` fallback, no Step 4 report.
+   `create:` absent -> when `HOME` is inside `$ROOT`, gitignore its parent directory first (the Step 2b sequence with that directory in place of `.worktrees`); then `git -C "$ROOT" worktree add "$HOME" -b "$BRANCH"`.
+4. Post-create check, always: `git -C "$ROOT" worktree list --porcelain` must print `worktree $HOME`; otherwise stop and report the mismatch (a wrong `home:` pattern, or a wrapper that places trees elsewhere).
+5. `WORKTREE="$HOME"`; `$WORKTREE` is the value every later step carries (`home: ../acme-mono-<name>` with branch `fix-x` gives `/work/acme-mono-fix-x`, so the basename `acme-mono-fix-x` is not the name). Go to Step 4.
+
+No overrides file, no section, or a section with none of the three keys (both shapes are the **legacy path**): the prose, if any, is instruction; continue at Step 1b - native tools, then a wrapper discovered from `AGENTS.md`, the repo root, `script/`, or `bin/`, then `.worktrees/`.
+
+## Step 1b - Prefer Native Worktree Tools (legacy path)
 
 Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, run the Step 3 clean-base check in the source checkout *before* invoking it, then use it and skip to Step 3.
 
@@ -76,7 +99,7 @@ Only when no native tool exists:
 
 ### 2a. Pick a location
 
-The canonical home is `<repo>/.worktrees/<branch>`. A project override or wrapper may define another path; otherwise use the canonical home. Do not ask local-vs-global or invent another path.
+The canonical home is `<repo>/.worktrees/<branch>`. A keyed `## using-git-worktrees` section never reaches this step (Step 1a creates at `home:`); on the legacy path a wrapper may define another path, otherwise use the canonical home. Do not ask local-vs-global or invent another path.
 
 ### 2b. Create - gitignore the home first
 
@@ -170,7 +193,9 @@ Re-run tests after rebasing.
 | `GIT_DIR != GIT_COMMON` | Already in worktree - report its path, create nothing |
 | Worktree path already listed by `git worktree list` | Report it, create nothing |
 | `git rev-parse --show-superproject-working-tree` returns a path | Submodule — treat as normal repo |
-| Project-native wrapper exists | Use the wrapper (commonly `script/worktree create`) |
+| `## using-git-worktrees` has `home:`/`create:`/`destroy:` | Keyed contract (Step 1a): run `create:` or the built-in add at `home:`, then the post-create check |
+| `## using-git-worktrees` absent or keyless | Legacy path: native tool, then wrapper discovery, then `<repo>/.worktrees/<branch>` |
+| Project-native wrapper exists (legacy path) | Use the wrapper (commonly `script/worktree create`) |
 | No native tool | Create `<repo>/.worktrees/<branch>` (gitignore `.worktrees/` first) |
 | Detached HEAD | Ask before branching |
 | Sandbox/permission failure | Work in place on a feature branch |
@@ -182,9 +207,11 @@ Re-run tests after rebasing.
 - About to `cd` into the worktree (carry the path instead)
 - About to call `git worktree add` directly when the project ships a wrapper (use the wrapper)
 - Created a `.worktrees/` worktree without gitignoring `.worktrees/` first
-- Placed a worktree outside `.worktrees/` (or the project's configured path) for no reason
+- Placed a worktree outside `.worktrees/` (or the `home:` key of `## using-git-worktrees`) for no reason
 - Source checkout dirty and you proceed without asking
 - About to run a test suite during worktree creation
+- Executed a `create:` or `destroy:` template with an unresolved `<token>` still in it
+- Fell back to `git worktree add` after a configured `create:` failed
 
 ## Integration
 
@@ -201,3 +228,5 @@ Re-run tests after rebasing.
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/verification-before-completion/SKILL.md

@@ -169,3 +169,5 @@ phase_tracker({ action: "complete", phase: "verify" })
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.

package/skills/writing-plans/SKILL.md

@@ -313,3 +313,5 @@ Auto-invoke `/skill:subagent-driven-development` in this session. Do not wait fo
 ## 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.
+
+The recognized headings, their readers, and the rules an override cannot change are listed in the [configuration front door](../../README.md#project-specific-overrides); an override extends or replaces the step it names and never lifts this skill's HARD CONSTRAINT or MUST text.