@lab43/q 0.5.0 → 0.6.0

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
 
@@ -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
 

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

@@ -15,39 +15,44 @@ The change comes from the invocation: named in the prompt, surfaced by the sessi
 
 - **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: @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: @lab43/q conventions/documentation.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.
+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: @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: @lab43/q conventions/principles.md, Colocate knowledge with its next reader).
+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/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: @lab43/q conventions/extensions.md).
+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 is created only when no existing topic owns the rule (source: @lab43/q conventions/documentation.md, Conventions docs). It arrives with its intro and its index line in the same change (source: @lab43/q conventions/documentation.md, Taxonomy).
+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
+
+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: @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.
+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. **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).

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

@@ -5,7 +5,9 @@ description: Turn session friction and the project's recorded deviations into up
 
 # Upstream
 
-Never edits q or an installed extension in place — changes go through a PR to the repo that owns it.
+Never edit q or an installed extension in place. The next install overwrites the change, and no other project ever sees it. Open a PR against the repo that owns the rule instead.
+
+Payload docs don't name q's own repo, its practices or its layout. This skill must: a PR needs a destination, and a change set landing there has to satisfy whatever that repo checks (exception: @lab43/q conventions/extensions.md, Which rules ship).
 
 Follow the run contract — `${CLAUDE_PLUGIN_ROOT}/references/run-contract.md`.
 
@@ -45,7 +47,7 @@ Then, for each destination with shipped candidates:
 
 ## Step 4: Open the PRs
 
-Push each destination branch and open its PR with `gh pr create` against the default branch — the Step 2 agreement covers these PRs. Author the body per the PR-authoring rules (see: @lab43/q conventions/pull-requests.md); the destination's own PR conventions and template win where they speak (source: @lab43/q conventions/pull-requests.md). Carry the provoking context from this session in the body — the PR is the paper trail, so provenance belongs there, never in the conventions prose (source: @lab43/q conventions/documentation.md, Conventions docs). If pushing to a repo is denied, fall back to a fork and say so.
+Push each destination branch and open its PR with `gh pr create` against the default branch — the Step 2 agreement covers these PRs. Author the body per the PR-authoring rules (see: @lab43/q conventions/pull-requests.md); the destination's own PR conventions and template win where they speak (source: @lab43/q conventions/pull-requests.md). Carry the provoking context from this session in the body — the PR is the paper trail, so provenance belongs there, never in the conventions prose (source: @lab43/q conventions/conventions.md, Conventions docs). If pushing to a repo is denied, fall back to a fork and say so.
 
 ## Step 5: Report
 

package/.claude-plugin/marketplace.json

@@ -1,6 +0,0 @@
-{
-  "name": "q",
-  "description": "Serves q's plugin from the installed package.",
-  "owner": { "name": "Lab43" },
-  "plugins": [{ "name": "q", "source": "./" }]
-}

package/agents/adversarial-reviewer.md

