@lab43/q 0.5.0 → 0.6.0

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: @lab43/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

@@ -31,6 +31,8 @@ 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.

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: @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.
+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
 

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

package/{references → q-extension/references}/agent-briefing.md

@@ -11,33 +11,43 @@ The documentation policy decides what the briefing must carry (see: @lab43/q con
 
 This project follows q, an agentic coding workflow. Its rules live in the project's own documentation. Those rules are conventions: binding decisions about how this project's code and docs get written, recorded as they are made. Guides sit alongside them — how to operate the project, rather than rules for writing it.
 
-If the session's skill list has no `/q:` skills, this machine is missing the q plugin — ask the user to install the project's dependencies (`npm install`, or the project's package manager's equivalent), then run `/q:sync`.
+If the session's skill list has no `/q:` skills, this machine is missing the q plugin — ask the user to install the project's dependencies (`npm install`, or the project's package manager's equivalent), then run `/q:reconcile`.
 
 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: @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`.
+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/conventions.md, Three tiers of conventions). q and the extensions are dependencies 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/`: `@lab43/q conventions/principles.md` is `node_modules/@lab43/q/conventions/principles.md` (source: @lab43/q conventions/documentation.md, Package doc paths).
+Package doc paths are package name plus path from the package's `q-extension/` payload directory, resolved under `node_modules/`: `@lab43/q conventions/principles.md` is `node_modules/@lab43/q/q-extension/conventions/principles.md` (source: @lab43/q conventions/documentation.md, Package doc paths).
 
-`@lab43/q` — the rules of the q workflow, governing how a project's work gets planned, decided, documented, and shipped:
+`@lab43/q` — <its `q.description`>
 
 - `@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/conventions.md` — rules for a project's conventions docs: the tiers they come in and which tier wins, what a conventions doc holds, and when a rule leaves prose for a stronger enforcement rung
 - `@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/specs.md` — rules for `docs/specs/` documents: what a spec holds, how it is written, and how the code is held to it
 - `@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
 
-`<package>` — the extension's description, restated:
+`<package>` — <its `q.description`>
 
 - `<package> conventions/<name>.md` — one line per doc, restating its intro
 
+`<this package>` — <its `q.description`>
+
+- `<this package> conventions/<name>.md` — one line per doc, restating its intro
+
 This project's own:
 
 - `docs/conventions/principles.md` — cross-cutting rules, including deviations from q's
 - `docs/conventions/documentation.md` — documentation rulings and deviations
 
+Specs:
+
+- `docs/specs/<name>.md` — one line per spec, restating its intro
+
 Guides:
 
 - `docs/guides/<name>.md` — one line per guide, restating its intro
@@ -47,9 +57,10 @@ 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.
+- **Head each group with what its docs govern** (source: @lab43/q conventions/documentation.md, Taxonomy). A package's group is headed by its name, an em dash, and the `q.description` from its `package.json`, q's own group included (see: @lab43/q conventions/extensions.md, Description). A package shipping no `q.description` gets a heading of its name alone, never its `description` — that field answers the registry's readers.
+- **Give the payload this repo ships its own group.** When the repo's own `q-extension/` holds `conventions/`, it ships those rules and consumes them too: index them in the same form as an installed extension's, read from the working tree rather than `node_modules/` (see: @lab43/q conventions/extensions.md, Authoring).
 - **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: @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.
+- **Drop a group with no entries.** A fresh project has no extensions, no specs, 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, from this repo's own payload, or the project's own, every spec, 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 — `dependencies` and `devDependencies` alike — whose installed copy carries both the `q-extension` keyword and a payload directory (source: @lab43/q conventions/extensions.md, Identity). An extension shipping no conventions docs contributes no lines, and so no group.
+- **Write each line as a path plus a blurb restating the doc's intro** — q's docs, an installed extension's, and this repo's own payload by their path form (see: @lab43/q conventions/documentation.md, Package doc paths), the project's own by repo-relative path.

package/q-extension/references/enforce-declarations.md

@@ -0,0 +1,16 @@
+# Enforce Declarations
+
+The machine-local enforcement procedure: make this machine match what the project declares. Enforce without asking — the declarations are the project's recorded decisions, and this merely applies them.
+
+1. Check that `node` and `npm` resolve. When either is missing, Node.js is not installed — report that fix. Nothing below runs without it.
+2. When `node_modules/` is missing a declared dependency, or holds a version other than the lockfile's, run the project's package-manager install — `npm install`, or the pnpm or yarn equivalent its lockfile indicates. That install is the whole update mechanism: a session reads q from `node_modules/@lab43/q` as it stands, so nothing else has to reach it.
+3. Register the project's marketplace: `claude plugin marketplace add --scope local ./`. The tracked settings only declare the marketplace — sessions resolve it against a machine-global registry the declaration does not update: an interactive session offers the registration behind a trust prompt, and a headless one never registers it at all. The manifest at the project root supplies the name, so nothing has to read or pass one. Skip this step when the project has no `.claude-plugin/marketplace.json`. The add fails outright against a directory holding no manifest. A project without one has not been scaffolded yet. Otherwise run it unconditionally, since the add changes nothing when the registry already points here. Local scope records the registration in the project's own `.claude/settings.local.json`, which does not keep it private.
+
+   Three situations need it:
+
+   - A fresh clone has never registered the marketplace.
+   - A declined trust prompt left it unregistered.
+   - Another checkout of this repo has repointed the project's name at itself. The machine-global registry holds one entry per marketplace name. The add repoints it back, because an entry whose name matches but whose path differs is updated to the new path.
+4. After any change above, run `/reload-plugins`.
+
+Name any tracked file the enforcement rewrote (a lockfile). That change stays in the tree as the user's.

package/q-extension/references/q-state.md

@@ -0,0 +1,31 @@
+# The q State File
+
+Format and writer rules for `.claude/q-state.json`, the consumer-side record of the versions a project was last reconciled against. The skills that read or write the file follow this doc; nothing else edits it.
+
+## What the file is
+
+The file holds machine-written version watermarks — never rules, never doc enumerations. Reconciliation is the work of folding a version change into the project — holding its docs against an extension release's changed rules, or its scaffolded surfaces against a new q version; `/q:reconcile` performs it. A watermark records the version the project was last reconciled against. Drift is the lockfile or the installed version disagreeing with it, however the move arrived — a hand-run npm install, a teammate's merge, a Dependabot bump. The skills and the session-start hook compare its versions against the lockfile and `node_modules`; nothing consults it for how to behave.
+
+## Format
+
+The file lives at `.claude/q-state.json`, committed. JSON, one key per line, so a watermark move reads as a one-line diff:
+
+```json
+{
+  "note": "Machine state written by q's skills. Never edit by hand; /q:reconcile repairs drift.",
+  "reconciledAgainst": {
+    "@lab43/q": "0.3.0"
+  }
+}
+```
+
+`reconciledAgainst` holds one entry for `@lab43/q` and one per installed extension: the version the project was last reconciled against. q's entry has the same shape as the rest, carrying no privilege and no separate field.
+
+## Writer rules
+
+- `/q:install` writes a missing `@lab43/q` entry when it scaffolds, from the version installed, which has no reconciliation debt. It never touches a present entry — a stale one is reconciliation's to move.
+- `/q:reconcile` writes watermarks as reconciliation's record: it moves a package's entry after reconciling its version move, writes an arrival's first entry from the version installed, and drops an entry as part of reconciling a departure. It writes nothing before a reconciliation — watermarks certify one.
+
+An absent file means no record — create it on the first watermark write.
+
+What divides this file from `package.json` is who writes it. The manifest is hand-authored and npm's to rewrite, so it carries what a person sets and a consumer reads — the q declaration, `q.description`. Watermarks are machine-written, so they live here, where the format stays q's to guarantee and nothing edits them by hand.