@marcomigozzi/trailhead 0.8.0 → 0.9.0

package/plugins/trailhead/skills/_shared/teamwork.md

@@ -21,26 +21,31 @@ Whoever claims a ticket **owns it end to end**: they work it and close it themse
 Claiming stops two sessions from working the *same* ticket; it does nothing about two sessions working *different* tickets in the **same checkout**. The working tree and the git index are process-global: two agents editing and committing in one clone corrupt each other's state regardless of ticket type (a `bug` is no more or less exposed than a `build`). The claim is the ticket-level lock; the **worktree is the filesystem-level one**.
 
 The repo's `trailhead:conventions` `isolation:` header decides:
-- **`none`** (default): one session at a time per checkout. Simplest, and correct for a repo worked one ticket at a time. Two concurrent sessions here must use **separate clones**, or they collide.
+- **`auto`** (default): resolve the mode at a ticket's **work-start, before any edit**. Ask once whether more than one ticket will be worked at once on this machine this session (this **is** the `clone` gate below, generalised to the whole mode, so a `clone` resolution never re-asks). **No** (a lone ticket): work in the current checkout, exactly like `none`. **Yes**: resolve by repo shape, a plain repo -> `worktree`, a **superrepo** (a `.gitmodules` at the checkout root that declares at least one submodule; equivalently `git submodule status` lists one) -> `clone` (the superproject clone + submodule provisioning below). Because trailhead resolves **one ticket per session**, the ask fires at most once per ticket work-start (so once per session in normal one-ticket-per-session work; a within-session ticket switch, discouraged, re-asks at the new ticket's work-start); the autonomous run (`/trailhead:auto`) **never asks** (it works tickets sequentially, so there is no concurrency) and resolves `auto` to the current checkout. `auto` is a **runtime interpretation**: the engine never writes `isolation: auto` into the conventions.
+- **`none`**: one session at a time per checkout. Simplest, and correct for a repo worked one ticket at a time. Two concurrent sessions here must use **separate clones**, or they collide.
 - **`worktree`**: each executing ticket runs in its own `git worktree` on a `trailhead/t<n>` branch (`git worktree add ../<repo>-t<n> -b trailhead/t<n>`), so concurrent sessions never share a working tree or index. Because git refuses to check out one branch in two worktrees, **worktree isolation implies a branch per ticket even under `git: main`**: the trunk is never checked out twice. At **Resolve**, integrate the branch to the trunk per `git:` (fast-forward or merge into `main`, or open the PR when `git: pr`), then `git worktree remove` it. On **Pause**, the `PAUSED` checkpoint records the worktree path and branch so a resume (by anyone, once released) lands back in it.
-- **`clone`**: each executing ticket works in its own **independent working copy** at `../<repo>-t<n>` (or the **submodule repo** at `../<sub>-t<n>` for submodule-scoped work) on a `trailhead/t<n>` branch. That is the point: it has its own installed dependencies, so it **builds and UATs like the real thing**: the isolation for **path-bound apps a worktree can't run** (React Native/Expo, native toolchains, a local `node_modules`). **A clone is heavy (a full clone + an install), so gate it every time: before cloning, ask whether more than one ticket will be worked at once on this machine this session. If not, skip the clone and work this ticket in the current checkout** (isolation only guards concurrent workspaces; a lone ticket has nothing to collide with). If yes, set it up at work-start by **whichever is faster**:
-  - **`git clone` + the project's install step** (clean git; pays the install cost), or
-  - **a folder copy that brings `node_modules`** (`cp -r` the repo or superproject) to **skip the reinstall**, usually faster for a big `node_modules`. **Catch (git independence):** a raw copy can leave the copy's `.git` (or a submodule's `.git` file) pointing back at the **original**, so its commits would leak there. Verify with `git -C <copy> rev-parse --absolute-git-dir` (and the same inside any submodule): it must resolve **inside the copy**. If it doesn't, re-point it, or use the `git clone` route and copy only `node_modules` across.
+- **`clone`**: each executing ticket works in its own **independent working copy** at `../<repo>-t<n>` on a `trailhead/t<n>` branch (for a submodule-bearing superrepo the clone is of the **superproject** with `--recurse-submodules`, never the submodule alone, so the gitlink bump has a home and each ticket gets independent submodule state; see **Git submodules force `clone`** below). That is the point: it has its own installed dependencies, so it **builds and UATs like the real thing**: the isolation for **path-bound apps a worktree can't run** (React Native/Expo, native toolchains, a local `node_modules`). **A clone is heavy (a full clone + an install), so gate it every time: before cloning, ask whether more than one ticket will be worked at once on this machine this session. If not, skip the clone and work this ticket in the current checkout** (isolation only guards concurrent workspaces; a lone ticket has nothing to collide with). If yes, set it up at work-start by **whichever is faster**:
+  - **`git clone` + the project's install step** (clean git; pays the install cost; add `--recurse-submodules`, or follow with `git submodule update --init --recursive`, when the repo has submodules so nested ones are provisioned too), or
+  - **a folder copy that brings `node_modules`** (`cp -r` the repo or superproject, submodule working trees included) to **skip the reinstall**, usually faster for a big `node_modules`. **Catch (git independence):** a raw copy can leave the copy's `.git` (or a submodule's `.git` file) pointing back at the **original**, so its commits would leak there. Verify with `git -C <copy> rev-parse --absolute-git-dir` **and the same inside every submodule (nested included)**: each must resolve **inside the copy's own tree**, not the original or another ticket's copy. If any points outside, re-point it, or use the `git clone` route and copy only `node_modules` across.
 
-  At **Resolve**, push the branch and integrate per `git:` (into `main`, or a PR); for a submodule, push the submodule branch, then bump the gitlink in the main working clone. Record the copy's path in the `PAUSED` checkpoint and delete it once integrated.
+  At **Resolve**, push the branch and integrate per `git:` (into `main`, or a PR); for submodule changes follow **publish-before-point** in **Git submodules force `clone`** below (push or merge the submodule commit first, only then bump the superproject gitlink), because the clone is disposable and a gitlink must never reference a commit that lives only in it. Record the copy's path in the `PAUSED` checkpoint and delete it once integrated.
 
-Prefer `worktree` whenever more than one session may run on a single clone. On a **monorepo** it is doubly worth it: `git worktree add` shares the object store, so it is far cheaper than a second full clone of a large tree.
+With the default `auto` this choice is made for you at each ticket's work-start; set `worktree` explicitly to force an eager worktree regardless. Prefer `worktree` whenever more than one session may run on a single clone. On a **monorepo** it is doubly worth it: `git worktree add` shares the object store, so it is far cheaper than a second full clone of a large tree.
 