@@ -1,62 +0,0 @@
----
-name: adversarial-reviewer
-description: Adversarial reviewer grounded in the project's conventions — tries to refute what it is given, reporting blocking findings vs nits with file:line references and convention citations. Invoke it two ways. Work review — a diff command or files to examine, code or prose, optionally with what the work is meant to deliver (an agreed scope, or the plan plus which of its steps are in scope, which came earlier, and which are deferred) — under the correctness and/or conventions lens. Plan review — a pre-implementation plan doc — under the feasibility and/or rigor lens. For an artifact outside the invoking project — another repo's checkout — the prompt names the conventions surface that grounds the review.
-tools: Read, Grep, Glob, Bash
-model: sonnet
----
-
-You are an adversarial reviewer for this repository. Your job is to try to refute the artifact you are given — assume it has problems and hunt for them. You are read-only: never modify files and never commit. An unexpected change in the working tree is covered by that, including one you believe you caused. Report it with your findings rather than reverting it. Never run a command that changes state outside this repository. Installs, plugin or package registrations, and writes to machine-wide config belong to the run, not to the review — a command that mutates them can break a project this review has nothing to do with.
-
-Baseline checks are not your job: lint, typecheck, and the test suites are verified green before a review is launched. Never run them — a green suite is not a finding, and re-running it adds nothing. Use Bash for git and investigation. If you suspect a specific defect that only executing code can confirm, run the narrowest command that tests that suspicion (a single test file or one name-filtered test), never a package or project suite. The same economy governs facts: where the artifact records how a fact was verified, audit that evidence — is the method sound, the source current? Driving the product (launching apps or simulators, exercising UI) is outside your scope: the run owns the environment. When a suspicion only the running product can settle, report it as a finding that names exactly what to check.
-
-Your prompt supplies an artifact and a lens; the artifact decides the review:
-
-- **Work review** (see: Work review) — the artifact is a diff, given as a git command (`git diff <sha>..HEAD`, `git diff main...HEAD`) and/or a list of changed files — or, with no change in play, the files or directories to examine for what's already wrong. The prompt may also supply what the work is meant to deliver: an agreed scope, or the plan plus which of its steps are in scope, which came earlier, and which are deferred. Lenses: **correctness**, **conventions**, or both.
-- **Plan review** (see: Plan review) — the artifact is a plan doc from `docs/plans/`, alone. Lenses: **feasibility**, **rigor**, or both.
-
-For an artifact outside this project — another repo's checkout — the prompt names a substitute grounding surface. Wherever these instructions read this project's docs — the agent briefing's docs index, the project's conventions — read that surface instead, and treat the artifact's own repo as the codebase to search.
-
-A combined review applies each lens in turn over the same artifact. If the prompt is missing something named here, do not review: return only a line naming what is missing, so the caller can relaunch with a complete prompt.
-
-What to hunt for is defined here, not by the prompt. Anything the prompt carries beyond the artifact, the lens, and what the work is meant to deliver is background. Background may add a place to look. It never narrows the hunt. An account of what changed and why is a claim to refute, not a fact to confirm.
-
-## Work review
-
-The artifact is a diff, or existing files with no change in play — code and prose alike. Your job is to refute it: show what shouldn't merge, or shouldn't stand. Given a diff, run its command and read every changed file in full; given files or directories, read them.
-
-Then hunt through the assigned lens or lenses:
-
-**correctness** — defects by universal engineering judgment, rules or no rules. Read enough surrounding/related code to judge integration points and the local idiom — then hunt: bugs, broken or missed edge cases, error handling, security implications, race conditions, state bugs, dead code, inconsistency with the surrounding code's patterns, missing or hollow test coverage (tests that exist but don't exercise the new behavior). This lens owns **reuse**: for each helper, component, or pattern the code introduces, search the codebase (Grep/Glob) for an existing implementation or established pattern that already covers it, and name the existing code to use instead. In prose, hunt claims the repo contradicts and references that don't resolve. When a plan or an agreed scope accompanies the work, verify the work actually delivers it — implemented, not just started — and treat falling short as a BLOCKING finding. With a plan, judge only the in-scope steps: a step assigned elsewhere and missing from the code is NOT a finding.
-
-**conventions** — defects against this project's recorded law. Read the conventions governing the artifact's territory first, found from the agent briefing's docs index. For prose, the writing rules always apply (see: @lab43/q conventions/writing.md). Then hunt: violations of those docs (cite the specific doc and rule for every finding), and documentation updates the change requires per the documentation policy (README, briefing, conventions docs). Check whether a reviewed file is a living exemplar — grep the project's conventions for its path. Drift in an exemplar outranks every other finding: the docs actively send imitators to it. On a code-versus-rule conflict the rule is presumed right; grep sibling sites for evidence — many sites deviating the same way indicts the rule, one site indicts the code. Report a rule the evidence indicts as a FOLLOW-UP, flagged as a candidate to amend the rule and carrying the evidence — that call is the user's, and the code is not the thing to fix.
-
-## Plan review
-
-The artifact is a plan doc in `docs/plans/` with no implementation yet — there is no diff to run. Your job is to refute the plan before any code is written. Read it in full. Its recorded decisions are constraints, not findings — do not relitigate them, but DO flag when verified evidence contradicts one (as a finding that names the evidence).
-
-Then hunt through the assigned lens or lenses:
-
-**feasibility** — the plan held against reality. Read every file, function, config value, and helper the plan names, plus the code around them — then hunt: claims about current behavior that the code contradicts (wrong file, wrong signature, behavior that doesn't exist); ripple effects the plan misses — search for tests, helpers, CI steps, scripts, and docs that depend on what the plan changes and aren't accounted for; plan steps already done or obsoleted by the current codebase; phases that can't stand alone as commits that build and pass their tests; insufficiency — executing every phase would still not deliver what the Goal section promises; over-engineering — machinery, phases, or generality the Goal does not require, where the codebase offers a simpler path (name it).
-
-**rigor** — the plan held against its standards. Read the plan format (see: @lab43/q conventions/plans.md) and the conventions governing the plan's territory, found from the agent briefing's docs index — then hunt: violations of either, quoting the failing text and citing the rule; and sections that contradict each other. When the plan is right and the cited rule looks stale, report the conflict as a FOLLOW-UP, flagged as a candidate to amend the rule — that call is the user's, and the plan is not the thing to fix.
-
-## Output
-
-Your final message is the review: the three sections below, each a numbered list of one-line findings, a section omitted when it is empty — except BLOCKING, which when empty is replaced by the line `NO BLOCKING FINDINGS`.
-
-```text
-BLOCKING:
-1. <anchor> — the defect, in one line; a finding that rests on a rule names it.
-
-NITS:
-1. ...
-
-FOLLOW-UPS:
-1. ...
-```
-
-- The anchor is the finding's evidence: `file:line` for code; the plan section plus what contradicts it for plans (`plan §Phase 2 vs src/services/email.ts:32`).
-- BLOCKING = what must not proceed. For a work review: wrong to merge, or wrong to leave as it stands — bugs, convention violations, reimplementation of existing code, missing tests for new behavior, unimplemented plan steps. For a plan: implementing it as written would fail, break something it doesn't mention, or violate conventions.
-- NITS = worth noting, fine to skip.
-- FOLLOW-UPS = improvements outside the review's scope, as candidates for future work — the reviewed code's approach beats an existing pattern used elsewhere (name where), duplication or debt discovered nearby. Never BLOCKING, never fixed here.
-- Do not invent findings to appear useful, and do not rubber-stamp — verify claims against the actual code, not its surface appearance. Every finding must name a concrete failure or a specific violated rule.

package/conventions/documentation.md

@@ -1,102 +0,0 @@
-# Documentation Policy
-
-Rules for what belongs in a project's documentation, where it lives, and how it stays accurate. Follow them over any instinct. Every doc this policy governs must stay reviewable by a human: hold every edit to the writing rules (see: @lab43/q conventions/writing.md).
-
-## Three tiers of conventions
-
-- **Framework conventions** — `@lab43/q`'s own `conventions/`, pinned in the project's `package.json`. It carries the rules of the workflow itself, and defines the format an extension follows. Every q project installs it, and none can remove it.
-- **Extension conventions** — the installed extensions (see: @lab43/q conventions/extensions.md), each pinned the same way, so rule improvements reach the project on pin updates. An extension extends q with rules of its own — for a library, a stack, or an organization's shared standards.
-- **Project conventions** — `docs/conventions/` in the consuming repo (a fixed contract path). Everything specific to the project's stack and codebase, plus its `documentation.md` mirror of this policy, where documentation rulings and deviations are recorded. These are living docs: skills grow them as decisions are made and groom them as they rot.
-
-**Precedence: project conventions win over any extension's rule, whichever extension carries it. An extension's rule in turn wins over q's.** A project overrides a rule by recording the deviation in the project conventions doc whose topic owns it (created if needed), so the override sits where a reader applying the rule will look.
-
-- A deviation is written as an ordinary rule: the decision and the rationale, plus an overrides marker (see: Markers) naming the rule it replaces.
-- A deviation is refined in place or deleted as the decision evolves, never appended as a log entry.
-- An override outlived by its target — updated to agree, or gone — is spent and comes out.
-- No other override mechanism exists or is needed — the readers are agents, so a stated deviation is the mechanism.
-
-A refinement that reaches beyond this project — one that would improve a q rule, or an extension's — is a candidate to upstream. Record it as an ordinary rule where it belongs and suggest `/q:upstream` to the user in the session. Never annotate the doc with its upstream candidacy.
-
-Conventions graduate into an extension when their audience grows beyond one project (source: @lab43/q conventions/extensions.md, Graduation).
-
-## Conventions docs
-
-Rules for whoever is about to write or evaluate code — the unit this workflow reads and grows.
-
-**One topic per doc, broadly targeted until proven otherwise**: a doc is about "tests", not about "mocking data in Jest". Narrow docs scatter rules a reader needs together and multiply index lines — a doc that proves narrower than its topic merges into the doc owning the broader one. A doc narrows only by splitting, when a second topic has demonstrably grown inside it.
-
-**Every statement is a rule** — something to follow, a constraint to check, or a decision that binds future code, phrased that way. A sentence that wouldn't change what a reader writes or flags gets cut.
-
-- Descriptions of how the system currently works are not conventions — the code and exemplars carry those.
-- Never facts readable from the code: directory listings, dependency lists, schema enumerations, config values, and model/version names rot the moment code moves, and the code already answers them.
-- Record decisions and rejected alternatives only when they're highly likely to come up again: the alternative is the first thing a reader would reach for, or something deliberately ignored reads as an oversight. Each rejection names the alternative and the reason, nothing more.
-- The rationale stands inline — never cite the repo's issues or PRs as provenance; git history is the paper trail. Links to other projects' trackers as evidence for external-tool claims, and operational pointers to pending work tracked in an issue, remain fine.
-
-**A rule lands in the doc whose topic owns it**, integrated into the section it belongs to (see: @lab43/q conventions/writing.md, Refine rather than append) — grep the surface first; the rule may sharpen a sentence already there. A new doc is created only when no existing topic owns the rule.
-
-## Taxonomy
-
-The policy owns what this taxonomy names — the `docs/` directories below, the README, and the briefing — plus an authored extension's `conventions/` and its description in its authoring repo (source: @lab43/q conventions/extensions.md, Authoring). Anything else under `docs/` — assets, generated output, tooling — is outside the policy: no rule here governs it, and grooming leaves it alone.
-
-File names are kebab-case. Every doc opens with a topic title and an intro stating what the doc is *for* — its purpose, not an inventory of its contents: "Guidance for writing tests", never "Mocking data in Jest, stubbing API calls, and assertion gotchas". A purpose holds as sections change; a contents list rots on the next edit — and purpose is what a reader deciding whether the doc applies actually needs.
-
-The intro is the authoritative description of its doc. The briefing index's line for the doc is drawn from it and restates it, and grooming checks each pair for agreement. A doc the index carries arrives complete in one change: its intro plus its index line.
-
-- **`docs/conventions/`** — the project's conventions docs (see: Conventions docs).
-- **`docs/plans/`** — feature plans across their whole lifecycle — upcoming, in flight, and shipped; format and lifecycle rules live in their own doc (see: @lab43/q conventions/plans.md). Grooming checks status only — surfacing stale `pending` plans for the user's ruling — and treats merged plans' frozen bodies as exempt from accuracy, duplication, and pruning checks.
-- **`docs/guides/`** — guides: instructions for using and operating the product, not for writing its code (deployment walkthroughs, feature guides, operational procedures). Step-by-step detail is fine, and so are inline code-readable specifics — bucket names, URLs, ports — a reader mid-task shouldn't have to dig out of code or config; only repo-referencing facts (script names, env vars, paths, such specifics) are held to accuracy — external-console steps can't be verified from the repo.
-- **`README.md`** — the human overview, answering an arriving reader's questions: what this is, what it does, how to use it.
-  - **Summarizing facts owned elsewhere is its normal mode**, not a violation — the obligation is checkability: a summary that mirrors one identifiable home carries a source marker; free-form overview prose is held accurate against the things it describes by grooming. Inline code-readable specifics — URLs, ports, commands — are fine under the same obligations; the arriving reader shouldn't have to dig for them.
-  - **Interface, not internals**: enumerating the product's interface (commands, skills, entry points) serves the reader and belongs; inventorying the repo's internals (directory layout, file lists) restates what browsing already shows — an internal detail earns mention only when it explains something non-obvious.
-  - **Prose is evergreen**: a sentence describing the current moment ("being migrated to…") rots silently once the moment passes — describe what the product is, and let git history carry the journey.
-- **`CLAUDE.md`** — the always-loaded agent briefing. Rejected: `AGENTS.md`, the cross-tool briefing convention — Claude Code doesn't read it, and q runs in Claude Code. Every line costs context in every session, so only what applies session-wide belongs; information needed for particular kinds of work lives in the relevant convention doc or skill, with at most a one-line pointer here. Two things are required:
-  - **The standing instructions** that make the conventions bind: all three tiers of conventions apply (see: Three tiers of conventions) — check them before writing code, before design decisions and reviews, and before changing docs — and doc changes go through `/q:update-docs`, the README and the briefing itself included.
-  - **The docs index** — one line per doc, restating its intro: every conventions doc, whether q's, an installed extension's, or the project's own, and every guide. Group the lines by where the docs come from. Head each group with what its docs govern, so a session reading the index can tell whose rules are whose. An installed extension's heading is its description (see: @lab43/q conventions/extensions.md, Description). An index line is routing, not content. A guide a session can't act on is still one it should know exists. Skills are never indexed: the session's skill list already carries every skill's name and description.
-
-## Single source of truth
-
-Every fact has exactly one home; every other doc links to it, never restates it. A fact's home is normally implied by the taxonomy and the docs' topics — cross-references carry readers there, and no record of the placement is needed. A placement is recorded in the project's `docs/conventions/documentation.md` only when a reasonable writer or groomer would have put the fact elsewhere — the record exists so grooming doesn't re-litigate it; obvious homes need no entry.
-
-**Restatements**: a doc may restate a rule or fact it operationally depends on — a skill's procedure executing it, the briefing orienting every session with it, a README table presenting it to humans — provided the restatement carries a source marker (see: Markers). The marker is the sanction; an unmarked restatement is ordinary duplication.
-
-Rejected: a standing central registry of all shared facts and their homes. It accumulates entries whose home is obvious from the doc's topic, and it rots like any other enumeration.
-
-## Package doc paths
-
-`q` names the workflow itself — in prose, in the plugin and marketplace a project publishes, and as what a user types to name it. `@lab43/q` is the npm package: use it wherever npm has to recognize the name — a path into the package, an install command, a `package.json` field.
-
-Reference q's docs and an extension's by package name plus path from the package root — `@lab43/q conventions/documentation.md`, `@acme/q-ext-x conventions/retries.md`. The name resolves to the installed copy in `node_modules/`, or to the package's working tree in the repo that authors it. Use the form for every such reference across the documentation surface — markers, the briefing's index lines, doc prose. Use it even for a sibling in the doc's own package: a reference must stay unambiguous when its text is quoted away from its file.
-
-Rejected: abbreviating `@lab43/q` to `q` in the path form. `q` is a different package on the public registry, so the abbreviated reference resolves to whatever `node_modules/q/` holds.
-
-## Markers
-
-Inline cross-references tying a statement to the doc it depends on. They are the documentation surface's own routing, and must suffice for a reader arriving with no skill running — the skills reinforce the routing but can't be assumed. Agents follow them to the related detail; `/q:groom-docs` reads them as recorded intent — a marked restatement or deviation is checked against its target rather than re-flagged as duplication or drift on every run.
-
-All share one grammar — `(verb: target)` or `(verb: target, section)`, the section naming a heading within the target. The target is one of:
-
-- a heading in the current doc (`see: Markers`)
-- a repo file or directory, by path from the repo root — a project doc (`docs/conventions/testing.md`), any other file a fact is read from (`source: config.yml`), or a directory when the text summarizes its files (`source: migrations/`)
-- one of q's docs or an extension's, by its path form (see: Package doc paths)
-
-In docs rendered for humans (README, guides), the marker may sit in an HTML comment — agents and grep read the raw file either way. A doc's comments are otherwise ordinary comments (see: @lab43/q conventions/principles.md, Comments carry constraints, not justification).
-
-Three markers, all ordinary language:
-
-- **`(see: X)`** — cross-reference. Nothing is copied; detail lives at X. No obligations attach.
-- **`(source: X)`** — provenance. This text restates a fact whose authoritative home is X (see: Single source of truth).
-- **`(overrides: X)`** — precedence. This rule deliberately replaces the named rule — a q rule (`overrides: @lab43/q conventions/documentation.md, Code examples in conventions docs`), an extension's rule (`overrides: @acme/q-ext-x conventions/retries.md, Backoff`), or a broader project convention (`overrides: docs/conventions/style.md, Magic numbers`).
-
-## Code examples in conventions docs
-
-Prose rules carry the conventions; code carries itself:
-
-- Each pattern names a **living exemplar** — a real file in the repo — and says which of its lines are load-bearing for the pattern, so an imitator doesn't copy the incidental along with the essential. Exemplar references and these notes are a sanctioned exception to the no-code-readable-facts rule; they exist to point *into* the code.
-- Short shape-only snippets are allowed where a rule is illegible without one. Snippets must not be copy-paste-complete: no import paths, no env-var literals, no full bodies. Anything an agent would paste verbatim must come from the exemplar.
-- Symbols, files, and helpers named in prose must exist — `/q:groom-docs` greps for them.
-
-Rejected: full copy-paste code templates, even compile-checked ones — doc inaccuracies cluster inside template code and code-readable fact restatements, not prose rules, and a stale template actively produces failing code.
-
-## Documentation is the last rung
-
-Documentation is the weakest enforcement rung (source: @lab43/q conventions/principles.md, Prefer the strongest enforcement rung): conventions prose carries only what components and lint can't express — decisions, rationale, rejected alternatives, cross-component gotchas. When a rule graduates into a component or a lint rule, delete its doc prose and move the rationale into the component or lint rule itself, where the reader who would remove it will see it. A doc entry survives graduation only if it meets the rejected-alternatives bar; git history keeps everything else.

package/conventions/extensions.md

@@ -1,52 +0,0 @@
-# Extensions
-
-The format behind the extension conventions tier — rules for authoring and publishing a q extension.
-
-## Identity
-
-A q extension is an npm package whose `package.json` carries the `q-extension` keyword. The keyword is the identity: how tooling tells extensions from a project's other dependencies, and how they are found on the registry. Carrying it means q's machinery:
-
-- discovers the package
-- indexes what it documents
-- reconciles the project against its releases
-
-Nothing without it is an extension — a project's own `docs/conventions/` included.
-
-q is not an extension but what extensions extend: the framework whose rules they add to and whose format they follow (source: @lab43/q conventions/documentation.md, Three tiers of conventions). `@lab43/q` carries no keyword, and is named outright wherever a rule reaches it.
-
-Installing an extension runs no code. The install passes `--ignore-scripts`, and an extension declares no lifecycle scripts. An extension may ship executable files — a plugin's hooks run inside a session — but nothing in it runs as a consequence of being installed.
-
-## Description
-
-`package.json`'s `description` states what the extension's rules govern. A consuming project's briefing heads the extension's group of index lines with it (source: @lab43/q conventions/documentation.md, Taxonomy). Name the territory the rules cover, not the package's shape. One sentence serves the session reading that briefing and the registry's readers alike.
-
-## Layout
-
-The layout is conditional on what the extension carries:
-
-- `conventions/` at the package root when it ships conventions docs, each written to the documentation policy (see: @lab43/q conventions/documentation.md).
-- `.claude-plugin/` when it ships a plugin.
-
-Every extension ships at least one of the two.
-
-An extension with no `conventions/` is watermarked but never indexed, having nothing for a briefing's docs index to carry. Watermarking and indexing are separate for that reason.
-
-Rejected: a `q` metadata key in `package.json` (configurable paths, a per-doc manifest) — every job it would do is already covered by the two directories above, the keyword, and the doc intros, and an enumeration of docs rots against its own contents.
-
-## Pinning
-
-An extension is authored in a project that itself uses q, with `@lab43/q` pinned in the extension's own `package.json` — an exact devDependency that is also the authoring project's live install (in a monorepo, the extension as a workspace), so pin and declaration are one field, never two to drift apart. Shipped in the tarball, the pin declares the q version the extension is written against; the skills hold it against a consuming project's own pin and flag drift. q carries no such pin: its version is the thing declared against.
-
-## Authoring
-
-In its authoring project, an extension's `conventions/` and its description join the documentation surface (see: Description). Both are groomed and reconciled against q's updates like the project's own docs. Moving the q pin asserts that reconciliation happened: the moved pin declares the docs written against the new version (see: Pinning). Don't record a deviation from a convention you ship — edit it. Deviations, overrides, and upstreaming are for rules you consume, not rules you author. In the authoring repo, references to the extension's docs resolve to its working tree (source: @lab43/q conventions/documentation.md, Package doc paths).
-
-An extension's doc may deviate from a q rule the same way a project doc does, stating the deviation with an overrides marker (see: @lab43/q conventions/documentation.md, Markers); the project's own rulings still win over any extension's (source: @lab43/q conventions/documentation.md, Three tiers of conventions).
-
-## Graduation
-
-Conventions graduate into an extension when their audience grows beyond one project — org-wide rules, or rules for code that uses a product. Graduating docs move out of the authoring project's `docs/conventions/` into the extension, never copied into both homes; the authoring project keeps only its project-specific rulings local.
-
-## Publishing
-
-The format says nothing about repositories: publishing an extension from a subdirectory of the authoring repo works as well as a dedicated repo. An extension published from a subdirectory sets `repository.directory` so registry links resolve to it. Use a `files` whitelist limiting the tarball to what the extension ships — npm adds `package.json`, the README, and the license itself.

package/conventions/issue-tracking.md

@@ -1,28 +0,0 @@
-# Issue Tracking
-
-Rules for working a project's issue tracker — the shared source of work items — from any session. Sign every item you file and every comment you post: "— Claude 🤖" (source: @lab43/q conventions/writing.md, Sign what you post).
-
-## Respect existing claims
-
-An item assigned to someone else, marked in progress or blocked, or with a fix already in review is not available to pick up. A claim that looks stale — long untouched, its PR closed unmerged — may be wrong: surface it to the user rather than working the item or silently passing it by.
-
-## Claim what you work
-
-Picking up a tracker item means assigning it to the user and moving it to the tracker's working status — on the user's agreement, asked once per session and carried forward.
-
-## Ask before filing
-
-Filing a new tracker item — the follow-up work a session surfaces — happens on the user's agreement, given per item rather than once per session. Ask the session's candidates together, in one batch. Each candidate is one piece of work. A bundled item gets half fixed and stays open. Write each agreed item to the authoring rules (see: Write for whoever picks it up).
-
-## Write for whoever picks it up
-
-An item is read by a session holding none of the context that produced it. Hold its prose to the writing rules (see: @lab43/q conventions/writing.md).
-
-- Name the work the item asks for in the title. A reader deciding what to open sees the title, not the body.
-- Back the item with what can be checked: the error text, the reproduction, the `file:line`.
-- Say what would be true once the item is closed. A closing condition left to guess gets the item closed wrong, or not at all.
-- Leave the fix to the run that takes the item. Where the approach was already decided, state it and say what decided it.
-
-## Work links back
-
-The PR addressing an item links to it from the PR body; when the tracker doesn't pick that link up automatically, comment the PR's link on the item — on the user's agreement, asked once per session and carried forward.