@lab43/q 0.4.0 → 0.5.0

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "q",
   "displayName": "q",
   "description": "An agentic coding workflow framework: skills for planning, implementing, verifying, and grooming, grounded in per-project conventions docs.",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "author": { "name": "Cameron Spencer", "email": "cameron@lab43.com" },
   "license": "MIT"
 }

package/README.md

@@ -10,7 +10,7 @@ Named for Q, the quartermaster who equips James Bond with his gadgets — q outf
 
 ## Adding q to a project
 
-```
+```sh
 npm install --save-dev --save-exact --ignore-scripts @lab43/q
 claude plugin marketplace add --scope local ./node_modules/@lab43/q
 claude plugin install q@q --scope project
@@ -30,7 +30,7 @@ npm delivers q's bytes before Claude Code is involved, so installing q doesn't r
 
 Install the project's dependencies, substituting your package manager where the project isn't on npm:
 
-```
+```sh
 npm install
 ```
 
@@ -45,6 +45,7 @@ That is the whole of it — q arrives as a pinned dependency, and the project's
   Do not switch a name in this column to <code>. GitHub gives <code> its own white-space: break-spaces. A value set on the element replaces the one inherited from the cell.
   Do not replace nowrap with a style attribute. GitHub strips style.
 -->
+<!-- markdownlint-disable MD033 -->
 <table>
   <tr>
     <th>Type</th>
@@ -66,15 +67,15 @@ That is the whole of it — q arrives as a pinned dependency, and the project's
   </tr>
   <tr>
     <td nowrap><samp>/q:uninstall-extension</samp></td>
-    <td>Remove an extension from a project, or reconcile a removal made out of band — the package, its briefing index lines, its watermark, and your ruling on each doc that references it.</td>
+    <td>Remove an extension from a project, or reconcile a removal made out of band — the package, its group in the briefing's docs index, its watermark, and your ruling on each doc that references it.</td>
   </tr>
   <tr>
     <th rowspan="8" scope="rowgroup">Workflow</th>
     <td nowrap><samp>/q:triage</samp></td>
-    <td>Choose what to work on next from a set of items — a Jira board, GitHub issues, a Notion doc — and hand each agreed pick to <code>/q:tackle</code>.</td>
+    <td>Choose what to work on next from a set of items — a Jira board, GitHub issues, a Notion doc — and hand each agreed pick to <code>/q:implement</code>.</td>
   </tr>
   <tr>
-    <td nowrap><samp>/q:tackle</samp></td>
+    <td nowrap><samp>/q:implement</samp></td>
     <td>Take on unplanned work — ground it in the code, then fix it in a single adversarially reviewed PR, escalate to planning, or show with evidence that nothing needs doing.</td>
   </tr>
   <tr>
@@ -115,17 +116,20 @@ That is the whole of it — q arrives as a pinned dependency, and the project's
     <td>Turn session friction and recorded deviations into PRs against the repos that own the rules — q's own, or an extension's.</td>
   </tr>
 </table>
+<!-- markdownlint-enable MD033 -->
 
 ## How it works
 
 <!-- source: docs/workflow-chart/chart.html -->
 <!-- regenerated by docs/workflow-chart/screenshot.py -->
+<!-- markdownlint-disable MD033 -->
 <a href="docs/workflow-chart/light.png">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="docs/workflow-chart/dark.png">
-    <img alt="The q workflow: work flows from triage and tackle through plan, implement, and human review to merge, with adversarial review gating plan and implement. Conventions documentation — project docs over the installed extensions over q — grounds each step; gotchas and corrections flow back down as rules on project docs, and rules that belong upstream leave as PRs." src="docs/workflow-chart/light.png">
+    <img alt="The q workflow: work flows from triage and start through plan, implement, and human review to merge, with adversarial review gating plan and implement. Conventions documentation — project docs over the installed extensions over q — grounds each step; gotchas and corrections flow back down as rules on project docs, and rules that belong upstream leave as PRs." src="docs/workflow-chart/light.png">
   </picture>
 </a>
+<!-- markdownlint-enable MD033 -->
 
 q's effect on your repo comes from context routing and documentation discipline — everything it produces lives in plain text files in your repo, and it works in one loop:
 
@@ -155,8 +159,8 @@ Every session start validates that installed, pinned, and watermarked versions s
 
 ## Markers
 
-<!-- source: q conventions/documentation.md, Markers -->
-<!-- source: q conventions/documentation.md, Single source of truth -->
+<!-- source: @lab43/q conventions/documentation.md, Markers -->
+<!-- source: @lab43/q conventions/documentation.md, Single source of truth -->
 
 q's documentation keeps every fact in exactly one authoritative home, but text still needs to point at, copy, or disagree with facts that live elsewhere. Markers declare which of those relationships is in play — making them visible to readers and checkable by grep, with no central list to maintain:
 
@@ -164,7 +168,7 @@ q's documentation keeps every fact in exactly one authoritative home, but text s
 | --- | --- |
 | `(see: X)` | Plain cross-reference — nothing copied, the detail lives at X. |
 | `(source: X)` | This text is a copy and X is the authority — `/q:groom-docs` checks that the copy still agrees with X. |
-| `(overrides: X)` | This rule deliberately replaces the named one — a q rule (`overrides: 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`). `/q:groom-docs` respects it, and `/q:upstream` picks up overrides worth carrying to the rule's owner. |
+| `(overrides: X)` | This rule deliberately replaces the named one — 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`). `/q:groom-docs` respects it, and `/q:upstream` picks up overrides worth carrying to the rule's owner. |
 
 ## Developing q
 
