superdev-cli 0.1.0

package/scripts/validate/style.mjs

@@ -0,0 +1,78 @@
+// Writing style. Superdev never generates or persists em dash characters or
+// emoji, and the rule is enforced at the storage boundary so nothing new can
+// land. This validator covers what is already on disk, and proves a clean tree
+// stays clean.
+//
+// Scope is files this project owns. Vendored material, build output and the
+// append-only ledgers are excluded: rewriting someone else's prose is not this
+// tool's business, and editing a record of what actually happened so it reads
+// as compliant is the dishonest reading of a policy about honesty.
+
+import { join } from "node:path";
+import { ERROR, finding, ownedFiles, readText } from "./common.mjs";
+import { EMOJI_PATTERN } from "../../src/model/screening.mjs";
+
+export const name = "style";
+
+// Written as an escape on purpose. A literal here would make this file fail its
+// own rule and every scan of the repository would report the scanner.
+const EM_DASH = "\u2014";
+// Imported, never restated. This validator once carried its own narrower idea
+// of emoji, so an arrow or a check mark passed the scan and was then refused by
+// the storage boundary: a file could be clean by the tool that judges the tree
+// and unstorable by the code that judges a record. One definition, one verdict.
+const EMOJI = new RegExp(EMOJI_PATTERN, "gu");
+
+// Build output only.
+//
+// The four talks/ ledger paths that used to sit here were left over from the
+// file-based architecture: history lives in the database now, and talks/ is a
+// generated projection whose content came through the storage boundary, so it
+// is already clean and stays in scope as proof.
+//
+// The compiled control centre is different. It is build output that embeds
+// third party code, and a minified Markdown parser carries a packed HTML entity
+// table whose index bytes land in Unicode blocks with emoji presentation. Those
+// are not emoji any reader will ever see; they are offsets in someone else's
+// lookup table. Rewriting a vendored library to satisfy a rule about the prose
+// this project writes would be the tail wagging the dog. The authored text in
+// that bundle is scanned at its source under ui/src, which is where a real
+// breach would be introduced and where it will still fail.
+const EXCLUDED = [/^dist\//, /^src\/service\/assets\/control-center\.html$/];
+
+export const isExcluded = (path) => EXCLUDED.some((pattern) => pattern.test(path));
+
+export function inspect(path, text) {
+  const findings = [];
+  text.split("\n").forEach((line, index) => {
+    let at = line.indexOf(EM_DASH);
+    while (at !== -1) {
+      findings.push(finding("ST-001", ERROR, `${path}:${index + 1}:${at + 1}`,
+        "em dash character; use a comma, colon, semicolon, parentheses or a hyphen"));
+      at = line.indexOf(EM_DASH, at + 1);
+    }
+    EMOJI.lastIndex = 0;
+    let match;
+    while ((match = EMOJI.exec(line)) !== null) {
+      findings.push(finding("ST-002", ERROR, `${path}:${index + 1}:${match.index + 1}`,
+        "emoji, which Superdev never generates"));
+      if (match.index === EMOJI.lastIndex) EMOJI.lastIndex++;
+    }
+  });
+  return findings;
+}
+
+export async function run(root) {
+  const findings = [];
+  const files = ownedFiles(root).filter((path) => !isExcluded(path));
+  if (!files.length) {
+    findings.push(finding("ST-000", ERROR, ".", "no project-owned text files found; there is nothing to scan"));
+    return { name, findings };
+  }
+  for (const path of files) {
+    const text = readText(join(root, path));
+    if (text === null) continue;
+    findings.push(...inspect(path, text));
+  }
+  return { name, findings };
+}

package/scripts/validate/validate-all.mjs

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+// The validation entry point. Runs every deterministic validator against one
+// repository root and reports what each of them found.
+//
+// Exit codes: 0 no findings, 1 findings, 2 usage error.
+//
+// A validator that throws is itself a finding. Swallowing the error would turn
+// a broken validator into a passing run, which is the single most expensive
+// failure mode a gate can have.
+
+import { existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { ERROR, finding } from "./common.mjs";
+
+import * as manifests from "./manifests.mjs";
+import * as skills from "./skills.mjs";
+import * as docsTemplates from "./docs-templates.mjs";
+import * as migrations from "./migrations.mjs";
+import * as markdown from "./markdown.mjs";
+import * as style from "./style.mjs";
+import * as privacy from "./privacy.mjs";
+import * as imports from "./imports.mjs";
+import * as dependencies from "./dependencies.mjs";
+import * as noTests from "./no-tests.mjs";
+import * as footprint from "./footprint.mjs";
+import * as dataModel from "./data-model.mjs";
+import * as recordLinks from "./record-links.mjs";
+import * as skillCommands from "./skill-commands.mjs";
+import * as specification from "./specification.mjs";
+
+/** Declaration order is report order, so two runs read the same way. */
+export const VALIDATORS = [
+  manifests, skills, docsTemplates, migrations, markdown,
+  style, privacy, imports, dependencies, noTests, footprint, dataModel, recordLinks, skillCommands, specification,
+];
+
+const USAGE = `Usage: node validate-all.mjs [--root <path>] [--only <name,...>] [--json] [--out <file>] [--help]
+  --root <path>   repository root to validate (default: current directory)
+  --only <names>  comma separated validator names, run only these
+  --json          machine-readable JSON on stdout
+  --out <file>    also write the JSON report to this exact path
+  --help          show this help
+
+Validators: ${VALIDATORS.map((v) => v.name).join(", ")}
+
+Exit codes: 0 clean, 1 findings, 2 usage error.`;
+
+export async function runAll(root, { only = [] } = {}) {
+  const selected = only.length ? VALIDATORS.filter((v) => only.includes(v.name)) : VALIDATORS;
+  const results = [];
+  for (const validator of selected) {
+    try {
+      const result = await validator.run(root);
+      results.push({ name: result.name ?? validator.name, findings: result.findings ?? [] });
+    } catch (err) {
+      results.push({
+        name: validator.name,
+        findings: [finding("VA-001", ERROR, ".", `the ${validator.name} validator threw: ${String(err?.stack ?? err?.message ?? err)}`)],
+      });
+    }
+  }
+  return results;
+}
+
+/** --out writes exactly the machine-readable report, atomically. */
+function writeReport(outPath, report) {
+  if (!outPath) return;
+  const target = resolve(outPath);
+  const tmp = join(dirname(target), `.tmp-validate-${process.pid}`);
+  mkdirSync(dirname(target), { recursive: true });
+  writeFileSync(tmp, JSON.stringify(report, null, 2) + "\n");
+  renameSync(tmp, target);
+}
+
+function printTable(results) {
+  const rows = results.map((result) => ({
+    name: result.name,
+    errors: result.findings.filter((f) => f.severity === ERROR).length,
+    warnings: result.findings.filter((f) => f.severity !== ERROR).length,
+  }));
+  const width = Math.max(9, ...rows.map((row) => row.name.length));
+  console.log(`${"validator".padEnd(width)}  errors  warnings  result`);
+  console.log(`${"-".repeat(width)}  ------  --------  ------`);
+  for (const row of rows) {
+    const verdict = row.errors || row.warnings ? "findings" : "clean";
+    console.log(
+      `${row.name.padEnd(width)}  ${String(row.errors).padStart(6)}  ${String(row.warnings).padStart(8)}  ${verdict}`,
+    );
+  }
+}
+
+async function main() {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      options: {
+        root: { type: "string", default: "." },
+        only: { type: "string" },
+        json: { type: "boolean", default: false },
+        out: { type: "string" },
+        help: { type: "boolean", default: false },
+      },
+      allowPositionals: true,
+    });
+  } catch (err) {
+    console.error(String(err.message ?? err));
+    console.error(USAGE);
+    process.exit(2);
+  }
+  if (parsed.values.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+
+  const root = resolve(parsed.positionals[0] ?? parsed.values.root);
+  if (!existsSync(root) || !statSync(root).isDirectory() || !existsSync(join(root, "package.json"))) {
+    console.error(`root is not a repository directory: ${parsed.positionals[0] ?? parsed.values.root}`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+
+  const only = (parsed.values.only ?? "").split(",").map((n) => n.trim()).filter(Boolean);
+  const unknown = only.filter((n) => !VALIDATORS.some((v) => v.name === n));
+  if (unknown.length) {
+    console.error(`unknown validator(s): ${unknown.join(", ")}`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+
+  const results = await runAll(root, { only });
+  const findings = results.flatMap((result) => result.findings.map((f) => ({ validator: result.name, ...f })));
+  const errors = findings.filter((f) => f.severity === ERROR).length;
+  const report = { version: 1, root, results, findings, errors };
+
+  if (parsed.values.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    printTable(results);
+    for (const result of results) {
+      if (!result.findings.length) continue;
+      console.log(`\n${result.name}`);
+      for (const item of result.findings) {
+        console.log(`  [${item.code}] ${item.severity} ${item.path}: ${item.message}`);
+      }
+    }
+    console.log(findings.length ? `\n${findings.length} finding(s)` : "\nclean");
+    if (errors === 0 && findings.length > 0) {
+      // Said out loud rather than left to the exit code, so a warning is not
+      // quietly treated as nothing.
+      console.log("No errors. The findings above are warnings and did not fail this run.");
+    }
+  }
+
+  writeReport(parsed.values.out, report);
+  // Errors fail the run; warnings are reported and do not.
+  //
+  // This used to exit on any finding, which made the whole gate fail on every
+  // fresh clone: the project database is git-ignored by design, so the three
+  // validators that read it correctly warn that they had nothing to check, and a
+  // release workflow running this on a checkout would have failed every time
+  // without anything being wrong.
+  //
+  // The distinction is not a relaxation. An error is a claim the repository makes
+  // that is false, and none of those is tolerated. A warning is something worth
+  // a reader's attention that does not make the tree incorrect, and a gate that
+  // cannot tell the two apart teaches people to ignore it.
+  process.exit(errors > 0 ? 1 : 0);
+}
+
+// Main-module guard: realpath both sides, because Node resolves symlinks when
+// it builds import.meta.url for the entry module and /tmp is one on macOS.
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) await main();

package/skills/debug/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: debug
+description: Investigate a failure to its root cause before anything is changed. Use for "why is this failing?", "this broke", "it works locally but not in production", a stack trace, a flaky test, corrupted output, or unexpected behavior. Assembles the evidence packet (exact reproduction, redacted logs, recent changes, environment differences, the feature and contracts involved, governing decisions), routes to the systematic-debugging provider when it is available, requires root-cause evidence that accounts for every important symptom before a fix, fixes at the layer all callers share, and verifies under the original failing conditions with a regression test. No feature interview for a defect.
+---
+
+# Debugging
+
+A symptom report names where it hurts, not what is wrong. Evidence first, then
+the fix, then proof under the conditions that originally failed.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call.
+
+## Steps
+
+1. **Build the evidence packet.**
+   - The exact reproduction, including what makes it stop reproducing.
+   - Errors and logs verbatim, with secrets redacted before they are pasted
+     anywhere or stored.
+   - Recent changes: diff, commits, dependency and configuration moves.
+   - Environment differences between where it works and where it does not.
+   - The product context: `SD task show <TASK-id>` if the failure has a task,
+     the feature and the contracts involved, and `SD decision list --json` for
+     the decisions that govern the area.
+   - `SD memory search "<symptom or component>"` for whether this has
+     been seen before. Recall is a lead, never a conclusion; verify it.
+2. **Track it as work.** A defect that takes more than a moment gets a task
+   linked to the feature and contract it breaks, so the investigation and its
+   outcome survive the session. See the `task` skill.
+3. **Route to the provider.** Superpowers systematic debugging owns this
+   methodology. Check readiness with `SD doctor`. If it is not ready, apply the
+   falsification discipline directly and say the specialist pass did not run:
+   symptoms verbatim, at least three hypotheses before testing any, evidence
+   that discriminates between them, the cheapest high-information check first,
+   one variable per experiment, failed experiments reverted.
+4. **Respect environment safety.** In an envx-managed project, run commands
+   through its stage runner rather than exporting values by hand. Never decrypt
+   or print a secret. Distinguish a missing-access failure from an application
+   failure; they look alike and are not.
+5. **Require root-cause evidence before any fix.** The explanation must account
+   for every important symptom, including the ones that do not fit neatly. A
+   plausible story that explains three of four symptoms is not a root cause.
+6. **Fix at the layer every caller shares.** Before editing, find every caller
+   of the function you are about to change. One guard in the shared path is
+   both the smaller diff and the correct fix; patching only the path the report
+   named leaves the siblings broken.
+7. **Verify under the original failing conditions**, add a regression test to
+   the product's own suite, and read the final diff.
+8. **Record the outcome.** `SD task evidence <TASK-id> --summary "<root cause
+   and fix>" --reference "<the failing case that now passes>"`, then complete with the verification as evidence. Update the
+   specification only when the intended behavior or operations actually changed:
+   a pure defect fix is not a specification change.
+
+## Boundaries
+
+- Never change a test so it passes without first proving the test was wrong.
+- Two failures of the same shape mean the problem model is wrong. Stop varying
+  details and re-examine the model.
+- Evidence of data corruption or a security compromise stops the work and gets
+  reported before anything else continues.
+- The regression test belongs to the product, from its accepted test plan. The
+  Superdev plugin has no test suite; never tell anyone to run tests for it.
+- Report an unproven cause as unproven. "Probably fixed" is not a result.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*

package/skills/decision/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: decision
+description: Find, record, revisit or supersede a project decision. Use for "what did we decide about X?", "why do we use Y?", "record this decision", "can we switch to Z now?", "can we add package P?" when it was declined before, or whenever proposed work conflicts with something already decided. Reads the decision records and their transitions from the database, checks whether a request follows, extends, conflicts with, triggers a revisit of or supersedes each active decision, and presents the owner with a bounded choice. History is append-only, so a decision is superseded with its scope named, never edited into a different past.
+---
+
+# Decisions
+
+A decision record explains why the product is the way it is, so the same
+argument is not had twice and a reversal is deliberate rather than accidental.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call.
+
+## Reading
+
+`SD decision list --json` returns decisions with status, scope, links and the
+supersession chain. Statuses are Proposed, Accepted, Rejected, Deferred,
+Superseded and Deprecated, and each one carries a transition history that only
+appends.
+
+The ADR Markdown under `talks/decisions/` is generated from those rows. Reading
+it is fine. Editing it does not change the decision: the edit becomes a proposal
+that a person reviews, and accepting the proposal updates the database first.
+`SD docs diff` shows any that are waiting.
+
+## Before consequential work: the conflict check
+
+1. Search the active decisions for the capability, dependency, file path,
+   surface or topic the work touches.
+2. For each match, classify the request: **follows** it, **extends** it,
+   **conflicts** with it, **triggers its revisit condition**, **supersedes** it,
+   or is **unrelated**.
+3. On a conflict, present exactly this and stop:
+   - the active decision, its rationale and its scope;
+   - its revisit triggers;
+   - what evidence has actually changed since;
+   - the consequences of each way forward.
+4. Offer exactly four options: preserve the decision, narrow the request to fit
+   it, run a time-boxed experiment that would produce the missing evidence, or
+   record a superseding decision.
+
+Never proceed past a conflict because the new work seems obviously better. The
+earlier decision had reasons; make them visible and let the owner choose.
+
+## Recording a decision
+
+A decision record carries: context; evidence with its epistemic label (measured,
+observed, reported, assumed) and where it came from; the criteria used; the
+options considered with why each was rejected; the decision itself; observable
+rationale (never private reasoning); consequences, positive, negative and
+neutral; risks and their mitigations; enforcement points; how it is verified;
+and its revisit triggers.
+
+Declined and deferred outcomes are first-class records. "Declined, not
+forgotten" is the point: a rejected option with a recorded reason and a revisit
+condition is what stops the same suggestion arriving every month.
+
+Decisions become records through the accepted-planning flow, the same as every
+other accepted content, and status changes are append-only transitions. Run
+`SD decision --help` for the subcommands this build exposes, and use the control
+center's decision view when a person is deciding interactively. Then
+`SD docs generate` renders the ADR.
+
+## Superseding
+
+- The new record names what it supersedes and why.
+- The old record gains a superseded-by pointer and stays readable, unedited.
+- **Partial supersession** names the exact scope that fell and the exact scope
+  that still stands. A vague partial supersession is worse than none, because
+  nobody can tell afterwards which half survived.
+- Never edit an earlier decision body to make it agree with the present. The
+  record is a history, and rewriting it destroys the only evidence of why the
+  reversal happened.
+
+## A previously declined dependency, requested again
+
+1. Find the record that declined it and read its actual reasons.
+2. Check whether each reason still holds. Reasons expire; assume nothing.
+3. Present the new evidence, or say plainly that there is none.
+4. Get explicit confirmation before adding it.
+5. Record a superseding decision if the direction changes, so the next agent
+   sees a reversal rather than a contradiction.
+
+Never install a declined dependency because it would be convenient right now.
+
+## Boundaries
+
+- One owner question at a time, with the recommendation stated.
+- A decision that governs work in flight blocks that work until it is resolved.
+  Report it; do not route around it.
+- Store observable rationale only. Never private model reasoning, secrets,
+  personal data or absolute machine paths.
+- Superdev decides its own conflicts. No transport, sync or external tool
+  arbitrates a decision by overwriting it.
+
+*Standalone note: on skills.sh, install the generated `superdev` package. It
+carries the orchestrator, the Docs capability and the runtime, and needs no
+repository. A single skill copied out on its own has no runtime; say which
+command was unavailable rather than working around it silently.*

package/skills/docs/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: docs
+description: Superdev's first-party documentation engine. Use for documenting or specifying a project ("document this project", "write the spec for X", "give me a complete Markdown summary"), classifying a project or discovering/clarifying requirements ("what questions should we answer before building?"), defining features, pages, UI actions, APIs, schemas, workflows, jobs, permissions, observability, compliance, NFRs, or test plans, ingesting source material ("process these notes/requirements"), reverse-engineering docs from code, initializing or adopting documentation without restructuring it, computing change impact, syncing docs after code changes, creating or superseding ADRs, validating documentation ("check docs against code", "find drift"), or generating doc indexes. Profile-aware - works with the talks/ default, module-based docs, legacy flat docs, or a custom structure through an adapter, never duplicating an existing source of truth.
+---
+
+# Docs Engine - Router
+
+Classify the operation, load only the reference it needs, run deterministic scripts for fragile work. Reference and asset paths below are relative to this skill directory. **Script invocation:** in plugin mode run scripts as `node "${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/<name>.mjs"` - never as a bare relative path, whose meaning would depend on the current working directory. On a standalone skill install (no plugin root), resolve `scripts/`, `references/`, and `assets/` relative to the directory containing this SKILL.md.
+
+## Writing style, always
+
+Superdev never generates or persists the em dash character (U+2014) or emoji.
+Use a period, comma, colon, semicolon, parentheses, or a simple hyphen instead.
+
+This binds everything Superdev writes: documentation, record descriptions, ADRs
+and change records, dashboard copy, generated Markdown, generated source
+comments, summaries, reports, templates, and commit messages it drafts. It also
+binds text taken from a provider: sanitize it or ask for a compliant rewrite
+before storing or displaying it.
+
+Enforcement is real, not advisory. Canonical record and operational state writes
+are checked and refused with the exact file, record and field
+(`E_STYLE_EM_DASH`, `E_STYLE_EMOJI`). Run the style scanner (`node "${CLAUDE_PLUGIN_ROOT}/scripts/style/style.mjs" scan`)
+to check a tree, and `fix --apply` to rewrite existing content. Never delete a
+sentence to satisfy the rule; rewrite its punctuation.
+
+## Always first
+
+1. **Profile:** read `talks/project.yaml` (documentation adapter) if present; otherwise run `node "${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/profile-detect.mjs" --root <project>` and report its evidence and confidence - never silently guess. Profiles: `references/profiles.md`.
+2. **State and decisions:** read `talks/state/` and active decisions if present; surface conflicts before mutating anything.
+3. **Authority:** current-state docs vs immutable history vs recall follow `${CLAUDE_PLUGIN_ROOT}/references/operating-model.md` §5. Epistemic labels per `${CLAUDE_PLUGIN_ROOT}/references/evidence-and-risk.md` §1. Record schemas (activity events, session summaries, decision fields) per `${CLAUDE_PLUGIN_ROOT}/references/project-record.md` §6.
+
+## Operation router
+
+| Requested operation | Load |
+|---|---|
+| Initialize documentation / adopt existing docs | `references/initialize-adopt.md` |
+| Ingest source material (engine-backed) | `references/ingestion.md` |
+| Classify project / discover or clarify requirements | `references/discovery.md` |
+| Cited Markdown project summary | `references/summarize.md` |
+| Foundations / module inventory | `references/foundations-modules.md` |
+| Define a feature (pick spec depth) | `references/spec-depths.md` |
+| Deep module decomposition | `references/module-decomposition.md` |
+| Pages, UI surfaces, action/state inventories | `references/surfaces-and-actions.md` |
+| APIs / data and schema | `references/apis-and-data.md` |
+| Workflows, state machines, async jobs, webhooks | `references/workflows-and-jobs.md` |
+| Roles/permissions, observability, compliance, NFRs, test plans | `references/quality-attributes.md` |
+| Create or supersede an ADR | `references/adr-authoring.md` |
+| Reverse-engineer existing code | `references/reverse-engineer.md` |
+| Change impact / doc sync / drift report / indexes | `references/change-tracking.md` |
+| Validate structure, links, or implementation parity | `references/validation.md` |
+
+Cross-cutting method references (loaded by the above, or directly when the task is exactly this): `references/edge-cases.md`, `references/diagrams.md`, `references/profiles.md`.
+
+## Deterministic scripts (run these; do not improvise their jobs)
+
+- `node "${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/profile-detect.mjs" --root <project> [--json] [--out <file>]` - profile evidence + confidence.
+- `node "${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/validate-docs.mjs" --root <project> [--profile <id>] [--baseline <file>] [--json] [--out <file>]` - structure, links, content rules; stable finding codes; writes nothing without `--out`.
+- `node "${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/template-lint.mjs" [--dir <path>] [--json]` - checks templates and fragments against known vendor/latency/region/regime/env-var patterns (a denylist scan: catches known violations, does not prove absence).
+
+Templates live in `assets/templates/` (universal, provider-neutral). Capability fragments live in `assets/fragments/` and activate **only** on detected code/configuration evidence or an accepted decision - never by default; the fragment inventory and activation rules are in `references/capability-fragments.md`. Fragment activation is recorded with its evidence.
+
+## Mutation and approval rules
+
+- Drafts before acceptance: generated or ingested content is a draft until the user approves it; accepted specs change only with approval.
+- No silent edits. Exceptions (still logged at the next checkpoint): typo fixes and user-facing copy corrections that change no meaning.
+- Consequential generation (new doc set, restructure, migration) requires explicit confirmation of the exact plan first.
+- Existing documentation is adopted through the profile adapter - never moved, rewritten, or duplicated without a separately approved migration.
+- History is immutable: superseded content gets status and banner, never deletion or rewriting; drift is marked (`Contradicted`/`Drift`), never silently resolved.
+- Change tracking is always on: after any accepted mutation, follow `references/change-tracking.md` (identify → classify → confirm → rewrite → record → ADR-if-architectural → re-verify).
+
+## Record-engine commands (durable state, events, sessions, indexes)
+
+The record engine is live - use it, never hand-assemble record files: `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/<cmd>.mjs"` where `<cmd>` is `init`/`adopt` (plan by default, `--apply` to write), `state` (get/set), `events` (append/list/verify - immutable, collision-safe), `session` (append/list - whitelisted fields only), `index` (rebuild/check - deterministic generated views incl. claims/contradictions/questions), `ownership` (validate/match/reverse), `migrate` (inspect/plan/apply/restore), `id` (mint/validate), `questions` (add/list/answer/defer - durable owner-question packets), `risk` (score - deterministic R0–R4 tiering; `gate` - enforces a tier's required artifacts by reading real records), `decisions` (ADR lifecycle, conflict search, declined-dependency check), `impact` (diff-to-impact analysis), `sync` (drift/plan/apply), `complete` (executable completion gate). Ingestion runs through `node "${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/ingest.mjs"` (inventory/ingest/propose/approve/reject/resolve/verify/list).
+
+## Pre-delivery verification checklist (every Docs operation, before claiming done)
+
+1. Profile respected - no structure imposed from a different profile; no duplicate source of truth created.
+2. Every load-bearing claim labeled and cited (file paths for code-derived claims).
+3. No invented stack specifics: vendors, frameworks, budgets, regions, and compliance scopes appear only from evidence or accepted decisions.
+4. Links resolve (`validate-docs.mjs` per the script rule above); touched specs pass parity checks where implementation exists.
+5. Mutations approved, drafts marked as drafts, history untouched, drift marked not erased.
+6. Change-tracking artifacts updated or explicitly reported pending; nothing claimed complete with required sync missing.
+7. Model-private reasoning absent - observable rationale only.
+
+*Standalone install note: this skill's own `references/`, `scripts/`, and `assets/` travel with it. The shared contracts under `${CLAUDE_PLUGIN_ROOT}/references/` ship with the Superdev plugin; on a standalone single-skill install state which shared contract was unavailable.*

package/skills/docs/assets/fragments/api/events.md

@@ -0,0 +1,14 @@
+# Fragment: Event-Driven API
+
+**Activates on evidence:** event/message contracts (topic definitions, event schema files, publisher/subscriber code) - record the paths found. Or an accepted decision.
+
+**Fills:** the "Style specifics" section of the API template.
+
+## Sections supplied
+
+- **Event name/topic:** naming convention as used; version suffix policy.
+- **Payload contract:** schema source cited; required vs optional fields; payload owner.
+- **Producers and consumers:** both sides named (modules/services), matching module event steps.
+- **Delivery semantics:** at-least-once/at-most-once as configured - stated honestly; consumer idempotency expectations.
+- **Ordering:** guarantees (per-key, none) and how consumers handle disorder.
+- **Schema evolution:** compatibility rules (additive-only, versioned topics) from project convention.

package/skills/docs/assets/fragments/api/graphql.md

@@ -0,0 +1,14 @@
+# Fragment: GraphQL API
+
+**Activates on evidence:** a GraphQL schema (SDL files, code-first schema builders, generated schema artifacts) - record the paths found. Or an accepted decision.
+
+**Fills:** the "Style specifics" section of the API template.
+
+## Sections supplied
+
+- **Operation type:** query / mutation / subscription and its schema name.
+- **Schema types:** input and payload types (cite the schema source; do not duplicate it).
+- **Authorization points:** where field/operation authorization is enforced (resolver guards, directive, middleware) - must match the permission matrices.
+- **N+1 and batching:** data-loader/batching behavior where the project has it (evidence).
+- **Error convention:** the project's error shape (error codes in extensions, union results, etc.) from evidence.
+- **Deprecation:** `@deprecated` usage and the migration expectation.

package/skills/docs/assets/fragments/api/local-only.md

@@ -0,0 +1,13 @@
+# Fragment: Local-Only API (in-process contracts)
+
+**Activates on evidence:** no network API surface - capabilities exposed as in-process module interfaces (exported functions/classes consumed across module boundaries). Or an accepted decision.
+
+**Fills:** the "Style specifics" section of the API template.
+
+## Sections supplied
+
+- **Contract location:** the exported interface (file, symbol) - the type signature is the contract.
+- **Consumers:** which modules import it (module boundaries still apply in-process).
+- **Error convention:** exceptions vs result types, as the project does it.
+- **Stability:** which interfaces are internal-stable (cross-module) vs private (may change freely).
+- **Statement:** the doc records explicitly that no network API exists for this capability - absence is a documented fact, not an omission.

package/skills/docs/assets/fragments/api/rest.md

@@ -0,0 +1,13 @@
+# Fragment: REST API
+
+**Activates on evidence:** HTTP route definitions with method verbs (route files, controller decorators, OpenAPI documents) - record the paths found. Or an accepted decision.
+
+**Fills:** the "Style specifics" section of the API template.
+
+## Sections supplied
+
+- **Method and path:** `{{VERB}} {{/resource/path}}` - resource-oriented naming; path params vs query params stated.
+- **Status codes:** success code(s) and each error code with its meaning and body shape.
+- **Content types:** request/response media types; pagination convention (cursor/offset) as used in this project.
+- **Caching:** cache headers/etags if the project uses them (evidence required).
+- **OpenAPI:** if a spec file exists, it is the contract source; the doc cites it and does not duplicate it.

package/skills/docs/assets/fragments/api/rpc.md

@@ -0,0 +1,13 @@
+# Fragment: RPC API
+
+**Activates on evidence:** procedure-style API definitions (typed procedure routers, RPC framework configs, IDL files) - record the paths found. Or an accepted decision.
+
+**Fills:** the "Style specifics" section of the API template.
+
+## Sections supplied
+
+- **Procedure:** namespace/router path and procedure name; call semantics (query vs mutation vs stream) per the framework in use.
+- **Input/output types:** cite the type definitions (schema-validation source is the contract).
+- **Middleware chain:** auth/logging/validation middleware applying to this procedure, in order.
+- **Transport:** how procedures are exposed (HTTP path convention, batching) from the project's configuration.
+- **Client usage:** how callers invoke it (generated client, hook convention) as evidenced in the codebase.

package/skills/docs/assets/fragments/async/event-bus.md

@@ -0,0 +1,13 @@
+# Fragment: Event Bus
+
+**Activates on evidence:** pub/sub topic configuration, event-bus client code, subscription definitions - record the paths found. Or an accepted decision.
+
+**Fills:** the mechanism sections of the jobs/webhooks template; pairs with the events API fragment when events are also the API style.
+
+## Sections supplied
+
+- **Topics and subscriptions:** topic map with publishers and every subscriber (a topic with unknown subscribers is a finding).
+- **Fan-out semantics:** per-subscriber delivery and failure isolation (one failing subscriber must not block others - verified from configuration).
+- **Ordering:** per-key ordering guarantees if any; consumer tolerance otherwise.
+- **Replay:** whether history is replayable, retention window, and the re-subscription procedure.
+- **Schema governance:** how event payload changes propagate to subscribers without breakage.

package/skills/docs/assets/fragments/async/none.md

@@ -0,0 +1,11 @@
+# Fragment: No Async System
+
+**Activates on evidence:** no queue, scheduler, event bus, or background-job mechanism configured. Or an accepted decision.
+
+**Fills:** the mechanism sections of the jobs/webhooks template.
+
+## Sections supplied
+
+- **Statement:** all work happens synchronously in request/interaction scope - recorded explicitly.
+- **Consequences documented:** long operations block their caller; the UI states for slow paths (edge-case category 11) matter more, not less.
+- **Boundaries:** operations currently near timeout limits are listed - they are the trigger list for introducing async later (becomes a decision when it happens).

package/skills/docs/assets/fragments/async/platform-jobs.md

@@ -0,0 +1,13 @@
+# Fragment: Platform-Managed Jobs
+
+**Activates on evidence:** platform job/function definitions (serverless background functions, platform cron, managed workflow definitions) - record the paths found. Or an accepted decision.
+
+**Fills:** the mechanism sections of the jobs/webhooks template.
+
+## Sections supplied
+
+- **Job definitions:** where each platform job is declared (config file, dashboard-as-code) and its trigger.
+- **Platform limits:** execution timeout, payload size, concurrency - from the platform's documented limits for the configured tier, cited.
+- **Retry behavior:** the platform's retry policy as configured; what the platform does on final failure.
+- **Local development:** how jobs run locally (emulator, manual trigger) so behavior is testable.
+- **Observability:** where platform logs/metrics for these jobs live and who can access them.

package/skills/docs/assets/fragments/async/queue.md

@@ -0,0 +1,13 @@
+# Fragment: Queue-Based Async
+
+**Activates on evidence:** queue client configuration, producer/consumer code, queue infrastructure definitions - record the paths found. Or an accepted decision.
+
+**Fills:** the mechanism sections of the jobs/webhooks template.
+
+## Sections supplied
+
+- **Queues:** each queue's name, message contract, producers, and consumers.
+- **Delivery:** the queue system's actual guarantee (at-least-once typically) - consumer idempotency is therefore mandatory and documented per job.
+- **Retry/backoff:** configured policy per queue; poison-message handling (dead-letter destination and its monitoring).
+- **Visibility/locking:** in-flight semantics (visibility timeout, lock duration) and what happens on consumer crash.
+- **Throughput controls:** concurrency limits, batch sizes, rate limits from configuration.