@lab43/q 0.4.0

package/skills/create-plan/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: create-plan
+description: Collaboratively create a plan in docs/plans, grounded in the codebase, hardened by adversarial review, and iterated with the user until it's ready for /q:implement-plan. The argument can be anything from a rough phrase to a detailed writeup. Produces the plan doc — never implements, never commits.
+---
+
+# Create Plan
+
+The idea to plan comes from the invocation, at any fidelity — a phrase ("email templates", "rate limiting") or a worked-out writeup; given nothing, ask what they want to plan. Whatever arrives is a starting point, not a transcript: a vague idea gets its details teased out, and a detailed one still gets grounded, verified, and challenged.
+
+## 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).
+- **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: 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.
+
+## Step 1: Explore
+
+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: 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
+
+Tease out the goals and key aspects with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). Beyond the design decisions themselves, two calls are settled here:
+
+- Scope boundaries are decisions too: record what's explicitly out of scope or deferred, and why.
+- The delivery shape — single PR or stacked, per the format's defaults (see: q conventions/plans.md, Delivery shape) and any PR rules the project's conventions record. The defaults usually decide it: state the call for veto rather than asking, unless the estimate is genuinely borderline.
+
+Once the scope, delivery shape, and key design decisions feel settled, ask for the go-ahead to write. That settled shape is the agreement: Steps 3 and 4 run autonomously inside it, and Step 5 is conversational again.
+
+## Step 3: Write the plan
+
+Write `docs/plans/<plan-name>.md` according to the plan format (see: q conventions/plans.md) and the writing rules (see: q conventions/writing.md).
+
+## Step 4: Adversarial review
+
+Validate the plan (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **feasibility** and **rigor** lenses, with two differences. Instead of an agreed scope, each reviewer gets the plan path and nothing more — the plan must stand alone, exactly as it will for `/q:implement-plan`. And anything still open after the third round goes to the user as an open risk, not a caveat.
+
+One policy for BLOCKING and NITS alike: make the straightforward fix; take a finding to the user, with the reviewer's evidence, when its fix would reopen a settled decision or significantly change the plan. FOLLOW-UPS are never folded into the plan — report them to the user in Step 5.
+
+## Step 5: User review
+
+A review loop. It has no closing step: the run ends when the user starts the implementation.
+
+1. Present the plan: a summary of the settled decisions, what adversarial review changed, any surviving findings, and the reviewers' follow-ups. Name anything the run left uncommitted. Show the corrections it recorded, so they are reviewed with the plan. Suggest the next step alongside: when the plan is ready, run `/q:implement-plan <plan-name>` after `/clear`. The plan doc is the complete handoff. Carrying the planning conversation along inflates every request's context and lets discussion that never made it into the plan steer the implementation.
+2. The user may ask questions and request changes. Treat each as potentially reopening design: answer with evidence, and fold every outcome into the doc immediately.
+3. When the accumulated changes merit another adversarial round (Step 4), ask — the user may not be done making changes — and run it on their yes.
+4. Repeat from 1, presenting what changed since the last presentation in place of the full summary.

package/skills/drive/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: drive
+description: Bring the product or toolchain up and exercise it — to see a change working, or to settle a question only running something can. Name what to exercise. Records what it learned in the project's driving manual. Never fixes what it finds.
+---
+
+# Drive
+
+What to exercise comes from the invocation — a flow, an endpoint, a command, a question only running something can settle. Given nothing, ask.
+
+## Ground rules
+
+- **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. Once you know what to exercise, proceed autonomously throughout: there is no agreement to converge on and nothing to deliver.
+- **Report, never fix**: report a failing launch, a broken flow, a wrong result. The fix belongs to the calling run, or to the user.
+- **Never skip silently**: stop and ask when the environment won't come up, when a dependency is missing, or when a feature can't be exercised. Name what's missing. Offer to install it when you know how, and do it only on the user's go-ahead. Never report a surface as exercised unless you exercised it.
+
+## Step 1: Read the driving manual
+
+Find the project's driving manual from the agent briefing's docs index, or from `docs/guides/` when the index doesn't name it. Read it. Follow what it cites.
+
+Derive how to drive when the project has no manual. Read its scripts, its config, and its README.
+
+## Step 2: Drive it
+
+Work out first what driving will bind — ports, databases, caches, devices — and which of those the repo holds only one of. The manual names them where a previous session recorded them, and the repo's scripts and config answer it where the manual doesn't. Then find out whether a peer already holds each one, under the conduct the run contract sets out (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Working alongside a peer): probe the resource itself — what is listening on the port, what holds the lock — and use `ListAgents` to put a session behind what you find.
+
+Wait rather than seize. Where the harness offers a one-shot idle notice — `SendMessage`'s `notify_when_idle` — subscribe rather than poll. The notice says a session went idle, never that it freed anything: a session that left a server running is idle while still holding the port. Treat it as a prompt to probe again, never as an all-clear. Tell the user when the wait turns open-ended rather than waiting silently.
+
+Announce the claim when you take it. When you finish, announce what you actually freed and what you left running — a stack you leave up still holds its port.
+
+Bring the target up. Never stop what you didn't start: a stack already running is the user's.
+
+Exercise it the way it will really be used: load the page, call the endpoint, run the command, walk the flow.
+
+Write whatever harness the driving needs in scratch space — a script, a fixture, a seeded request. Leave it there. Report a harness worth keeping rather than planting it in the project.
+
+Keep a record as you go: the commands you ran, what you saw, and every step the manual didn't tell you.
+
+## Step 3: Update the manual
+
+Record what cost you time, and what would cost the next session time:
+
+- what has to be installed or running first — a database, a container stack, local certificates, an MCP server
+- the commands that bring it up, plus the ports, URLs, and credentials they need
+- the path to what you exercised — the route, the seed data, the login
+- what a session may run its own copy of, and what it must take turns over
+- how to claim and release each thing it takes turns over
+- the failure that looks like a bug in the code and isn't
+
+Write a failure as its symptom, its cause, and what to do about it. A symptom the next session can't match against what they're seeing teaches nothing.
+
+Leave out what the scripts and the config already answer. A manual of obvious facts is surface that rots.
+
+The manual is a set of directions, not a log. Where its instructions failed you, rewrite them. Never leave a wrong instruction standing next to its correction.
+
+Create the manual when the project has none. Name it `docs/guides/driving-manual.md`, unless the project's own docs layout points somewhere else.
+
+Make the change through `/q:update-docs`. Deliver nothing here. The change joins the calling run's change, or waits uncommitted.
+
+## Step 4: Report
+
+Report what you exercised and what it demonstrated, claim by claim — the evidence a PR's Testing section carries (source: q conventions/pull-requests.md, Sections). Name what changed in the manual, and say whether that change is still uncommitted. Name anything you waited on, and how long it held you. Report what failed and stop there.

package/skills/groom-docs/SKILL.md

@@ -0,0 +1,62 @@
+---
+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: q conventions/documentation.md) and its writing rules (see: 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: q conventions/documentation.md, Three tiers of conventions).
+2. The project's recorded rulings and deviations: `docs/conventions/documentation.md` plus any "(overrides: …)" markers across `docs/conventions/` — grep for them. These win over both.
+
+If the project has no `docs/conventions/` directory, or `node_modules/@lab43/q/` is absent (a fresh clone may just need `npm install`), stop and suggest the fix — without both there is no surface or rubric to groom against.
+
+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:
+
+- `docs/conventions/*.md`, `README.md`, `CLAUDE.md` (the agent briefing) — full checks.
+- The `conventions/` of any extension this repo authors — a working-tree `package.json` carrying the `q-extension` keyword — full checks, like the project's own conventions (source: q conventions/extensions.md). Anything else the project's own `documentation.md` puts on the surface joins it, under rubric item 2.
+- `docs/guides/*.md` — **guide mode**, per the policy's Taxonomy rules.
+- `docs/plans/*.md` — **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; guides clustered separately, in guide mode): every checkable claim — file paths, symbol names, behavior descriptions, commands — verified against current source. Exemplar references get a deeper check: the file exists and still exhibits the rules its doc attaches to it.
+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 marked override whose target updated to agree or disappeared is spent — propose deleting it (source: q conventions/documentation.md, Three tiers of conventions). Those docs 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.
+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: q conventions/plans.md, Frontmatter); list every `pending` plan with its age (last git commit date).
+
+## Step 3: Consolidate with the user
+
+Merge the findings into proposed edits, each stating its remedy and citing its finding — a conversational stretch (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), and any fact that couldn't be verified either way.
+- 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. **Local review's gate**: run the gate 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: 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/implement-plan/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: implement-plan
+description: Implement a plan from docs/plans end-to-end and open the PR or stacked PRs its delivery call names, with every commit, push, and PR gated by the review mode the user picks up front. Name the plan or give its path.
+---
+
+# Implement Plan
+
+Given no plan, list the `pending` plans in `docs/plans/` and ask which one.
+
+## Ground rules
+
+- **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
+- **Track resolutions**: keep a scratchpad note of each review round's BLOCKING findings and how each was resolved (fixed / rejected with reason) — it feeds the PR's Callouts and Caveats, stated as facts about the change.
+- **Context hygiene**: use subagents (Explore for recon, background Bash for checks, `adversarial-reviewer` for review) to keep large output out of the main context.
+- **Plan doc amendments**: when execution deviates from the plan or a verification step contradicts it, fold the outcome into the plan doc as a marked amendment per the lifecycle rules (see: q conventions/plans.md, Lifecycle), alongside the work of the phase that surfaced it.
+- **Doc updates**: make the doc changes the plan schedules through `/q:update-docs`, alongside the phase that carries them.
+
+## Step 1: Understand
+
+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.
+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.
+
+## Step 2: Clarify
+
+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 autonomous stretch won't have to stop for. 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 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:
+
+**Single PR:**
+
+```bash
+git fetch origin && git checkout -b <plan-name> origin/<default-branch>
+```
+
+**Stacked PRs** — one branch per PR group from the plan's Phases section, chained bottom-up. Requires the `gh stack` extension (install with `gh extension install github/gh-stack` if `gh extension list` lacks it):
+
+```bash
+git fetch origin
+git rev-parse <default-branch> origin/<default-branch>
+gh stack init <plan-name>/01-<group-slug> --base <default-branch>
+```
+
+`--base` takes a branch name. `gh stack` records it verbatim and hands it to GitHub as every layer's PR base, and GitHub rejects a remote-tracking ref: `--base origin/main` pushes the branches and then fails each PR with "Base ref must be a branch". That is why the `rev-parse` above runs first — it must print the same SHA twice, because a local branch behind its remote silently becomes the stack's base. Fast-forward it before initializing when it isn't. Each later group's branch is created in Step 4 as work reaches it; only the first group's is created here. When the run lives in a worktree, the whole stack lives in that one worktree — later layers as branches inside it, never new worktrees.
+
+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 review, hold the commit; when the user's approval starts the committing, the plan doc — clarifications folded in — is committed first, the two-commit split being history local mode gives up.
+
+## Step 4: Implement in phases
+
+In a stacked run, this step and Step 5 alternate: implement a group's phases here, wrap its PR there, and return for the next group.
+
+Derive phases from the plan's Phases section — a boundary problem visible up front was Step 2's to settle and fold in. The plan's breakdown is not yours to redesign; when implementation reveals a phase that can't stand alone as a commit that builds and passes its tests, merge or split at that seam and record the change as a plan amendment.
+
+In local review, commits wait for the user's review at each PR boundary (Step 5): phases accumulate uncommitted, and a phase's adversarial review takes the uncommitted diff plus the phase's file list.
+
+Then work phase by phase. In a stacked run, a phase that starts a new PR group first opens the group's branch — `gh stack add <plan-name>/<NN>-<group-slug>`, the first group using Step 3's branch — so the group's phases commit to their own branch. A new group records its group-start SHA as Step 3 describes.
+
+In ship mode, record the phase-start SHA (`git rev-parse HEAD`) at the start of each phase. It scopes the phase's review diff.
+
+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 review. 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
+
+When a group's last phase lands, finish that PR before starting the next group:
+
+1. **Verify its work in the running product**: drive what the PR delivers through `/q:drive`, naming the flows to exercise. Derive the scope from the group's content — a judgment that can land on nothing at all, when Step 4's checks fully characterize the work. The final PR is the exception. Drive the plan's Verification section: the integrated state exists now, and its end-to-end proof belongs ahead of this last review. Run the project's full test suite too — the run's only unscoped check. Fix what verification catches and re-verify. In ship mode, commit what this step produced: the fixes, plus anything driving recorded. Record for the PR's Testing section what was exercised and what it demonstrated. The standing suite goes unlisted (source: q conventions/pull-requests.md, Sections).
+2. **Final review**: validate the PR's diff (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses. Hand the reviewers the plan path, which plan steps this PR delivers (and that the rest live in other PRs), and the diff scope — `git diff <group-start-sha>..HEAD` in ship mode; the uncommitted diff plus the group's file list (every file its phases touched) in local review. Per loop round, re-drive a flow from item 1 only when a fix could change what driving showed. Surviving findings become Caveats in the PR description.
+3. **Local review's gate**: run the gate over the PR's uncommitted diff (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate); commits land onto the PR's layer.
+4. **Mark the plan completed** — last or only PR: set `status: completed` in the plan doc's frontmatter and commit it (in a stacked run the lower PRs still show `pending`; the flip lands when the whole stack merges). In local review this flip rides the approval just given. That is a deliberate exception to the gate: the approval already covers this bookkeeping. Don't ask again.
+5. **Open the PR**, so the user can start reviewing while later groups build. Author every PR's title and body per the PR-authoring rules (see: q conventions/pull-requests.md).
+
+   Single PR: `git push -u origin <plan-name>`, then `gh pr create`.
+
+   Stacked: `gh stack submit --auto` pushes the layers built so far and creates the new PR as a draft. GitHub links the stack, runs CI on every layer as if it targeted the default branch, and cascade-merges bottom-up from whichever PR the user merges. `--auto` is required, because the interactive editor the command otherwise opens cannot be driven. It names the PR from the branch and writes no body. Write the title and body with `gh pr edit`, then `gh pr ready` to take it out of draft. Never hand the user a PR marked ready before its body is written.
+6. **Hand the PR over**: give the user its URL and what it delivers. In a stacked run this hand-off is not the closing report, however much it reads like one. Return to Step 4 and open the next group's branch in the same turn.
+
+## Step 6: Report
+
+Reached once a run: after the only PR, or after the stack's last. Every earlier group returns to Step 4 instead.
+
+Close the session by reporting the PR URL(s), the phase list, any caveats, any amendment raised instead of applied, and any follow-up work — filed in the tracker on the user's agreement (source: q conventions/issue-tracking.md, Ask before filing).