@@ -179,6 +183,7 @@ To work on q:
 
 - `claude` in your checkout auto-loads your working copy of the plugin (the repo declares itself as the `q` marketplace in `.claude/settings.json`); from any other project, `claude --plugin-dir <path to your checkout>` loads it. SKILL.md edits apply immediately; `/reload-plugins` picks up hook and agent changes mid-session.
 - When the `q:` skills don't load in your checkout, the CLI's registry holds that directory under a name other than `q`, so `q@q` resolves to nothing. `claude plugin marketplace add` matches the registry by path, so re-adding `./` just reports the stale entry. Remove it with `claude plugin marketplace remove <name>`, then add `./` again.
-- `claude plugin validate --strict .` checks the marketplace manifest; `claude plugin validate --strict skills` and `claude plugin validate --strict agents` check the components; `npm run check-versions` checks that the two manifests carrying a version agree.
-- Releasing is separate from merging, and PRs never touch a `version`; the steps live in `docs/guides/releasing.md`.
-- When another session is already working your checkout, take a worktree rather than sharing it. A worktree needs no setup here: the repo has no dependencies to install. `.claude/settings.json` is tracked, so the plugin loads there.
+- `npm run check` runs every check the repo has, `npm test` among them. `package.json` names them; this line deliberately doesn't, because a list here goes stale the next time one is added. CI runs it on every pull request and on pushes to `main`.
+- `npm install` installs the pre-commit hook that runs `npm run check`. A tree you have not installed commits without checking anything.
+- Releasing is separate from merging, and PRs never touch a `version`. The steps live in `docs/guides/releasing.md`.
+- When another session is already working your checkout, take a worktree rather than sharing it. Run `npm install` in it. `.claude/settings.json` is tracked, so the plugin loads there.

package/agents/adversarial-reviewer.md

@@ -28,7 +28,7 @@ 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: 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.
+**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
 
@@ -38,13 +38,13 @@ 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: 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.
+**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.
 

package/conventions/documentation.md

@@ -1,11 +1,11 @@
 # 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: q conventions/writing.md).
+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: 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.
+- **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.
@@ -17,7 +17,7 @@ Rules for what belongs in a project's documentation, where it lives, and how it
 
 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: q conventions/extensions.md, Graduation).
+Conventions graduate into an extension when their audience grows beyond one project (source: @lab43/q conventions/extensions.md, Graduation).
 
 ## Conventions docs
 
@@ -32,18 +32,18 @@ Rules for whoever is about to write or evaluate code — the unit this workflow
 - 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: 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, and it arrives complete in one change: its intro (see: Taxonomy) plus its line in the agent briefing's index.
