@lab43/q 0.4.0 → 0.6.0

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

@@ -12,30 +12,30 @@ Given no plan, list the `pending` plans in `docs/plans/` and ask which one.
 - **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.
+- **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: @lab43/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.
+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.
 
 ## 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:
+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 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.
+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
 
@@ -63,7 +63,7 @@ In a stacked run, this step and Step 5 alternate: implement a group's phases her
 
 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.
+In local mode, 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.
 
@@ -74,18 +74,18 @@ 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.
+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
 
 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).
+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: @lab43/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 mode. 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. **The local gate**: run it 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 mode this flip rides the go-ahead just given. That is a deliberate exception to the gate: the go-ahead 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: @lab43/q conventions/pull-requests.md).
 
    Single PR: `git push -u origin <plan-name>`, then `gh pr create`.
 
@@ -96,4 +96,4 @@ When a group's last phase lands, finish that PR before starting the next group:
 
 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).
+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: @lab43/q conventions/issue-tracking.md, Ask before filing).

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
+   ## Claude Code
+
+   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`.

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

@@ -36,7 +36,7 @@ Every entry on the list goes one of two ways:
 
 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.
+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.
 
 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.
 
@@ -60,10 +60,10 @@ Drive what you built through `/q:drive`. What to exercise: each resource the run
 
 ## 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.
+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 mode. 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).
+1. **The local gate**: run it 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: @lab43/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: @lab43/q conventions/issue-tracking.md, Ask before filing).

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

@@ -0,0 +1,110 @@
+---
+name: reconcile
+description: Reconcile the project's records with what npm already did — q or an extension updated, installed, or removed (your own npm install, a teammate's merge, a Dependabot bump). The changes ship as a PR. Also sets up or repairs this machine for a q-using project — use it on a fresh clone, or whenever the session-start check reports drift. A project with no q scaffold routes to /q:install instead. A run finding nothing to reconcile repairs the machine, asks nothing, and stops.
+---
+
+# Reconcile
+
+Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
+
+## Step 1: Enforce the declarations
+
+Propose `/q:install` and stop in either of these states — there is nothing to reconcile yet:
+
+- The project declares no `@lab43/q` devDependency. It has nothing to enforce.
+- It declares one but has no `.claude/q-state.json`. q's bytes arrived. The scaffold that records them has not run.
+
+Otherwise enforce the declarations per `${CLAUDE_PLUGIN_ROOT}/references/enforce-declarations.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: Take stock
+
+Read `.claude/q-state.json` (see: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md) and compare:
+
+- the version the project's lockfile resolves for `@lab43/q` and for each extension against its `reconciledAgainst` entry, and the version installed under `node_modules/` against the lockfile's, in both directions — the extensions are the direct dependencies, in `dependencies` and `devDependencies` alike, whose installed copy carries both halves of an extension's identity — the `q-extension` keyword and a payload directory (source: @lab43/q conventions/extensions.md, Identity). A dependency carrying the keyword, shipping no payload, and holding no `reconciledAgainst` entry is not an extension: leave it out of scope rather than reporting a missing record no skill could resolve. A watermarked package stays in scope however it changed, because a record already exists and only reconciliation or removal clears it
+
+Each finding routes to its remedy:
+
+- A lockfile version differing from its watermark (moved, never reconciled) — a version move: this run reconciles it (Step 5). When the release stopped shipping a payload, the rules departed while the code stayed: reconcile it as a departure (Step 6) instead.
+- An entry for an extension in neither `dependencies` nor `devDependencies` (removed, the removal never reconciled) — a departure: this run reconciles it (Step 6). Read both before treating it as one: an extension held as a regular dependency is healthy, and reading `devDependencies` alone reports it as removed. `@lab43/q` never routes here — a project that dropped its q declaration is Step 1's stop.
+- A `reconciledAgainst` map with no `@lab43/q` entry → `/q:install`, invoked bare. The scaffold was never fully recorded, and scaffolding is install's to complete. A state file missing altogether never reaches this step — it is Step 1's stop.
+- Any other declared extension with no entry, from either dependency map — an arrival, installed by hand and never recorded: this run reconciles it (Step 7).
+
+Alongside, hold each third-party extension's q declaration — the `@lab43/q` devDependency in its own `node_modules/<extension>/package.json` (source: @lab43/q conventions/extensions.md, Pinning) — against the project's own installed q, and flag a mismatch either way in the close. A declaration ahead of the project's q closes by the developer moving q forward; one behind closes only by that extension's release. A ranged q declaration states no version at all — flag it as the extension author's to fix.
+
+## Step 4: Settle delivery
+
+A run that found nothing to reconcile — no finding at all, or only the `/q:install` hand-off — skips to Step 10: it asks nothing and delivers nothing, Steps 1 and 2 having changed machine state only. 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). The findings are the agreement — the rest of the run is autonomous. However many packages moved, one run reconciles them into one change: they are the same project catching up with the same npm install.
+
+## Step 5: Reconcile each version move
+
+Diff the two published versions: `npm pack <package>@<version>` for the watermark and for the installed version into a scratch directory, extract both, and diff the trees. Diff the whole tarball rather than the payload's `conventions/` alone, because a release can change skills, hooks, agents and references too. Work only from the diff. What it touched decides which of these applies, and a diff may touch more than one:
+
+- **Changed conventions docs** — hold the project's docs, and the exception markers its code carries, against each changed rule:
+  - remove an override whose target updated to agree or disappeared — it is spent (source: @lab43/q conventions/conventions.md, Three tiers of conventions)
+  - re-check each "(source: …)" restatement against its changed home
+  - re-check each exception against its changed rule — retarget one whose rule moved, and remove one that is spent, its rule gone or changed to admit the site (source: @lab43/q conventions/documentation.md, Markers)
+  - prune a project rule the new text now owns — it is duplication now
+  - ask about a project rule the new text contradicts, the one call the go-ahead didn't settle: keep it as a recorded deviation (add the overrides marker) or adopt the incoming rule. Adopting can leave code non-conforming — suggest `/q:review` on the affected area; bringing code back into conformance is out of scope here
+
+  An extension authored in this repo is part of that surface: re-check its docs and its own `q.description` the same way. The exact `@lab43/q` pin in its root `package.json` is also that extension's shipped declaration of which q version its rules were written against — the manifest goes into the published tarball, which makes this the one `package.json` entry still read as a version (source: @lab43/q conventions/extensions.md, Pinning). Flag it when it no longer names the q the project now runs; moving it is the developer's npm edit.
+
+  Then sync the briefing's index lines for the package — a doc added or removed changes the list, and a changed intro means rewriting the doc's blurb (see: @lab43/q conventions/documentation.md, Taxonomy).
+- **A changed `q.description`** — rewrite that extension's group heading in the briefing's docs index (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`). A release can change the blurb alone.
+- **A changed plugin**, q's or an extension's — re-run `/q:install`, scoped to join this run's change: it is idempotent, creating what the new version's scaffold expects and correcting what has drifted from it. A plugin's changed contents reach sessions from `node_modules/` as they stand; the re-run is what registers a plugin the release started shipping. A plugin the release stopped shipping takes the reverse: remove it from the project's marketplace the way Step 6 does for a departed extension.
+
+After each package's reconciliation, write its watermark per `${CLAUDE_PLUGIN_ROOT}/references/q-state.md`: its `reconciledAgainst` entry to its installed version.
+
+Step 4's go-ahead already covers this reconciliation, the prunes, drops and watermark writes included. Apply it without re-asking.
+
+## Step 6: Reconcile each departure
+
+The developer already removed the package; this run reconciles the records it left behind. Run the package manager's dependency install once, catching up any lockfile and `node_modules` remnants the removals left — it realizes what the manifest already declares: no named package, no manifest write. A package that departed by dropping its payload takes the same treatment minus that install — its code is still installed, and only its records leave. Then, for each departed extension, remove without asking — each item a no-op when already absent:
+
+1. Remove the extension's group from the agent briefing's docs index — its heading and every line under it. An extension that shipped no conventions docs has no group to remove.
+2. Drop the extension's `reconciledAgainst` entry, per `${CLAUDE_PLUGIN_ROOT}/references/q-state.md`.
+3. Remove the extension's plugin from the project's marketplace. Drop the `.claude-plugin/marketplace.json` entry whose `source` is `./node_modules/<extension>/q-extension`. Then drop the `enabledPlugins` key in `.claude/settings.json` that names the removed entry's plugin at the project's marketplace. Leave every other entry and key alone. An extension that shipped no plugin has neither.
+
+Then rule on what the departure orphaned. Grep the docs the documentation policy owns (see: @lab43/q conventions/documentation.md, Taxonomy) for the extension's name, and grep the project's code for exception markers naming it, excluding `node_modules/` and build artifacts. Every hit lost its backing with the extension: an overrides marker's target, an exception marker's target, a restatement's home, a cross-reference's destination. On a clean sweep, skip this. Otherwise recommend a resolution for each hit, grounded in the documentation policy, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes) — one AskUserQuestion batch. The user rules. Apply the rulings.
+
+## Step 7: Reconcile each arrival
+
+The developer already installed the package; this run records it. For each arrived extension:
+
+1. Verify both halves of its identity (source: @lab43/q conventions/extensions.md, Identity): `node_modules/<extension>/package.json` carries the `q-extension` keyword, and the package holds `q-extension/conventions/`, `q-extension/.claude-plugin/`, or both. Step 3 scoped by this same identity; re-verify at the acting site, because the watermark write is what a misclassification would poison. A package failing the check is reported in the close and left alone — no index lines, and above all no watermark, which would record a package q cannot reconcile.
+2. An extension shipping conventions docs gets its own group in the briefing's docs index, written to that file's rules (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`). One shipping none is watermarked without being indexed, having no docs to index (source: @lab43/q conventions/extensions.md, Layout).
+3. An extension shipping a plugin gets it registered in the project's marketplace: re-run `/q:install`, scoped to join this run's change. One shipping none has nothing to load.
+4. Write its watermark from the version in `node_modules/<extension>/package.json`. Never overwrite a present entry, stale or not: a stale watermark moves only by reconciling the version move behind it (source: ${CLAUDE_PLUGIN_ROOT}/references/q-state.md).
+
+Report in the close, per arrival:
+
+- A missing `q.description`, if the package ships conventions docs without one (source: @lab43/q conventions/extensions.md, Description). Its group falls back to a heading of the package name alone (source: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`). Name it as the extension author's to fix, not the installing project's. Index it anyway — one missing blurb does not stop rules that otherwise work.
+- 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.
+
+## Step 8: Adversarial review
+
+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 9: Open the PR
+
+Skip this step when Step 4 found nothing to deliver.
+
+1. **The local gate**: run it 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: @lab43/q conventions/pull-requests.md).
+
+## Step 10: Report, then hand off
+
+Close the session by reporting:
+
+- 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 version move reconciled and what its release changed.
+- Each arrival reconciled — the group and lines indexed, the plugin registered, the watermark written — with Step 7's per-arrival notes, and each package that failed the identity check, left alone.
+- Each departure reconciled — the records and plugin registration dropped, any lockfile catch-up applied, and each orphaned reference with the user's ruling. Name a departure by dropped payload as a release that stopped shipping rules, since the project may want the dependency reconsidered.
+- Any plugin an install re-run left without a marketplace entry, and why.
+- Each flagged q declaration, and what closes it.
+
+Then, where Step 3 found no `@lab43/q` record, make its `/q:install` hand-off — a full run of its own that asks and delivers for itself.

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

@@ -15,6 +15,7 @@ The target comes from the invocation. Map it to an artifact the adversarial revi
 - **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.
+- **A spec doc in `docs/specs/`**: a work review over the spec itself plus the files carrying its spec markers. Find them by grepping the repo for `spec:` followed by the doc's path, excluding `node_modules/` and build artifacts.
 
 ## Step 2: Launch the review
 
@@ -22,7 +23,7 @@ Launch `adversarial-reviewer` subagents over the artifact, passing what the agen
 
 ## Step 3: Rule with the user
 
-A conversational stretch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes). Triage the findings:
+In conversational mode (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.
@@ -34,7 +35,7 @@ Fixes to an outstanding change another run owns stay uncommitted with it — don
 
 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.
+3. Sweep the rulings for lessons the docs should carry: a rejected finding whose reason is a rule nobody wrote down, a finding rejected because this one site is legitimately outside the rule, 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
 
@@ -43,6 +44,6 @@ When delivering now, validate the whole diff being delivered (see: ${CLAUDE_PLUG
 ## 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).
+2. **The local gate**: run it 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: @lab43/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 → q-extension/skills}/triage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: triage
-description: Choose what to work on next from a set of items — a Jira board, GitHub issues, a Notion doc, a file or pasted list — and work through it one pick at a time. Priority guidelines steer the ranking when given ("newest first"). Each agreed pick runs as a /q:tackle cycle in this session, claimed in the source (assignee, status) only with the user's agreement. For a single known item, invoke /q:tackle directly.
+description: Choose what to work on next from a set of items — a Jira board, GitHub issues, a Notion doc, a file or pasted list — and work through it one pick at a time. Priority guidelines steer the ranking when given ("newest first"). Each agreed pick runs as a /q:implement cycle in this session, claimed in the source (assignee, status) only with the user's agreement. For a single known item, invoke /q:implement directly.
 ---
 
 # Triage
@@ -8,30 +8,30 @@ description: Choose what to work on next from a set of items — a Jira board, G
 ## Ground rules
 
 - **Follow the run contract** — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
-- **Triage ranks, tackle grounds**: judge items on what the source says — titles, descriptions, labels, dates — never by exploring the code. Grounding an item against the codebase is the first step of its tackle cycle, not a triage cost paid across the whole set.
-- **Conventions govern the tracker**: read and follow the issue-tracking conventions (see: q conventions/issue-tracking.md), plus any project rulings, which win. Never re-ask what they settle.
-- **Track the session**: keep a scratchpad note of the session's agreements (review mode, write-backs, priority guidelines) and each item's outcome. An outcome is the PR, plan, or nothing-to-do verdict the tackle cycle produced, or that the user skipped the item. Ranking and the closing recap read from this note, and it keeps the loop intact when earlier cycles are compacted away.
+- **Ranking is not grounding**: judge items on what the source says — titles, descriptions, labels, dates — never by exploring the code. Grounding an item against the codebase is the first step of its implement cycle, not a triage cost paid across the whole set.
+- **Conventions govern the tracker**: read and follow the issue-tracking conventions (see: @lab43/q conventions/issue-tracking.md), plus any project rulings, which win. Never re-ask what they settle.
+- **Track the session**: keep a scratchpad note of the session's agreements (review mode, write-backs, priority guidelines) and each item's outcome. An outcome is the PR, plan, or nothing-to-do verdict the implement cycle produced, or that the user skipped the item. Ranking and the closing recap read from this note, and it keeps the loop intact when earlier cycles are compacted away.
 
 ## Step 1: Read the set
 
 The set comes from the invocation — a Jira board or filter, a GitHub repo's issues, a Notion doc, a file, a pasted list; given nothing, ask what to triage. Read it with whatever tool serves the source, fetching summaries rather than full item histories. Note any priority guidelines the invocation carries.
 
-Read the priority the user set, when the source records one — a hand-ordered position, a priority field, a label. A default listing order is not one: creation date and ID say nothing about priority. A fetch can drop the priority silently. Confirm the call you use preserves it. A GitHub milestone records its priority as a hand-ordered position. That order comes back only through GraphQL:
+Read the priority the user set, when the source records one — a hand-ordered position, a priority field, a label. A default listing order is not one: creation date and ID say nothing about priority. A fetch can drop fields silently. Confirm the call you use preserves the priority and carries descriptions, labels, dates, assignees. A GitHub milestone records its priority as a hand-ordered position. That order comes back only through GraphQL:
 
 ```bash
-gh api graphql -f query='{repository(owner:"<owner>",name:"<repo>"){milestones(query:"<milestone-title>",first:10){nodes{title issues(first:100,states:OPEN){nodes{number title}}}}}}'
+gh api graphql -f query='{repository(owner:"<owner>",name:"<repo>"){milestones(query:"<milestone-title>",first:10){nodes{title issues(first:100,states:OPEN){nodes{number title body labels(first:20){nodes{name}} assignees(first:10){nodes{login}} createdAt updatedAt}}}}}}'
 ```
 
 `milestones(query:)` matches titles by substring, so take the node whose title is the one you were given. `gh issue list --milestone` returns creation order instead. Omitting `states: OPEN` pulls in the milestone's closed issues.
 
-Set aside items not available to pick up rather than proposing them (source: q conventions/issue-tracking.md, Respect existing claims). Check the project's open PRs (`gh pr list`) against the set — the source may not show a fix in review. Ask the peers what work items they hold, and set those aside too (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Working alongside a peer). Any session holds an item, not just another triage run — a `/q:tackle` invoked straight on an issue holds it too. A peer triaging the same set holds no item until it picks. Never divide the set between sessions. Never ask the user to resolve the overlap. Name the set-asides once; the user can pull any back in.
+Set aside items not available to pick up rather than proposing them (source: @lab43/q conventions/issue-tracking.md, Respect existing claims). Check the project's open PRs (`gh pr list`) against the set — the source may not show a fix in review. Ask the peers what work items they hold, and set those aside too (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Working alongside a peer). Any session holds an item, not just another triage run — a `/q:implement` invoked straight on an issue holds it too. A peer triaging the same set holds no item until it picks. Never divide the set between sessions. Never ask the user to resolve the overlap. Name the set-asides once; the user can pull any back in.
 
 ## Step 2: Settle the session
 
 In conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes), settle the session in one batch of questions:
 
-- The review mode every tackle cycle will run under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes).
-- The write-backs the issue-tracking conventions gate on a session-wide agreement: claiming each agreed pick, commenting PR links (see: q conventions/issue-tracking.md). Skip what the source can't support and what conventions already settle.
+- The review mode every implement cycle will run under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes).
+- The write-backs the issue-tracking conventions gate on a session-wide agreement: claiming each agreed pick, commenting PR links (see: @lab43/q conventions/issue-tracking.md). Skip what the source can't support and what conventions already settle.
 - Anything about the set itself that ranking genuinely turns on.
 
 Settle each answer once and don't re-ask it per item, though the user may change any answer between items. Don't ask for priority guidelines when none were given. Rank on the first of these the set gives you:
@@ -44,9 +44,9 @@ State the basis with each proposal so the user can redirect it.
 
 ## Step 3: Propose and hand off
 
-Rank what remains — items neither picked nor skipped this session — and take the top one. Announce it to the peers before proposing it: you hold an item from the moment you pick it, so no two sessions spend a conversation scoping the same one. Then propose it: the recommended item, why it's next under the guidelines (or the stated basis), and the runners-up. When a set-aside would outrank the pick, or an item's claim looks stale, flag it alongside the proposal: the status may be wrong, and the user rules (source: q conventions/issue-tracking.md, Respect existing claims). The user may agree, pick a different item, adjust the guidelines — reranking takes effect immediately — or stop. Release the item you announced as soon as you are no longer holding it, and announce the next one you take up.
+Rank what remains — items neither picked nor skipped this session — and take the top one. Announce it to the peers before proposing it: you hold an item from the moment you pick it, so no two sessions spend a conversation scoping the same one. Then propose it: the recommended item, why it's next under the guidelines (or the stated basis), and the runners-up. When a set-aside would outrank the pick, or an item's claim looks stale, flag it alongside the proposal: the status may be wrong, and the user rules (source: @lab43/q conventions/issue-tracking.md, Respect existing claims). The user may agree, pick a different item, adjust the guidelines — reranking takes effect immediately — or stop. Release the item you announced as soon as you are no longer holding it, and announce the next one you take up.
 
-The agreed pick authorizes its handoff, nothing more. Claim the item in the source when claiming was agreed. Then continue into `/q:tackle` in this session, passing only what triage settled: the item's reference in its source (its text, when the set was pasted inline), the review mode, and any constraints from the conversation. Tackle reads the source itself and settles the verdict, route, and approach with the user — the pick decides only what's next.
+The agreed pick authorizes its handoff, nothing more. Claim the item in the source when claiming was agreed. Then continue into `/q:implement` in this session, passing only what triage settled: the item's reference in its source (its text, when the set was pasted inline), the review mode, and any constraints from the conversation. The run reads the source itself and settles the verdict, route, and approach with the user — the pick decides only what's next.
 
 ## Step 4: Loop
 

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

@@ -14,41 +14,46 @@ Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
 The change comes from the invocation: named in the prompt, surfaced by the session's own work, or handed over by a delegating skill. On a bare invocation, sweep the session for candidates — decisions made, gotchas hit, corrections taken. Route each by what it is:
 
 - **A lesson, pattern, or decision to record — including a decision to change an existing convention** → the conventions path, Step 3.
-- **A fact, instruction, or overview change for the product's readers** → the surface the taxonomy assigns it — a guide, the README, or the briefing, whether or not the invocation named one (see: q conventions/documentation.md, Taxonomy).
-- **A plan change** → the lifecycle's rules — status flips and marked amendments; authoring new plans belongs to `/q:create-plan`, and amendments during an implementation run to `/q:implement-plan`, not here (see: q conventions/plans.md, Lifecycle).
+- **A fact, instruction, or overview change for the product's readers** → the surface the taxonomy assigns it — a guide, the README, or the briefing, whether or not the invocation named one (see: @lab43/q conventions/documentation.md, Taxonomy).
+- **A spec change — a commitment the product makes, which the invocation names: the user's instruction, or a plan's scheduled step** → the spec path, Step 4. A bare sweep never takes this route: report a swept lesson that reads as a product commitment to the user as a spec candidate, and leave it unwritten (source: @lab43/q conventions/documentation.md, Taxonomy).
+- **A plan change** → the lifecycle's rules — status flips and marked amendments; authoring new plans belongs to `/q:create-plan`, and amendments during an implementation run to `/q:implement-plan`, not here (see: @lab43/q conventions/plans.md, Lifecycle).
 - **A change that belongs in a q skill's instructions** → not a doc change; flag it as an upstream candidate — suggest `/q:upstream`. (A change that belongs in an extension's doc stays on the conventions path — Step 3 records it locally as a deviation first.)
 
 ## Step 2: Read the policy
 
-Read 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, and the project's `docs/conventions/documentation.md` — its recorded rulings and deviations win on conflict.
+Read 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, and the project's `docs/conventions/documentation.md` — its recorded rulings and deviations win on conflict.
 
 ## Step 3: The conventions path — qualify the lesson
 
-Read q's principles (see: q conventions/principles.md), plus any installed extension's doc whose topic governs cross-cutting principles, and the project's `docs/conventions/principles.md`. Then hold the lesson to four gates, in order:
+Read q's principles (see: @lab43/q conventions/principles.md), plus any installed extension's doc whose topic governs cross-cutting principles, and the project's `docs/conventions/principles.md`. Then hold the lesson to four gates, in order:
 
 1. **Is it a rule?** Would it change what a future reader writes or flags? Narrative, descriptions of current behavior, and code-readable facts don't qualify — the code carries those. What qualifies is the binding form: the constraint, the do/don't, the decision with rationale. No rule in it ends the path — report that, don't force an entry.
-2. **Where will its next reader be standing?** A fact needed only when touching one specific site becomes a comment there, in code or in a doc's markup, not a conventions entry. A lesson the next person would re-trip writing similar code elsewhere is cross-cutting even with one current instance — that one goes in the doc. Genuinely uncertain: comment now, promote on second occurrence (source: q conventions/principles.md, Colocate knowledge with its next reader).
-3. **Is prose the right rung?** A rule that a component or lint could hold shouldn't settle for documentation (source: q conventions/principles.md, Prefer the strongest enforcement rung). If a stronger rung exists, propose *that* as the fix (or schedule it), with the rationale colocated in the component or lint rule.
-4. **Which tier?** A lesson about the project's code belongs in its `docs/conventions/`. A lesson that seems to belong elsewhere — about the q workflow itself, or a topic an installed extension owns — is recorded in the project's `docs/conventions/` too, as a marked project deviation where it contradicts that rule, and flagged to the user in the session as an upstream candidate — suggest `/q:upstream`. Workflow-general versus project-specific is hard to call from inside one project: record and flag, don't withhold (source: q conventions/documentation.md, Three tiers of conventions). The exception is an extension this repo authors: a lesson its docs own is edited directly into them — the author changes the rule; overrides and upstreaming are the consumer's mechanism (source: q conventions/extensions.md).
+2. **Where will its next reader be standing?** A fact needed only when touching one specific site becomes a comment there, in code or in a doc's markup, not a conventions entry. A lesson the next person would re-trip writing similar code elsewhere is cross-cutting even with one current instance — that one goes in the doc. Genuinely uncertain: comment now, promote on second occurrence (source: @lab43/q conventions/principles.md, Colocate knowledge with its next reader). When the lesson is that this one site sits outside a rule, the comment carries an exception marker naming that rule (see: @lab43/q conventions/documentation.md, Markers).
+3. **Is prose the right rung?** A rule that a component or lint could hold shouldn't settle for documentation (source: @lab43/q conventions/principles.md, Prefer the strongest enforcement rung). If a stronger rung exists, propose *that* as the fix (or schedule it), with the rationale colocated in the component or lint rule.
+4. **Which tier?** A lesson about the project's code belongs in its `docs/conventions/`. A lesson that seems to belong elsewhere — about the q workflow itself, or a topic an installed extension owns — is recorded in the project's `docs/conventions/` too, as a marked project deviation where it contradicts that rule, and flagged to the user in the session as an upstream candidate — suggest `/q:upstream`. Workflow-general versus project-specific is hard to call from inside one project: record and flag, don't withhold (source: @lab43/q conventions/conventions.md, Three tiers of conventions). One case differs: a repo that publishes rules of its own. Decide whether the lesson belongs in what it publishes or in its own `docs/conventions/` (see: @lab43/q conventions/extensions.md, Which rules ship).
 
-A lesson through the gates gets a home: the topically-owning doc — grep the surface first, q's conventions and every installed extension's included: a project rule may already exist to refine, and a rule q or an extension already carries is already law — record it only as a marked deviation if the lesson disagrees, never as a copy. A new doc only when no existing topic owns the rule, arriving with its intro and briefing-index line in the same change (source: q conventions/documentation.md, Conventions docs).
+A lesson through the gates gets a home: the topically-owning doc — grep the surface first, q's conventions and every installed extension's included: a project rule may already exist to refine, and a rule q or an extension already carries is already law — record it only as a marked deviation if the lesson disagrees, never as a copy. A new doc is created only when no existing topic owns the rule (source: @lab43/q conventions/conventions.md, Conventions docs). It arrives with its intro and its index line in the same change (source: @lab43/q conventions/documentation.md, Taxonomy).
 
-## Step 4: Confirm the scope
+## Step 4: The spec path — hold each statement
 
-Confirm what the session derived, in a conversational stretch — candidates a sweep surfaced, a genuinely contestable home or treatment: state each change, its home, and its treatment — what gets rewritten, deleted, or added. A change the invocation spelled out — the user's prompt or a calling skill's — is already agreed and skips this step: state its classification's small calls rather than asking.
+Read the specs rules (see: @lab43/q conventions/specs.md). Hold each statement to the admission test: it belongs when a future change breaking it should stop for the user's ruling, and it is cut otherwise (source: @lab43/q conventions/specs.md, What a spec holds). Put each statement in the spec doc whose feature owns it, or create that doc, arriving with its intro and its index line in the same change (source: @lab43/q conventions/documentation.md, Taxonomy). When the change amends a section, visit every site marked with it (source: @lab43/q conventions/specs.md, Enforcement). A stronger rung is still preferred for the commitment itself: propose the test, the validation, or the constraint that would enforce it, each carrying the spec marker. The statement stays in the spec regardless, because a spec's prose survives a test holding it (source: @lab43/q conventions/specs.md, Enforcement).
+
+## Step 5: Confirm the scope
+
+Confirm what the session derived, in conversational mode (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Collaboration modes) — candidates a sweep surfaced, a genuinely contestable home or treatment: state each change, its home, and its treatment — what gets rewritten, deleted, or added. A change the invocation spelled out — the user's prompt or a calling skill's — is already agreed and skips this step: state its classification's small calls rather than asking.
 
 In a run invoked directly by the user, ask which review mode — local or ship — the delivery runs under (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Review modes), even when a spelled-out change skips the rest of this step.
 
-## Step 5: Apply per policy
+## Step 6: Apply per policy
 
-Act autonomously once the scope is agreed. In a run that delivers here (Steps 6–7), first pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch). Then edit the docs directly rather than proposing wording and waiting for approval — the user reviews the applied changes as a git diff. Draft to each surface's own taxonomy rules (see: q conventions/documentation.md, Taxonomy) and the writing rules (see: q conventions/writing.md). Keep the briefing's docs index in sync if membership or a gloss changed, to the shape the briefing template defines (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`). In a delivering run's ship mode, commit.
+Act autonomously once the scope is agreed. In a run that delivers here (Steps 7–8), first pick the delivery branch (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, The delivery branch). Then edit the docs directly rather than proposing wording and waiting for approval — the user reviews the applied changes as a git diff. Draft to each surface's own taxonomy rules (see: @lab43/q conventions/documentation.md, Taxonomy) and the writing rules (see: @lab43/q conventions/writing.md). Keep the briefing's docs index in sync if membership or a gloss changed, to the shape the briefing template defines (see: `${CLAUDE_PLUGIN_ROOT}/references/agent-briefing.md`). In a delivering run's ship mode, commit.
 
-## Step 6: Adversarial review
+## Step 7: Adversarial review
 
-Changes made for a calling skill end at Step 5: they join the calling run's change, which validates and delivers them. The exception is a caller that asks for full delivery: those changes continue here like a direct run's, under the review mode the calling run settled. Validate the applied changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
+Changes made for a calling skill end at Step 6: they join the calling run's change, which validates and delivers them. The exception is a caller that asks for full delivery: those changes continue here like a direct run's, under the review mode the calling run settled. Validate the applied changes (see: ${CLAUDE_PLUGIN_ROOT}/references/run-contract.md, Validation) with the **correctness** and **conventions** lenses.
 
-## Step 7: Open the PR
+## Step 8: 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).
+1. **The local gate**: run it 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: @lab43/q conventions/pull-requests.md).
 3. Close the session by reporting each change and its home, plus anything swept but not recorded and why.