@lab43/q 0.5.0 → 0.6.1

package/q-extension/references/q-state.md

@@ -0,0 +1,31 @@
+# The q State File
+
+Format and writer rules for `.claude/q-state.json`, the consumer-side record of the versions a project was last reconciled against. The skills that read or write the file follow this doc; nothing else edits it.
+
+## What the file is
+
+The file holds machine-written version watermarks — never rules, never doc enumerations. Reconciliation is the work of folding a version change into the project — holding its docs against an extension release's changed rules, or its scaffolded surfaces against a new q version; `/q:reconcile` performs it. A watermark records the version the project was last reconciled against. Drift is the lockfile or the installed version disagreeing with it, however the move arrived — a hand-run npm install, a teammate's merge, a Dependabot bump. The skills and the session-start hook compare its versions against the lockfile and `node_modules`; nothing consults it for how to behave.
+
+## Format
+
+The file lives at `.claude/q-state.json`, committed. JSON, one key per line, so a watermark move reads as a one-line diff:
+
+```json
+{
+  "note": "Machine state written by q's skills. Never edit by hand; /q:reconcile repairs drift.",
+  "reconciledAgainst": {
+    "@lab43/q": "0.3.0"
+  }
+}
+```
+
+`reconciledAgainst` holds one entry for `@lab43/q` and one per installed extension: the version the project was last reconciled against. q's entry has the same shape as the rest, carrying no privilege and no separate field.
+
+## Writer rules
+
+- `/q:install` writes a missing `@lab43/q` entry when it scaffolds, from the version installed, which has no reconciliation debt. It never touches a present entry — a stale one is reconciliation's to move.
+- `/q:reconcile` writes watermarks as reconciliation's record: it moves a package's entry after reconciling its version move, writes an arrival's first entry from the version installed, and drops an entry as part of reconciling a departure. It writes nothing before a reconciliation — watermarks certify one.
+
+An absent file means no record — create it on the first watermark write.
+
+What divides this file from `package.json` is who writes it. The manifest is hand-authored and npm's to rewrite, so it carries what a person sets and a consumer reads — the q declaration, `q.description`. Watermarks are machine-written, so they live here, where the format stays q's to guarantee and nothing edits them by hand.

package/{references → q-extension/references}/run-contract.md

@@ -11,7 +11,9 @@ A run is in one of two modes, depending on whether the user has agreed on what t
 
 ## Review modes
 
-Work that will become commits runs in one of two review modes, settled up front — with the run's opening questions, or at the go-ahead that enters autonomous mode. Once settled it is never revisited mid-run: a ship run reaches its PR without stopping again, so the user comes back to a PR waiting, not a prompt asking whether to open one.
+Work that will become commits runs in one of two review modes, settled up front — with the run's opening questions, or at the go-ahead that enters autonomous mode. Once settled, the run never reopens it: a ship run reaches its PR without stopping again, so the user comes back to a PR waiting, not a prompt asking whether to open one.
+
+The user can still overrule a step: telling a local run to commit now (see: The local gate), or a ship run to hold its push. The ruling spends itself on the step it names — the mode stands for everything after, however much the instruction resembles the other mode's procedure. Name the conflict before complying rather than inferring a switch.
 
 - **Local** — nothing is committed unreviewed: work pauses uncommitted at each review point the running skill defines, and the user's go-ahead is what commits it.
 - **Ship** — commit as the running skill's own procedure calls for, without asking, and push when the work is done; the user reviews on GitHub, so finish by directing them to the PR(s). The grant ends at the PR: merging is the user's.
@@ -44,7 +46,7 @@ An existing local branch is checked out as it stands, which may be behind the re
 
 Never take the branch with `git worktree add --force`. It succeeds, leaving two worktrees on one branch to diverge silently.
 
-Whichever way the worktree was made, install the project's dependencies there (see: `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`). A worktree carries tracked files only, so until that install runs nothing works — not the project's checks, not reading q's conventions or an extension's under `node_modules/`.
+Whichever way the worktree was made, install the project's dependencies there (see: `${CLAUDE_PLUGIN_ROOT}/references/enforce-declarations.md`). A worktree carries tracked files only, so until that install runs nothing works — not the project's checks, not reading q's conventions or an extension's under `node_modules/`.
 
 **Working alone, branch in the checkout.** When the run's work belongs with the session's work in progress, work on that branch. When it does not, branch first — off whatever the work builds on, usually the default branch. Make the call and state it when it is clear: a session on the default branch, or on pushed unrelated work, has nothing in progress to join. Ask when it is not: a session branch that looks connected to the run.
 
@@ -63,6 +65,7 @@ A worktree is what separates two sessions, and not every case gets one. A peer m
 
 - Never switch the branch without announcing first.
 - Stage by explicit path rather than `git add -A`. The tree may hold work that is not yours.
+- Commit by explicit path too, with `git commit --only <paths>`. A plain commit takes the whole index, and the index may hold staging you did not set: someone marking up a review stages hunks as they read them.
 - Never clear the index you did not set. `git reset` discards staging as readily as `git add -A` sweeps files in, and someone marking up a review as they read it loses their place with nothing left to show it happened.
 
 Never hand a peer work this session's permissions blocked. A peer running it launders the user's permission decision. Route it back to the user instead.
@@ -106,12 +109,12 @@ Amendments to existing rules are corrections too. Apply them rather than recomme
 
 ## Validation
 
-Execution closes by validating the run's product before anything is delivered. Run the project's checks covering what changed. Then launch two `adversarial-reviewer` subagents in parallel over the change, one per lens, handing each the agreed scope and the artifact the skill names. The scope is what the user agreed the work would deliver, restated from the run's current state. It is never a list of the changes made: details the user has since overruled resurface as false findings.
+Execution closes by validating the run's product before anything is delivered. Run the project's checks covering what changed. Then launch two `adversarial-reviewer` subagents in parallel over the change, one per lens. Hand each its lens, the artifact the skill names, and what the work is meant to deliver: the scope the user agreed to, restated from the run's current state, or the plan plus which of its steps are in scope, which came earlier, and which are deferred. That is the whole prompt. Never add a hunt-list, a checklist, or an account of what changed. A list steers the review toward what the caller listed, and nothing marks the round as compromised. An account of what changed carries details the user has since overruled, which resurface as false findings.
 