+**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/` in its authoring repo (source: 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.
+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.
+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: 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/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.
@@ -51,7 +51,7 @@ The intro is the authoritative description of its doc. The briefing index's line
   - **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. 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.
+  - **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
 
@@ -63,11 +63,15 @@ Rejected: a standing central registry of all shared facts and their homes. It ac
 
 ## Package doc paths
 
-Reference q's docs and an extension's by package name plus path from the package root — `@acme/q-ext-x conventions/retries.md`. `q` is the alias for `@lab43/q`: `q conventions/documentation.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.
+`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 doc 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.
+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:
 
@@ -75,13 +79,13 @@ All share one grammar — `(verb: target)` or `(verb: target, section)`, the sec
 - 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: q conventions/principles.md, Comments carry constraints, not justification).
+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: 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`).
+- **`(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
 
@@ -95,5 +99,4 @@ Rejected: full copy-paste code templates, even compile-checked ones — doc inac
 
 ## Documentation is the last rung
 
-Documentation is the weakest enforcement rung (source: 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.
-
+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

@@ -12,15 +12,19 @@ A q extension is an npm package whose `package.json` carries the `q-extension` k
 
 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: q conventions/documentation.md, Three tiers of conventions). `@lab43/q` carries no keyword, and is named outright wherever a rule reaches it.
+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: q conventions/documentation.md).
+- `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.
@@ -35,9 +39,9 @@ An extension is authored in a project that itself uses q, with `@lab43/q` pinned
 
 ## Authoring
 
-In its authoring project, an extension's `conventions/` joins the documentation surface — 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: q conventions/documentation.md, Package doc paths).
+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: q conventions/documentation.md, Markers); the project's own rulings still win over any extension's (source: q conventions/documentation.md, Three tiers of conventions).
+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
 

package/conventions/issue-tracking.md

@@ -1,6 +1,6 @@
 # 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: q conventions/writing.md, Sign what you post).
+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
 
@@ -12,7 +12,16 @@ Picking up a tracker item means assigning it to the user and moving it to the tr
 
 ## 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.
+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
 

package/conventions/plans.md

@@ -55,6 +55,6 @@ Deviations discovered while the implementation runs are recorded as amendments
 - *(deviation: …)* — reality diverged from the text: a step done differently, a decision or given that shifted mid-run. States what happened instead, and what forced it.
 - *(result: …)* — the outcome of a step the plan could only pose as a question — a check, a measurement, a re-verified fact.
 
-After merge, a plan's body is frozen history: it describes the world at planning time, and readers treat plan age (git history) as the recency signal. How grooming treats plans is the documentation policy's rule (see: q conventions/documentation.md, Taxonomy).
+After merge, a plan's body is frozen history: it describes the world at planning time, and readers treat plan age (git history) as the recency signal. How grooming treats plans is the documentation policy's rule (see: @lab43/q conventions/documentation.md, Taxonomy).
 
 Rejected: an `archive/` directory for terminal plans (moves break links; status is machine-readable in place) and a `superseded` status (chain-tracking costs more than it returns; a plan implemented then reversed stays `completed` — both plans are accurate history).

package/conventions/principles.md

