@lab43/q 0.4.0 → 0.6.0

package/q-extension/conventions/extensions.md

@@ -0,0 +1,70 @@
+# Extensions
+
+The format behind the extension conventions tier — rules for authoring and publishing a q extension.
+
+## Identity
+
+A q extension is an npm package that carries the `q-extension` keyword in its `package.json` and ships a `q-extension/` payload directory (see: Layout). Both halves identify it. The keyword is how tooling tells extensions from a project's other dependencies and how they are found on the registry. The payload is what the keyword promises. A package carrying the keyword and shipping nothing is not an extension, and q's machinery passes over it in silence rather than reporting a state no skill can repair.
+
+Look for extensions across a project's direct `dependencies` as well as its `devDependencies`. A package can ship rules and code together — a component library carrying the conventions for using it — and a project that imports such a package holds it as a regular dependency. Meeting both halves means q's machinery:
+
+- discovers the package
+- indexes what it documents
+- registers the plugin it ships, for the project's sessions to load
+- reconciles the project against its releases
+
+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/conventions.md, Three tiers of conventions). `@lab43/q` carries no keyword, and is named outright wherever a rule reaches it.
+
+## Which rules ship
+
+A repo that publishes rules has two homes for a rule it writes, and every rule goes to one of them. A repo that publishes none has one home, `docs/conventions/`, and becoming a publisher is the user's call rather than a session's.
+
+- **The payload** — everything under the package's `q-extension/` directory, which is what binds its consumers (see: Layout).
+- **`docs/conventions/`** — rules for developing the repo itself: its own code, its docs, its repo mechanics. Consumers are never bound by these and never routed to them.
+
+The test is one question: would this change what a session in a consuming repo writes or flags? Yes puts it in the payload. No keeps it local.
+
+A rule can pass that test later, as its audience outgrows one project — org-wide rules, or rules for code that uses a product. Move it then: out of `docs/conventions/` into the payload, never copied into both, its index line crossing from the project's group to the payload's rather than disappearing (see: Authoring).
+
+**Payload is addressed solely to consumers.** Payload docs never name the repo that authors them, its development practices, or its internal layout. Even acknowledging that they might be read from inside that repo muddies them for the audience they speak to. A repo still follows the payload it ships, as a consuming project of its own rules.
+
+Rejected: shipping the payload's conventions at the contract path, `docs/conventions/`, so that one path means conventions everywhere. It conflates what the package ships with the repo's own working rules, so a consumer reading the shipped docs would meet repo-local rulings as law.
+
+## Description
+
+`package.json`'s `q.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.
+
+## Layout
+
+A package's payload is a `q-extension/` directory at its package root. Everything the package ships for q lives inside it. Name `q-extension` in the `files` whitelist: without it the package ships no rules at all, announces itself as an extension anyway, and nothing warns.
+
+What it holds depends on what the extension carries:
+
+- `conventions/` when it ships conventions docs, each written to the documentation policy (see: @lab43/q conventions/documentation.md).
+- `.claude-plugin/` when it ships a plugin, beside whatever that plugin loads — its skills, agents and hooks. `q-extension/` is then the plugin root, and `${CLAUDE_PLUGIN_ROOT}` resolves to it. A consuming project registers the plugin in its own marketplace under the `name` in the plugin's `plugin.json`, so that name is the namespace its sessions type: `/<name>:<skill>`. Choose one no other extension is likely to carry. `q` is taken. What else a plugin may hold is Claude Code's to decide; q fixes only where its root sits.
+
+Every extension ships at least one of the two, which is what identifies a payload (see: Identity). Anything else the package ships for q sits beside them.
+
+An extension shipping no conventions docs 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` naming paths or listing docs — the payload directory and the keyword already answer where everything is, and an enumeration of docs rots against its own contents. The key carries the description and nothing else (see: Description).
+
+## Pinning
+
+Declare `@lab43/q` as a devDependency in the `package.json` at the repo root. That is the only place anything looks for it, whatever else the repo holds — a monorepo declares q at the root, never in a workspace manifest. Keep it a devDependency: q is tooling rather than code a project imports, and a project holding it in `dependencies` goes unvalidated at session start, silently.
+
+Declare each extension in that same root manifest. `dependencies` and `devDependencies` both serve (see: Identity), but no other manifest does — a declaration in a workspace package is one nothing reads. The specifier's form is the project's own choice: q reads versions from the lockfile and `node_modules`, never from the manifest.
+
+A repo that publishes rules already declares q at its root, like any q project, with one requirement of its own: the pin is exact. With the payload at that root, the published package is the repo itself — its `package.json` goes into the tarball, and the pin in it tells consumers which q version the rules were written against. That is a fact only an exact version can state, and the manifest is the author's only channel for it: the lockfile that would resolve a range never ships. The declaration stays inert in consumers — npm installs no dependency's devDependencies — so extensions declaring different q versions never collide; the gap is surfaced at reconciliation and closes through releases.
+
+## Authoring
+
+In its authoring project, an extension's conventions docs and its `q.description` join the documentation surface (see: Description). Both are groomed and reconciled against q's updates like the project's own docs.
+
+They are indexed there too. The authoring repo's briefing gives them a group of their own, shaped like a consumed extension's and headed the same way. The group carries no pin, because a repo does not depend on itself, and no watermark, because a watermark certifies that changed rules have been absorbed and there is nothing to absorb in rules you are editing.
+
+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/conventions.md, Three tiers of conventions).
+
+The plugin the extension ships loads from the working tree too. Add its entry to the project's own marketplace by hand, beside q's: sourced at `./q-extension` and named by the `name` in its `plugin.json`. Enable it in `.claude/settings.json` the way q's entry is enabled there.
+
+All of this assumes the payload sits at the repo's own root. Publish from a sub-package of a larger repo and consumers install it exactly the same way, but the authoring repo gets none of the above: no group in its briefing, and a root declaration that is not the pin the package ships (see: Pinning).

package/q-extension/conventions/issue-tracking.md

@@ -0,0 +1,56 @@
+# 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). A project's own tracker conventions win over this doc (source: @lab43/q conventions/conventions.md, Three tiers of conventions), and so does an issue template the tracker carries.
+
+## 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
+
+Whoever reads an item holds none of the context that produced it. Hold its prose to the writing rules (see: @lab43/q conventions/writing.md).
+
+Four readers act on an item, each deciding something different:
+
+- Whoever ranks the tracker decides whether the work is worth doing, and when.
+- Whoever picks it up decides what to build.
+- Whoever reviews the result decides whether the item is done.
+- Whoever hits the same symptom later decides whether this item is their problem.
+
+Name the work the item asks for in the title. The first reader and the last meet the title alone, and decide from it whether to open the item at all.
+
+### Sections
+
+Compose the body from these sections, in order. Most items need only Goal. Add another only when it has something a reader needs. A body carrying only a Goal needs no headings. Head each section once the body carries more than one.
+
+- **Goal** — what the problem is and why it needs solving. For a bug, the behavior that should hold instead.
+- **Evidence** — what a reader can check: the reproduction, the `file:line`, the rule the behavior contradicts, a link to the error log or dashboard showing it. Paste an error message verbatim as well as linking to it. Whoever hits the same symptom searches for that string. A log link ages out while the item stays open.
+- **Constraints** — what the work must respect: the limits found, the dead ends walked, anything deliberately excluded, an approach already decided (see: State the goal, not the solution).
+- **Callouts** — what the other sections don't hold and whoever picks it up still needs: an approach noticed but not settled, a question the run will have to answer, a link to a related item. Nothing here binds. The run that takes the item rules on all of it. Something nobody would ask about is noise here.
+- **Closed when** — what is true once the item is closed. A closing condition left to guess gets the item closed wrong, or not at all.
+
+Cut the story of the session that surfaced the item. It belongs to none of these sections.
+
+### State the goal, not the solution
+
+Leave the fix to the run that takes the item. A spelled-out fix is the most perishable thing an item can carry. It was written without the current code in front of the author. The run that picks the item up then reads it as a premise instead of deriving its own, and the work starts from an assumption nobody checked.
+
+What was found while writing the item still belongs, stated as a finding rather than a direction (see: Sections). Where the approach was already decided, state it and say what decided it.
+
+### The body is the work as intended
+
+While an item sits unclaimed, keep the body currently true. Fold in whatever changes what the item asks for, so nobody reconstructs the ask by reading the thread in order. What someone reported seeing stays as they wrote it. Folding in changes the ask, never the account. Edit the body on the user's agreement, as with claiming and commenting.
+
+Once the item is claimed (see: Claim what you work), the body freezes. Everything a run learns from then on goes in a comment. Planning is work like any other, so a `/q:create-plan` run is under the freeze too. The body is the rubric the work is checked against, and a run that edits it moves its own goalposts.
+
+## 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.

package/{conventions → q-extension/conventions}/plans.md

@@ -8,7 +8,11 @@ The plan documents the work, not the conversation that produced it: the reader i
 
 - Every sentence either directs work or prevents a wrong decision — cut anything else.
 - State each fact in one section only; other sections reference it, never restate it.
-- A reference may run forward when the acting section comes later. Treat each forward reference as evidence to weigh: the plan may be presenting information in the wrong order.
+- A reference may run forward when the acting section comes later. Treat a forward reference from any section but Context as evidence to weigh: the plan may be presenting information in the wrong order.
+
+## Filename
+
+A plan is `docs/plans/<date>-<plan-name>.md`. The date is the day the plan was created, as `YYYY-MM-DD`, so the directory lists plans in the order they were written. The plan name is the part after the date. It names the plan everywhere else: the branch that implements it, the invocation that runs it.
 
 ## Frontmatter
 
@@ -21,7 +25,7 @@ The plan documents the work, not the conversation that produced it: the reader i
 In order. A section with nothing load-bearing to say for this plan is omitted, never padded — and what already binds every session (the conventions docs, the project's standing tooling) goes without saying:
 
 - **Goal** — what the plan delivers and why it's worth doing.
-- **Context** — the givens the plan inherits rather than chooses: what is true today, with `file:line` references, and any constraints the solution must respect — invariants, compatibility, external realities. A fact the code can't witness states how it was verified — the source read, or the check run — as evidence reviewers audit instead of repeating the verification. A given needs no defending rationale; anything that could have gone another way is a Decision instead.
+- **Context** — the givens the plan inherits rather than chooses: what is true today, with `file:line` references, and any constraints the solution must respect — invariants, compatibility, external realities. The spec sections governing the plan's territory are givens of this kind: cite each by doc and section. Head each group of givens by the tension it holds, never by where the facts were read from. A fact the code can't witness states how it was verified — the source read, or the check run — as evidence reviewers audit instead of repeating the verification. Every given says what it bears on: the consequence it has for this plan, or the Decision or step it constrains. A given needs no defending rationale; anything that could have gone another way is a Decision instead.
 - **Decisions** — numbered, each carrying its rationale from the discussion (the why, not just the what) and its rejected alternatives inline. Rationale is the shortest argument that keeps a decision from being reopened. Rejected alternatives appear only when a reviewer would plausibly re-propose them.
 - **Out of scope** — only work a reader would otherwise assume was included, each item marked deferred or declined, with why. Not a parking lot: adjacent ideas the discussion surfaced but the plan doesn't need stay out entirely.
 - **Phases** — the implementation sequence, per Phases below.
@@ -55,6 +59,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 (see: Filename) 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 → q-extension/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
 
@@ -31,10 +31,12 @@ A private note only the agent reads — a memory file, a stored preference — i
 
 A comment, in code or in a doc's markup, states what its file cannot show: the constraint, the gotcha, the reason a workaround must stay. The test: does the comment change how the next reader edits this site? If not, cut it.
 
+An exception marker's reason passes the test (see: @lab43/q conventions/documentation.md, Markers). It stops the next reader pulling the site back into line with a rule it is excused from. A spec marker passes it too: it tells the next reader the site enforces a commitment, which they would otherwise remove as an ordinary check.
+
 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 → q-extension/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/conventions.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/q-extension/conventions/specs.md

@@ -0,0 +1,31 @@
+# Specs
+
+Rules for `docs/specs/` documents: what a spec holds, how it is written, and how the code is held to it. A spec states what the product commits to. Whether a rule is a spec's or a convention's is the taxonomy's call (see: @lab43/q conventions/documentation.md, Taxonomy).
+
+## Format
+
+One feature or domain per doc. Every spec opens with a title and an intro stating the feature's purpose, which is the territory the doc commits to. Sections group commitments. A section heading is what a marker cites, so it names the commitment's subject and stays stable across edits. Refine a spec in place. Delete the spec of a retired feature.
+
+Specs are the project's own. An extension ships conventions and a plugin, never specs. A library's commitments to the code using it are conventions, and the conventions tier already carries them.
+
+## What a spec holds
+
+Every statement is a commitment: what the product must do or must never do. A statement belongs when a future change breaking it should stop for the user's ruling. Cut what fails that test. Rationale sits inline wherever a decision would otherwise be reopened. What does not belong is a description of how the implementation works today, the screens, fields, and internals the code already shows.
+
+## Enforcement
+
+Mark the code that enforces a commitment: the validation that rejects the bad input, a guard in the UI, a database constraint, the test that proves the rule. Each carries a spec marker naming the spec and the section, in that file's own comment syntax (see: @lab43/q conventions/documentation.md, Markers). Code that merely relies on the commitment carries nothing. Almost everything downstream relies on a commitment in some way, so marking relying code would put markers everywhere and the count would stop meaning anything. When enforcing and relying are hard to tell apart, ask what happens without the code. Without enforcing code the product can break the commitment. Without relying code it cannot.
+
+Rejected: a marker on every site a spec binds. "Bound by" has no edge a reviewer could hold, so the boundary would be litigated on every diff.
+
+The marker makes discovery a grep in both directions. To find the specs a change is bound by, grep the changed files and their tests for markers. To find the code a spec amendment must visit, grep the repo for markers naming the amended section. Every marked site moves with the amendment. That grep is the floor of the search, not the whole of it. Enforcing code that missed its marker, and code that relied on the old commitment, are found only by reading the territory. Mark the enforcing code the reading finds.
+
+Rejected: a spec naming the files or tests that enforce it. That enumeration rots when code moves. The marker carries the same fact in the one place that moves with the code.
+
+A statement stays in the spec after a test holds it. That is a carve-out from the last-rung rule, which deletes prose once a stronger rung holds it (see: @lab43/q conventions/conventions.md, Documentation is the last rung). The spec records the intent behind the test, so the test cannot drift from the commitment without the drift being visible.
+
+## Disagreement
+
+A change that contradicts a spec ships with the amendment or does not ship. It has two exits: revert the change, or amend the spec in the same change. Only the user picks which, because amending a spec is a product decision. A run that finds its agreed work contradicts a spec has stepped outside its agreement, and stops for the user's ruling.
+
+A plan that changes committed behavior edits the spec in the phase that ships the behavior.

package/{conventions → q-extension/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/q-extension/hooks/locked-version.mjs

@@ -0,0 +1,169 @@
+// Resolve the version a project's lockfile records for a direct dependency —
+// the anchor of the session-start hook's version checks.
+//
+// Dependency-free scanning, no YAML library: each reader knows just enough of
+// its format to find a direct dependency's version. Malformed input of any
+// kind — a missing file, unparseable text, an absent package, an unexpected
+// shape — returns undefined rather than throwing; the caller decides what
+// silence means, and the hook importing this must never exit on a stack trace.
+
+import fs from "node:fs";
+import path from "node:path";
+
+const read = (file) => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+
+const unquote = (text) => text.replace(/^["']|["']$/g, "");
+
+// npm: package-lock.json (lockfileVersion 3) names a direct dependency's
+// version at packages["node_modules/<name>"].version.
+const npmVersion = (text, name) => {
+  let lock;
+  try {
+    lock = JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+  const version = lock?.packages?.[`node_modules/${name}`]?.version;
+  return typeof version === "string" ? version : undefined;
+};
+
+// pnpm: pnpm-lock.yaml (lockfileVersion '9.0') records the root importer's
+// direct dependencies as
+//   importers: → .: → dependencies:/devDependencies: → <name>: → version:
+// at two spaces per level. A peer-dependency suffix rides the version, as
+// 7.5.0(peer@1.0.0), and is not part of it.
+const pnpmVersion = (text, name) => {
+  let inImporters = false;
+  let inRoot = false;
+  let inDeps = false;
+  let inName = false;
+  for (const raw of text.split(/\r?\n/)) {
+    const entry = raw.trim();
+    if (!entry) continue;
+    const indent = raw.length - raw.trimStart().length;
+    if (indent === 0) {
+      inImporters = entry === "importers:";
+      inRoot = inDeps = inName = false;
+    } else if (!inImporters) {
+      continue;
+    } else if (indent === 2) {
+      inRoot = entry === ".:";
+      inDeps = inName = false;
+    } else if (!inRoot) {
+      continue;
+    } else if (indent === 4) {
+      inDeps = entry === "dependencies:" || entry === "devDependencies:";
+      inName = false;
+    } else if (!inDeps) {
+      continue;
+    } else if (indent === 6) {
+      inName = unquote(entry.replace(/:$/, "")) === name;
+    } else if (inName && indent === 8) {
+      const match = entry.match(/^version:\s*(.+)$/);
+      if (match) return unquote(match[1]).replace(/\(.*/, "");
+    }
+  }
+  return undefined;
+};
+
+// yarn, both formats: blocks keyed by comma-separated dependency descriptors.
+// A key quoted whole (berry) and keys quoted per descriptor (classic) both
+// come apart the same way: split on the commas, strip the quote characters
+// each piece kept.
+const yarnBlocks = (text) => {
+  const blocks = [];
+  let current = null;
+  for (const line of text.split(/\r?\n/)) {
+    if (/^[^\s#]/.test(line)) {
+      current = {
+        descriptors: line
+          .replace(/:\s*$/, "")
+          .split(",")
+          .map((descriptor) => unquote(descriptor.trim())),
+        lines: [],
+      };
+      blocks.push(current);
+    } else if (line.trim() && current) {
+      current.lines.push(line);
+    }
+  }
+  return blocks;
+};
+
+const blockVersion = (block, form) => {
+  for (const line of block.lines) {
+    if (line.length - line.trimStart().length !== 2) continue;
+    const match = line.trim().match(form);
+    if (match) return unquote(match[1]);
+  }
+  return undefined;
+};
+
+// berry: the block keyed "<root>@workspace:." maps each direct dependency to
+// its specifier, npm:-prefixed; the block keyed "<name>@npm:<specifier>"
+// carries the resolved version.
+const berryVersion = (blocks, name) => {
+  const workspace = blocks.find((block) =>
+    block.descriptors.some((descriptor) => descriptor.endsWith("@workspace:.")),
+  );
+  if (!workspace) return undefined;
+  let specifier;
+  let inDeps = false;
+  for (const line of workspace.lines) {
+    const entry = line.trim();
+    const indent = line.length - line.trimStart().length;
+    if (indent === 2) {
+      inDeps = entry === "dependencies:" || entry === "devDependencies:";
+    } else if (inDeps && indent === 4) {
+      const match = entry.match(/^(.+?):\s+(.+)$/);
+      if (match && unquote(match[1]) === name) specifier = unquote(match[2]);
+    }
+  }
+  if (typeof specifier !== "string") return undefined;
+  const block = blocks.find((b) => b.descriptors.includes(`${name}@${specifier}`));
+  return block && blockVersion(block, /^version:\s*(.+)$/);
+};
+
+// classic: nothing marks a direct dependency, so the block is found by the
+// specifier the project's package.json records — one descriptor among the
+// comma-separated key.
+const classicVersion = (blocks, name, specifier) => {
+  if (typeof specifier !== "string") return undefined;
+  const block = blocks.find((b) => b.descriptors.includes(`${name}@${specifier}`));
+  return block && blockVersion(block, /^version\s+"([^"]*)"$/);
+};
+
+/**
+ * The version the lockfile in `projDir` resolves for the direct dependency
+ * `name`, or undefined when no lockfile is readable or the package can't be
+ * found in it. `specifier` is the dependency's own entry in the project's
+ * package.json — only yarn classic needs it (see above). Dispatches on which
+ * lockfile exists; a file that exists but misleads settles the answer as
+ * undefined rather than falling through to the next format.
+ */
+export const lockedVersion = (projDir, name, specifier) => {
+  try {
+    const npmText = read(path.join(projDir, "package-lock.json"));
+    if (npmText !== null) return npmVersion(npmText, name);
+    const pnpmText = read(path.join(projDir, "pnpm-lock.yaml"));
+    if (pnpmText !== null) return pnpmVersion(pnpmText, name);
+    const yarnText = read(path.join(projDir, "yarn.lock"));
+    if (yarnText !== null) {
+      const blocks = yarnBlocks(yarnText);
+      // __metadata's presence is what tells berry from classic — its value
+      // moves between yarn releases.
+      return blocks.some((block) => block.descriptors.includes("__metadata"))
+        ? berryVersion(blocks, name)
+        : classicVersion(blocks, name, specifier);
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+};

package/q-extension/hooks/session-start.mjs

@@ -0,0 +1,155 @@
+// Validate the project's q setup and, when it doesn't validate, tell the
+// session to run /q:reconcile. Claude Code loads whatever plugin version is on
+// disk, so drift surfaces only if something checks at session start — no
+// other channel runs every session. The checks anchor on the lockfile and on
+// node_modules — the lockfile is exact whatever the manifest's specifier
+// looks like, and npm moves it even when the specifier stays put: the q copy
+// this session loaded vs the lockfile's @lab43/q, each watermarked package's
+// lockfile version vs its watermark vs its installed version, and the
+// reverse direction — an installed extension with no watermark entry
+// (installed by hand, never indexed).
+//
+// The remedy is uniform — /q:reconcile 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. Two silences are designed. A project
+// that declares no @lab43/q devDependency is not a q project. A dependency
+// with no watermark entry that cannot be read as an extension is not one to
+// report. Fail every other missing or unreadable input like any other
+// invalid state.
+
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { lockedVersion } from "./locked-version.mjs";
+
+const proj = process.env.CLAUDE_PROJECT_DIR || ".";
+const root =
+  process.env.CLAUDE_PLUGIN_ROOT ||
+  path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+// Keep in sync with the message in session-start.sh (bash can't import it).
+const MESSAGE =
+  "The q plugin could not validate this project's q setup, so its conventions and tooling may be stale or broken. Run /q:reconcile to repair it.";
+
+const fail = () => {
+  console.log(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "SessionStart",
+        additionalContext: MESSAGE,
+      },
+    }),
+  );
+  process.exit(0);
+};
+const read = (file) => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+};
+const parse = (text) => {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+};
+const installedVersion = (dir) => parse(read(path.join(dir, "package.json")) ?? "")?.version;
+
+// The manifest is read for membership and specifiers, never for versions:
+// @lab43/q in devDependencies is what makes this a q project, and a
+// watermarked package missing from both dependency maps was removed out of
+// band. A missing manifest means not a q project. One that exists but can't
+// be read or parsed fails like any other invalid state.
+let pkgText;
+try {
+  pkgText = fs.readFileSync(path.join(proj, "package.json"), "utf8");
+} catch (e) {
+  if (e.code === "ENOENT" || e.code === "ENOTDIR") process.exit(0);
+  fail();
+}
+const pkg = parse(pkgText);
+if (pkg === undefined) fail();
+
+const depMap = (field) =>
+  pkg && typeof pkg[field] === "object" && pkg[field] !== null ? pkg[field] : {};
+
+const devDeps = depMap("devDependencies");
+// An extension may be a regular dependency: a package shipping rules can also
+// be one the project builds on. q never is — it is tooling, so it stays a
+// devDependency check below.
+const deps = { ...depMap("dependencies"), ...devDeps };
+
+// Declaring no @lab43/q devDependency is a designed silence.
+if (!Object.hasOwn(devDeps, "@lab43/q")) process.exit(0);
+
+// The q this session actually loaded. CLAUDE_PLUGIN_ROOT is the directory it
+// was resolved from, and npm wrote that copy's version, so comparing it
+// against the lockfile also catches a session running some other checkout's q.
+//
+// The version sits one level above that directory. The plugin root is the
+// payload directory, and npm requires package.json at the package root holding
+// it, so the two are never the same directory.
+const loaded = installedVersion(path.join(root, ".."));
+if (typeof loaded !== "string") fail();
+// A missing lockfile, or one that cannot resolve q, reads as undefined and
+// fails this comparison like any other drift.
+const lockedQ = lockedVersion(proj, "@lab43/q", devDeps["@lab43/q"]);
+if (loaded !== lockedQ) fail();
+
+// Watermarks. A project with q declared but no state file is unrecorded drift.
+const stateText = read(path.join(proj, ".claude/q-state.json"));
+if (stateText === null) fail();
+
+const state = parse(stateText);
+if (state === undefined || typeof state !== "object" || state === null) fail();
+
+const recon = state.reconciledAgainst ?? {};
+if (typeof recon !== "object" || recon === null || Array.isArray(recon)) fail();
+// q is the framework rather than an extension, so it is checked by name: a
+// declared project with no entry for it is caught here. The reverse-direction
+// loop below cannot stand in. It identifies extensions by a keyword read from
+// node_modules, which q does not carry and which an uninstalled or stale copy
+// doesn't supply either.
+if (!Object.hasOwn(recon, "@lab43/q")) fail();
+
+for (const [ext, mark] of Object.entries(recon)) {
+  if (typeof mark !== "string") fail();
+  if (!Object.hasOwn(deps, ext)) fail(); // removed, never reconciled
+  if (typeof deps[ext] !== "string") fail(); // not a specifier — invalid state
+  const locked = lockedVersion(proj, ext, deps[ext]);
+  if (locked !== mark) fail(); // moved or unresolvable, never reconciled
+  const inst = installedVersion(path.join(proj, "node_modules", ext));
+  if (typeof inst !== "string") fail();
+  if (inst !== locked) fail(); // node_modules stale against the lockfile
+}
+
+// Reverse direction: a dependency whose installed copy is an extension but
+// that has no watermark entry was installed by hand and never indexed.
+// Identity is both halves — the q-extension keyword, and a payload directory
+// holding conventions/ or .claude-plugin/. Either alone describes a package
+// that is not an extension and has no watermark to be missing.
+//
+// Both are readable only from the package's own copy under node_modules, so a
+// dependency whose manifest is absent or unparseable is skipped rather than
+// reported.
+// throwIfNoEntry covers a missing path, but stat still throws on an
+// unreadable one, and this hook must never exit on a stack trace.
+const isDir = (p) => {
+  try {
+    return fs.statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+};
+const hasPayload = (dir) =>
+  ["conventions", ".claude-plugin"].some((sub) => isDir(path.join(dir, "q-extension", sub)));
+
+for (const dep of Object.keys(deps)) {
+  if (Object.hasOwn(recon, dep)) continue;
+  const installed = path.join(proj, "node_modules", dep);
+  const keywords = parse(read(path.join(installed, "package.json")) ?? "")?.keywords;
+  if (Array.isArray(keywords) && keywords.includes("q-extension") && hasPayload(installed)) fail();
+}

package/{hooks → q-extension/hooks}/session-start.sh

@@ -1,22 +1,23 @@
 #!/bin/bash
 # SessionStart hook entry point. The checks live in session-start.mjs; this
 # wrapper exists so a missing node fails loud with a useful message instead of
-# a cryptic exec error. Node is a given on a project that pins q, which arrives
-# as an npm dependency. The gate below keeps the checks off projects that pin no
-# q at all.
+# a cryptic exec error. Node is a given on a project that declares q, which
+# arrives as an npm dependency. The gate below keeps the checks off projects
+# that declare no q at all.
 
 proj="${CLAUDE_PROJECT_DIR:-.}"
 pkg="$proj/package.json"
 [ -f "$pkg" ] || exit 0
 # Match "@lab43/q" in key position only. As a value it is the name of q's own
-# manifest, which pins nothing. This stays a loose pre-filter: it also matches
+# manifest, which declares no q. This stays a loose pre-filter: it also matches
 # the key under dependencies. session-start.mjs exits silently unless the key
 # is a devDependency.
 grep -qE '"@lab43/q"[[:space:]]*:' "$pkg" 2>/dev/null
 status=$?
-# Exit only on a clean miss: the manifest was read and pins no q. Any other
-# failure means the manifest could not be read, and a project that may well pin
-# q must not be skipped silently — fall through and let the checks report it.
+# Exit only on a clean miss: the manifest was read and declares no q. Any other
+# failure means the manifest could not be read, and a project that may well
+# declare q must not be skipped silently — fall through and let the checks
+# report it.
 [ "$status" -eq 1 ] && exit 0
 
 root="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
@@ -24,7 +25,7 @@ root="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "$0")/.." && pwd)}"
 if ! command -v node >/dev/null; then
   # No node means the checks can't run — same remedy as any other failure.
   # Keep the message in sync with MESSAGE in session-start.mjs.
-  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"The q plugin could not validate this project'"'"'s q setup, so its conventions and tooling may be stale or broken. Run /q:sync to repair it."}}\n'
+  printf '{"hookSpecificOutput":{"hookEventName":"SessionStart","additionalContext":"The q plugin could not validate this project'"'"'s q setup, so its conventions and tooling may be stale or broken. Run /q:reconcile to repair it."}}\n'
   exit 0
 fi