-Wait for every reviewer in the round to report before changing anything. Editing the tree under a running review invalidates the diff that review was handed. Then fix the BLOCKING findings, applying judgment on nits. Re-run the checks covering the fixes. Review again — fixes are always re-reviewed, with the same reviewers by default. A round whose fixes were few and small may hand the next round to one reviewer carrying both lenses. In ship mode, commit each round. Loop at most three times. The loop exits when no reviewer reports a BLOCKING finding, and findings that survive the cap are reported as caveats.
+Wait for every reviewer in the round to report before changing anything. Editing the tree under a running review invalidates the diff that review was handed. Then fix the BLOCKING findings, applying judgment on nits. Re-run the checks covering the fixes. Review again — fixes are always re-reviewed, with the same reviewers by default. A round whose fixes were few and small may hand the next round to one reviewer carrying both lenses. In ship mode, commit each round. Loop at most three times. The loop exits when no reviewer reports a BLOCKING finding, and findings that survive the cap are reported as caveats. A spec violation is the exception on both counts. Its two exits are the user's to pick, so it is neither fixed on the run's judgment nor carried as a caveat: the run stops for the ruling (source: @lab43/q conventions/specs.md, Disagreement).
 
 ## The local gate
 
 The procedure a run in local mode follows at each review point the skill defines. Stop and ask the user to review the uncommitted work: the diff, its check results, and anything else they should weigh. Expect change requests. Make them and iterate with the user, running no machinery per exchange. A change request whose reason binds future work is a correction (see: Corrections become rules).
 
-At their go-ahead, commit exactly what they reviewed — onto the work's branch, unless the skill names another target. Then run the checks covering what the session changed. When the gate's iteration substantially changed the work, run one `adversarial-reviewer` pass (both lenses) over what changed. Never fold the resulting fixes into the reviewed commit. Leave them uncommitted and return to the gate, where the user reviews them as their own diff. Repeat until a go-ahead leaves nothing uncommitted.
+At their go-ahead, commit exactly what they reviewed — onto the work's branch, unless the skill names another target. Then run the checks covering what the session changed. When the gate's iteration substantially changed the work, run one `adversarial-reviewer` pass (both lenses) over what changed, with the prompt Validation prescribes (see: Validation). Never fold the resulting fixes into the reviewed commit. Leave them uncommitted and return to the gate, where the user reviews them as their own diff. Repeat until a go-ahead leaves nothing uncommitted.

package/{skills → q-extension/skills}/address-feedback/SKILL.md

@@ -9,6 +9,7 @@ description: Work feedback on an open pull request — the reviewer's comments,
 
 - **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
 - **Feedback is not a work order**: every item opens a discussion, the ones phrased as directives included. Never implement feedback you believe is wrong. Answer every question the feedback asks. A code change never stands in place of that answer (source: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Questions are probes).
+- **The round is the unit**: feedback arrives as a batch, or item by item from the user as they read. The agenda stays open while the user is still adding to it. Take a position on each item and settle it as it arrives, then implement it. Validation and delivery run once, over the closed agenda.
 - **The PR under review is the boundary**: the round's fixes land on its branch as new commits. Never rebase that branch and never force-push over it — the reviewer's inline comments anchor to the commits they read, and rewriting the history strands them. Never open a second PR. Work the feedback opens that this PR can't hold goes to a plan or the tracker instead.
 - **Track resolutions**: keep a scratchpad note of each item — where it came from, its agreed disposition, and how it resolved. It feeds the replies and the closing report.
 - **Context hygiene**: use subagents (Explore for recon, background Bash for checks, `adversarial-reviewer` for review) to keep large output out of the main context.