@@ -19,7 +19,7 @@ Two guards:
 - Extract sameness, not resemblance: extract only mechanical duplicates that must change together. Keep code that merely looks similar but diverges in semantics separate (a link styled to mimic a button's visuals is still a link — two components, not one).
 - Don't treat imitating an exemplar as copying: the rule targets verbatim plumbing and scaffolding, not structural similarity to the file a convention doc holds up as the model.
 
-When tooling genuinely forces a copy (an environment that can't import shared modules), mark both copies with a keep-in-sync note so the duplication reads as intent, not oversight. A plain note, not a `(source:)` marker (see: q conventions/documentation.md, Markers): neither copy is the authority it would name.
+When tooling genuinely forces a copy (an environment that can't import shared modules), mark both copies with a keep-in-sync note so the duplication reads as intent, not oversight. A plain note, not a `(source:)` marker (see: @lab43/q conventions/documentation.md, Markers): neither copy is the authority it would name.
 
 ## Colocate knowledge with its next reader
 
@@ -34,7 +34,7 @@ A comment, in code or in a doc's markup, states what its file cannot show: the c
 What fails the test is the author addressing someone other than that reader, in two shapes:
 
 - **Justification** — defending the chosen design, weighing alternatives, narrating how the solution was arrived at. That addresses the reviewer, and it's noise once merged; git history and the PR carry it.
-- **Pointers to unmaintained artifacts** — plan docs (frozen after merge) (source: q conventions/plans.md, Lifecycle), tickets, PRs, external trackers. State the constraint in the comment itself, or point at the convention doc that owns it. The one sanctioned link: a ticket tracking work that will change this code when it lands — a workaround awaiting an upstream fix, a shim awaiting a migration. The dependency is stated inline so the comment stands alone; the link exists only to check the pending work's status.
+- **Pointers to unmaintained artifacts** — plan docs (frozen after merge) (source: @lab43/q conventions/plans.md, Lifecycle), tickets, PRs, external trackers. State the constraint in the comment itself, or point at the convention doc that owns it. The one sanctioned link: a ticket tracking work that will change this code when it lands — a workaround awaiting an upstream fix, a shim awaiting a migration. The dependency is stated inline so the comment stands alone; the link exists only to check the pending work's status.
 
 ## Prefer the strongest enforcement rung
 

package/conventions/pull-requests.md

@@ -1,6 +1,6 @@
 # Pull Requests
 
-Rules for authoring a pull request. Hold its prose to the writing rules (see: q conventions/writing.md). Sign the body and every comment or reply on it: "— Claude 🤖" (source: q conventions/writing.md, Sign what you post). A project's own PR conventions win over this doc (source: q conventions/documentation.md, Three tiers of conventions), and so does a PR template in the repo.
+Rules for authoring a pull request. Hold its prose to the writing rules (see: @lab43/q conventions/writing.md). Sign the body and every comment or reply on it: "— Claude 🤖" (source: @lab43/q conventions/writing.md, Sign what you post). A project's own PR conventions win over this doc (source: @lab43/q conventions/documentation.md, Three tiers of conventions), and so does a PR template in the repo.
 
 ## Title
 
@@ -19,7 +19,7 @@ Describe the change, never the run that produced it. Review rounds, rulings, and
 
 Compose the body from these sections, in order. Most PRs need only Summary and Testing. Add another section only when it has something the reviewer needs.
 
-- **Summary** — the rubric the reviewer checks the diff against: what is true after merge that wasn't before, and why. State outcomes, not edits: one claim per deliverable, each something the reader can now rely on. The diff is the catalog of changes. When the diff is large, say where the substance lives and which files are mechanical fallout. The Summary links the work's source: the tracker item when one exists (source: q conventions/issue-tracking.md, Work links back), and the plan doc when the PR implements a plan. Where the tracker closes an item from the link's wording, word it to close only in the PR whose merge finishes the item — the last layer of a stack, the only PR otherwise. Every other layer links the item without closing it, or the first merge closes work the rest of the stack hasn't delivered.
+- **Summary** — the rubric the reviewer checks the diff against: what is true after merge that wasn't before, and why. State outcomes, not edits: one claim per deliverable, each something the reader can now rely on. The diff is the catalog of changes. When the diff is large, say where the substance lives and which files are mechanical fallout. The Summary links the work's source: the tracker item when one exists (source: @lab43/q conventions/issue-tracking.md, Work links back), and the plan doc when the PR implements a plan. Where the tracker closes an item from the link's wording, word it to close only in the PR whose merge finishes the item — the last layer of a stack, the only PR otherwise. Every other layer links the item without closing it, or the first merge closes work the rest of the stack hasn't delivered.
 - **Callouts** — answers to the questions the diff will raise:
   - Choices that look wrong but are deliberate.
   - Expected changes deliberately not made.

package/conventions/writing.md

@@ -20,6 +20,14 @@ Never regulate prose with a length target — "keep it short", "a few sentences"
 
 Use the words a reader would use to describe the thing. Write "errors now show a message instead of crashing", not "error handling was hardened with graceful degradation". Jargon and category labels make the reader translate before they can follow.
 
+## One name per concept
+
+Once a concept has an established name, use exactly that name everywhere. A synonym reads as a second concept.
+
+Check whether a plainer word would do before a name becomes established (see: Plain words).
+
+Rejected: a glossary — it either duplicates the definitions the home docs already carry, or becomes the central registry of shared facts the documentation policy rejects (source: @lab43/q conventions/documentation.md, Single source of truth).
+
 ## Instructions are commands
 
 Write an instruction — to a human or an agent — as a command: "commit the fixes", never "the fixes are committed" or "the run commits the fixes". Passives and narration hide who acts. Keep declarative sentences for facts a reader relies on.

package/hooks/session-start.mjs

@@ -9,9 +9,11 @@
 //
 // The remedy is uniform — /q:sync re-derives the specifics and routes each
 // finding to its remedy — so every failure emits the same message and
-// the script stops at the first one. The only designed silence is a project
-// that declares no @lab43/q devDependency; anything else missing or
-// unreadable fails like any other invalid state.
+// the script stops at the first one. Two silences are designed. A project
+// that declares no @lab43/q devDependency is not a q project. A devDependency
+// with no watermark entry and no readable manifest cannot be identified as an
+// extension. Fail every other missing or unreadable input like any other
+// invalid state.
 
 import fs from "node:fs";
 import path from "node:path";
@@ -71,7 +73,7 @@ const devDeps =
     ? pkg.devDependencies
     : {};
 
-// Declaring no @lab43/q devDependency is the one designed silence. A pin that
+// Declaring no @lab43/q devDependency is a designed silence. A pin that
 // is declared but is not a version string is an invalid state like any other,
 // and fails the way a malformed pin fails for every extension below.
 if (!Object.hasOwn(devDeps, "@lab43/q")) process.exit(0);
@@ -114,8 +116,9 @@ for (const [ext, mark] of Object.entries(recon)) {
 
 // Reverse direction: a devDependency whose installed manifest carries the
 // q-extension keyword but that has no watermark entry was installed by hand
-// and never indexed. A dependency that isn't installed can't be identified as
-// an extension — skip it.
+// and never indexed. The keyword is readable only from the package's own
+// manifest under node_modules. A devDependency whose manifest is absent or
+// unparseable is therefore skipped here rather than reported.
 for (const dep of Object.keys(devDeps)) {
   if (Object.hasOwn(recon, dep)) continue;
   const keywords = parse(

package/package.json

@@ -1,10 +1,16 @@
 {
   "name": "@lab43/q",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "An agentic coding workflow framework: skills for planning, implementing, verifying, and grooming, grounded in per-project conventions docs.",
   "files": ["conventions", "skills", "agents", "hooks", "references", ".claude-plugin"],
   "scripts": {
-    "check-versions": "node scripts/check-versions.mjs"
+    "prepare": "husky",
+    "check": "npm run check-plugin && npm run check-versions && npm run check-markdown && npm run check-frontmatter && npm test",
+    "test": "node --test 'test/*.test.mjs'",
+    "check-plugin": "claude plugin validate --strict . && claude plugin validate --strict skills && claude plugin validate --strict agents",
+    "check-versions": "node scripts/check-versions.mjs",
+    "check-markdown": "markdownlint-cli2",
+    "check-frontmatter": "node scripts/check-frontmatter.mjs"
   },
   "license": "MIT",
   "publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" },
@@ -13,5 +19,13 @@
     "type": "git",
     "url": "git+https://github.com/Lab43/q.git"
   },
-  "homepage": "https://github.com/Lab43/q#readme"
+  "homepage": "https://github.com/Lab43/q#readme",
+  "devDependencies": {
+    "husky": "^9.1.7",
+    "js-yaml": "^5.4.2",
+    "markdownlint-cli2": "^0.23.2"
+  },
+  "overrides": {
+    "smol-toml": "^1.8.0"
+  }
 }

package/references/agent-briefing.md

@@ -2,7 +2,7 @@
 
 The shape of a project's agent briefing — `CLAUDE.md`. `/q:install` scaffolds it, `/q:update-docs` extends it, and `/q:groom-docs` checks it.
 
-The documentation policy decides what the briefing must carry (see: q conventions/documentation.md, Taxonomy). This file gives that a shape.
+The documentation policy decides what the briefing must carry (see: @lab43/q conventions/documentation.md, Taxonomy). This file gives that a shape.
 
 ## The template
 
@@ -15,21 +15,21 @@ If the session's skill list has no `/q:` skills, this machine is missing the q p
 
 When another session is already working this repo, take a worktree rather than sharing the checkout.
 
-Conventions come in three tiers: q's own, the conventions of any installed extensions, and this project's own `docs/conventions/` (source: q conventions/documentation.md, Three tiers of conventions). q and the extensions are pinned in `package.json`. Project rules win over an extension's rule, and an extension's rule wins over q's. Check all three tiers before writing code, before design decisions and reviews, and before changing docs. Doc changes — the README and this briefing itself included — go through `/q:update-docs`.
+Conventions come in three tiers: q's own, the conventions of any installed extensions, and this project's own `docs/conventions/` (source: @lab43/q conventions/documentation.md, Three tiers of conventions). q and the extensions are pinned in `package.json`. Project rules win over an extension's rule, and an extension's rule wins over q's. Check all three tiers before writing code, before design decisions and reviews, and before changing docs. Doc changes — the README and this briefing itself included — go through `/q:update-docs`.
 
-Package doc paths are package name plus path from the package root, resolved under `node_modules/`. `q` abbreviates `@lab43/q`: `q conventions/principles.md` is `node_modules/@lab43/q/conventions/principles.md` (source: q conventions/documentation.md, Package doc paths).
+Package doc paths are package name plus path from the package root, resolved under `node_modules/`: `@lab43/q conventions/principles.md` is `node_modules/@lab43/q/conventions/principles.md` (source: @lab43/q conventions/documentation.md, Package doc paths).
 
-q:
+`@lab43/q` — the rules of the q workflow, governing how a project's work gets planned, decided, documented, and shipped:
 
-- `q conventions/principles.md` — cross-cutting rules for any design decision, plan, or review
-- `q conventions/documentation.md` — what belongs in a project's documentation, where it lives, and how it stays accurate
-- `q conventions/extensions.md` — the extension format: rules for authoring and publishing a q extension
-- `q conventions/plans.md` — format, sequencing, and lifecycle rules for `docs/plans/` documents
-- `q conventions/issue-tracking.md` — rules for working a project's issue tracker from any session
-- `q conventions/pull-requests.md` — rules for authoring a pull request
-- `q conventions/writing.md` — rules for writing prose: docs, plans, PR bodies, anything a human or agent will read
+- `@lab43/q conventions/principles.md` — cross-cutting rules for any design decision, plan, or review
+- `@lab43/q conventions/documentation.md` — what belongs in a project's documentation, where it lives, and how it stays accurate
+- `@lab43/q conventions/extensions.md` — the extension format: rules for authoring and publishing a q extension
+- `@lab43/q conventions/plans.md` — format, sequencing, and lifecycle rules for `docs/plans/` documents
+- `@lab43/q conventions/issue-tracking.md` — rules for working a project's issue tracker from any session
+- `@lab43/q conventions/pull-requests.md` — rules for authoring a pull request
+- `@lab43/q conventions/writing.md` — rules for writing prose: docs, plans, PR bodies, anything a human or agent will read
 
-Installed extensions:
+`<package>` — the extension's description, restated:
 
 - `<package> conventions/<name>.md` — one line per doc, restating its intro
 
@@ -47,8 +47,9 @@ Guides:
 
 - **Write into `CLAUDE.md`**, creating it when it doesn't exist. Leave any `AGENTS.md` the project keeps for other tools alone. Linking the two is the project's call, not q's.
 - **Conform to the structure**: the section heading, the groups in the order they run here, one line per doc. Name each group for what it actually holds.
+- **Head each group with what its docs govern** (source: @lab43/q conventions/documentation.md, Taxonomy). q's group takes the heading spelled out above. Each installed extension gets a group of its own, headed by its package name and the `description` from its `package.json` (see: @lab43/q conventions/extensions.md, Description). Restate that description as written. Shortening an unwieldy one is the extension author's job. An extension shipping no description gets a heading of its name alone.
 - **Treat the prose as a floor, not a script.** Carry at least what the template's prose carries. Leave the project's own wording where it says the same thing. Where a statement isn't true of the project — it authors an extension rather than installing one, or loads the plugin some other way — say what is true instead.
 - **Keep what the project put there** — its own standing instructions, notes, and index entries beyond the required ones. Work missing information into what is already written rather than bolting a sentence alongside it. Rewrite freely to do that, but drop nothing the project said.
 - **Drop a group with no entries.** A fresh project has no extensions and no guides, so those groups arrive with the first one of each. The q group is always there.
-- **Index every doc the policy requires, and nothing stale** — every conventions doc, from q, from an installed extension, or the project's own, and every guide (source: q conventions/documentation.md, Taxonomy). Drop the line for a doc that is gone, including every line of an extension the project no longer installs. The installed extensions are the direct dependencies whose own `package.json` carries the `q-extension` keyword (source: q conventions/extensions.md). An extension shipping no `conventions/` contributes no lines.
-- **Write each line as a path plus a blurb restating the doc's intro** — q's docs and an extension's by package name plus path from the package root (see: q conventions/documentation.md, Package doc paths), the project's own by repo-relative path.
+- **Index every doc the policy requires, and nothing stale** — every conventions doc, from q, from an installed extension, or the project's own, and every guide (source: @lab43/q conventions/documentation.md, Taxonomy). Drop the line for a doc that is gone. An extension the project no longer installs loses every line and its heading with them. The installed extensions are the direct dependencies whose own `package.json` carries the `q-extension` keyword (source: @lab43/q conventions/extensions.md). An extension shipping no `conventions/` contributes no lines, and so no group.
+- **Write each line as a path plus a blurb restating the doc's intro** — q's docs and an extension's by package name plus path from the package root (see: @lab43/q conventions/documentation.md, Package doc paths), the project's own by repo-relative path.

package/references/q-state.md

@@ -28,4 +28,4 @@ The file lives at `.claude/q-state.json`, committed. JSON, one key per line, so
 - `/q:uninstall-extension` drops the extension's entry as part of reconciling its removal.
 - `/q:sync` reads and compares; it never writes. Watermarks certify reconciliation, and sync never reconciles.
 
-An absent file means no record — create it on the first watermark write. The file never ships in an extension: it lives in `.claude/`, outside the `files` whitelist a tarball is built from (source: q conventions/extensions.md).
+An absent file means no record — create it on the first watermark write. The file never ships in an extension: it lives in `.claude/`, outside the `files` whitelist a tarball is built from (source: @lab43/q conventions/extensions.md).

package/references/run-contract.md

@@ -7,13 +7,13 @@ How every q skill run operates, from invocation to finish. Skills reference this
 A run is in one of two modes, depending on whether the user has agreed on what to do yet:
 
 - **Conversational** — nothing agreed yet: converge with the user. Present candidates with trade-offs and a recommendation, decide at the right altitude (see: Decide at the right altitude), and proceed to execution only on the user's go-ahead. The conversation ends in an agreement — a plan doc, a confirmed scope, a converged approach.
-- **Autonomous** — an agreement exists: execute it without asking. Interrupt only when the work would step outside what was agreed — a conflict discovered mid-run, an architectural fork, scope the agreement doesn't cover. Small calls inside the agreement stay autonomous: choose what is most consistent with the agreement, the conventions, and the surrounding code, and flag the calls a reviewer would question where the output gets reviewed: the PR body (see: q conventions/pull-requests.md), or the end-of-run report when the run delivers no PR. When the agreement is exhausted or must be reopened, the run is conversational again.
+- **Autonomous** — an agreement exists: execute it without asking. Interrupt only when the work would step outside what was agreed — a conflict discovered mid-run, an architectural fork, scope the agreement doesn't cover. Small calls inside the agreement stay autonomous: choose what is most consistent with the agreement, the conventions, and the surrounding code, and flag the calls a reviewer would question where the output gets reviewed: the PR body (see: @lab43/q conventions/pull-requests.md), or the end-of-run report when the run delivers no PR. When the agreement is exhausted or must be reopened, the run is conversational again.
 
 ## Review modes
 
 Work that will become commits runs in one of two review modes, settled up front — with the run's opening questions, or at the go-ahead that enters autonomous mode. Once settled it is never revisited mid-run: a ship run reaches its PR without stopping again, so the user comes back to a PR waiting, not a prompt asking whether to open one.
 
-- **Local** — nothing is committed unreviewed: work pauses uncommitted at each review point the running skill defines, and the user's approval is what commits it.
+- **Local** — nothing is committed unreviewed: work pauses uncommitted at each review point the running skill defines, and the user's go-ahead is what commits it.
 - **Ship** — commit as the running skill's own procedure calls for, without asking, and push when the work is done; the user reviews on GitHub, so finish by directing them to the PR(s). The grant ends at the PR: merging is the user's.
 
 ## The delivery branch
@@ -54,6 +54,11 @@ Establish what is true by looking, wherever looking can settle it: `git worktree
 
 Announce what a peer would otherwise have to discover, before you act rather than after — `SendMessage` reaches any peer `ListAgents` lists. Announce the work you take up, and again when you put it down: the tracker item, the plan, or both where a plan names items. You hold it from the moment you pick it, not from the moment a tracker records it — a peer reading only the tracker sees nothing and duplicates your work.
 
+Send nothing else. A message to a peer carries only what keeps two sessions from duplicating or colliding over the same work. Every message surfaces in the user's session, so every message spends the user's attention.
+
+- Never send a peer a suggestion, an opinion, or a finding, unless they need it to avoid a collision.
+- Answer a peer only when the answer changes what they do. No reply is owed.
+
 A worktree is what separates two sessions, and not every case gets one. A peer may arrive after the branch was settled. The user may be working in the tree alongside the run. Sharing a checkout adds three precautions:
 
 - Never switch the branch without announcing first.
@@ -80,7 +85,7 @@ A question about the state of the work — "anything else to decide?", "does any
 
 ## Batch questions
 
-Questions cost attention: collect them into one AskUserQuestion batch (recommended option first) rather than asking one at a time. Put everything an answer depends on inside the question itself. The go-ahead that closes a conversation is different: ask it in plain text, stating the agreed scope, so the user can green-light it or keep refining. In a long collaborative phase, keep the running state visible — decisions settled, questions still open — so the user never has to reconstruct it.
+Questions cost attention: collect them into one AskUserQuestion batch (recommended option first) rather than asking one at a time. Put everything an answer depends on inside the question itself. The go-ahead that closes a conversation is different: ask it in plain text, stating the agreed scope, so the user can grant it or keep refining. In a long collaborative phase, keep the running state visible — decisions settled, questions still open — so the user never has to reconstruct it.
 
 ## Corrections become rules
 
@@ -95,7 +100,7 @@ Route every recording through `/q:update-docs`. It classifies the lesson and hol
 
 Record a correction in the change that prompted it. The diff at each review point carries its own doc updates, so a user approving the work sees everything the run proposes. A correction that arrives during review joins that iteration. Never defer one to the closing report, and never leave the user trusting that a doc update will follow.
 
-A correction lands in whatever change was in flight, which is often a change whose stated scope does not cover it. Say so where the work is reviewed: the PR body's Callouts, or the closing report when the run delivers no PR (see: q conventions/pull-requests.md, Sections). A reviewer who meets an unexplained edit to standing law reads it as scope creep.
+A correction lands in whatever change was in flight, which is often a change whose stated scope does not cover it. Say so where the work is reviewed: the PR body's Callouts, or the closing report when the run delivers no PR (see: @lab43/q conventions/pull-requests.md, Sections). A reviewer who meets an unexplained edit to standing law reads it as scope creep.
 
 Amendments to existing rules are corrections too. Apply them rather than recommending them. A recommendation the user has to find in the output gets scanned past, while a diff hunk is something they can read and push back on. Raise an amendment instead of applying it when it would put existing code out of conformance: that is a migration, and its scope is the user's.
 
@@ -107,6 +112,6 @@ Wait for every reviewer in the round to report before changing anything. Editing
 
 ## The local gate
 
-The procedure local review runs at each review point the skill defines. Stop and ask the user to review the uncommitted work: the diff, its check results, and anything else they should weigh. Expect change requests. Make them and iterate with the user, running no machinery per exchange. A change request whose reason binds future work is a correction (see: Corrections become rules).
+The procedure a run in local mode follows at each review point the skill defines. Stop and ask the user to review the uncommitted work: the diff, its check results, and anything else they should weigh. Expect change requests. Make them and iterate with the user, running no machinery per exchange. A change request whose reason binds future work is a correction (see: Corrections become rules).
 
 At their go-ahead, commit exactly what they reviewed — onto the work's branch, unless the skill names another target. Then run the checks covering what the session changed. When the gate's iteration substantially changed the work, run one `adversarial-reviewer` pass (both lenses) over what changed. Never fold the resulting fixes into the reviewed commit. Leave them uncommitted and return to the gate, where the user reviews them as their own diff. Repeat until a go-ahead leaves nothing uncommitted.