package/skills/install/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: install
+description: Install q into a project, or add an extension to one. Invoke bare to set q up; name an extension to install it. Idempotent, safe to re-run on a partially set-up project. 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`. The invocation picks the path: a bare run bootstraps q (Steps 3–4); an extension run adds the extension install (Step 5) after them. A run naming `q` or `@lab43/q` is a bare run, because q is the framework rather than an extension (source: q conventions/extensions.md, Identity). 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) — candidates for migration
+- Whether an earlier run's scaffold sits uncommitted in the working tree
+- On an extension run: whether the named extension is already pinned, installed, indexed, and watermarked
+- 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 bare run where Step 1 found nothing missing or drifted beyond an unpopulated `node_modules/`, no migration candidates, and no scaffold sitting uncommitted from an earlier run — there is nothing to change or deliver. Enforce the pins per `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md` (machine state, not a repo change), then stop with the closing report (Step 8).
+- An extension run where the named extension is already pinned, installed, indexed, and watermarked, Step 1 found nothing missing from the q scaffold, and no install sits uncommitted from an earlier run — report that and stop.
+- 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); on an extension run the connected-work case is the extension arriving with the dependency that ships it.
+
+## 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: q conventions/principles.md).
+   ```
+
+   `docs/conventions/documentation.md`:
+
+   ```markdown
+   # Documentation
+
+   This project's documentation rulings and deviations (see: q conventions/documentation.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 installs as one pinned npm package, carrying its conventions and its plugin together:
+   - Ensure a root `package.json` — create `{"private": true}` if the project has none.
+   - If `@lab43/q` is not yet in `devDependencies`: `npm install --save-dev --save-exact --ignore-scripts @lab43/q` (via the project's package manager when it isn't npm). If it is, leave the recorded pin alone.
+
+   That pin is the only place a q version appears. Moving it and installing is the whole of an update.
+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`. 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 the `q` entry 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-pins.md). Two projects sharing a name means the second one loads a q version it never pinned.
+
+   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. Keeping a name the project chose gives up guaranteed uniqueness, which is the better trade against renaming a marketplace the project owns.
+
+   ```json
+   {
+     "name": "<marketplace>",
+     "owner": { "name": "this project" },
+     "metadata": { "description": "Pins this project's q version. The name must stay unique to this project. Sharing another project's name makes this one resolve to that project's pinned q." },
+     "plugins": [
+       {
+         "name": "q",
+         "source": "./node_modules/@lab43/q",
+         "description": "The q workflow plugin, pinned for this project."
+       }
+     ]
+   }
+   ```
+
+   Then merge into `.claude/settings.json`, leaving other keys untouched. Key both entries to whatever name the manifest records, and correct either if it has drifted from it:
+
+   ```json
+   {
+     "extraKnownMarketplaces": {
+       "<marketplace>": { "source": { "source": "directory", "path": "./" } }
+     },
+     "enabledPlugins": { "q@<marketplace>": true, "q@q": false }
+   }
+   ```
+
+   Write the path by hand, relative to the project root — `claude plugin marketplace add` records an absolute path, which breaks every other checkout of the repo.
+
+   `"q@q": false` retires the bootstrap marketplace the package ships. Its name is the same in every copy of q, so leaving it enabled means loading whichever copy registered that name last. Disabling it is what makes the project's own pin authoritative.
+5. **Enforce the declarations** — make this machine match the pins just declared, per `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.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. **README setup instructions** — ensure the README tells a collaborator using Claude Code how to bring up a fresh clone: install the project's dependencies, which is what delivers q. Fold that into the project's existing setup instructions or setup script — a dependency install the project already documents (`npm install`, a pnpm or yarn equivalent, a bootstrap script) covers it, and a README already carrying the information needs nothing. Present the q steps as applying to collaborators who use Claude Code, never as requirements for working in the repo. Create a minimal README with just these instructions when the project has none.
+9. Scaffold nothing else. An empty taxonomy directory arrives when its first document does.
+
+## Step 4: Migration proposals (existing projects only)
+
+On an extension run, skip this step unless Step 3 just bootstrapped a previously q-less project. If Step 1 found convention-like content outside `docs/conventions/` — rules in the briefing that apply only to particular kinds of work, rule-carrying docs elsewhere in `docs/` — read `node_modules/@lab43/q/conventions/documentation.md` and propose moving the content per its taxonomy, via AskUserQuestion — a conversational stretch. Apply approved moves, leaving a one-line pointer behind where the policy calls for one.
+
+## Step 5: Install the extension (extension runs only)
+
+The named extension is the agreement — install it autonomously. If it is not yet in `devDependencies` (via the project's package manager when it isn't npm):
+
+```
+npm install --save-dev --save-exact --ignore-scripts <extension>
+```
+
+If it is, leave the recorded pin alone and make this machine match through `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`.
+
+Verify what arrived is an extension: `node_modules/<extension>/package.json` carries the `q-extension` keyword, and the package root holds a `conventions/` directory, a `.claude-plugin/` directory, or both (source: q conventions/extensions.md). If not, `npm uninstall` it and report — never index it. When the run changed nothing else, switch back to the prior branch and delete any branch this run created; when Step 3 bootstrapped the project, keep that scaffold, carry on to Step 6, and report the extension failure in the close.
+
+An extension shipping `conventions/` gets one briefing index line per doc the index doesn't already carry, under its extensions group and contiguous with any lines it already has: package name plus path from the package root (see: q conventions/documentation.md, Package doc paths), blurb restating the doc's intro (source: q conventions/documentation.md, Taxonomy). One shipping no `conventions/` is watermarked without being indexed, having no docs to index (source: q conventions/extensions.md, Layout).
+
+When the extension has no `reconciledAgainst` entry, write one from the version in `node_modules/<extension>/package.json` (see: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md) — an extension Step 1 found pinned and installed by hand included. Never overwrite a present entry, stale or not — it is reconciliation's to move (source: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md).
+
+Installing an extension's plugin is not yet part of this step: q scaffolds only its own marketplace entry.
+
+## Step 6: Adversarial review
+
+Invoked from another skill's run, stop here — the changes are that run's to validate and deliver. When the run changed nothing tracked — every proposal declined on an otherwise complete project — 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 8), 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 first. In both modes, validate the changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
+
+## Step 7: Open the PR
+
+1. **Local review's gate**: run the gate over the uncommitted changes (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: q conventions/pull-requests.md).
+
+## Step 8: Report
+
+Close the session by reporting:
+
+- What was created.
+- What already existed and was left untouched.
+- What was proposed, and the user's decisions.
+- On an extension run:
+  - The extension and version installed, and the index lines added.
+  - Any overrides markers its docs carry against q's rules. These are deviations the project now lives under. The project's own rulings still win on conflict.
+  - Its q declaration — its `@lab43/q` devDependency (source: q conventions/extensions.md) — held against the project's own pin. An extension written against a newer q than the project runs is the signal to suggest `/q:update`. One written against an older q, or carrying no declaration, is noted as-is — no update closes it.

package/skills/parallelize/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: parallelize
+description: Give a repo's parallel sessions their own copies of what they contend over while driving — ports, databases, caches, devices. Use when sessions collide over something the repo holds only one of, or to prepare a repo before parallel work starts. Invoke it bare to sweep the repo, or name a resource to scope it. Isolates what can be isolated, names what sessions must take turns over instead, and records both in the driving manual. Changes the repo and ships a PR, escalating to /q:create-plan when the build is plan-sized.
+---
+
+# Parallelize
+
+## Ground rules
+
+- **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
+- **Isolation is an optimization, never a precondition**: sessions take turns over whatever stays shared, which works in any repo today. A resource left un-isolated is a fact to record, not a failure.
+- **Track resolutions**: keep a scratchpad note of each review round's BLOCKING findings and how each was resolved (fixed / rejected with reason) — it feeds the PR's Callouts and Caveats, stated as facts about the change.
+- **Context hygiene**: use subagents (Explore for recon, background Bash for checks, `adversarial-reviewer` for review) to keep large output out of the main context.
+
+## Step 1: Read the repo
+
+Find what this repo runs and what those things bind. An unfamiliar repo shape is the normal case, so read what is there rather than looking for a shape you recognize. Read whatever declares it:
+
+- service and container definitions
+- scripts, and the tasks the package manager or build tool exposes
+- test and build configuration
+- CI workflows
+- environment templates, and the defaults they carry
+- the driving manual, which may already name what a session must take turns over
+
+Use an Explore subagent for breadth; read the load-bearing files yourself. An invocation that named a resource scopes the step to that one: establish what binds it and what would collide, and skip the sweep.
+
+The outcome is one list: everything this repo holds exactly one of that a session needs while working. Each entry names what binds it, what would collide, and where the repo declares it (`file:line`).
+
+## Step 2: Agree what to isolate
+
+Every entry on the list goes one of two ways:
+
+- **Isolated** — each session gets its own. A port derived per session rather than fixed, a database or schema named per session, a cache or scratch directory keyed per session.
+- **Shared** — there can only be one, so sessions take turns over it. A licensed device, a staging environment, an external account. Say how a session claims it and how it releases it. Something that could be isolated, but not within one reviewable PR, is not shared — that is the escalation below.
+
+Settle the run with the user, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). One batch: the list, which way each entry goes, and 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 green light, not the last answer, is what makes the rest of the run autonomous.
+
+When the agreed isolation won't fit one reviewable PR, continue into `/q:create-plan` in this session on the go-ahead, handing over what Step 1 found and what the batch already settled. This run ends there; the plan carries the build.
+
+## Step 3: Build it
+
+1. Settle the branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch). This work is its own delivery unit, so the call is a fresh branch. Require a clean working tree first — if anything is uncommitted, stop and show the user. Branch, unless the contract's peer check already put this run on a worktree's branch:
+
+   ```bash
+   git fetch origin && git checkout -b <work-slug> origin/<default-branch>
+   ```
+
+2. Implement the agreed isolation, 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).
+4. In ship mode, commit — before review, so the review history is inspectable in git.
+
+When building reveals the work is deeper than the agreement — a redesign, more than one reviewable PR's worth of change — interrupt: present the discovery and recommend `/q:create-plan`. Planning starts only on the user's go-ahead; what this run learned and built goes into its scope.
+
+## Step 4: Record it
+
+Drive what you built through `/q:drive`. What to exercise: each resource the run isolated, with two copies running at once, plus each one Step 2 left shared. The build never touched the shared ones, and a driving session still has to take its turn over them.
+
+## Step 5: Adversarial review
+
+Validate the diff (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses. Hand the reviewers the agreed scope and the diff scope: `git diff origin/<default-branch>...HEAD` in ship mode, or the uncommitted diff plus the changed-file list in local review. Per loop round, re-drive a resource only when a fix could change what driving showed. Surviving findings become Caveats in the PR description.
+
+## Step 6: Open the PR
+
+1. **Local review's gate**: run the gate over the session's uncommitted work (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
+2. **Open the PR**: `git push -u origin <work-slug>`, then `gh pr create`, per the PR-authoring rules (see: q conventions/pull-requests.md).
+3. Close the session by reporting the PR URL, every resource left shared, any caveats, any amendment raised instead of applied, and any follow-up work — filed in the tracker on the user's agreement (source: q conventions/issue-tracking.md, Ask before filing).

package/skills/review/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: review
+description: Review anything ad hoc — the session's change, a diff, a file or directory, a doc's prose, a feature, a plan doc — through the project's conventions-grounded adversarial reviewer. The user rules on the findings; approved fixes are applied, and delivery is the user's choice — shipped as their own PR, or left in the working tree for later delivery. Given no target, reviews the session's outstanding change. A finding can indict a convention rather than the artifact — either side may change. Planned work is reviewed inside its own run.
+---
+
+# Review
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
+
+## Step 1: Resolve the target
+
+The target comes from the invocation. Map it to an artifact the adversarial reviewer takes:
+
+- **Nothing given**: the session's outstanding change. That is the uncommitted diff plus the changed-file list, untracked files included — or, with a clean tree, the branch's diff against the default branch. Say which was picked. When both are empty, ask for a target.
+- **A diff, file, or directory**: as given.
+- **A feature or area named in words**: locate its files (an Explore subagent for breadth) and confirm the file list with the user before reviewing.
+- **A plan doc in `docs/plans/`**: a plan review when its status is `pending`. Review any other plan as prose.
+
+## Step 2: Launch the review
+
+Launch `adversarial-reviewer` subagents over the artifact, passing what the agent's description names: the artifact — a diff command or file list, or the plan path — and the lenses, plus what the work is meant to deliver when the invocation stated it. Lenses follow the artifact: **feasibility** and **rigor** for a plan review, **correctness** and **conventions** for everything else, prose included. Launch one reviewer per lens, in parallel.
+
+## Step 3: Rule with the user
+
+A conversational stretch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). Triage the findings:
+
+- **Fix outright**: a finding that is clearly right, with a fix that reopens nothing. Apply it and present it as applied, where the user can veto it.
+- **Reject outright**: a finding the session's context refutes. Present it with its reason — never drop one silently, since the refuting context may itself be wrong.
+- **Rule**: everything contestable goes to the user (AskUserQuestion), ranked — blocking, nits, follow-ups — each with a recommendation. Group documentation gaps on their own, so they can't hide among the other findings. A finding whose evidence indicts a cited rule is always ruled, never fixed or rejected outright: the user decides which side changes, and an approved amendment is executed in Step 4.
+
+Fixes to an outstanding change another run owns stay uncommitted with it — don't commit, and don't ask about delivery. For any other target, ask in the same batch how the work is delivered: local or ship (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes), or leave it uncommitted in the working tree — a session may run several reviews and deliver the accumulated work once. When the target was the user's own uncommitted work, delivery covers that work and the fixes together: they can't be separated.
+
+## Step 4: Apply
+
+1. When delivering now, create a branch unless the session is already on one.
+2. The rulings are the agreement — apply the approved fixes autonomously, approved convention amendments included. Fixes and amendments that land in policy-governed docs go through `/q:update-docs`, the documentation surface's single write path. Run the project's checks covering what changed.
+3. Sweep the rulings for lessons the docs should carry: a rejected finding whose reason is a rule nobody wrote down, or a correction the next reviewer would have to re-derive. Each one is a correction to record (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Corrections become rules). In ship mode, commit the fixes and the recordings together.
+
+## Step 5: Adversarial review
+
+When delivering now, validate the whole diff being delivered (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses — the target's review found the defects, but the fixes themselves have not been reviewed until now. Work joining an outstanding change another run owns, or left in the tree, is validated by the run that delivers it.
+
+## Step 6: Deliver
+
+1. Fixes not delivered now — joining an outstanding change another run owns, or left in the tree — stay uncommitted for the run that delivers them. Skip to the report.
+2. **Local review's gate**: run the gate over the uncommitted fixes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The local gate).
+3. **Open the PR**: push the branch and open the PR per the PR-authoring rules (see: q conventions/pull-requests.md).
+4. Close the session by reporting: findings and rulings including what was dropped, the check results, the doc entries recorded, and any amendment raised instead of applied, listed on its own. When work was left in the tree, say that it is unvalidated until delivered, and that a later bare `/q:review` reviews and delivers the accumulation.

package/skills/sync/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: sync
+description: Set up or repair this machine for a q-using project, handing off to /q:install, /q:update, or /q:uninstall-extension when the project's records don't match its pins. Use on a fresh clone or a new machine, or whenever the session-start check says the project's q setup did not validate. Never moves pins and never reconciles docs; the only tracked file it may touch is a lockfile a dependency install rewrites.
+---
+
+# Sync
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`. The invocation is the agreement — proceed autonomously throughout. Sync delivers no repo change, so there is no branch, review mode, or PR.
+
+## Step 1: Enforce the pins
+
+Two states have nothing to sync yet. Propose `/q:install` and stop for either:
+
+- The project declares no `@lab43/q` devDependency. It has no pins to enforce.
+- It declares one but has no `.claude/q-state.json`. q's bytes arrived. The scaffold that records them has not run. This is the window between the bootstrap install and the first `/q:install`. It is the state the session-start check reports.
+
+Otherwise enforce the pins per `${CLAUDE_PLUGIN_ROOT}/references/enforce-pins.md`.
+
+## Step 2: Check the GitHub CLI
+
+Run `gh auth status`, and `gh repo view` to confirm the repo's `origin` is GitHub-hosted — q's workflow skills require both. When either fails, report the fix: install via https://cli.github.com and authenticate with `gh auth login` for a missing or unauthenticated CLI; a failing `gh repo view` with an authenticated CLI means `origin` is not GitHub-hosted.
+
+## Step 3: Compare pins against watermarks
+
+Read `.claude/q-state.json` (see: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md) and compare:
+
+- the pin of `@lab43/q` and of each extension in `package.json` against its `reconciledAgainst` entry, in both directions — the extensions are the direct `devDependencies` whose own `package.json` carries the `q-extension` keyword (source: q conventions/extensions.md)
+
+Each finding routes to its remedy:
+
+- A pin differing from its watermark (moved out of band, unreconciled) → `/q:update`, invoked bare once — a bare run covers every such finding.
+- An entry for an extension no longer in `package.json` (removed out of band, the removal never reconciled) → `/q:uninstall-extension`, with the extension name, one run per extension.
+- No record where one belongs → `/q:install` — bare for a missing state file or a missing `@lab43/q` entry; with the extension name for any other pinned extension that has no entry, one run per extension. These were installed or scaffolded by hand, never recorded.
+
+Never write the state file — watermarks certify reconciliation, and sync never reconciles (source: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md).
+
+## Step 4: Report, then hand off
+
+Report:
+
+- What Step 1 enforced, and any tracked file it rewrote (a lockfile) left in the tree as the user's.
+- The GitHub CLI result, with the fix when it failed.
+- Each finding from Step 3 and the remedy it routes to.
+
+Then make Step 3's hand-offs — each invocation a full run of its own that asks and delivers for itself. Make the `/q:install` and `/q:uninstall-extension` runs before any `/q:update` run, so update starts from repaired records.