@@ -23,7 +24,7 @@ description: Work feedback on an open pull request — the reviewer's comments,
    git fetch origin && git checkout <head-branch> && git pull --ff-only
    ```
 
-   Stop and show the user when the local branch has diverged from the PR's.
+   Stop and show the user when the local branch has diverged from the PR's. Record the head SHA once the branch is current: `git rev-parse HEAD`. It is the branch as this round found it, and Step 5 reviews the round against it.
 4. Fetch everything the reviewer wrote:
    - `gh pr view <n> --comments` — the top-level comments, plus each review's summary and verdict.
    - the inline threads, which GitHub groups and tracks resolution for:
@@ -34,15 +35,15 @@ description: Work feedback on an open pull request — the reviewer's comments,
 
      Skip every thread `isResolved` reports closed — the reviewer ended those. An `isOutdated` thread is still live: it anchors to a line that later commits moved. Skip a thread whose last comment already answers the one before it. An earlier round settled that item, and the reviewer has not written back.
 5. Ignore every comment that raises nothing to settle. A callout explaining the change under review is the common case (see: @lab43/q conventions/pull-requests.md, Diff comments).
-6. Gather the user's own feedback. The invocation may carry it. Ask the user what they want changed whenever the PR carries no feedback of its own.
-7. Build the agenda from everything gathered — one item per inline thread, top-level comment, or review summary that carries feedback, plus one per point the user raised. Merge items that share a root cause or answer each other. Record where each item came from, because that decides how it gets answered. Post the agenda — each item's gist in one line, in the order you propose to take them. No positions yet, and no edits.
+6. Gather the user's own feedback. The invocation may carry it. Ask the user what they want changed whenever the PR carries no feedback of its own. Always ask whether more is coming, because the user may still be reading the PR and add items as they go.
+7. Build the agenda from everything gathered — one item per inline thread, top-level comment, or review summary that carries feedback, plus one per point the user raised. Merge items that share a root cause or answer each other. Record where each item came from, because that decides how it gets answered. Post the agenda — each item's gist in one line, in the order you propose to take them. No positions yet, and no edits. Leave the agenda open when the user has more coming, and add each new item to it as it arrives. The agenda closes when the user says nothing more is coming. Ask them rather than reading a pause as the end.
 
 ## Step 2: Take a position on each item
 
 Establish ground truth before forming a position:
 
 - the code the item points at, and its history
-- the conventions governing that territory, found from the agent briefing's docs index
+- the conventions and specs governing that territory, found from the agent briefing's docs index
 - the primary source, wherever the item turns on how a dependency or tool behaves — the library's own code, its documentation, its upstream issues
 
 Never agree or push back from memory of an external fact (package versions, library APIs, option names, tool behavior). Run the check whenever running one can settle the question.
@@ -74,28 +75,31 @@ Ask one batch, carrying only what the user has to rule on:
 - whether each resolution is posted back where the feedback was written, asked once for the round. Skip it when nothing was written on the PR.
 - the review mode (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Review modes). In this run, ship covers commit and push to the PR. Local commits nothing until the user has reviewed the diff.
 
-Answers settle decisions. They are not the agreement. Close the conversation by summarizing the agreed scope and asking for the go-ahead. That go-ahead, not the last answer, is what makes the rest of the run autonomous.
+Ask the batch's round-wide questions at the first item and carry the answers forward. A later item reopens the batch only for the fork it turns on.
+
+Answers settle decisions. They are not the agreement. While the agenda is open, a go-ahead authorizes the item it names and nothing beyond it. Implement that item, then return to Step 2 with the next one. Ask for the round's go-ahead once the agenda is closed, summarizing the agreed scope. That go-ahead is what makes the rest of the run autonomous.
 
 An item beyond this PR is not resolved here. Settle the rest of the round, and take it to `/q:create-plan` or to the tracker on the user's call.
 
 ## Step 4: Implement
 
-1. Record the branch's head SHA before changing anything: `git rev-parse HEAD`. It is the branch as this round found it, and Step 5 reviews the round against it.
-2. Implement each agreed fix, following the governing conventions and matching surrounding code.
-3. Verify: run the project's checks — lint, typecheck, and the tests covering what changed, as the project's briefing, conventions, or scripts name them (parallel background subagents are fine). When a fix changed a drivable surface — an endpoint, a screen — drive it through `/q:drive`, naming that surface as what to exercise.
-4. In ship mode, commit — before review, so the review history is inspectable in git.
+1. Implement each agreed fix, following the governing conventions and matching surrounding code.
+2. Verify: run the project's checks — lint, typecheck, and the tests covering what changed, as the project's briefing, conventions, or scripts name them (parallel background subagents are fine). When a fix changed a drivable surface — an endpoint, a screen — drive it through `/q:drive`, naming that surface as what to exercise.
+3. In ship mode, commit — before review, so the review history is inspectable in git.
 
 When the agreed fixes turn out to need a redesign, or more change than this PR can hold, interrupt. Present the discovery and recommend `/q:create-plan` or a tracker item. Neither starts without the user's go-ahead.
 
 ## Step 5: Adversarial review
 
-Validate the round (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Validation) with the **correctness** and **conventions** lenses. The round is the product, so its diff runs from Step 4's recorded SHA: `git diff <recorded-sha>...HEAD` in ship mode, or the uncommitted diff plus the changed-file list in local mode. Hand the reviewers the agreed dispositions as the scope. Per loop round, re-drive a surface only when a fix could change what driving showed.
+Validate the round (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Validation) with the **correctness** and **conventions** lenses. Enter this step once, over a closed agenda. Settling one item while the agenda is still open is iteration, so never launch reviewers over it.
+
+The round is the product, so its diff runs from Step 1's recorded SHA: `git diff <recorded-sha>`, which holds the round's work whether or not it is committed. Name any file the round added and left untracked, which no diff shows. Hand the reviewers the agreed dispositions as the scope. In each pass of the validation loop, re-drive a surface only when a fix could change what driving showed.
 
 ## Step 6: Deliver to the PR
 
 1. **The local gate**: run it over the session's uncommitted work (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The local gate).
 2. **Push**: `git push origin HEAD`.
-3. **Bring the PR body up to date** wherever the round changed what it claims, the findings that survived Step 5 included (see: @lab43/q conventions/pull-requests.md).
+3. **Bring the PR body and title up to date** wherever the round changed what they claim, the findings that survived Step 5 included (see: @lab43/q conventions/pull-requests.md).
 4. **Reply**, when replying was agreed: post each item's resolution where the feedback was written. Skip an item the user raised in session. It has no thread to answer. Give the reviewer what they need to understand it — the answer, the evidence behind a push-back, or the reason a fix took the shape it did. Sign each reply (source: @lab43/q conventions/writing.md, Sign what you post). Write each reply to a file and pass it by path, so apostrophes in the prose can't break the command. Reply to an inline thread at its first comment's `databaseId`:
 
    ```bash

package/q-extension/skills/clean-worktrees/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: clean-worktrees
+description: Clear the git worktrees that finished parallel sessions leave behind. Use when worktrees have piled up in a repo, or before starting parallel work in a cluttered one. Invoke it bare — it sweeps the repo itself. It reports what each worktree holds and whether that work has reached the remote, and the user rules on the list before anything is removed. Never deletes a branch, and delivers no repo change or PR.
+---
+
+# Clean Worktrees
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. This run changes no tracked file, so there is no branch, review mode, or PR.
+
+## Step 1: Sweep
+
+1. Run `git fetch origin`. Never add `--prune`. It drops the tracking ref for a branch the remote deleted on merge. That worktree's commits then look like they never reached a remote, which blocks the cleanup this skill exists for.
+2. Run `git worktree prune`. It clears the registrations whose directory is already gone. A locked worktree keeps its registration either way, because locking is what protects a registration from pruning.
+3. Run `git worktree list --porcelain` for the worktrees. Then list the directories under `.claude/worktrees/`. One that git does not list is not a worktree. Never delete it.
+
+Two worktrees are never candidates. Rule them out first:
+
+- the main worktree, which `git worktree list` names first. Git refuses to remove it.
+- the worktree this session is running in, which `git rev-parse --show-toplevel` names. It reports the worktree's root from any depth, so it matches the path `git worktree list` reports however deep the session has moved.
+
+Ask the peers what they hold, before probing anything. `ListAgents` lists the live candidates (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The delivery branch). With none listed, every worktree is leftovers. Otherwise ask each candidate it lists which worktrees they are working in. The repo cannot show what work a peer is on (source: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Working alongside a peer). A session that made a worktree and stepped out of it leaves nothing behind to show that it did.
+
+A worktree a peer claims is never removable. Silence is not a claim: a candidate that has not answered by the end of the sweep holds nothing, and every worktree stays as removable as the rest of the test found it. Never wait on a reply. Report the silence in Step 2 instead, so the user rules on the list knowing one candidate never accounted for itself.
+
+Then establish what each of the rest holds:
+
+- whether it is locked, which `git worktree list --porcelain` reports. A locked worktree is never removable. Its directory may be gone, which fails every command below. Report it and probe no further.
+- whether its tree is clean — `git -C <path> status --porcelain`
+- whether every commit it carries has reached a remote — `git -C <path> log --oneline HEAD --not --remotes` prints the ones that have not
+
+Then establish whether its work has landed. Run `gh pr list --head <branch> --state all` for each branch's pull requests. Never use `git branch --merged` for this. A squash-merged branch is not an ancestor of the default branch, so that test reports long-merged work as unmerged. A detached worktree has no branch, so it has no pull requests to read.
+
+A worktree is removable when it holds nothing the remote does not already have:
+
+- its tree is clean
+- no commit it carries is missing from a remote
+- it is not locked
+- no peer claims it
+
+Removing one costs only the checkout. It deletes no ref, and by the test above every commit the worktree carries is already on a remote.
+
+## Step 2: Agree what goes
+
+Settle the list with the user, in conversational mode (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Collaboration modes). How a removable worktree reaches the user depends on what its pull requests say:
+
+- Merged or closed — the work is done with. Name it in the go-ahead below, for the user to veto rather than asking them (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Decide at the right altitude).
+- Open, or no pull request at all — nothing says the work is finished. Put it in a batch of choices (see: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, Batch questions), and say what its pull requests showed. The user may be coming back to the checkout.
+
+A sweep that turns up none of the second kind asks no questions at all.
+
+Close with the go-ahead, in plain text. State what it removes. Name any candidate that never answered the ask, and which of the worktrees it removes that candidate might yet claim. State what the go-ahead leaves out, and why:
+
+- the worktrees ruled out before probing
+- the worktrees that failed the removable test
+- the directories git does not list
+
+The go-ahead is the agreement.
+
+## Step 3: Clear it
+
+Remove what the user agreed to, without asking again.
+
+1. Drop any worktree a peer has claimed since the sweep, whether the reply arrived while Step 2 was still settling the list or after the go-ahead. A late reply still settles ownership, and the user agreed to remove a worktree nobody had claimed. Report each one dropped.
+2. Remove each remaining agreed worktree with `git worktree remove <path>`. Never `--force` (source: `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`, The delivery branch). A removal that refuses means something changed since the sweep — show the user what it reports instead of forcing past it.
+3. Leave every branch alone. Deleting the branch a removed worktree held is the user's call.
+4. Report what was removed, what was left and why, and each directory under `.claude/worktrees/` that git does not list.