-**If the header never set `isolation:` at all** (a repo charted or adopted before it was chosen, so it silently defaults to `none`), the **work-start check** (SKILL.md Mode 2) catches it: on a real collision risk (another in-progress ticket, or path-bound tooling in this ticket's `Scope:`) it proposes the fitting mode and, whatever the user decides (including keeping `none`), writes the `isolation:` key so the choice is recorded and it never prompts again. A header that already carries `isolation:` (any value) was chosen deliberately and is left alone.
+**If the header never set `isolation:` at all**, it resolves to **`auto`** (the default) at runtime: the work-start concurrency ask decides the mode by repo shape (above), and **nothing is written** into the conventions. This supersedes the earlier behaviour where an absent key silently meant `none` with a one-time collision sanity-check that wrote a key; that nudge-and-write flow is **gone**. A header that already carries `isolation:` (any value, including `none` or `auto`) was chosen deliberately and is honoured as-is.
 
 **When a worktree can't build, use `clone`: path-bound tooling.** A worktree isolates *source*, but it is a fresh directory at a new path with no installed dependencies. For a package or submodule whose build/run is **bound to a fixed path** (React Native/Expo, native toolchains, anything with a local `node_modules`, a Metro/bundler cache, or absolute-path config), the code checks out but the app **won't build or UAT from the worktree** without reinstalling and reconfiguring. For those set **`isolation: clone`** (a dedicated clone installs its own deps and runs like the real app), or, if you don't want per-ticket clones, keep **`isolation: none`** and **serialise** that package (one session at a time on it; the other takes a disjoint `Scope:`). Worktree isolation shines where any checkout builds from any path (most libraries, Go/Rust/Python source trees, docs); `clone` is its heavier counterpart for path-bound app toolchains.
 
-**Git submodules are separate repos.** When a ticket's changes land inside a submodule (its own repo, gitlink-tracked by the superproject), isolate at the *submodule* level, not the superproject: a `git worktree` **of the submodule** on its own branch, commit there, then **bump the gitlink** in the superproject (which follows the superproject's own `git:`/`isolation:`). A superproject worktree does **not** cleanly carry submodule state (`git worktree add` leaves submodules uninitialised, and linked-worktree submodule support is historically incomplete), so never isolate the superproject to isolate submodule-only work. If the submodule holds a **path-bound app** (so a worktree won't build it), set **`isolation: clone`**: a per-ticket clone of the submodule repo that installs its own deps, works and UATs, then pushes its branch and has the gitlink bumped in the main clone. If you want neither per-submodule worktrees nor per-ticket clones, keep **`isolation: none` for submodule work** (commit in the submodule + bump the gitlink in the current checkout), stating the tradeoff: that submodule then **serialises** across sessions (overlapping `Scope:` holds at claim).
+**Git submodules force `clone`, never `worktree`.** A submodule is its own repo, gitlink-tracked by the superproject. When a superrepo **has submodules** (a `.gitmodules` file) and isolation is requested, **`isolation: worktree` is escalated to `isolation: clone`**: superproject worktrees share the one real submodule git dir (`.git/modules/<sub>`), so two worktrees that check a submodule out to different commits corrupt each other, whereas a clone gives each ticket a fully independent submodule git dir. Whether a given ticket will *write* a submodule cannot be told up front, so worktree is disallowed outright here rather than allowed-only-if-read-only. `isolation: none` is unchanged (single checkout, overlapping-`Scope:` tickets serialise); the escalation applies whenever isolation would be `worktree`, and the same rule makes the default **`auto`**'s superrepo branch resolve straight to `clone` (see the `auto` bullet above), never `worktree`, for the same reason. Handling is end-to-end:
+- **Provision at setup.** Stand the clone up with `git clone --recurse-submodules` (or a follow-up `git submodule update --init --recursive`; nested submodules need `--recursive`), so every submodule the ticket's `Scope:` names is populated and pinned at the superproject's recorded commit **before any build or test runs**. The folder-copy shortcut must bring the submodule working trees too and pass the git-independence check inside each of them (above).
+- **Integrate at Resolve, publish before you point.** A submodule change lives in the sub-repo, so commit it **inside the submodule on a branch** (never the default detached HEAD, or the commit is lost when the clone is torn down). A gitlink must **never** reference a commit that exists only in the disposable clone, so **publish the submodule commit first** (push it to the submodule's canonical remote, its configured upstream / `.gitmodules` url; under `git: pr`, open and *merge* the submodule PR), **whatever the isolation mode** (this holds under `none` too, not just per-ticket clones), and **only then bump the superproject gitlink** to that published commit and integrate the superproject per `git:` (`main`, or a PR). **Nested submodules integrate leaf-first:** commit and push the deepest submodule, bump-commit-push its parent's gitlink, up through every level, superproject last. Each commit carries a `Refs:` trailer for this ticket, but a submodule commit is in a **different repo**, so its trailer must be **fully qualified at the superrepo ticket**, `Refs: <owner>/<superrepo>#<n>` (a bare `Refs: #<n>` would resolve against the submodule's own issue tracker); only superproject commits use the bare `Refs: #<n>`.
+- **Verify inside each submodule.** Run `git status` **inside every submodule the ticket touched** (nested included), not just the superproject: the superproject only ever shows a submodule as "modified", never that submodule's own dirty working tree. Every submodule path a ticket touches is named in its `Scope:` so setup, integration, and Verify all know which sub-repos to walk.
+- **`isolation: none`** is the escape hatch when you want neither per-ticket clones nor the escalation: commit inside the submodule (on a branch) + push it + bump the gitlink in the current checkout, accepting that the submodule then **serialises** across sessions (overlapping `Scope:` holds at claim).
 
 **A ticket that spans two or more submodules.** First ask whether it should be **split**: if the work decomposes into per-submodule pieces wired by a blocker (the gitlink bump waits on the code), prefer that. It stays one ticket only when the change is genuinely atomic across them (a shared contract both sides must adopt together). Then:
-- **Commits are coordinated, never one cross-repo commit** (git can't span repos): commit inside each submodule on its branch **first** (the objects must exist before anything can point at them), then a **single superproject commit that bumps all the gitlinks together** is the atomic "these versions ship as a set" record.
+- **Commits are coordinated, never one cross-repo commit** (git can't span repos): commit inside each submodule on its branch and **publish it first** (push, or merge its PR under `git: pr`; the objects must exist on a remote before anything durable can point at them), then a **single superproject commit that bumps all the gitlinks together** is the atomic "these versions ship as a set" record. Each submodule commit's `Refs:` is fully qualified at the superrepo ticket (`Refs: <owner>/<superrepo>#<n>`); the superproject commit uses the bare `Refs: #<n>`.
 - Its **`Scope:` lists every submodule path it touches**, so the coupling check treats a shared submodule path as overlap and flags a second session touching either one.
-- Under `isolation: worktree`, isolate **each touched repo** another session might also touch (a worktree per submodule, plus the parent for the bump); under `none`, work them in the current checkout and accept that each touched submodule serialises against other sessions.
+- When isolation is requested, the submodules force **`clone`** (worktree is escalated, above), so each touched sub-repo is already independent in the clone; under `none`, work them in the current checkout and accept that each touched submodule serialises against other sessions.
 
 ## Pausing & resuming
 Switching away from a ticket mid-work (to clear a blocker, chase an urgent bug, or just stop) must not lose the thread.
@@ -59,7 +64,7 @@ A repo can hold **more than one live map** at once: you park one to work another
 A ticket is sized to one ~100K-token session. When a claimed ticket turns out too big, or fans into distinct pieces, **split it**: don't grind through an oversized ticket. **Splitting is never autonomous.** Whether it was asked for explicitly (`/trailhead:split`) or surfaced mid-work ("this is too big once I'm in it"), **stop and ask the user before creating anything** (the split's shape, which children, is an advisory choice that **offers** the delegate option, per the injection recipe in `choices.md`):
 1. **Propose the split and wait for a go-ahead.** Present the children you would create (each one's title and why it's a distinct session-sized piece) and how the original's blockers would re-point, then **wait for the user's confirmation**. Create nothing until they say go: this is a stop-and-ask moment like the rest of the engine's, never the agent's own call. (An explicit `/trailhead:split` is the user asking *to* split, not a go-ahead on *how*: you still propose the decomposition and confirm it.)
 2. **Create the child tickets** (create-then-wire): each carries `Parent: <map>`, a `Split from: <original name+link>` line, its type label, the map's `trailhead:map-<n>` label + native sub-issue edge (like any ticket), and `trailhead:blocked` if it has an open blocker. **When children block each other** (B builds on A), wire B's blocker (both the `## Blocked by` line and the native dependency) at the **sibling child's real id (A)**, never at the split-origin: that original is being superseded and closed, so nothing may point at it as a live blocker. Describe A by role if you like, but *link its actual number*.
-3. **Supersede the original**: post a comment listing the children (`split into <names+links>`), label it **`trailhead:superseded`**, and **close it**. The children fully replace it.
+3. **Supersede the original**: post a comment listing the children (`split into <names+links>`), label it **`trailhead:superseded`**, **drop its native sub-issue edge from the map** (the eager drop at close in `substrate-commands.md`: label first, then the 404-tolerant DELETE, then close, so a slot is reclaimed while the label, `trailhead:map-<n>`, `Parent:` and split-origin links stay intact), and **close it**. The children fully replace it.
 4. The superseded ticket stays **out of `Decisions so far`** (it wasn't a decision walked; its children are). If other tickets were blocked by the original, re-point their `## Blocked by` at the relevant child and re-evaluate their `trailhead:blocked`.
 
 Splitting is not resolving: a superseded ticket delivered nothing itself. (If instead the ticket sits beyond the destination, that's *out of scope*, not a split.)
@@ -69,7 +74,9 @@ Two frontier tickets can be *unblocked of each other* yet still collide: they to
 
 **Path scope sharpens this (monorepo).** When tickets carry a `Scope:` line (the package/dir(s) they work in, see the ticket anatomy in SKILL.md), use it as the first filter: **disjoint scopes parallelize safely** (two tickets in unrelated packages can't share a file), so the check narrows to tickets whose scopes overlap or that both touch a shared lib / root config. Absent a `Scope:` line, fall back to the file/seam judgement above. Scope is a *hint that rules coupling out fast*, never a guarantee it exists: overlapping scopes still need the shared-writable-resource test before you flag.
 
-**Serialising a scope (`isolation: none`).** This is how you keep two sessions off the same submodule/package when worktrees don't fit (a path-bound app, see the isolation section). Under `isolation: none` the working tree is shared, so **two in-progress tickets whose `Scope:` overlaps cannot run at once**, whatever they touch inside it. So make the scope check a **hold at claim time, not an advisory flag**: right after claiming (before any work), scan the other in-progress tickets' `Scope:` lines; if one **overlaps** this ticket's scope, **stop and tell the user** the scope is busy (name the ticket and its holder), and offer to take a **disjoint-scope** frontier ticket instead or to wait. That overlap-holds-at-claim rule *is* "serialise `app/`": two `Scope: app/` tickets can't proceed together, no extra config needed, and the conventions prose only has to name which scope is serialised for humans. Under `isolation: worktree` this reverts to advisory (each ticket has its own worktree), and disjoint scopes always run free.
+**Serialising a scope (`isolation: none`).** This is how you keep two sessions off the same submodule/package when worktrees don't fit (a path-bound app, see the isolation section). Under `isolation: none` the working tree is shared, so **two in-progress tickets whose `Scope:` overlaps cannot run at once**, whatever they touch inside it. So make the scope check a **hold at claim time, not an advisory flag**: right after claiming (before any work), scan the other in-progress tickets' `Scope:` lines; if one **overlaps** this ticket's scope, **stop and tell the user** the scope is busy (name the ticket and its holder), and offer to take a **disjoint-scope** frontier ticket instead or to wait. That overlap-holds-at-claim rule *is* "serialise `app/`": two `Scope: app/` tickets can't proceed together, no extra config needed, and the conventions prose only has to name which scope is serialised for humans. Under `isolation: worktree` or `clone` this reverts to advisory (each ticket has its own workspace), and disjoint scopes always run free (the same-submodule case below is the one overlap `clone` still hard-holds).
+
+**Submodules count as shared scope (superrepo).** Treat **the same submodule path as overlapping scope**, exactly like the same superproject file. Two tickets that touch one submodule contend on its single gitlink tree entry and on the submodule's own shared history, so they **hard-serialise at claim** (a hold, like `isolation: none`), and this **holds even under `clone`**: the escalation gives each ticket an independent submodule *working copy*, but they still integrate to one shared submodule remote and one shared gitlink, so the same-submodule overlap is the one case where `clone` does **not** revert to the advisory-only treatment (unlike disjoint scopes, which run free). Two tickets touching *different* submodules each add a superproject commit that bumps a gitlink; those touch different index paths so git merges them cleanly, but they still **race at superproject push time** (two gitlink-bump commits pushed to `main` concurrently: git rejects the second, which pulls or rebases, re-verifies the gitlink, and retries), so coordinate the gitlink bumps rather than treating different-submodule tickets as needing no coordination at all.
 
 ## Concurrent edits to the map
 The map issue's **body** is a shared mutable document: two sessions appending to `Decisions so far` at once will clobber each other (GitHub doesn't merge bodies). So:

package/plugins/trailhead/skills/_shared/techniques/grilling.md

@@ -2,6 +2,7 @@
 Interrogate the human live, one question at a time, until the decision is unambiguous and its rationale is captured. This is human-in-the-loop: the decision is theirs, so never answer on their behalf, never assume an answer you haven't heard, never proceed on silence.
 
 - **Map the decision as a tree.** Every choice branches into the choices that hang off it. The *frontier* is every question whose prerequisites are already settled: the ones you can ask now without guessing. A question whose answer depends on another still-open one isn't on the frontier yet; it arrives there the moment that answer lands. You don't ask the frontier in a batch: you pick one from it, and recompute after the answer.
+- **Breadth before depth: enumerate the whole surface first.** When the subject is a space with many parts (mapping an app or a project's scope, not a single isolated choice), open by enumerating every functional area it implies (for a video player: media library, search, thumbnails, filters, genres, the player itself, ...) and get them all onto the record before deep-diving any one. Depth on the current thread is seductive, but the tree only ever grows the questions you actually raise, so an area you never name never enters it and stays silently missing. Fan out first (name every area), then converge each. The deliverable is coverage of the whole surface, not a deep answer on one corner of it.
 - **One question at a time, with your pick.** Number the question, state it, and offer your recommended answer. Then stop and wait. Each answer reshapes the tree: settled decisions push the frontier outward. Recompute and ask the next. Grilling stays human-decides: the **grilled questions themselves never offer the delegate option** (a recommended answer is not the delegate option), because converging a decision is the human's. A separate meta-ask a call-site may put *before* grilling (e.g. the `build`/`quick` Discuss "do you want a grilling round?") is its own advisory choice and can offer delegate/defer per that call-site. **When a grilled decision is genuinely blocked on a prerequisite, offer defer in prose** (state it in words as part of the question), per the recipe in `../choices.md`.
 - **Facts are your job, decisions are theirs.** When a question needs a fact from the environment (filesystem, code, tools), go find it yourself; never ask the human what you could look up. Only questions downstream of that lookup wait; ask the rest now.
 - **Refuse vague and hedged answers.** "Good," "fast," "simple," "users," "later" are not answers: probe. *Fast how: sub-second, or handles large datasets? Users: the Customer or the operator?* Make the abstract concrete: "walk me through it," "give me an example," "what does that actually look like?"
@@ -10,5 +11,5 @@ Interrogate the human live, one question at a time, until the decision is unambi
 - **Steelman and play devil's advocate.** State the strongest case for the option they're leaning away from. Attack the option they favor from its weakest seam. If it survives, the decision is stronger; if it cracks, you found the real question.
 - **Detect and open up tradeoffs.** When "or / versus / torn between / which is better" appears, pause: name what each side optimizes for, what each sacrifices, which aligns with the goal, then recommend with reasoning. Skip for trivial or already-decided choices.
 - **Play back your understanding** before closing each branch: restate the decision and its rationale in your words and have them confirm or correct.
-- **Stop only when the frontier is empty**: every branch visited, nothing silently assumed, the choice unambiguous *and* the why recorded.
+- **Stop only when the frontier is empty**: every branch visited, nothing silently assumed, the choice unambiguous *and* the why recorded. **For a multi-part space** (per the breadth bullet above) also require every functional area to have been enumerated and visited: an empty frontier reached while whole areas were never raised is a false finish, because the tree only ever grew the questions you raised. A single isolated choice has no areas to enumerate, so its empty frontier is a real finish.
 

package/plugins/trailhead/skills/trailhead/SKILL.md

@@ -1,32 +1,21 @@
 ---
 name: trailhead
 description: "Start and drive a large project (more than one agent session can hold) as a map of decision tickets on GitHub Issues, resolving one at a time until the way to the destination is clear. Self-contained (zero external-plugin dependencies: trailhead ships its own `trailhead-*` engine agents and needs only an authenticated gh CLI): map-based onboarding and a discuss→plan→execute→verify engine with atomic commits, with everything (map, discussion, plan, verification) living on the Issues. Invoke only when the user explicitly runs `/trailhead` (or a `/trailhead:<verb>` command) or asks to chart, adopt, or work a trailhead map, and do not auto-invoke for generic planning, project, or task-tracking requests."
-argument-hint: "[new|adopt|work|quick|whiteboard|ticket|inbox|map|dashboard|config|grill|split|pause|resume|auto|update|bug|todo|idea|seed|note] [text | ticket]"
+argument-hint: "[new|adopt|work|quick|whiteboard|ticket|inbox|map|dashboard|config|grill|split|pause|resume|auto|update|prune|bug|todo|idea|seed|note] [text | ticket]"
 ---
 
 `trailhead` charts a large project as a **shared map on GitHub Issues**, then works its **tickets** one at a time until the way to the destination is clear. This skill is the **entry point**: bare `/trailhead` runs **smart entry** (detect the repo state and propose the next move); a verb runs that verb's engine. Everything lives on the Issues; the repo holds code only.
 
 ## Load first, in order
 
-Before doing anything, read the shared core (paths relative to this file):
-
-`_shared/` is a **sibling** of this cluster's own directory (reached at `../_shared/`), never a child of it: the cluster dir holds only this cluster's own files (its `SKILL.md`, and a `references/` dir if it has one), so `_shared/` does not show up in a listing of it, and that absence never means the core is missing. Resolve and read `../_shared/`; never treat "no `_shared/` inside my own cluster dir" as "no shared core installed" and skip the core.
-
-1. `../_shared/principles.md`: refer by name, result-oriented output, no em-dashes, git per conventions, one ticket per session.
-2. `../_shared/ticket-language.md`: write all Issue prose and commit bodies in `config.ticket.language` (default `en`), independent of the chat language.
-3. `../_shared/substrate.md`: the GitHub-Issues model: labels, the frontier query, the map / ticket / dashboard / whiteboard anatomy, and the base-command cookbook pointer.
-4. `../_shared/session-handoff.md`: how every resolution closes (`/clear` first, then the next command).
-5. `../_shared/configuration.md`: the three config layers and the load contract.
-6. `../_shared/techniques.md`: the technique index and the subagent-type rule.
-
-Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file), before any isolation workspace is set up.
+Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_shared/` is a **sibling** of this cluster's own directory (at `../_shared/`), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
 
 ## Routing: verb to engine
 
 The **first word** of the arguments is the verb; the rest is the text or a ticket number. `/trailhead <verb>` and `/trailhead:<verb>` are equivalent.
 
 - **No verb** to **smart entry** (below): this skill handles it directly.
-- **A verb** to hand off to the skill that owns it, passing the whole argument string. **The skill-split migration ([map #53](https://github.com/ToRvaLDz/trailhead/issues/53)) lands the cluster skills one at a time.** The **chart cluster is built (#59)**: `new`, `adopt`, `ticket`, `inbox`, and `grill` route to the **`trailhead-chart`** skill (call the Skill tool with skill name `trailhead-chart` and arguments `<verb> <rest>`). The **work cluster is built (#60)**: `work`, `quick`, `pause`, `resume`, `split`, and `auto` route to the **`trailhead-work`** skill (call the Skill tool with skill name `trailhead-work` and arguments `<verb> <rest>`). The **view cluster is built (#61)**: `map`, `dashboard`, and `whiteboard` route to the **`trailhead-view`** skill (call the Skill tool with skill name `trailhead-view` and arguments `<verb> <rest>`). The **capture cluster is built (#62)**: `bug`, `todo`, `idea`, `seed`, and `note` route to the **`trailhead-capture`** skill (call the Skill tool with skill name `trailhead-capture` and arguments `<verb> <rest>`). The **manage cluster is built (#63)**: `config` and `update` route to the **`trailhead-manage`** skill (call the Skill tool with skill name `trailhead-manage` and arguments `<verb> <rest>`). Then carry out the target skill's instructions.
+- **A verb** to hand off to the skill that owns it, passing the whole argument string. **The skill-split migration ([map #53](https://github.com/ToRvaLDz/trailhead/issues/53)) lands the cluster skills one at a time.** The **chart cluster is built (#59)**: `new`, `adopt`, `ticket`, `inbox`, and `grill` route to the **`trailhead-chart`** skill (call the Skill tool with skill name `trailhead-chart` and arguments `<verb> <rest>`). The **work cluster is built (#60)**: `work`, `quick`, `pause`, `resume`, `split`, and `auto` route to the **`trailhead-work`** skill (call the Skill tool with skill name `trailhead-work` and arguments `<verb> <rest>`). The **view cluster is built (#61)**: `map`, `dashboard`, and `whiteboard` route to the **`trailhead-view`** skill (call the Skill tool with skill name `trailhead-view` and arguments `<verb> <rest>`). The **capture cluster is built (#62)**: `bug`, `todo`, `idea`, `seed`, and `note` route to the **`trailhead-capture`** skill (call the Skill tool with skill name `trailhead-capture` and arguments `<verb> <rest>`). The **manage cluster is built (#63)**: `config`, `update`, and `prune` route to the **`trailhead-manage`** skill (call the Skill tool with skill name `trailhead-manage` and arguments `<verb> <rest>`). Then carry out the target skill's instructions.
 - **Unrecognised verb** to treat the whole string as `idea` (route to `trailhead-capture` as `idea <text>`).
 
 The namespaced `/trailhead:<verb>` commands reach their target skill directly through their own command wrapper; this routing table only covers the bare `/trailhead <verb>` form.
@@ -37,7 +26,7 @@ With no verb, detect the repo state and **propose**, do not dead-end:
 
 - **No map** to offer *chart* (`/trailhead:new`) or *adopt* (`/trailhead:adopt`); or point at `/trailhead:whiteboard` if the repo has loose `trailhead:whiteboard` tickets but no map.
 - **Map present with a workable frontier** to route to *work*. Bare `/trailhead:work` takes one ticket to act on, but present the frontier as a **set to choose from** when its tickets are mutually independent, never a crowned first-listed (see **Frontier order carries no priority** in `../_shared/substrate.md`).
-- **Map present but its frontier is empty** (everything left is gated or still fog, or the map is complete-except-gated) to lay out the sensible moves as a short list, and **always include `/trailhead:quick "<text>"` right after `/trailhead:map`** as the way to do a discrete piece of work off the map now (`/trailhead:quick <n>` to work a loose ticket), alongside `/trailhead:map` for the full view, `/trailhead:whiteboard` when loose work waits, `/trailhead:new` to chart the next map, the captures (`todo` / `idea` / `bug` / `seed`) for new work, and graduating a fog line into a ticket when it is sharp enough.
+- **Map present but its frontier is empty** (everything left is gated or still fog, or the map is complete-except-gated) to lay out the sensible moves as a short list, and **always include `/trailhead:quick "<text>"` right after `/trailhead:map`** as the way to open and do a *new* discrete piece of work off the map now (an existing loose ticket is worked anchored on `/trailhead:work <n>`, with `/trailhead:quick <n>` as the no-split alternative), alongside `/trailhead:map` for the full view, `/trailhead:whiteboard` when loose work waits, `/trailhead:new` to chart the next map, the captures (`todo` / `idea` / `bug` / `seed`) for new work, and graduating a fog line into a ticket when it is sharp enough.
 
 **Self-heal the pinned dashboard** before proposing: ensure the repo's `trailhead:dashboard` index exists and is pinned. Ensure the label, then **create + pin only if missing, re-pin if the pin was dropped, and never rewrite the body on this render** (the dashboard model is in `../_shared/substrate.md`; the exact `gh` commands live in the substrate cookbook, at `../_shared/substrate-commands.md`). So a repo that adopted trailhead before the dashboard existed gets one on the next bare `/trailhead`.
 

package/plugins/trailhead/skills/trailhead-capture/SKILL.md

@@ -9,18 +9,9 @@ argument-hint: "[bug|todo|idea|seed|note] [--of <ticket>] <text>"
 
 ## Load first, in order
 
-Before doing anything, read the shared core (paths relative to this file):
+Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_shared/` is a **sibling** of this cluster's own directory (at `../_shared/`), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
 
-`_shared/` is a **sibling** of this cluster's own directory (reached at `../_shared/`), never a child of it: the cluster dir holds only this cluster's own files (its `SKILL.md`, and a `references/` dir if it has one), so `_shared/` does not show up in a listing of it, and that absence never means the core is missing. Resolve and read `../_shared/`; never treat "no `_shared/` inside my own cluster dir" as "no shared core installed" and skip the core.
-
-1. `../_shared/principles.md`: refer by name, result-oriented output, no em-dashes, git per conventions, one ticket per session.
-2. `../_shared/ticket-language.md`: write all Issue prose and commit bodies in `config.ticket.language` (default `en`), independent of the chat language.
-3. `../_shared/substrate.md`: the GitHub-Issues model: labels, the frontier query, the map / ticket / dashboard / whiteboard anatomy, and the base-command cookbook pointer.
-4. `../_shared/session-handoff.md`: how every resolution closes (`/clear` first, then the next command).
-5. `../_shared/configuration.md`: the three config layers and the load contract.
-6. `../_shared/techniques.md`: the technique index and the subagent-type rule.
-
-Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file). A capture writes at most one issue; no isolation workspace is set up.
+A capture writes at most one issue; no isolation workspace is set up.
 
 ## Routing: verb to engine
 

package/plugins/trailhead/skills/trailhead-capture/references/capture.md

@@ -2,7 +2,7 @@
 
 Capture without breaking flow, but with the **tracker** as destination, not scattered files. The verbs are named in this cluster's `../SKILL.md`; here is the detail of each. One capture = one action + one confirmation line; it resolves nothing.
 
-**Confirmation line.** Confirm the capture by the ticket's name (not a bare `#number`) and where it landed. **If you point at working it later, lead with `/clear`**: the confirmation is a place you point at the next ticket, so the [Session handoff](../../_shared/session-handoff.md)'s `/clear`-first rule applies: a compact, future-conditional one-liner is fine (a capture is not a resolution, so no full labelled block), along the lines of *"to work it later: `/clear`, then `/trailhead:work 45`"* (in the user's conversation language). Never a bare `/trailhead:work 45` with no `/clear`.
+**Confirmation line.** Confirm the capture by the ticket's name (not a bare `#number`) and where it landed. **If you point at working it later, lead with `/clear`**: the confirmation is a place you point at the next ticket, so the [Session handoff](../../_shared/session-handoff.md)'s `/clear`-first rule applies: a compact, future-conditional one-liner is fine (a capture is not a resolution, so no full labelled block), along the lines of *"to work it later: `/clear`, then `/trailhead:work 45`"* (in the user's conversation language). Never a bare `/trailhead:work 45` with no `/clear`, and (the same post-`/clear` invariant the [Session handoff](../../_shared/session-handoff.md) states) **never place after `/clear` an action the agent must perform that depends on context `/clear` erases**: a capture confirmation points only at user-runnable commands, which satisfies this by construction, so keep it that way. **Whenever the confirmation does point at working the ticket (a `seed` parked on its trigger, or a fog `note`/`idea` that is not a ticket yet, is the case where it does not), anchor the next step to `/trailhead:work <n>`, always:** it is the recommendation (the full engine, which can split and keeps the map record), and the confirmation names it first. `/trailhead:quick <n>` is **only** the off-map / no-split alternative (one alternative, described two ways: `quick` is the same work done off the map, without splitting), offered *alongside* `work`, **never in its place**. This holds for a **whiteboard** capture too, where both apply (`quick` is the no-split variant of `work`): the anchor stays `/trailhead:work <n>` for consistency. Same spirit as chart's codified close (#147).
 
 **Language (do not skip):** the captured ticket (title + body) is written in `config.ticket.language` (default `en`), **regardless of the language you are chatting in**. A capture fired in Italian still lands as an English ticket. This is the easiest place to slip, because a capture echoes the user's one-line phrasing; translate it, do not mirror it. See the *Ticket language* rule in `../../_shared/ticket-language.md`.
 

package/plugins/trailhead/skills/trailhead-chart/SKILL.md

@@ -9,18 +9,7 @@ argument-hint: "[new|adopt|ticket|inbox|grill] [idea | <type> <title> | issue |
 
 ## Load first, in order
 
-Before doing anything, read the shared core (paths relative to this file):
-
-`_shared/` is a **sibling** of this cluster's own directory (reached at `../_shared/`), never a child of it: the cluster dir holds only this cluster's own files (its `SKILL.md`, and a `references/` dir if it has one), so `_shared/` does not show up in a listing of it, and that absence never means the core is missing. Resolve and read `../_shared/`; never treat "no `_shared/` inside my own cluster dir" as "no shared core installed" and skip the core.
-
-1. `../_shared/principles.md`: refer by name, result-oriented output, no em-dashes, git per conventions, one ticket per session.
-2. `../_shared/ticket-language.md`: write all Issue prose and commit bodies in `config.ticket.language` (default `en`), independent of the chat language.
-3. `../_shared/substrate.md`: the GitHub-Issues model: labels, the frontier query, the map / ticket / dashboard / whiteboard anatomy, and the base-command cookbook pointer.
-4. `../_shared/session-handoff.md`: how every resolution closes (`/clear` first, then the next command).
-5. `../_shared/configuration.md`: the three config layers and the load contract.
-6. `../_shared/techniques.md`: the technique index and the subagent-type rule.
-
-Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file), before any isolation workspace is set up.
+Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_shared/` is a **sibling** of this cluster's own directory (at `../_shared/`), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
 
 ## Routing: verb to engine
 
@@ -52,3 +41,5 @@ Run a standalone **Grilling** (plus **Domain vocabulary**) session on a decision
 ## First-time config offer (end of chart / adopt)
 
 Charting hand-resolves nothing, so a fresh chart or adopt closes with this offer. When a project has a map but **no `.trailhead/config.json` yet**, put an **explicit two-way choice** to the user and wait for their pick: **(a) accept as-is** (continue on the current or proposed values, which writes an empty `{}`), or **(b) run `/trailhead:config`** to configure everything through the guided menu (models / design / TDD / ...). **Always name both paths and let the user choose; never silently take one.** You may show the values you would default to, but frame the close as this binary: **do not** pre-fill the config keys and ask for an open-ended inline edit, and **do not** interview the user key-by-key inline (that is `/trailhead:config`'s job). Ask this **only once**: running config writes the file, and *accept as-is* writes an empty `{}`, so once `.trailhead/config.json` exists it is never offered again (a `{}` file means "reviewed, using defaults").
+
+After this offer, the chart / adopt close renders the codified **next-step block** (`/trailhead:work`-anchored, `/clear` first). Its authoritative wording is single-sourced in **`references/charting.md`** (Mode 1 step 6, reached by Mode 1-bis), so read it there rather than restating its rules here.

package/plugins/trailhead/skills/trailhead-chart/references/charting.md

@@ -7,18 +7,28 @@ The user invokes with a loose idea.
 
 0. **Ensure a tracker repo exists (offer to create one if missing).** Everything trailhead writes lives on a GitHub repo's Issues, so before charting, confirm the current directory has one. Detect it with `gh repo view`: on success a GitHub repo with a remote is present, so say nothing and proceed. If there is **no GitHub repo** (no `origin` / GitHub remote, or `gh repo view` fails), **stop and ask the user** whether to create one, offering **private (default)** or **public**. On their choice: if the directory is not yet a git repo, `git init` and make an initial commit first; then `gh repo create <name> --private|--public --source=. --remote=origin --push` (take `<name>` from the directory, confirmed with the user), so the repo exists on GitHub with `origin` set. Charting continues only once a GitHub repo is in place: every step below writes to its Issues. If the user declines to create one, there is nowhere to chart, so stop and say so. This never fires when a repo already exists (`/trailhead:adopt` and re-charting on an existing repo skip straight past it).
 1. **Name the destination.** Run the **Grilling** + **Domain vocabulary** techniques to pin down what this map tends toward. The destination fixes the scope, so it's settled first. Default: a working artifact.
-2. **Map the frontier.** Grill again, **breadth-first**: fan out across the whole space rather than deep on one thread, surfacing the open decisions and the first steps takeable now. **If no fog surfaces** (the way is already clear, the whole thing fits one session) you don't need a map: stop and ask how to proceed. **Harvest parked work:** from **earlier maps on this repo**, gather the artifacts their *Out of scope* `→ future map` breadcrumbs point at (**parked seeds/todos**, see **Out of scope**) **and the ideas** left in their *Not yet specified* fog, then **ask the user which belong in *this* map**; pull the chosen seeds/todos in as tickets and the chosen ideas in as fog (or as tickets, if now sharp enough), and leave (or update the destination on) the rest.
-3. **Create the map** (`trailhead:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into *Not yet specified*. Run the **first-use repo setup** (see **Substrate** → `../../_shared/substrate-commands.md`) now: labels **and** the label-guard check/install. Once the map issue has its number `<n>`, **create its per-map label `trailhead:map-<n>`** (every ticket of this map carries it and is a native sub-issue of the map; the map issue itself is found by its number, so it does **not** carry the label; see **Multiple maps on one repo**). **If this repo already has another open `trailhead:map`**, tell the user the new map runs concurrently (its own scoped frontier) and set it as the active map (`.trailhead/active-map`). Then set up **conventions**: if no `trailhead:conventions` issue exists, run a **brief conventions brainstorming** (breadth-first, in the spirit of grilling but short: a handful of questions, not a full session) to surface the project's way of working: `git:` `main`|`pr`, `release:` `command`|`auto`, and `isolation:` `none`|`worktree` (the header, the last asked as *"will more than one session run on a single clone at once?"* → `worktree`; a monorepo leans `worktree`), **plus** the narrative a new contributor would need: release/deploy specifics (environments, manual steps, OTA vs full build, versioning), tooling that must be driven a certain way (a specific MCP/CLI, e.g. a Lovable project piloted via its MCP), code & style rules, testing/UAT norms. Distil into the issue (header + prose); link it from the map's Notes. Don't invent: leave out or ask what you can't determine. If one already exists, just link it (reuse across maps). Finally, **ensure the repo's `trailhead:dashboard` index issue exists** (see **The dashboard**): create and pin it if missing (the fixed 3rd pinned slot, alongside codebase + conventions), then **write it to list this map** (charting a map is a structural event); if it already exists, refresh it.
+2. **Map the frontier.** Grill again, **breadth-first**: **enumerate every functional area the destination implies** and **capture each one (headed for a fog entry under *Not yet specified* at minimum) before deep-diving any single area**. Fan out across the whole space rather than deep on one thread, surfacing the open decisions and the first steps takeable now. **The deliverable is the coverage the map will carry, not the grilling transcript: every area the destination implies must land on the map at step 3, as fog or as a ticket, so nothing is silently missing.** **If no fog surfaces** (the way is already clear, the whole thing fits one session) you don't need a map: stop and ask how to proceed. **Harvest parked work:** from **earlier maps on this repo**, gather the artifacts their *Out of scope* `→ future map` breadcrumbs point at (**parked seeds/todos**, see **Out of scope**) **and the ideas** left in their *Not yet specified* fog, then **ask the user which belong in *this* map**; pull the chosen seeds/todos in as tickets and the chosen ideas in as fog (or as tickets, if now sharp enough), and leave (or update the destination on) the rest.
+3. **Create the map** (`trailhead:map`): Destination and Notes filled in, Decisions-so-far empty, the fog sketched into *Not yet specified*. **Every functional area enumerated in step 2 must appear here, as a fog entry or a ticket, before moving on: the map is the coverage deliverable.** Run the **first-use repo setup** (see **Substrate** → `../../_shared/substrate-commands.md`) now: labels **and** the label-guard check/install. Once the map issue has its number `<n>`, **create its per-map label `trailhead:map-<n>`** (every ticket of this map carries it and is a native sub-issue of the map; the map issue itself is found by its number, so it does **not** carry the label; see **Multiple maps on one repo**). **If this repo already has another open `trailhead:map`**, tell the user the new map runs concurrently (its own scoped frontier) and set it as the active map (`.trailhead/active-map`). Then set up **conventions**: if no `trailhead:conventions` issue exists, run a **brief conventions brainstorming** (breadth-first, in the spirit of grilling but short: a handful of questions, not a full session) to surface the project's way of working: `git:` `main`|`pr`, `release:` `command`|`auto`, and `isolation:` `auto`|`none`|`worktree`|`clone` (default **`auto`**, which decides per ticket at work-start by asking *"will more than one ticket be worked at once on this machine this session?"* and picking `worktree` for a plain repo or `clone` for a submodule superrepo; a project can force `none`/`worktree`/`clone` explicitly), **plus** the narrative a new contributor would need: release/deploy specifics (environments, manual steps, OTA vs full build, versioning), tooling that must be driven a certain way (a specific MCP/CLI, e.g. a Lovable project piloted via its MCP), code & style rules, testing/UAT norms. Distil into the issue (header + prose); link it from the map's Notes. Don't invent: leave out or ask what you can't determine. If one already exists, just link it (reuse across maps). Finally, **ensure the repo's `trailhead:dashboard` index issue exists** (see **The dashboard**): create and pin it if missing (the fixed 3rd pinned slot, alongside codebase + conventions), then **write it to list this map** (charting a map is a structural event); if it already exists, refresh it.
 4. **Create the tickets you can specify now** as child issues (each with `trailhead:ticket` + its type + this map's `trailhead:map-<n>` label, **plus `trailhead:blocked` when the mapped dependency graph already shows it has a blocker**, and set as a **native sub-issue** of the map, see **Child→map link** under Substrate), then wire the blocking in a **second pass** (issues need ids before they can reference each other): for each ticket **read its Question and wire a blocker for every still-open ticket whose output it consumes** (don't stop at the first/obvious one) by wiring its `## Blocked by` line + native dependency together (moves 1-2 of the three-move wiring; the `trailhead:blocked` label, move 3, already rode in at creation, see **Substrate**). **Set the blocked label at creation, not via a post-creation `--add-label` pass:** a bulk `--add-label` burst spawns one repo-side label-guard run per ticket and reddens the Actions history with sheddable no-op runs; riding the label in the ticket's `issues.opened` event avoids that entirely. Wiring sorts them into frontier (unblocked) and blocked; the rest stays fog.
 5. **Fire the research subagents.** For each `research` ticket created, run the **Research** technique in parallel, findings on a `research/<name>` branch with a pointer from the ticket.
 6. **Offer config, then stop.** Charting is one session's work; it hand-resolves nothing. Before ending, make the **first-time config offer** (see **First-time config offer** in `../SKILL.md`): the project now has a fresh map and no `.trailhead/config.json`, so put the **two-way choice** to the user, **accept as-is** (writes `{}`) or **run `/trailhead:config`** for the guided menu, and let them pick. Name both paths; don't pre-fill the config keys and ask for an inline edit, and don't interview them key-by-key here (that's `/trailhead:config`'s job). Once the file exists it's never offered again. **No `trailhead:codebase` issue is created here**: greenfield has no code to map yet. It's created later, once the repo has substantial code (see Mode 2 step 1 and the **Codebase** row under Substrate), so at chart two of the three permanent pins (the dashboard + conventions) are filled and the codebase slot fills in later. Maps are never pinned.
 
+**Next-step block (the close of chart, and of adopt).** Charting hand-resolves nothing, so the **Session handoff** ritual (`../../_shared/session-handoff.md`) does not fire here; render this codified next-step block instead, **right after the first-time config offer above**, styled on the handoff's own next-step block and written in the user's conversation language. Newly charted tickets are **map-frontier** tickets, so the primary move is `/trailhead:work` (the full engine: it can split and keeps the map record), with `/trailhead:quick` only as the off-map alternative. Every bullet below is a thing to do **after** the `/clear`, which leads; never point at the next command without it, and never demote `/clear` to a trailing parenthetical.
+
+> **Prossimo passo:**
+> - `/clear`: per liberare il contesto
+> - poi `/trailhead:work <numero>` per lavorare **<nome del primo ticket di frontiera>** (è un ticket di mappa: `work` lo porta avanti col motore completo, può splittarlo, tiene il record della mappa)
+> - `/trailhead:map` per la vista completa o `/trailhead:dashboard` per l'indice di tutte le mappe e del whiteboard, se vuoi guardare prima di scegliere
+> - in alternativa `/trailhead:quick "<il pezzo>"` solo per lavorare un pezzo fuori mappa
+
+Same rules as the handoff block: **name the ticket, put its number (never the title) in the `/trailhead:work` command**; when several **mutually independent** frontier tickets sit on the frontier, present them as a **set to choose from** rather than crowning one (see **Frontier order carries no priority** in `../../_shared/substrate.md`). **If charting left no unblocked frontier ticket** (everything landed as fog or blocked), point the block at `/trailhead:map` to pick which fog to specify next, exactly as the empty-frontier case in the handoff. This block is **Mode 1's close, single-sourced here**; **Mode 1-bis (adopt) reaches it through its "As Mode 1, steps 4–6" reference**, so it applies to both protocols with no duplicate block.
+
 ## Mode 1-bis: Adopt an existing project, `/trailhead:adopt`
 When the code already exists (project in progress). Like Mode 1, but start from **reality**, not a blank page. One heavy step at entry, then all lean.
 
 1. **Map the codebase (once per repo).** Heavy step, *only* at adoption: it does not repeat per ticket, and **not per map**. First check for an existing **`trailhead:codebase`** issue: if one exists (an earlier map on this repo created it) and the code hasn't materially drifted, just **link it** from this map's Notes and skip the fan-out. Otherwise run the **Codebase map** technique (a parallel fan-out of reader subagents) for a structured understanding (architecture, stack, decisions already embodied, risk areas) and distil the essence into the repo's **`trailhead:codebase` issue** (create it, label `trailhead:codebase`), then link that issue from the map's Notes. Discard the raw. Because it's a standalone repo-scoped issue, the next map reuses it instead of re-deriving or losing it.
 2. **Name the destination of the remaining stretch.** **Grilling** + **Domain vocabulary**, **seeded by the map you just built**: not "what is the project" but "what's left to reach working / the next milestone".
 3. **Backfill the decisions already made.** Choices already embodied in the code (now visible from the map) or stated by the user go into `Decisions so far` as **ticket-less** lines (they're already closed), so the map reflects reality and doesn't pretend greenfield. Link to code/commits where useful.
-4. **Map the frontier of the remainder** → tickets specifiable now + fog in *Not yet specified*, then wire the blocking and fire the research. **Harvest parked work** (todos *and* ideas) from earlier maps on this repo (their `→ future map` *Out of scope* lines and their *Not yet specified* fog), asking the user which belong here, as in Mode 1 step 2. As Mode 1, steps 4–6.
+4. **Map the frontier of the remainder**, **breadth-first as in Mode 1 step 2**: enumerate every functional area still standing between the code and the destination and **land each on the map (fog in *Not yet specified* at minimum) before deep-diving any one**, so the map makes every remaining section visible; the map, not the transcript, is the deliverable to check for that coverage. This yields → tickets specifiable now + fog in *Not yet specified*, then wire the blocking and fire the research. **Harvest parked work** (todos *and* ideas) from earlier maps on this repo (their `→ future map` *Out of scope* lines and their *Not yet specified* fog), asking the user which belong here, as in Mode 1 step 2. As Mode 1, steps 4–6.
 
-The tracker is the existing repo's (`gh` in its directory); run the **first-use repo setup** (see `../../_shared/substrate-commands.md`) on first use (missing `trailhead:*` labels **and** the label-guard check/install (adopting an existing repo is exactly when the guard tends to be missing)) and set up the `trailhead:conventions` issue via a **brief conventions brainstorming** (see Mode 1 step 3), but here, **seed the questions from what's discoverable** so you confirm rather than ask blind: an existing `CLAUDE.md`/`AGENTS.md`, CI workflows, the PR-vs-`main` git history, package scripts, deploy config. **Detect a monorepo** (a `pnpm-workspace.yaml`, a `workspaces` field, an `nx.json`/`turbo.json`, or several packages under `packages/`|`apps/`) and, if found, propose `isolation: worktree` and note that tickets should carry a `Scope:` line, **unless the buildable units are path-bound** (see below). **Detect git submodules** (a `.gitmodules` file) and, if found, add the prose rule that submodule work is committed **inside the submodule + a gitlink bump in the parent**, isolated at the submodule (not the superproject); a submodule path is a natural `Scope:` (see **Working as a team**). **Before proposing `worktree`, check for path-bound tooling** (a React Native/Expo app, native toolchains, a package whose build depends on a local `node_modules`/bundler cache/absolute-path config): those don't build from a worktree, so for them propose **`isolation: clone`** (a per-ticket clone that installs its own deps and builds), or `isolation: none` + **serialize** if the user doesn't want per-ticket clones. Worktree is for units that build from any path. Propose the values you inferred and let the human correct/complete them; create the issue if absent, link it from the map's Notes. Also **ensure the repo's `trailhead:dashboard` index issue exists** (see **The dashboard**): create and pin it if missing (the fixed 3rd pinned slot, alongside codebase + conventions) and write it to list this map.
+The tracker is the existing repo's (`gh` in its directory); run the **first-use repo setup** (see `../../_shared/substrate-commands.md`) on first use (missing `trailhead:*` labels **and** the label-guard check/install (adopting an existing repo is exactly when the guard tends to be missing)) and set up the `trailhead:conventions` issue via a **brief conventions brainstorming** (see Mode 1 step 3), but here, **seed the questions from what's discoverable** so you confirm rather than ask blind: an existing `CLAUDE.md`/`AGENTS.md`, CI workflows, the PR-vs-`main` git history, package scripts, deploy config. **Detect a monorepo** (a `pnpm-workspace.yaml`, a `workspaces` field, an `nx.json`/`turbo.json`, or several packages under `packages/`|`apps/`) and, if found, keep the default `isolation: auto` (it picks `worktree` for such a plain/monorepo checkout at work-start) and note that tickets should carry a `Scope:` line, **unless the buildable units are path-bound** (see below). **Detect git submodules** (a `.gitmodules` file) and, if found, add the prose rule that submodule work is committed **inside the submodule (on a branch), published, then a gitlink bump in the parent**, and that a **submodule-bearing superrepo resolves to `clone`** under the default `auto` (a superproject `worktree` cannot safely carry submodule state, so worktree is escalated to `clone`); a submodule path is a natural `Scope:` (see **Working as a team**). **For path-bound tooling** (a React Native/Expo app, native toolchains, a package whose build depends on a local `node_modules`/bundler cache/absolute-path config): those don't build from a worktree, so for them prefer an explicit **`isolation: clone`** (a per-ticket clone that installs its own deps and builds), or `isolation: none` + **serialize** if the user doesn't want per-ticket clones. Worktree is for units that build from any path. Propose the values you inferred and let the human correct/complete them; create the issue if absent, link it from the map's Notes. Also **ensure the repo's `trailhead:dashboard` index issue exists** (see **The dashboard**): create and pin it if missing (the fixed 3rd pinned slot, alongside codebase + conventions) and write it to list this map.

package/plugins/trailhead/skills/trailhead-chart/references/inbox.md

@@ -14,7 +14,7 @@ gh issue list --state open --json number,title,author,labels \
 ```bash
 gh issue list --label trailhead:fog --state open --search "sort:updated-desc"
 ```
-This is **how you notice a fog has cleared**: you don't watch each thread; you run the inbox (as you would to triage new issues), and the parked-fog section surfaces the parked items that moved. For each, decide: **graduate** (adopt in place, see Fog of war), **keep parked** (still vague), or **drop** (turned out out-of-scope/dead → `trailhead:out-of-scope` + close). Optionally, a participant can nudge readiness by commenting on the thread; you confirm at graduation.
+This is **how you notice a fog has cleared**: you don't watch each thread; you run the inbox (as you would to triage new issues), and the parked-fog section surfaces the parked items that moved. For each, decide: **graduate** (adopt in place, see Fog of war), **keep parked** (still vague), or **drop** (turned out out-of-scope/dead → `trailhead:out-of-scope`, drop any native sub-issue edge to reclaim a slot, then close: the eager drop in `../../_shared/substrate-commands.md` is 404-tolerant, so a fog with no edge is a no-op). Optionally, a participant can nudge readiness by commenting on the thread; you confirm at graduation.
 
 **Out-of-scope lines actually deferred?** Scan the map's *Out of scope* section for lines that are **deferred**, not truly ruled out: ones that **name a gate or trigger** (*gated by X*, *quando X*, *dipende da X*), carry a **this-only scope qualifier** (*per questo slice*, *for now*, *in this milestone*, not for the product), describe a **feature wanted later** (already annotated `→ future map`, or plainly still on the roadmap), or **are the gate of an existing `trailhead:seed`**. That last one is a **near-deterministic check**: cross-reference every open `trailhead:seed`'s trigger / `## Blocked by` against the *Out of scope* lines; a line some seed waits on is a **live gate**, so it cannot be "ruled out" and the cluster is **mis-wired** (the gate was left behind), re-route it. A line **decided against for the product** (won't be built, wrong approach, no "for this slice" qualifier) stays put; and a line **already properly parked** (annotated `→ future map` with its dependent seeds wired to a live trigger) is settled, skip it. Only **un-parked** deferred lines surface here. For each deferred line, **ask the user** (never decide silently) how to re-route it, `seed` / `idea` / `todo`, and **which map** it belongs to (this one, or a future / other map), then apply the **out-of-scope-vs-deferred** rules (see `../../_shared/out-of-scope.md`): **re-route the gate first**, tie its dependents to the gate's new form with a **live trigger** (never a dead "ruled out" line), and **move the whole cluster together**. Update or remove the *Out of scope* line to match where each item went (a future-map item stays as an annotated `→ future map` line; an item pulled into this map leaves *Out of scope* entirely).
 
@@ -22,7 +22,7 @@ For each issue in the first two sections (incoming issues, parked fog), decide,
 
 - **Adopt → a ticket.** Integrate it *in place* (same issue number, so the reporter stays credited): append a trailhead block to the body: `Parent: <map name+link>`, `Adopted-from: opened by @<author>`, a reframed `## Question` (the decision/build the *map* will act on), and `## Blocked by`, **without erasing the reporter's original text above it**. Apply `trailhead:ticket` + the right type label (`bug`/`decision`/`build`/`research`/`task`) as a write-access maintainer (which also satisfies Trust & provenance), plus the map's `trailhead:map-<n>` label + native sub-issue edge (like any ticket, so it joins the right map's frontier); add `trailhead:blocked` if it has an open blocker. It lands on the frontier. Comment to the reporter that it's been picked up.
 - **Fog.** In scope but not sharp enough to ticket → **keep the issue open and label it `trailhead:fog`** (parked: still visible and tracked, but the `trailhead:*` label drops it out of the inbound query, so it won't re-surface at every triage). Then use the open issue as a **clarification space**: post a comment with the questions that would make it concrete, in the spirit of **Grilling**, but async ("what would *done* look like? which users? where does it show?"), and invite the reporter and anyone interested to refine it in the thread. The fog dissipates through that conversation as much as through other work landing; others can carry the discussion with the reporter without you in the loop. **You don't lose it**: `gh issue list --label trailhead:fog` is the durable list, and the reporter follows their own open issue. When the thread (or the wider work) has made the question sharp, **adopt it in place**: swap `trailhead:fog` for `trailhead:ticket` + the type label, add `Parent:` and the now-answerable `## Question`, and it lands on the frontier: same issue, same reporter, the clarifying discussion preserved above.
-- **Out of scope.** Beyond the destination → label `trailhead:out-of-scope`, close with the why.
+- **Out of scope.** Beyond the destination → label `trailhead:out-of-scope`, **drop its native sub-issue edge** to reclaim a slot (the eager drop in `../../_shared/substrate-commands.md`, 404-tolerant, so an un-adopted inbound issue with no edge is a no-op), then close with the why.
 - **Duplicate.** Link the existing ticket and close.
 - **Needs info.** Ask the reporter for a repro or specifics; leave it open.
 

package/plugins/trailhead/skills/trailhead-manage/SKILL.md

@@ -1,32 +1,24 @@
 ---
 name: trailhead-manage
 user-invocable: false
-description: "trailhead manage cluster: the admin verbs that keep a trailhead install healthy. Show the effective config or change it through a guided menu (config); check for a newer trailhead and install it where that is safe (update). A cohesion cluster of the trailhead skill split, loading the shared `_shared/` core; reached through the `/trailhead:<verb>` command wrappers and the bare `/trailhead` dispatcher. Not auto-invoked: it runs only when one of these verbs is dispatched."
-argument-hint: "[config|update] [get|set …]"
+description: "trailhead manage cluster: the admin verbs that keep a trailhead install healthy. Show the effective config or change it through a guided menu (config); check for a newer trailhead and install it where that is safe (update), and prune a map's sub-issue edges to reclaim slots under GitHub's 100-cap (prune). A cohesion cluster of the trailhead skill split, loading the shared `_shared/` core; reached through the `/trailhead:<verb>` command wrappers and the bare `/trailhead` dispatcher. Not auto-invoked: it runs only when one of these verbs is dispatched."
+argument-hint: "[config|update|prune] [get|set … | map]"
 ---
 
-`trailhead-manage` is the **manage cluster** of the trailhead skill: the admin verbs that keep a trailhead install healthy. `config` shows the effective config or changes it (a guided menu, or `get` / `set <key> <value>`); `update` checks for a newer trailhead and installs it where that is safe. Everything lives on the GitHub Issues; the repo holds code only.
+`trailhead-manage` is the **manage cluster** of the trailhead skill: the admin verbs that keep a trailhead install healthy. `config` shows the effective config or changes it (a guided menu, or `get` / `set <key> <value>`); `update` checks for a newer trailhead and installs it where that is safe; `prune` reclaims a map's native sub-issue slots under GitHub's 100-cap. Everything lives on the GitHub Issues; the repo holds code only.
 
 ## Load first, in order
 
-Before doing anything, read the shared core (paths relative to this file):
+Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_shared/` is a **sibling** of this cluster's own directory (at `../_shared/`), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
 
-`_shared/` is a **sibling** of this cluster's own directory (reached at `../_shared/`), never a child of it: the cluster dir holds only this cluster's own files (its `SKILL.md`, and a `references/` dir if it has one), so `_shared/` does not show up in a listing of it, and that absence never means the core is missing. Resolve and read `../_shared/`; never treat "no `_shared/` inside my own cluster dir" as "no shared core installed" and skip the core.
-
-1. `../_shared/principles.md`: refer by name, result-oriented output, no em-dashes, git per conventions, one ticket per session.
-2. `../_shared/ticket-language.md`: write all Issue prose and commit bodies in `config.ticket.language` (default `en`), independent of the chat language.
-3. `../_shared/substrate.md`: the GitHub-Issues model: labels, the frontier query, the map / ticket / dashboard / whiteboard anatomy, and the base-command cookbook pointer.
-4. `../_shared/session-handoff.md`: how every resolution closes (`/clear` first, then the next command).
-5. `../_shared/configuration.md`: the three config layers and the load contract.
-6. `../_shared/techniques.md`: the technique index and the subagent-type rule.
-
-Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file). These admin verbs resolve no ticket and set up no isolation workspace.
+These admin verbs resolve no ticket and set up no isolation workspace.
 
 ## Routing: verb to engine
 
-The **first word** of the arguments is the verb (`config` or `update`); the rest is that verb's argument (`get`, `set <key> <value>`, or empty).
+The **first word** of the arguments is the verb (`config`, `update`, or `prune`); the rest is that verb's argument (`get`, `set <key> <value>`, a map, or empty).
 
 - **`config [get|set …]`** to **`../_shared/configuration-reference.md`**: the config keys, their semantics, and the guided menu setup. With no argument it runs the guided setup; `config get` prints the merged config read-only (project `.trailhead/config.json` over global over defaults, showing which source wins each key); `config set <key> <value>` writes one key directly (to the project `.trailhead/config.json`, or to `~/.claude/trailhead/config.json` with `--global`). Read that file and follow it.
 - **`update`** to **`references/updating.md`**: the update protocol (detect the install channel, compare the installed version with the latest from the matching source, install the newer one where it is safe). Read that file and follow it.
+- **`prune [map]`** to **`references/pruning.md`**: reclaim native sub-issue slots on a map near or at GitHub's 100 sub-issue cap by dropping the edges of closed and orphan tickets and re-adding missing ones, keeping every reference (Parent line, Decisions-so-far pointer, map label). With no argument it prunes the active map. Read that file and follow it.
 
 The full config **key reference** is a single source, shared with the rest of the skill: `../_shared/configuration-reference.md` (keys + guided setup).

package/plugins/trailhead/skills/trailhead-manage/references/pruning.md

@@ -0,0 +1,48 @@
+# Pruning a map's sub-issue edges
+
+`/trailhead:prune [map]` reclaims native sub-issue slots on a map that is near or at **GitHub's hard cap of 100 native sub-issues per issue**, so new tickets can keep attaching to the map's visual sub-issue tree. It never loses anything from the record: it drops only the **native edge**, and every reference stays (the ticket's `Parent:` line, the map's `Decisions so far` pointer, and the `trailhead:map-<n>` label).
+
+**Why this is safe.** The frontier is computed from the `trailhead:map-<n>` **label**, never from the native edge (see `../../_shared/substrate.md`). So the native sub-issue edge is purely GitHub's visual rendering: dropping the edge of a closed ticket, or of an open ticket that no longer belongs to this map, changes nothing in engine behaviour (selection, blocking, resolution). Only GitHub's sub-issue tree and progress bar are affected, and a dropped edge can always be re-added later.
+
+## 1. Resolve the target map
+
+The argument is the map (number or URL). With no argument, use the active map (`.trailhead/active-map`); if there is no active map and more than one `trailhead:map` is open, list them and ask which. Set/refresh `.trailhead/active-map` to the map being pruned (see **Multiple maps on one repo** in `../../_shared/multi-map.md`).
+
+## 2. Read the count and list the edges
+
+Read the map's native sub-issue count (one cheap field), then list every native sub-issue of the map, **paginated** (never a single page), capturing each one's number, id, and state. The exact `gh` commands are in `../../_shared/substrate-commands.md` (section "Sub-issue cap and pruning"); this protocol only says how to use them.
+
+## 3. Classify each edge (bidirectional reconcile)
+
+Classify every edge by its target, so the pass converges the map's edges to exactly "its open, still-labelled tickets":
+- **Target is CLOSED** -> **remove** the edge (reclaim the slot; references kept). This is mostly resolved tickets: since #151 a superseded / out-of-scope close already sheds its edge eagerly at close (see the eager drop in `../../_shared/substrate-commands.md`), so a closed ticket still carrying its edge here is normally a resolved one (or a pre-#151 / fallback legacy edge).
+- **Target is OPEN and still carries `trailhead:map-<n>` for this map** -> **keep** the edge.
+- **Target is OPEN but does NOT carry `trailhead:map-<n>` for this map** (an orphan: a ticket that no longer belongs to this map) -> **remove** the edge. It does not belong here; its own map, if any, holds its own edge. Confirm the label is genuinely absent before removing (read the ticket's labels), so a ticket that is legitimately mid-wiring is never stripped.
+
+Also compute the **missing** set: open tickets that **do** carry `trailhead:map-<n>` for this map but have **no** edge in the list above (re-derived by diffing, so no stored state is needed).
+
+## 4. Preview and confirm (never mutate silently)
+
+Show a preview and wait for an explicit go-ahead before any change:
+- edges to **remove**: how many closed, how many orphan-open, and the resulting `total` (X -> Y);
+- edges to **add**: how many missing edges for open labelled tickets, and how many will fit under the cap after the removals.
+
+This choice is advisory (a process choice): offer the delegate option per `../../_shared/choices.md`. On anything but an explicit yes, stop and change nothing.
+
+## 5. Apply
+
+Remove each classified-for-removal edge with the DELETE from `../../_shared/substrate-commands.md` (section "Sub-issue cap and pruning"), passing the edge's internal `id` captured in step 2. Then **re-read** `sub_issues_summary.total` (do not trust the pre-removal count) and add the missing edges up to the remaining capacity (100 - current total), each independently, with the re-add POST from that same section. The missing set came from a label diff, so it holds issue *numbers*, not internal ids: resolve each missing ticket's internal id first (the POST snippet in the cookbook shows the `$(gh api .../<ticket> --jq .id)` substitution).
+
+Because each id came from step 2's listing, a 404 here means the edge is no longer native (a detach that raced this run, for example a concurrent prune): the slot is already free, so count it toward the reconciled/removed result and keep going, per the 404-tolerance documented in the cookbook. That is distinct from a genuine failure.
+
+Report **per edge**: each removal and each add, success or failure. A single edge failing (for example a concurrent creation consuming the last slot) is never fatal: record it and continue.
+
+## 6. Report
+
+Say plainly what happened: slots reclaimed (closed + orphan removed), edges re-added, and the new `total` against 100. An already-detached edge caught as a 404 is a clean no-op, not a failed edge; keep it out of any failure count, distinct from a genuine edge failure (a transient API error or a permissions error), which is what "record it and continue" covers. If open labelled tickets still lack an edge because capacity ran out, **list them** and note that a later `/trailhead:prune` (once more tickets close) will attach them. Never close, reopen, relabel, or otherwise touch any ticket: prune only ever adds or removes the map's native sub-issue edges.
+
+## Notes
+
+- Prune touches **only this map's** native edges; it never mutates another map's tree, and never a ticket's body, labels, or state.
+- The dashboard flags a map `near cap · <total>/100` (total >= 90) or `at cap` (total >= 100), appending `· prunable` when the map has closed edges to reclaim, and offers `/trailhead:prune`; it never auto-prunes (see the dashboard render in `../../trailhead-view/SKILL.md`).
+- At edge-add time the engine pre-checks the cap and offers prune instead of silently dropping the edge (see the child->map procedure in `../../_shared/substrate-commands.md`).

package/plugins/trailhead/skills/trailhead-view/SKILL.md

@@ -9,18 +9,9 @@ argument-hint: "[map|dashboard|whiteboard] [map]"
 
 ## Load first, in order
 
-Before doing anything, read the shared core (paths relative to this file):
+Before doing anything, read `../_shared/load-first.md` and follow it: the shared-core load contract (the six core files, in order, then the effective config). `_shared/` is a **sibling** of this cluster's own directory (at `../_shared/`), never a child of it; its absence from a listing of the cluster dir is expected, not a missing core.
 
-`_shared/` is a **sibling** of this cluster's own directory (reached at `../_shared/`), never a child of it: the cluster dir holds only this cluster's own files (its `SKILL.md`, and a `references/` dir if it has one), so `_shared/` does not show up in a listing of it, and that absence never means the core is missing. Resolve and read `../_shared/`; never treat "no `_shared/` inside my own cluster dir" as "no shared core installed" and skip the core.
-
-1. `../_shared/principles.md`: refer by name, result-oriented output, no em-dashes, git per conventions, one ticket per session.
-2. `../_shared/ticket-language.md`: write all Issue prose and commit bodies in `config.ticket.language` (default `en`), independent of the chat language.
-3. `../_shared/substrate.md`: the GitHub-Issues model: labels, the frontier query, the map / ticket / dashboard / whiteboard anatomy, and the base-command cookbook pointer.
-4. `../_shared/session-handoff.md`: how every resolution closes (`/clear` first, then the next command).
-5. `../_shared/configuration.md`: the three config layers and the load contract.
-6. `../_shared/techniques.md`: the technique index and the subagent-type rule.
-
-Load the **effective config** (per `../_shared/configuration.md`) at session start, from the map's project root (`.trailhead/config.json` plus the global file). These are read-only renders: no isolation workspace is set up.
+These are read-only renders: no isolation workspace is set up.
 
 ## Routing: verb to engine
 
@@ -78,7 +69,7 @@ So `Decisions so far` / `Not yet specified` / `Out of scope` refer to these bloc
 A repo's trailhead surface is spread across issues: one or more maps, a whiteboard, an inbox. The **dashboard** is the single pinned entry point that indexes all of it: a permanent, repo-scoped issue labelled **`trailhead:dashboard`**, created once at the first chart/adopt and occupying the **fixed 3rd pinned slot** alongside `trailhead:codebase` and `trailhead:conventions` (see `../_shared/substrate.md`). Maps themselves are **never pinned**: a pin is server-side and global to the repo, but the active map is client-side per-checkout state (`.trailhead/active-map`, gitignored), so no single map is "the" map to pin. The dashboard gives one stable pinned index that scales to any number of maps and to the whiteboard.
 
 It holds:
-- a link to **every open `trailhead:map`** (found via the `trailhead:map` label); GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it never recomputes per-ticket progress. **Per open map it also runs one cheap `0 open scoped issues?` pre-filter** and, for a candidate confirmed to have no remaining fog (see the exhaustion check in `../_shared/substrate-commands.md`), flags an **exhausted-but-open** map (destination reached, map issue never closed) as `exhausted · closeable`, so the render can offer to close it (below);
+- a link to **every open `trailhead:map`** (found via the `trailhead:map` label); GitHub renders each map's sub-issue **progress bar natively**, so the dashboard only links, it never recomputes per-ticket progress. **Per open map it also runs one cheap `0 open scoped issues?` pre-filter** and, for a candidate confirmed to have no remaining fog (see the exhaustion check in `../_shared/substrate-commands.md`), flags an **exhausted-but-open** map (destination reached, map issue never closed) as `exhausted · closeable`, so the render can offer to close it (below). It also flags each open map **`near cap · <total>/100`** (total >= 90) or **`at cap`** (total >= 100) from `sub_issues_summary.total`, appending **`· prunable`** when the map has closed edges to reclaim, so the render can offer `/trailhead:prune` (below);
 - the **whiteboard** as its own section (frontier / in-progress / blocked, or a link to the `whiteboard` view);
 - dynamic **counts**: untriaged inbox size, whiteboard frontier size.
 
@@ -86,6 +77,8 @@ It holds:
 
 **Exhausted-but-open maps: flag and offer to close.** The one-shot "close this map?" prompt fires only at the exhaustion moment (a `work` handoff, or a `map` render on the exhausted map). If that moment was skipped, or the user chose to leave the map open, an exhausted map lingers with nothing re-surfacing it. So the dashboard is the recurring surface that catches it: for every open map flagged `exhausted · closeable` (the `0 open scoped issues?` pre-filter confirmed against remaining fog, see `../_shared/substrate-commands.md`), the render **offers to close it** (route any un-parked deferred *Out of scope* line first, exactly as the `map` exhaustion check does), `gh issue close` on a yes, leave it open on a no. Never auto-close: flag + offer only. The count runs per map, but the body read (fog confirm + deferred routing) is bounded to the exhausted candidates, so this stays within the dashboard-only-links spirit.
 
+**Near/at-cap maps: flag and offer to prune.** The same advisory posture applies to GitHub's 100 native sub-issue cap: a map flagged `near cap · <total>/100` or `at cap · prunable` gets the render's offer to run `/trailhead:prune`, never an auto-prune (see the cap-aware edge wiring and the `gh` mechanics in `../_shared/substrate-commands.md`).
+
 **Freshness: structural events + on demand.** The pinned issue is rewritten when the surface changes **structurally** and **on demand** via `dashboard`. The structural events are: a map is **charted** or **exhausted** (a map appears or disappears), and a **whiteboard ticket is born or resolved**. It is **not** rewritten on every *map* ticket resolve: that would churn a pinned issue (and its notifications) constantly, and each map's native sub-issue progress bar already tracks its per-ticket progress. **The whiteboard has no such native progress bar** (its tickets are sub-issues of nothing), so the dashboard's whiteboard section and count are the only place whiteboard state shows: a whiteboard ticket appearing or being resolved *is* a structural change to the indexed surface, and refreshes the dashboard. **One timing exception for `quick`:** a ticket born by `quick "<text>"` is born *and* resolved in the same session, so refreshing at its birth would only be duplicated (and superseded) by the resolution refresh a moment later. So a `quick`-born ticket refreshes at the session **handoff** (Resolve), or at **`/trailhead:pause`** if the session pauses before Resolve, **not** at the birth instant; a ticket born by a **terminal capture** (a `bug`/`todo`/`idea` routed to the whiteboard, whose session ends at creation) still refreshes at birth, since that is its only refresh point. Links + counts stay good enough refreshed at these events and on demand.
 
 **Self-heal (read-only entry points).** A repo that adopted trailhead before the dashboard existed, or one whose pin was later dropped, has no pinned index until the next chart/adopt or an explicit `dashboard`. To close that gap, the frequent **read-only entry points self-heal the pin**: the bare `/trailhead` smart entry, the `map` render, and the `whiteboard` render each ensure the dashboard exists and is pinned before rendering, idempotently and cheaply, mirroring the "ensure the label exists before applying it" pattern: ensure the `trailhead:dashboard` label, then
@@ -99,7 +92,7 @@ It holds:
 
 ## Render the whiteboard: `whiteboard`
 
-Not all work belongs to a map. A **bug**, a **todo**, or a one-off **task** may be about something else entirely, or simply not worth charting a map for. The **whiteboard** is where that loose work lives: tickets labelled **`trailhead:whiteboard`**, map-less (no `trailhead:map-<n>` label, no `Parent:` line, no native sub-issue edge). A ticket is on a map **or** on the whiteboard, never both. Loose tickets are created there by a capture routed to the whiteboard or born there by `quick`, and worked with `quick <n>` or `work <n>` (the capture and work clusters own those paths). This engine only **renders** the whiteboard.
+Not all work belongs to a map. A **bug**, a **todo**, or a one-off **task** may be about something else entirely, or simply not worth charting a map for. The **whiteboard** is where that loose work lives: tickets labelled **`trailhead:whiteboard`**, map-less (no `trailhead:map-<n>` label, no `Parent:` line, no native sub-issue edge). A ticket is on a map **or** on the whiteboard, never both. Loose tickets are created there by a capture routed to the whiteboard or born there by `quick`, and worked with `work <n>` (the anchor: works the ticket whole and can split) or `quick <n>` (the no-split variant); the capture and work clusters own those paths. This engine only **renders** the whiteboard.
 
 It has its **own frontier**, off every map's (see **Map frontier vs whiteboard frontier** in `../_shared/substrate.md`):
 ```bash