superdev-cli 0.1.0

package/skills/docs/scripts/validate-docs.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+/**
+ * Profile-aware documentation validator. Design guarantees:
+ *  - flags parse independently of positional roots; --json is never a path
+ *  - read-only; writes only to an explicit --out path
+ *  - prohibitions are declarations; only actual usage in executable surfaces
+ *    (package scripts, Makefiles, CI) is flagged - never prose. Scope: only
+ *    backticked commands ("never use/run `X`") are machine-checkable
+ *  - template folders and adapter-excluded globs are exempt from checks
+ *  - historical/superseded documents (status marker within the first ~30
+ *    lines) are exempt from active-contract checks
+ *  - workspace members are scanned, not only the root package
+ *  - profile-specific requirements; never forces talks-v1 on other profiles
+ *  - findings carry stable rule ids + evidence paths; no file content is echoed
+ *    (secret-safe by construction)
+ *
+ * Finding codes:
+ *  DV-STRUCT-001 P0 required artifact missing (per profile)
+ *  DV-STRUCT-002 P1 unregistered (orphan) module folder
+ *  DV-TESTPLAN-001 P1 module missing its test plan (profiles that require one)
+ *  DV-LINK-001 P0 broken relative link in current-state doc
+ *  DV-PROHIB-001 P0 declared-prohibited command actually used in an executable surface
+ *  DV-SUNSET-001 P2 expired "remove after YYYY-MM-DD" marker
+ *  DV-PROFILE-001 P0 adapter declares an unrecognized profile (fail closed)
+ *  DV-PATH-001 P0 adapter path is absolute (must be project-relative)
+ *  DV-PATH-002 P0 adapter path traverses outside the project root
+ *  DV-PATH-003 P0 adapter path escapes the project root through a symlink
+ *  DV-WS-001 P1 unsupported or unsafe workspace pattern (inspection incomplete)
+ *
+ * Adapter data (talks/project.yaml) is untrusted repository input: declared
+ * paths are validated (absolute/traversal/symlink-escape rejected, field name
+ * reported without echoing the value) BEFORE any read they would direct.
+ *
+ * Exit codes: 0 clean, 1 findings, 2 usage error.
+ */
+import { parseArgs } from "node:util";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { detectProfile, readYamlSubset, dependencyInventory } from "./profile-detect.mjs";
+
+const USAGE = `Usage: node validate-docs.mjs [--root <path>] [--profile <id>] [--baseline <file>] [--json] [--out <file>] [--help]
+  --root <path>      project root to validate (default: current directory)
+  --profile <id>     override profile (talks-v1 | module-docs | legacy-flat-docs | custom)
+  --baseline <file>  suppress known findings: JSON array of "RULE:path:detail" (or "RULE:path") fingerprints
+  --json             machine-readable JSON on stdout
+  --out <file>       also write the JSON report to this exact path
+  --help             show this help`;
+
+const DEFAULT_EXCLUDES = ["_templates", "node_modules", ".git", "vendor", "dist", "build"];
+export const KNOWN_PROFILES = new Set(["talks-v1", "module-docs", "legacy-flat-docs", "custom", "none"]);
+
+/** Root-confinement check for an adapter-declared relative path. Returns a
+ *  finding (field name only - the value is never echoed) or null when safe. */
+export function checkAdapterPath(root, field, value) {
+  const v = String(value);
+  if (path.isAbsolute(v) || /^[A-Za-z]:[\\/]/.test(v))
+    return { ruleId: "DV-PATH-001", severity: "P0", file: "talks/project.yaml", detail: `absolute path in docs.${field}` };
+  if (v.split(/[\\/]/).includes(".."))
+    return { ruleId: "DV-PATH-002", severity: "P0", file: "talks/project.yaml", detail: `path traversal in docs.${field}` };
+  const rootReal = fs.realpathSync(root);
+  const resolved = path.resolve(rootReal, v);
+  if (resolved !== rootReal && !resolved.startsWith(rootReal + path.sep))
+    return { ruleId: "DV-PATH-002", severity: "P0", file: "talks/project.yaml", detail: `path resolves outside root in docs.${field}` };
+  if (fs.existsSync(resolved)) {
+    const real = fs.realpathSync(resolved);
+    if (real !== rootReal && !real.startsWith(rootReal + path.sep))
+      return { ruleId: "DV-PATH-003", severity: "P0", file: "talks/project.yaml", detail: `symlink escape in docs.${field}` };
+  }
+  return null;
+}
+
+/** Validate every adapter-controlled path field before any read they direct. */
+export function checkAdapterPaths(root, adapterDocs) {
+  const findings = [];
+  const single = { canonicalRoot: adapterDocs.canonicalRoot, modulesRoot: adapterDocs.modulesRoot, ownership: adapterDocs.ownership };
+  for (const [field, value] of Object.entries(single)) {
+    if (typeof value !== "string") continue;
+    const f = checkAdapterPath(root, field, value);
+    if (f) findings.push(f);
+  }
+  for (const [field, list] of [["required", adapterDocs.required], ["excluded", adapterDocs.excluded]]) {
+    if (!Array.isArray(list)) continue;
+    list.forEach((value, i) => {
+      const bare = String(value).replace(/[*]/g, "x"); // confine the shape; globs share path rules
+      const f = checkAdapterPath(root, `${field}[${i}]`, bare);
+      if (f) findings.push(f);
+    });
+  }
+  return findings;
+}
+
+/** relPosix uses "/" on every platform. Multi-segment excludes match on path
+ *  boundaries; single-name excludes match any path segment. Empty entries never match. */
+export function isExcluded(relPosix, excludes) {
+  return excludes.some((ex) => {
+    if (!ex) return false;
+    if (ex.includes("/")) return relPosix === ex || relPosix.startsWith(ex + "/");
+    return relPosix.split("/").includes(ex);
+  });
+}
+
+function walkMd(dir, root, excludes, out = []) {
+  if (!fs.existsSync(dir)) return out;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const full = path.join(dir, entry.name);
+    const relPosix = path.relative(root, full).split(path.sep).join("/");
+    if (isExcluded(relPosix, excludes)) continue;
+    if (entry.isDirectory()) walkMd(full, root, excludes, out);
+    else if (entry.name.endsWith(".md")) out.push(relPosix);
+  }
+  return out;
+}
+
+/** Historical detection window: the first 30 lines (accommodates frontmatter). */
+export function isHistorical(text, markers) {
+  const head = text.split("\n").slice(0, 30).join("\n");
+  if (/^\s*-?\s*\**Status:?\**\s*(Superseded|Deprecated|Historical|Archived)/im.test(head)) return true;
+  return markers.some((m) => head.includes(m));
+}
+
+/** Prohibition declarations: "never use/run `X`" in prose. Scope: only
+ *  backticked commands are machine-checkable; unbackticked prose prohibitions
+ *  are deliberately out of scope (stated in references/validation.md). */
+export function collectProhibitions(text) {
+  const out = [];
+  for (const m of text.matchAll(/never\s+(?:use|run)\s+`([^`\n]+)`/gi)) out.push(m[1].trim());
+  return out;
+}
+
+/** Executable surfaces where prohibited-command *usage* counts. */
+export function collectExecutableUsage(root, inventory) {
+  const usage = [];
+  const { packages } = inventory ?? dependencyInventory(root);
+  for (const pkg of packages) {
+    for (const [name, cmd] of Object.entries(pkg.scripts)) {
+      usage.push({ where: `${pkg.path}#scripts.${name}`, text: String(cmd) });
+    }
+  }
+  for (const candidate of ["Makefile", "makefile"]) {
+    const p = path.join(root, candidate);
+    if (fs.existsSync(p)) usage.push({ where: candidate, text: fs.readFileSync(p, "utf8") });
+  }
+  const ciDirs = [path.join(root, ".github", "workflows"), path.join(root, ".ci")];
+  for (const dir of ciDirs) {
+    if (!fs.existsSync(dir)) continue;
+    for (const f of fs.readdirSync(dir)) {
+      if (/\.(ya?ml|sh)$/.test(f)) usage.push({ where: path.relative(root, path.join(dir, f)), text: fs.readFileSync(path.join(dir, f), "utf8") });
+    }
+  }
+  return usage;
+}
+
+export function checkLinks(root, relFile, text) {
+  const findings = [];
+  const dir = path.dirname(path.join(root, relFile));
+  for (const m of text.matchAll(/\[[^\]]*\]\(([^)\s]+)\)/g)) {
+    const target = m[1];
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/\/|#)/i.test(target)) continue;
+    const clean = target.split("#")[0];
+    if (!clean) continue;
+    let decoded = clean;
+    try {
+      decoded = decodeURIComponent(clean);
+    } catch {
+      // literal % in the target - check the raw string instead of crashing
+    }
+    if (!fs.existsSync(path.resolve(dir, decoded)))
+      findings.push({ ruleId: "DV-LINK-001", severity: "P0", file: relFile, detail: `broken link: ${clean}` });
+  }
+  return findings;
+}
+
+export function checkSunset(relFile, text, today) {
+  const findings = [];
+  for (const m of text.matchAll(/remove after (\d{4}-\d{2}-\d{2})/gi)) {
+    if (m[1] < today) findings.push({ ruleId: "DV-SUNSET-001", severity: "P2", file: relFile, detail: `expired sunset marker (${m[1]})` });
+  }
+  return findings;
+}
+
+/** Adapter exclude globs reduce to the matcher's two shapes: "**\/name/**" →
+ *  segment exclude "name"; "dir/sub/**" → boundary-prefix exclude "dir/sub".
+ *  Entries that reduce to nothing are dropped - an empty exclude must never match. */
+export function normalizeExclude(glob) {
+  let e = String(glob).replace(/^\.\//, "");
+  if (e.startsWith("**/")) e = e.slice(3).replace(/\/?\*\*.*$/, "").replace(/\/.*$/, "");
+  else e = e.replace(/\/?\*\*.*$/, "");
+  return e.replace(/\/$/, "");
+}
+
+function profileConfig(profile, adapter, detected) {
+  const cfg = {
+    excludes: [...DEFAULT_EXCLUDES],
+    historicalMarkers: [],
+    required: [],
+    modulesRoot: null,
+    docsRoot: null,
+    requireModuleTestPlan: false,
+  };
+  const a = adapter?.docs ?? {};
+  if (Array.isArray(a.excluded)) cfg.excludes.push(...a.excluded.map(normalizeExclude).filter(Boolean));
+  if (Array.isArray(a.historicalMarkers)) cfg.historicalMarkers.push(...a.historicalMarkers);
+  if (Array.isArray(a.required)) cfg.required.push(...a.required);
+  cfg.docsRoot = a.canonicalRoot ?? detected?.docsRoot ?? null;
+  cfg.modulesRoot = a.modulesRoot ?? null;
+
+  if (profile === "talks-v1") {
+    cfg.docsRoot ??= "talks";
+    cfg.required.push("talks/project.yaml", "talks/state/schema-version.json");
+    cfg.modulesRoot ??= "talks/project/modules";
+    cfg.requireModuleTestPlan = true;
+  } else if (profile === "module-docs") {
+    if (!cfg.modulesRoot && cfg.docsRoot) cfg.modulesRoot = `${cfg.docsRoot}/modules`;
+    cfg.requireModuleTestPlan = true;
+  }
+  // legacy-flat-docs and custom: only adapter-declared requirements - never talks-v1's.
+  return cfg;
+}
+
+export function validateDocs(root, { profile: profileOverride, baselinePath } = {}) {
+  if (profileOverride && !KNOWN_PROFILES.has(profileOverride))
+    throw new RangeError(`unknown profile: ${profileOverride} (known: ${[...KNOWN_PROFILES].join(", ")})`);
+  const detected = detectProfile(root);
+  const adapter = detected.adapter ?? null;
+
+  // Fail closed BEFORE any adapter-directed read or profile interpretation.
+  if (adapter?.docs) {
+    const early = [];
+    if (adapter.docs.profile && !KNOWN_PROFILES.has(adapter.docs.profile))
+      early.push({ ruleId: "DV-PROFILE-001", severity: "P0", file: "talks/project.yaml", detail: "unrecognized docs.profile (fail closed; no checks were run)" });
+    early.push(...checkAdapterPaths(root, adapter.docs));
+    if (early.length) {
+      const counts = { P0: early.filter((f) => f.severity === "P0").length, P1: early.filter((f) => f.severity === "P1").length, P2: 0 };
+      return { version: 1, profile: "rejected", profileSource: "adapter", root: path.resolve(root), counts, suppressed: 0, findings: early };
+    }
+  }
+
+  const profile = profileOverride ?? detected.profile;
+  const cfg = profileConfig(profile, adapter, detected);
+  const findings = [];
+  const today = new Date().toISOString().slice(0, 10);
+
+  for (const req of cfg.required) {
+    if (!fs.existsSync(path.join(root, req)))
+      findings.push({ ruleId: "DV-STRUCT-001", severity: "P0", file: req, detail: "required artifact missing" });
+  }
+
+  if (cfg.modulesRoot && fs.existsSync(path.join(root, cfg.modulesRoot))) {
+    for (const entry of fs.readdirSync(path.join(root, cfg.modulesRoot), { withFileTypes: true })) {
+      if (!entry.isDirectory() || entry.name.startsWith(".") || entry.name.startsWith("_")) continue;
+      const moduleRel = path.join(cfg.modulesRoot, entry.name);
+      if (!fs.existsSync(path.join(root, moduleRel, "module.md"))) {
+        findings.push({ ruleId: "DV-STRUCT-002", severity: "P1", file: moduleRel, detail: "unregistered (orphan) module folder - no module.md" });
+      } else if (cfg.requireModuleTestPlan && !fs.existsSync(path.join(root, moduleRel, "test-plan.md"))) {
+        findings.push({ ruleId: "DV-TESTPLAN-001", severity: "P1", file: moduleRel, detail: "module missing test-plan.md" });
+      }
+    }
+  }
+
+  const inventory = dependencyInventory(root);
+  for (const u of inventory.unsupported) {
+    findings.push({ ruleId: "DV-WS-001", severity: "P1", file: "package.json", detail: `workspace inspection incomplete: ${u.reason} (${u.pattern})` });
+  }
+
+  const scanRoot = cfg.docsRoot && fs.existsSync(path.join(root, cfg.docsRoot)) ? path.join(root, cfg.docsRoot) : root;
+  const mdFiles = walkMd(scanRoot, root, cfg.excludes);
+  const prohibitions = new Set();
+  for (const rel of mdFiles) {
+    const text = fs.readFileSync(path.join(root, rel), "utf8");
+    const historical = isHistorical(text, cfg.historicalMarkers);
+    for (const p of collectProhibitions(text)) if (!historical) prohibitions.add(p);
+    if (historical) continue; // historical docs are exempt from active-contract checks
+    findings.push(...checkLinks(root, rel, text));
+    findings.push(...checkSunset(rel, text, today));
+  }
+
+  if (prohibitions.size) {
+    const usage = collectExecutableUsage(root, inventory);
+    for (const prohibited of prohibitions) {
+      for (const u of usage) {
+        if (u.text.includes(prohibited))
+          findings.push({ ruleId: "DV-PROHIB-001", severity: "P0", file: u.where, detail: `prohibited command in executable surface` });
+      }
+    }
+  }
+
+  let suppressed = 0;
+  let active = findings;
+  if (baselinePath) {
+    const baseline = new Set(JSON.parse(fs.readFileSync(baselinePath, "utf8")));
+    // Fingerprint includes the detail so one baselined finding never hides a
+    // different finding of the same rule in the same file.
+    active = findings.filter((f) => {
+      const hit = baseline.has(`${f.ruleId}:${f.file}:${f.detail}`) || baseline.has(`${f.ruleId}:${f.file}`);
+      if (hit) suppressed += 1;
+      return !hit;
+    });
+  }
+
+  const counts = { P0: 0, P1: 0, P2: 0 };
+  for (const f of active) counts[f.severity] += 1;
+  return { version: 1, profile, profileSource: profileOverride ? "override" : detected.source, root: path.resolve(root), counts, suppressed, findings: active };
+}
+
+function main() {
+  let args;
+  try {
+    args = parseArgs({
+      options: {
+        root: { type: "string", default: "." },
+        profile: { type: "string" },
+        baseline: { type: "string" },
+        json: { type: "boolean", default: false },
+        out: { type: "string" },
+        help: { type: "boolean", default: false },
+      },
+      allowPositionals: false,
+    }).values;
+  } catch (err) {
+    console.error(String(err.message ?? err));
+    console.error(USAGE);
+    process.exit(2);
+  }
+  if (args.help) {
+    console.log(USAGE);
+    process.exit(0);
+  }
+  if (!fs.existsSync(args.root) || !fs.statSync(args.root).isDirectory()) {
+    console.error(`root is not a directory: ${args.root}`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+  if (args.baseline && !fs.existsSync(args.baseline)) {
+    console.error(`baseline file not found: ${args.baseline}`);
+    process.exit(2);
+  }
+  if (args.profile && !KNOWN_PROFILES.has(args.profile)) {
+    console.error(`unknown profile: ${args.profile} (known: ${[...KNOWN_PROFILES].join(", ")})`);
+    console.error(USAGE);
+    process.exit(2);
+  }
+  const report = validateDocs(args.root, { profile: args.profile, baselinePath: args.baseline });
+  if (args.json) console.log(JSON.stringify(report, null, 2));
+  else {
+    console.log(`docs validation - profile ${report.profile}, ${report.findings.length} finding(s) (P0=${report.counts.P0} P1=${report.counts.P1} P2=${report.counts.P2}${report.suppressed ? `, ${report.suppressed} baseline-suppressed` : ""})`);
+    for (const f of report.findings) console.log(`  [${f.severity}] ${f.ruleId} ${f.file} - ${f.detail}`);
+    if (!report.findings.length) console.log("  clean");
+  }
+  if (args.out) {
+    const outDir = path.dirname(path.resolve(args.out));
+    const tmpOut = path.join(outDir, `.tmp-report-${process.pid}`);
+    fs.mkdirSync(outDir, { recursive: true });
+    fs.writeFileSync(tmpOut, JSON.stringify(report, null, 2) + "\n");
+    fs.renameSync(tmpOut, path.resolve(args.out));
+  }
+  process.exit(report.findings.length ? 1 : 0);
+}
+
+// Main-module guard: realpath both sides - Node resolves symlinks (e.g. /tmp
+// on macOS) when building import.meta.url for the entry module.
+if (process.argv[1] && import.meta.url === pathToFileURL(fs.realpathSync(process.argv[1])).href) main();

package/skills/doctor/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: doctor
+description: Check whether Superdev can actually work here, and report exactly what to do when it cannot. Use for "is superdev set up correctly?", "why is this failing to start?", "check my environment", "is provider X available?", "the database will not open", "the service is not responding", or before substantial work in an unfamiliar environment. Two programs answer different halves: the CLI doctor reports the storage engine, database integrity, schema version, documentation sync and record alignment; the capability inspector reports harness lifecycle coverage and readiness for every specialist provider. Read only by default, so it installs nothing, enables nothing, decrypts nothing, and reports an unproven state as unproven rather than as ready.
+---
+
+# Doctor
+
+Report the truthful state of everything Superdev depends on, with the exact
+command that fixes each gap. Never install anything without consent to a named
+plan.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call.
+
+## Two programs, two questions
+
+They are separate on purpose and neither reports the other's subject. Running
+one and presenting it as the whole picture is the mistake this section exists to
+prevent.
+
+**Is this project healthy?**
+
+```
+SD doctor --root <project> [--json]
+```
+
+Reports: storage engine, database and schema version, migration history drift,
+integrity, documentation sync, record alignment and freshness. Exit `1` when a
+check finds a problem.
+
+With `--json`, read the **exit code** or `data.ok`. The envelope's top level
+`ok` reports only that the command ran, so it says `true` on a run where a check
+failed. Each check carries `{ name, ok, detail }` and no remediation field: the
+fixes below are this skill's knowledge, not the tool's output.
+
+**Can this machine run Superdev's specialist work?**
+
+```
+node "${CLAUDE_PLUGIN_ROOT}/scripts/doctor/doctor.mjs" inspect --root <project> [--json]
+```
+
+Reports: which harnesses are present and ready, which providers are installed
+and invocable here, and what lifecycle automation actually fires. Read only. It
+writes nothing and installs nothing.
+
+It exits `1` whenever any provider is not ready, which on a machine that has
+deliberately not installed one is a normal state rather than a fault. Read the
+report, not the exit code.
+
+## Steps
+
+1. **Run both.** A healthy project database says nothing about whether a
+   provider is installed, and a ready provider says nothing about whether the
+   database opens.
+2. **Read every section**, not just the failing one. A passing engine with a
+   failing integrity check is not a healthy project.
+3. **Report each gap with its remediation**, in the order that unblocks the most
+   work.
+4. **Take consent separately** for anything that installs or changes the
+   machine. One named plan, one informed yes. Never `--all`, never a silent
+   `-y`, and strip those flags from any command you relay.
+5. **Re-run** afterwards to prove the gap closed. A plan is not evidence; a
+   passing re-run is.
+
+## What `SD doctor` checks
+
+**Storage engine.** Reported rather than tested: reaching doctor at all proves
+the engine loaded, so this row is always a pass and exists to say so. Superdev
+has exactly one engine and no fallback, and nothing degrades quietly to a second
+one, because there is no second one.
+
+The failing case never reaches doctor. When the engine is missing no command runs
+at all, and every one of them says so in the same sentence rather than failing
+with a package resolver error. The usual cause
+is worth knowing: a Claude Code marketplace install **copies** the plugin into
+the harness's own cache, and `node_modules` is git-ignored, so the copy arrives
+with no engine. The fix is `npm install` in that copied directory, not in the
+original checkout. Nothing installs it automatically.
+
+**Database.** File presence, schema version, applied migrations, drift in the
+recorded migration history, integrity and foreign-key check. `SD db status` is
+the same ground on its own. Repairs:
+
+- Schema behind the plugin: `SD db migrate --apply` (it backs up first).
+- Corrupt or unopenable: `SD db restore <file> --apply` from a rolling backup
+  under `.superdev/`, or `SD import <file> --apply` from a portable export.
+- Before any risky maintenance: `SD db backup --apply`.
+
+`db migrate`, `db restore` and `import` all refuse while the control center
+holds the database. Each refusal names the command that frees it.
+
+**Documentation and alignment.** Whether generated Markdown still matches the
+database, whether any record maps to nothing that declares it, and whether the
+generated files were built from an older revision than the database now carries.
+
+**Local service.** `SD services` lists what is running and on which port. `SD
+start`, `SD stop` and `SD restart` manage the one for this project. A running
+service never locks out the command line: readers open read only, writers hold
+the lock for milliseconds.
+
+## What the capability inspector checks
+
+**Harness lifecycle coverage.** What can actually fire here, measured rather
+than assumed:
+
+- Claude Code: session hooks are active.
+- Codex: hooks require explicit trust, and its tool hooks cover shell commands
+  only, so edit-triggered staleness marking never fires there.
+- skills.sh: no hook mechanism at all, so the orchestrator must run `SD resume`
+  and the before-implementation sequence explicitly.
+
+Report this honestly rather than implying automation that will not happen, and
+name the explicit command that covers the gap.
+
+**Providers.** Superpowers, Claude Mem, Frontend Design, Impeccable, Find Skills
+and skills.sh, Task Observer, and envx. For each: whether it is installed and
+whether it is invocable *here*, with its resolved version or `unknown`. Those are
+different states and are reported separately. An unproven state is reported as
+unproven, never as ready.
+
+`inspect`, `setup` and `plan` all write nothing and install nothing: `setup`
+summarises readiness and `plan` produces a plan and a `planId` without executing
+it. Only `apply` and `lock` change anything, `apply` by running an approved
+plan's commands and `lock` by writing a capabilities file. Reach for `inspect`
+unless the user has asked to install something.
+
+## Installing a provider
+
+Never implicitly, and never as a side effect of a check.
+
+`doctor.mjs plan` computes a `planId` over the exact commands it intends to run.
+`doctor.mjs apply` refuses unless both `--plan-id` and `--consent` are given and
+the recomputed id still matches. Commands run as argument arrays rather than
+through a shell, and a command carrying shell metacharacters or a blanket flag
+such as `--all`, `-y` or `--yes` is rejected outright.
+
+**Environment safety.** envx is detected the same way every other provider is,
+by whether its CLI is present and invocable. Neither program opens an envx stage
+file or reads its configuration, so do not report on the contents of either.
+Never decrypt anything, never print a value, and never list a secret name that
+the project has not already committed to a file the user can read.
+
+## Interpreting the result
+
+- A missing provider is a truthful degradation, not a substitution. Say which
+  specialist pass will not run and what Superdev will do instead.
+- A recorded readiness lock that disagrees with live state loses: live state
+  wins and the disagreement is reported.
+- Do not report a capability as working because it worked in a previous session
+  on another machine.
+
+## Boundaries
+
+- Read only by default. No installs, no updates, no enabling a disabled plugin
+  on the user's behalf, no writing project files, no network calls to unrelated
+  services.
+- Never tell anyone to run tests for the Superdev plugin. It has none, by
+  design. Deterministic validators check artifacts; they are not a test suite
+  and they do not prove product behavior.
+- Products built with Superdev do get tests, derived from their accepted product
+  test plan. That is the product's tooling, not the plugin's.
+
+*Standalone note: on skills.sh, install the generated `superdev` package and run
+`npm install` inside it. 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/feature/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: feature
+description: Specify new or changed product behavior before it is built, at a depth proportionate to its risk. Use for "add X", "build Y", "change how Z works", "users should be able to ...", or any request that creates or alters what the product does. Picks microspec, standard spec or full design; checks governing decisions first; interviews only for what is genuinely undecided; records the feature with its module, milestone, goals, acceptance criteria, edge cases, workflows, surfaces and UI actions, API operations, data entities, migrations, integrations, jobs, permissions and NFRs in the database; then derives tasks from what was accepted. Bug fixes route to debug and behavior-preserving refactors need no feature interview.
+---
+
+# Feature Specification
+
+New behavior gets an accepted specification before it gets code. The database
+then derives the work from that specification, so a feature that was never
+specified cannot produce a valid task.
+
+`SD` means the installed `superdev` command, with `--root <project>` on
+every call.
+
+## Steps
+
+1. **Confirm this is feature work.** A defect routes to `debug`. A
+   behavior-preserving refactor needs no interview, only a task linked to what
+   it touches. Everything that changes what the product does belongs here.
+2. **Check governing decisions.** `SD decision list --json`, then read the ones
+   touching this capability, its dependencies or its files. A conflict routes to
+   the `decision` skill before any specification work, not after.
+3. **Read what already exists.** `SD status --json` for the modules, milestones
+   and features already accepted. New behavior usually extends a feature rather
+   than creating one.
+4. **Pick the depth** (brief section 9.2). Depth determines which fields and
+   child records are required before acceptance:
+   - **Microspec**: small, local, reversible behavior. Purpose, user, scope,
+     primary flow, acceptance criteria, affected contracts, edge and error
+     behavior, verification.
+   - **Standard spec**: normal cross-component behavior. Adds surfaces and UI
+     actions, API operations, data entities, roles and permissions, workflow and
+     its steps, state transitions, non-happy paths, observability, rollout, test
+     plan.
+   - **Full design**: architecture, authentication, tenancy, public contracts,
+     migrations, privacy, security, billing, high-risk integrations. Adds
+     alternatives considered, sequence and state diagrams, migration and
+     rollback plan, capacity and performance targets, failure recovery,
+     operations, compatibility, and one or more decision records.
+5. **Interview for what is undecided only.** Plain language, why the answer
+   matters, a recommended default, an example when it helps. Batch three to
+   five; ask one at a time for anything irreversible. "I do not know" becomes
+   the default plus a recorded assumption.
+6. **Route the specialist passes.** Superpowers brainstorming shapes the
+   behavior, Superpowers planning shapes the implementation approach. Check
+   readiness with `SD doctor`. If a provider is not ready, say so, run the
+   interview here instead, and never present your own work as that provider's
+   methodology.
+7. **Record the specification.** `SD plan` presents new and changed features for
+   acceptance and stores what is accepted (`SD plan --help` for scoping it to
+   one module or feature). Every feature belongs to exactly one module and
+   exactly one delivery milestone, and supports at least one goal. A capability
+   that genuinely spans two stages becomes two bounded features with a
+   dependency between them, never one feature with two milestones.
+8. **Fill the contracts the depth requires.** `SD feature specify <FEAT-id>`
+   writes the six microspec covers: `--purpose`, `--user`, `--in`, `--out`,
+   `--flow`, `--criterion "what || how it is verified"` and
+   `--edge category:behavior`. `SD feature depth <FEAT-id>` says what is still
+   missing, and `SD feature depth <FEAT-id> <depth>` changes how much is owed.
+   The deeper covers are their own records: workflows and steps, surfaces and
+   their states, UI actions, API operations, data entities and fields,
+   migrations, integrations, jobs and webhooks, roles and permissions, NFRs,
+   observability, and the product test plan. All of them become the contract
+   that tasks link to with `SD task update <TASK-id> --link type:id`.
+9. **Generate the documentation.** `SD docs generate`, then `SD docs diff` to
+   confirm nothing on disk is now an unreviewed proposal.
+10. **Derive the work.** `SD derive <FEAT-id>`, present the derived
+    plan for acceptance, then hand to the `task` skill for the
+    before-implementation sequence. Implementation starts there, never here.
+
+## Module completeness
+
+For each module, capture or deliberately mark not applicable: pages and
+surfaces; UI composition; actions; API surface; data; end-to-end wiring; state
+machines; events; edge cases; UI states; telemetry; accessibility;
+internationalization; feature flags; responsive behavior; user-facing copy; URL
+state and deep links; performance; discoverability and SEO; compliance and
+product tests.
+
+"Not yet considered" is not an answer. Either it is specified, or it is marked
+not applicable with a reason, or it is an open question with an owner.
+
+## UI-bearing features
+
+A surface is not specified until every interactive element on it has: label,
+purpose, the role and permission that may use it, precondition, the action it
+performs, input and validation, the API or local effect, and its loading,
+disabled, empty, success, error and offline states, plus keyboard behavior,
+accessible name, focus behavior, responsive behavior, and confirmation for
+anything destructive. Telemetry only when explicitly approved.
+
+Route direction and implementation to **Frontend Design**, and critique,
+accessibility, interaction quality and polish to **Impeccable**. Check both with
+`SD doctor`. Name each provider that ran and each that did not, with the reason.
+A run that says nothing about a provider is not a passing run.
+
+Validate against the real interface, not only headless assertions: exercise each
+contracted state, keyboard navigation, focus restoration, accessible names and
+responsive behavior, and keep the screenshot or recording as the evidence
+attached to the task.
+
+## Changing an accepted feature
+
+Specification first, then the task delta.
+
+1. Update the feature and its contracts, and take acceptance for the change.
+2. `SD docs generate` so the projection matches.
+3. `SD derive <FEAT-id>` regenerates the task plan as a delta. The feature is
+   positional, not a flag.
+4. Completed tasks are never rewritten. They are superseded or reopened with
+   their history intact.
+
+Work that appears mid-implementation and is outside the accepted scope stops and
+comes back here. It must not live only in the conversation or in the code.
+
+## Boundaries
+
+- A feature is complete only when its accepted contract components are complete
+  and its acceptance criteria carry current evidence. Progress is derived; there
+  is no command to declare a feature done.
+- No invented stack specifics. Vendors, frameworks, budgets, regions and
+  compliance scopes come from repository evidence or an accepted decision.
+- Product tests come from the accepted product test plan and the project's own
+  tooling. Never invent a framework because it is popular, and never write a
+  test task for the Superdev plugin.
+- Never store secrets, personal data, private identifiers or absolute machine
+  paths in a specification.
+
+*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.*