package/{skills → q-extension/skills}/create-plan/SKILL.md

@@ -10,7 +10,7 @@ The idea to plan comes from the invocation, at any fidelity — a phrase ("email
 ## Ground rules
 
 - **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
-- **Plan, don't implement**: implement nothing, and make no commits unless the user asks. The plan doc is this skill's product — `docs/plans/<plan-name>.md` (create the directory on the first plan). Two writes sit outside it: what driving taught, recorded in the project's driving manual, and the corrections planning turns up (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Corrections become rules).
+- **Plan, don't implement**: implement nothing, and make no commits unless the user asks. The plan doc is this skill's product — `docs/plans/<date>-<plan-name>.md` (source: @lab43/q conventions/plans.md, Filename), creating the directory on the first plan. Two writes sit outside it: what driving taught, recorded in the project's driving manual, and the corrections planning turns up (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Corrections become rules).
 - **Ground everything**: every claim about current behavior comes from reading the code (cite `file:line`); every external fact (package versions, library APIs, option names, client support) is verified during planning, never stated from memory — online where reading settles it, and through `/q:drive` where only running something can, naming the question to settle as what to exercise. A plan resting on an unverified assumption is a planning failure, not a note for the implementer.
 - **Evidence can flip decisions**: when exploration contradicts a tentative decision (a planned feature depends on data that turns out not to exist), surface the finding prominently and re-decide before it gets written into the plan.
 - **Tooling limitations never dictate content** (see: @lab43/q conventions/principles.md): if a design choice would break a test helper, CI step, or script, the plan schedules the tooling fix — it does not bend the design around it.
@@ -20,7 +20,7 @@ The idea to plan comes from the invocation, at any fidelity — a phrase ("email
 Before proposing anything, establish current state:
 
 1. The relevant code — use an Explore subagent for breadth; read the load-bearing files yourself.
-2. The conventions governing the affected territory, found from the agent briefing's docs index — plus this workflow's own rubric, the plan format (see: @lab43/q conventions/plans.md).
+2. The conventions and specs governing the affected territory, found from the agent briefing's docs index — plus this workflow's own rubric, the plan format (see: @lab43/q conventions/plans.md).
 3. Prior plans in the same territory (`docs/plans/`, if it exists). Read their decisions and rejected alternatives for the rationale, not the ruling: a rejection whose grounds still hold isn't re-proposed; one whose grounds have shifted is back on the table, with its history. Deferrals are candidates to raise with the user, not inheritances. Status matters: a `pending` plan in the same territory is a possible collision to surface, and an `abandoned` one's decisions never bound anything. Trust newer plans and the code over older ones, and take no format cues — the plan format doc is the only format authority.
 
 ## Step 2: Discuss
@@ -34,7 +34,7 @@ Once the scope, delivery shape, and key design decisions feel settled, ask for t
 
 ## Step 3: Write the plan
 
-Write `docs/plans/<plan-name>.md` according to the plan format (see: @lab43/q conventions/plans.md) and the writing rules (see: @lab43/q conventions/writing.md).
+Write `docs/plans/<date>-<plan-name>.md` according to the plan format (see: @lab43/q conventions/plans.md) and the writing rules (see: @lab43/q conventions/writing.md). Cite the spec sections governing the territory in Context, as givens (source: @lab43/q conventions/plans.md, Sections). When the plan changes committed behavior, schedule the spec's amendment in the phase that ships the behavior (source: @lab43/q conventions/specs.md, Disagreement).
 
 ## Step 4: Adversarial review
 

package/q-extension/skills/groom-docs/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: groom-docs
+description: Audit the project's whole documentation surface against the documentation policy and consolidate what has drifted. Approved edits ship as a PR. Use when docs feel inflated or stale, after a stretch of merged changes, or on a docs-cleanup request.
+---
+
+# Groom Docs
+
+**Read the rubric first, and follow it over any instinct:**
+
+1. q's documentation policy (see: @lab43/q conventions/documentation.md), its conventions rules (see: @lab43/q conventions/conventions.md), and its writing rules (see: @lab43/q conventions/writing.md), plus any installed extension's doc whose topic governs documentation. An extension's rule beats q's where the two disagree (source: @lab43/q conventions/conventions.md, Three tiers of conventions).
+2. The project's recorded rulings and deviations, which win over both: `docs/conventions/documentation.md` plus any "(overrides: …)" markers across `docs/conventions/` — grep for them. An exception marker is a recorded ruling of a different kind, excusing its one site rather than replacing a rule (see: @lab43/q conventions/documentation.md, Markers). Honour one where you meet it; the accumulation check is what counts them.
+
+Stop and suggest the fix when the project has no `docs/conventions/` directory, or when q's `conventions/` don't resolve by their path form (see: @lab43/q conventions/documentation.md, Package doc paths). Without both there is no surface or rubric to groom against. A fresh clone missing q's `conventions/` may just need `npm install`.
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
+
+## Step 1: Inventory
+
+Build the grooming surface, taking each item only if it exists in this project. Read each `docs/` directory whole: every markdown file under it, subdirectories included (source: @lab43/q conventions/documentation.md, Taxonomy).
+
+- `docs/conventions/`, `README.md`, `CLAUDE.md` (the agent briefing) — full checks.
+- `docs/specs/` — **spec mode**: the full checks, with accuracy reversed, per the policy's `docs/specs/` taxonomy rule.
+- `q-extension/conventions/` — the conventions in the payload this repo ships, when that directory exists — full checks, like the project's own conventions (source: @lab43/q conventions/extensions.md, Layout). The root manifest's `q.description` joins the surface with them (source: @lab43/q conventions/extensions.md, Description). Anything else the project's own `documentation.md` puts on the surface joins it, under rubric item 2.
+- `docs/guides/` — **guide mode**, per the policy's Taxonomy rules.
+- `docs/plans/` — **status check only**, per the policy's `docs/plans/` taxonomy rule.
+
+Project-local `.claude/` skills and agents are outside the surface — q doesn't govern them. Everything installed under `node_modules/` is read-only, q's conventions and every extension's alike — never groomed.
+
+## Step 2: Fan out verification (read-only subagents)
+
+Launch read-only subagents in parallel — one per check below, except accuracy, which fans out per doc cluster; the duplication and consistency sweeps each hold the whole surface, since cross-file checks can't be sharded. Each reads the rubric first and returns findings with `file:line` citations:
+
+1. **Accuracy, per doc cluster** (conventions docs grouped by area; specs clustered separately, in spec mode; guides clustered separately, in guide mode): every checkable claim — file paths, symbol names, behavior descriptions, commands — verified against current source. In spec mode the check reverses: a commitment the code does not honor is a finding for the user, never a doc correction, because a spec may run ahead of its code (source: @lab43/q conventions/documentation.md, Taxonomy). Exemplar references get a deeper check: the file exists and still exhibits the rules its doc attaches to it. An authored extension's `q.description` is checked with its docs: it must still name the territory they govern.
+2. **Duplication sweep**, cross-surface: facts stated in more than one place. For each, name the home — implied by the taxonomy, or assigned by a recorded ruling; where the call is genuinely contestable, flag it for the user, whose decision becomes a new ruling. The sweep also runs **cross-tier**, comparing project docs against q's conventions and every installed extension's: a project statement matching one of their rules in substance is duplication to prune; one differing from such a rule without an overrides marker naming it is drift or an unrecorded deviation — escalate to the user; a site carrying an exception marker naming the rule is neither, being excused from it rather than in conflict with it; a marked override whose target updated to agree or disappeared is spent — propose deleting it (source: @lab43/q conventions/conventions.md, Three tiers of conventions). Docs installed under `node_modules/` are read-only: an extension's stale override of a q rule, or two extensions in conflict, can't be edited here — escalate; the remedy is a project ruling or the extension author's.
+3. **Dead references**: every file, symbol, helper, script, and skill named anywhere on the surface exists. Greps must exclude build artifacts (`dist/`, `node_modules/`, and the like) — stale generated files resurrect deleted symbols.
+4. **Consistency**: the agent briefing matches the briefing template (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`); any README skills/conventions table matches its home (skill tables drift-check against `SKILL.md` frontmatter descriptions); cross-references between docs resolve. One concept goes by one name across the surface. Report a synonym against the name its home doc establishes (source: @lab43/q conventions/writing.md, One name per concept).
+5. **Organization**: each doc's structure — topic scope, intro, section placement, and splits or merges across docs — conforms to the policy. Findings here become reorganization proposals.
+6. **Plan statuses** (if `docs/plans/` exists): every plan has valid `status` frontmatter (source: @lab43/q conventions/plans.md, Frontmatter); list every `pending` plan with its age (last git commit date).
+7. **Exception accumulation**: grep the repo for exception markers, excluding `node_modules/` and build artifacts, and group the hits by the rule each names. Match the marker's shape rather than the bare word — `(exception:` where prose carries it, and a comment line beginning `exception:` where a comment does (source: @lab43/q conventions/documentation.md, Markers). Ordinary English use of the word matches neither, and a malformed target still matches, which is what lets the malformations below be seen at all. Skip the text that defines the marker and the examples illustrating it. Report every rule carrying more than one, for the user's ruling — several exceptions against one rule are evidence the rule wants revisiting. Report each of these too: a marker naming no doc or no section, one whose named doc or section does not exist, one carrying no reason, one whose reason the surrounding text no longer bears out, and one whose rule has changed to admit its site, which makes it spent. A file outside the grooming surface joins the run for its exceptions alone: nothing else in it is groomed, and a fix to one goes to the user rather than being applied autonomously.
+8. **Spec markers**: grep the repo for spec markers, excluding `node_modules/` and build artifacts. Match the marker's form, `spec:` followed by a path under `docs/specs/` (source: @lab43/q conventions/documentation.md, Markers). Never match the bare keyword: `spec:` is an ordinary YAML key, at the top of every Kubernetes manifest a project carries, and the path is what no key carries. Skip the text that defines the marker and the examples illustrating it. Report each marker naming a doc or section that does not exist, and each spec section no marker names. An unmarked section is reported and not required: not every commitment is testable.
+
+## Step 3: Consolidate with the user
+
+Merge the findings into proposed edits, each stating its remedy and citing its finding — in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes).
+
+- Apply autonomously: wording-level fixes, replacing a single restated sentence or bullet with a cross-reference to its home, and dead-reference corrections.
+- **Everything else goes to the user** (AskUserQuestion) — including larger deletions and rewrites, any reorganization, any `pending` plan proposed as `abandoned` (only the user flips a status), any fact that couldn't be verified either way, and every spec commitment the code does not honor. Report that one as unmet, never as violated: only the user knows whether it is in progress, missed, or regressed (source: @lab43/q conventions/documentation.md, Taxonomy).
+- When a user ruling sets a precedent, record it in the same run: project-specific rulings go in the project's `docs/conventions/documentation.md`; a ruling that would apply to every q project is recorded as a project deviation and flagged in the report as a candidate to upstream (via `/q:upstream`).
+- In the same batch, ask which review mode — local or ship — the delivery runs under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes).
+
+## Step 4: Apply
+
+1. Pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch).
+2. Step 3's rulings are the agreement — apply the approved edits autonomously. In ship mode, commit them.
+3. Re-run the dead-reference and consistency checks over the result — approved edits can break each other's targets.
+
+## Step 5: Adversarial review
+
+Validate the applied edits (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
+
+## Step 6: Open the PR
+
+1. **The local gate**: run it over the uncommitted edits (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
+2. **Open the PR**: push the branch and open the PR per the PR-authoring rules (see: @lab43/q conventions/pull-requests.md).
+3. Close the session by reporting: what changed per doc, what was deduped and into where, every autonomous fix, every user decision and its outcome, any upstream-to-q candidates, and anything that couldn't be verified — named explicitly, never silently dropped.

package/{skills → q-extension/skills}/implement/SKILL.md

@@ -18,15 +18,15 @@ The work comes from the invocation, at any fidelity — an issue number or URL,
 
 1. Announce the item to the peers before reading it — investigating it is already work a peer should not duplicate (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Working alongside a peer). A run continued from `/q:triage` arrives with the item already announced. Release it whenever this run stops working the item, whether it turns out unavailable or the verdict is nothing to do.
 2. Read the work item at its source — its description, comments, and related items, when the source carries them — and whatever it cites: stack traces, linked discussions, named files. Read it fresh even when a caller just read it: a tracker moves for reasons no peer announces. An item no longer available to pick up goes back to the user before any further work (source: @lab43/q conventions/issue-tracking.md, Respect existing claims).
-3. Read the conventions governing the affected territory, found from the agent briefing's docs index.
+3. Read the conventions and specs governing the affected territory, found from the agent briefing's docs index.
 4. Explore the affected code — use an Explore subagent for breadth; read the load-bearing files yourself.
 5. Check `docs/plans/` (if it exists) for collisions: surface a `pending` plan in the same territory in Step 2 rather than silently working around it.
 
-The outcome is a verdict: what the work actually is, whether the item's claims hold against the code, and how big the real change is.
+The outcome is a verdict: what the work actually is, whether the item's claims hold against the code, how big the real change is, and whether it contradicts a spec.
 
 ## Step 2: Agree
 
-Settle the run with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). One batch: the verdict and a recommended route, the approach where the fix is genuinely forked, and — when fixing here — the review mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). In this run, ship covers commit, push, and the PR; local commits nothing until the user has reviewed the diff.
+Settle the run with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). One batch: the verdict and a recommended route, the approach where the fix is genuinely forked, the exit when the work contradicts a spec — amend the spec with the change, or reshape the work to honor it (source: @lab43/q conventions/specs.md, Disagreement) — and — when fixing here — the review mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). In this run, ship covers commit, push, and the PR; local commits nothing until the user has reviewed the diff.
 
 Answers settle decisions. They are not the agreement. Close the conversation by summarizing the agreed scope and asking for the go-ahead. That go-ahead, not the last answer, is what makes the rest of the run autonomous.
 

package/{skills → q-extension/skills}/implement-plan/SKILL.md

@@ -19,7 +19,7 @@ Given no plan, list the `pending` plans in `docs/plans/` and ask which one.
 
 1. Read the plan in full.
 2. Announce the plan, and the items its `tracks` frontmatter names, before going further (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Working alongside a peer). Release them if the run ends without delivering.
-3. Read the conventions governing the plan's territory, found from the agent briefing's docs index.
+3. Read the conventions and specs governing the plan's territory, found from the agent briefing's docs index.
 4. Explore the affected code — use an Explore subagent for broad reconnaissance.
 5. Plans can predate refactors: check every plan step against the current codebase and note steps that are already done, obsolete, or in conflict with current structure.
 6. The plan's external facts were verified at planning time. If the plan has aged — the dependency manifests, lockfile, or files the plan cites changed since the doc was last written (its last commit, or mtime if uncommitted) — re-verify the load-bearing ones before building on them; a plan executed fresh skips this.
@@ -28,14 +28,14 @@ Given no plan, list the `pending` plans in `docs/plans/` and ask which one.
 
 Clarify the plan with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes) — everything asked here is a question the run won't have to stop for once it is autonomous. One batch, via AskUserQuestion:
 
-- The ambiguities, plan/codebase conflicts, and scope questions Step 1 surfaced — when none need the user's attention, state your working assumptions instead. If consequential questions keep accumulating, the plan is underspecified — say so and suggest revising it with `/q:create-plan` before implementing.
+- The ambiguities, plan/codebase conflicts, scope questions, and any spec the plan's work contradicts without scheduling the amendment, as Step 1 surfaced them — when none need the user's attention, state your working assumptions instead. If consequential questions keep accumulating, the plan is underspecified — say so and suggest revising it with `/q:create-plan` before implementing.
 - The review mode, always asked (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes): in this run, ship covers every commit (a stacked run's `gh stack` operations included), push, and PR; local commits nothing until the user has reviewed it, each PR's content at that PR's boundary.
 
 What emerges completes the agreement: the plan, as clarified, authorizes the rest of the run as autonomous.
 
 ## Step 3: Branch
 
-Settle the branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch). A plan is its own delivery unit, so the call is fresh branching. Require a clean working tree first, the plan doc itself excepted — it may be untracked or modified. Stop and ask the user what to do with anything else. Branch per the plan's `delivery` frontmatter (absent means single-PR). A single-PR run skips the command below when the contract's peer check already put it on a worktree's branch; a stacked run's `gh stack init` adopts that branch or creates its first layer:
+Settle the branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch). A plan is its own delivery unit, so the call is fresh branching. Require a clean working tree first, the plan doc itself excepted — it may be untracked or modified. Stop and ask the user what to do with anything else. Branch per the plan's `delivery` frontmatter (absent means single-PR). `<plan-name>` below is the plan's filename without its date prefix (source: @lab43/q conventions/plans.md, Filename). A single-PR run skips the command below when the contract's peer check already put it on a worktree's branch; a stacked run's `gh stack init` adopts that branch or creates its first layer:
 
 **Single PR:**
 
@@ -55,7 +55,7 @@ gh stack init <plan-name>/01-<group-slug> --base <default-branch>
 
 Either way, in ship mode record the group-start SHA (`git rev-parse HEAD`) as soon as the branch exists, before anything commits to it. It scopes this PR's final review in Step 5. Each later group records its own when its branch opens in Step 4.
 
-A plan doc not yet in merged history — new, or changed since it merged — becomes the run's first commit, at the bottom of the stack in a stacked run — exactly as planning left it. Material Step 2 clarification answers are folded in as a second commit on top, so the diff between the two records what clarification changed. In local mode, hold the commit; when the user's go-ahead starts the committing, the plan doc — clarifications folded in — is committed first, the two-commit split being history local mode gives up.
+A plan doc not yet in merged history — new, or changed since it merged — becomes the run's first commit, at the bottom of the stack in a stacked run — exactly as planning left it. Material Step 2 clarification answers are folded in as a second commit on top, so the diff between the two records what clarification changed. Both commits land in local mode too. The plan as planning left it is already the user's reviewed work, so committing it holds back nothing local mode protects, and every amendment the run adds then shows as a diff against it.
 
 ## Step 4: Implement in phases
 
@@ -74,7 +74,7 @@ For each phase:
 1. **Implement** the phase's steps, following the governing conventions and matching surrounding code.
 2. **Verify**: run the project's checks — lint, typecheck, and the tests covering what the phase touched, as the project's briefing, conventions, or scripts name them (parallel background subagents are fine). When the phase produced a newly drivable surface — an endpoint, a screen — drive it through `/q:drive`, naming that surface as what to exercise. This is a cheap incremental check so later phases don't build on something broken, not the full verification pass; fix what it catches before moving on.
 3. **Commit the implementation**, in ship mode, before review — so the review history is inspectable in git.
-4. **Adversarial review**: launch a single `adversarial-reviewer` subagent over the phase's diff with **both lenses** (correctness + conventions). Give it: the plan path, the full derived phase breakdown (which plan steps are in this phase, which came earlier, which are deferred), and the diff scope — `git diff <phase-start-sha>..HEAD` in ship mode; the uncommitted diff plus the phase's file list in local mode. One review per phase — there is no per-phase re-review loop; the PR's final review (Step 5) is the backstop that verifies the fixes.
+4. **Adversarial review**: launch a single `adversarial-reviewer` subagent over the phase's diff with **both lenses** (correctness + conventions). Give it: the plan path, the full derived phase breakdown (which plan steps are in this phase, which came earlier, which are deferred), and the diff scope — `git diff <phase-start-sha>..HEAD` in ship mode; the uncommitted diff plus the phase's file list in local mode. The lenses and those inputs are the whole prompt (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation). One review per phase — there is no per-phase re-review loop; the PR's final review (Step 5) is the backstop that verifies the fixes.
 5. **Fix**: fix all BLOCKING findings (apply your judgment on NITS), re-run the checks covering the fixed code — re-driving the phase's surface only when a fix could change what driving showed — and, in ship mode, commit the fixes. A review with no accepted findings gets no commit.
 
 ## Step 5: Wrap up each PR

package/q-extension/skills/install/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: install
+description: Set up q in a project the developer has already npm-installed it into, or repair a scaffold that has drifted. Invoke bare. Safe to re-run on a partially set-up project. An extension's arrival is /q:reconcile's. The changes ship as a PR.
+---
+
+# Install
+
+The scaffold is deliberately near-empty — this skill creates the structure the other skills expect, not content.
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. Scaffolding brings q's surfaces to the forms in Step 3: create what is absent, correct what has drifted. Any run therefore completes a partially set-up project. Never rewrite what the user owns — each item below marks its own boundary.
+
+## Step 1: Survey current state
+
+Hold the project against each of Step 3's scaffold items, noting what is absent and what has drifted from its form. Alongside, check:
+
+- Convention-like docs living elsewhere — a `docs/` scan for rule-carrying files, a briefing bloated with per-task rules
+- Content already in `docs/conventions/` that has drifted from the documentation policy
+- Whether an earlier run's scaffold sits uncommitted in the working tree
+- The GitHub CLI: `gh auth status`, and that the repo's `origin` is GitHub-hosted (`gh repo view` succeeds). q's workflow skills require both. If either fails, tell the user the fix (install via <https://cli.github.com> and authenticate with `gh auth login`; `gh repo view` failing with an authenticated CLI means `origin` is not GitHub-hosted) and continue — the scaffold still lands.
+
+## Step 2: Settle delivery
+
+Skip this step in any of these cases:
+
+- A run where Step 1 found nothing missing or drifted, and no scaffold sitting uncommitted from an earlier run — there is nothing to change or deliver. An unpopulated `node_modules/` is machine state rather than drift: a fresh clone nobody has installed on. Enforce the declarations per `${CLAUDE_PLUGIN_ROOT}/references/enforce-declarations.md`, which populates it, then stop with the closing report (Step 5).
+- Step 1 found no `@lab43/q` in `devDependencies` in the repo root's `package.json` — q's bytes have not arrived, and nothing scaffolds without them. Report the bootstrap for the developer to run — `npm install --save-dev --save-exact --ignore-scripts @lab43/q`, or their package manager's equivalent — and stop with the closing report (Step 5): this skill runs no package manager against a named package.
+- Step 1's GitHub CLI check failed — there is no delivery to settle.
+- Another skill's run invoked this one — the changes join that run's change.
+
+Otherwise ask which review mode — local or ship — the run delivers under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes). Then pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch).
+
+## Step 3: Scaffold
+
+The invocation is the agreement — scaffold autonomously; on a fully set-up, undrifted project the whole step is a no-op:
+
+1. **The two mirror docs** — create each if missing, with exactly this content; if present, leave it untouched. A seeded doc is the user's from creation, intro and entries alike — never corrected on a re-run. `docs/conventions/principles.md`:
+
+   ```markdown
+   # Principles
+
+   This project's cross-cutting rules, including any deviations from q's (see: @lab43/q conventions/principles.md).
+   ```
+
+   `docs/conventions/documentation.md`:
+
+   ```markdown
+   # Documentation
+
+   This project's documentation rulings and deviations (see: @lab43/q conventions/conventions.md, Three tiers of conventions).
+   ```
+
+   No other conventions doc is scaffolded — `/q:update-docs` creates each topical doc when its first entry is recorded.
+2. **The q dependency** — q arrives as one npm package, its conventions and its plugin together, and the developer installs it; Step 2 stopped any run where it is undeclared. Its declaration lives in `devDependencies` in the `package.json` at the repo root — the only place anything looks for it, whatever else the repo's layout holds (source: @lab43/q conventions/extensions.md, Pinning). Leave the recorded declaration alone.
+3. **Agent briefing** — ensure the project's briefing carries the section the briefing template defines, adding what is missing and correcting drift, per that file's rules (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`).
+4. **Plugin declaration** — the project publishes its own marketplace, sourcing the q it already has in `node_modules` and the plugin of each installed extension that ships one. Two files hold it, created if missing.
+
+   `.claude-plugin/marketplace.json` at the project root is the conventional path for a project publishing a marketplace, so the file is shared territory rather than q's. Merge q's entry and the extensions' into an existing manifest: leave every other `plugins` entry and the recorded name untouched. Write the whole file only when creating it.
+
+   The marketplace needs a name no other project on the machine will use. The registry the CLI resolves against holds one entry per marketplace name, machine-wide (source: ${CLAUDE_PLUGIN_ROOT}/references/enforce-declarations.md). Two projects sharing a name means the second one loads another project's q rather than its own.
+
+   Name it `q-pin-<owner>-<repo>-<suffix>` — for example, `q-pin-acme-storefront-4f2ab9`. Owner and repo keep the name legible in that registry. The suffix is six random hex characters. It is what keeps the name unique. Read owner and repo from the repo's GitHub origin with `gh repo view --json nameWithOwner`. Use the project directory's name in their place when that command yields nothing. Lowercase the whole name and replace every character outside `a-z0-9-` with a hyphen.
+
+   Generate that name only when creating the file. A project that already records one keeps it, whatever it is. Other clones have already registered that name locally. Regenerating it strands them.
+
+   ```json
+   {
+     "name": "<marketplace>",
+     "owner": { "name": "this project" },
+     "metadata": { "description": "Pins the q this project's sessions load. The name must stay unique to this project. Sharing another project's name makes this one resolve to that project's q." },
+     "plugins": [
+       {
+         "name": "q",
+         "source": "./node_modules/@lab43/q/q-extension",
+         "description": "The q workflow plugin, pinned for this project."
+       }
+     ]
+   }
+   ```
+
+   An extension ships a plugin when its payload holds `.claude-plugin/` (source: @lab43/q conventions/extensions.md, Layout). Look for one across the installed extensions — the direct dependencies, in `dependencies` and `devDependencies` alike, whose installed copy carries both halves of an extension's identity (source: @lab43/q conventions/extensions.md, Identity). Each extension shipping a plugin gets an entry beside q's, sourced at `./node_modules/<package>/q-extension` and named by the `name` in its `q-extension/.claude-plugin/plugin.json`, with that manifest's `description` when it carries one. Tell entries apart by `source`, never by name — the name is the author's to choose. Bring an entry whose source is already present to this form in place. An extension whose plugin manifest names no plugin, or names one that another source's entry already holds, gets no entry: report it as the extension author's to fix. An entry already in the manifest keeps its name against a newcomer claiming it. Between two extensions arriving with the same name, neither gets an entry.
+
+   Then merge into `.claude/settings.json`, leaving other keys untouched. Key the marketplace and every plugin entry to whatever name the manifest records, and correct any that has drifted from it:
+
+   ```json
+   {
+     "extraKnownMarketplaces": {
+       "<marketplace>": { "source": { "source": "directory", "path": "./" } }
+     },
+     "enabledPlugins": { "q@<marketplace>": true, "<plugin>@<marketplace>": true }
+   }
+   ```
+
+   Write this settings entry by hand, its `path` the literal `./` shown — producing it with `claude plugin marketplace add` records an absolute path instead, which breaks every other checkout of the repo.
+5. **Enforce the declarations** — make this machine match what the project now declares, per `${CLAUDE_PLUGIN_ROOT}/references/enforce-declarations.md`.
+6. **State file** — write `.claude/q-state.json` per `${CLAUDE_PLUGIN_ROOT}/references/q-state.md`: a `reconciledAgainst` entry for `@lab43/q`, from the version in `node_modules/@lab43/q/package.json`. Write only absent watermarks — a present entry, stale or not, is reconciliation's to move (source: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md).
+7. **Ignore rules** — ensure `.gitignore` covers `node_modules/`, `.claude/settings.local.json`, and `.claude/worktrees/`, and that the committed scaffold files are not ignored: run `git check-ignore` on `.claude/settings.json`, `.claude-plugin/`, and `.claude/q-state.json`, fixing the rules until it reports nothing. A bare negation under an ignored `.claude/` does nothing — the directory rule itself must become `.claude/*` plus the negations. Leave every unrelated ignore rule alone.
+8. **The README's q section** — when the README doesn't mention q, add this section verbatim:
+
+   ```markdown
+   ## Working with q
+
+   This project uses [q](https://www.npmjs.com/package/@lab43/q), an agentic coding workflow that grounds Claude Code sessions in the project's own conventions. It arrives with the project's dependencies, and Claude Code loads it from the repo's tracked settings.
+
+   The project's rules live in `docs/conventions/`, and q ships rules of its own inside the package. Sessions read both before writing code, and record new decisions into the project's docs as they are made — the docs assemble themselves out of the work.
+
+   A session lists every `/q:` skill. Start with these:
+
+   - `/q:implement` — take on a task or bug
+   - `/q:create-plan`, then `/q:implement-plan` — plan bigger work, then execute the plan
+   - `/q:review` — review anything against the project's conventions
+   ```
+
+   When the README already mentions q, keep its wording; correct only what it says about q that is no longer true. When the project has no README, create a minimal one holding just this section.
+9. Scaffold nothing else. An empty taxonomy directory arrives when its first document does.
+
+## Step 4: Deliver
+
+Invoked from another skill's run, stop here — the changes are that run's to validate and deliver. When the run changed nothing tracked and no earlier run's scaffold awaits delivery: switch back to the prior branch, delete any branch this run created, and report that and stop. When Step 1's GitHub CLI check failed, stop here with the closing report (Step 5), adding:
+
+- That the changes stay uncommitted — restate the `gh` fix.
+- That a re-run delivers them once `gh` is in place.
+
+Otherwise, in ship mode, commit. No adversarial review closes this run: the scaffold is deliberately deterministic — much of it is verbatim templates a reviewer would only second-guess — and the user reviews the delivered diff. Then:
+
+1. **The local gate**: run it over the uncommitted changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate) — minus the adversarial pass the gate otherwise adds after substantial iteration. The no-review ruling above covers the gate's too.
+2. **Open the PR**: push the branch and open the PR per the PR-authoring rules (see: @lab43/q conventions/pull-requests.md).
+
+## Step 5: Report
+
+Close the session by reporting:
+
+- What was created.
+- What already existed and was left untouched.
+- Each shipped plugin left without a marketplace entry, and why.
+- Convention-like content Step 1 found outside `docs/conventions/` — migration candidates this run leaves alone. Moving a project's existing docs is its own delivery: suggest `/q:create-plan` for a docs tree, or `/q:implement` for a handful of rules.
+- Content already in `docs/conventions/` that has drifted from the documentation policy — grooming's territory: suggest `/q:groom-docs`.