superdev-cli 0.1.0 → 0.1.2

package/scripts/providers/registry.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * Provider registry - the canonical adapter contract for every external
+ * capability Superdev orchestrates.
+ *
+ * WHAT THIS FILE IS: identity, ownership boundary, and the machine-checkable
+ * parts of each adapter contract - how to DETECT a provider, how to probe its
+ * readiness without side effects, where it is installed from, what consent its
+ * installation needs, what a bounded context packet may contain, and what
+ * evidence its output must carry.
+ *
+ * WHAT THIS FILE IS NOT: a copy of any provider's methodology. Superdev never
+ * vendors, renames, reimplements, or approximates provider guidance. Each entry
+ * records WHERE the capability lives and HOW to reach it - never what it says.
+ * If a provider is absent, Superdev reports the truthful capability state and a
+ * remediation plan; it never silently substitutes its own approximation.
+ *
+ * Identities below were VERIFIED against a live environment (installed plugin
+ * records, marketplace sources, CLI/npm metadata) - never guessed. Anything that
+ * could not be verified is marked `unresolved` and reported as such.
+ */
+
+/** Capability states (contract §21.1). */
+export const CAPABILITY_STATES = [
+  "available-and-ready", "installed-but-disabled", "installed-but-incompatible",
+  "installed-but-unhealthy", "missing", "marketplace-unavailable", "policy-blocked",
+  "authentication-required", "optional-and-absent", "unknown",
+];
+export const READY_STATES = new Set(["available-and-ready"]);
+
+/** How a provider is delivered - determines detection and installation. */
+export const DELIVERY = { CLAUDE_PLUGIN: "claude-plugin", AGENT_SKILL: "agent-skill", CLI: "cli" };
+
+/** Failure classes every adapter maps its errors onto. */
+export const FAILURE_CLASSES = [
+  "not-installed", "disabled", "incompatible-version", "misconfigured",
+  "unauthenticated", "invocation-error", "partial-output", "malformed-output",
+  "timeout", "policy-blocked",
+];
+
+/**
+ * The seven mandatory provider integrations. Each entry carries the complete
+ * 15-element adapter contract. `identity` is the verified canonical identity.
+ */
+export const PROVIDERS = [
+  {
+    id: "superpowers",
+    title: "Superpowers",
+    // 1. canonical provider identity (VERIFIED)
+    identity: { delivery: DELIVERY.CLAUDE_PLUGIN, plugin: "superpowers", marketplace: "claude-plugins-official", ref: "superpowers@claude-plugins-official" },
+    // 2. ownership boundary
+    ownership: "Externally owned by the claude-plugins-official marketplace. Superdev routes to it and consumes its outputs; it never reproduces its brainstorming, planning, TDD, debugging, review, or finishing methodology.",
+    // 3. applicable intents
+    intents: ["brainstorm", "plan", "implement-tdd", "debug", "review", "finish"],
+    // 4. detection mechanism (read-only)
+    detection: { kind: "claude-plugin-record", key: "superpowers@claude-plugins-official" },
+    // 5. readiness probe (non-destructive)
+    readiness: { kind: "skill-namespace", expect: "superpowers:", note: "the loaded session exposes superpowers:* skills" },
+    // 6. installation source
+    install: { marketplaceSource: { source: "github", repo: "anthropics/claude-plugins-official" }, command: "claude plugin install superpowers@claude-plugins-official", verified: true },
+    // 7. consent requirements
+    consent: { required: true, class: "install-plugin", prompt: "Install the Superpowers plugin from the claude-plugins-official marketplace?" },
+    // 8. invocation contract
+    invocation: { kind: "skill", pattern: "superpowers:<skill>", examples: ["superpowers:brainstorming", "superpowers:systematic-debugging", "superpowers:test-driven-development"], superdevNeverInlines: true },
+    // 9. structured context packet (bounded - never the whole record)
+    contextPacket: ["objective", "acceptedConstraints", "relevantDecisionIds", "openOwnerQuestionIds", "riskTier", "requiredRecordOutputs"],
+    // 10. expected output / evidence contract
+    output: { form: "narrative + artifacts authored into talks/", evidence: ["providerInvoked", "providerIdentity", "artifactPaths"], mustBeTraceable: true },
+    // 11. failure classification
+    failures: ["not-installed", "disabled", "incompatible-version", "invocation-error", "partial-output"],
+    // 12. unavailable-provider behavior
+    unavailable: "State plainly that Superpowers was unavailable, run Superdev's OWN gates (scope contract, spec depth, completion evidence), and record that the specialist methodology was not applied.",
+    // 13. no-substitution behavior
+    noSubstitution: "Superdev must not present its own gates as Superpowers' methodology, and must not claim brainstorming/TDD/debugging discipline it did not obtain from the provider.",
+    // 14. privacy and secret boundary
+    privacy: { sends: "bounded context packet only", never: ["raw talks/ tree", "secrets", "PII", "model-private reasoning"], screened: true },
+    // 15. tests - see tests/integration/provider-contracts.test.mjs
+    testsRef: "tests/integration/provider-contracts.test.mjs",
+  },
+  {
+    id: "claude-mem",
+    title: "Claude Mem",
+    identity: { delivery: DELIVERY.CLAUDE_PLUGIN, plugin: "claude-mem", marketplace: "thedotmack", ref: "claude-mem@thedotmack" },
+    ownership: "Externally owned (github thedotmack/claude-mem). A recall/search CACHE - never project authority.",
+    intents: ["recall", "search-prior-work"],
+    detection: { kind: "claude-plugin-record", key: "claude-mem@thedotmack" },
+    readiness: { kind: "skill-namespace", expect: "claude-mem:", note: "the loaded session exposes claude-mem:* skills" },
+    install: { marketplaceSource: { source: "github", repo: "thedotmack/claude-mem" }, command: "claude plugin install claude-mem@thedotmack", verified: true },
+    consent: { required: true, class: "install-plugin", prompt: "Install the Claude Mem plugin from thedotmack/claude-mem?" },
+    invocation: { kind: "skill", pattern: "claude-mem:<skill>", examples: ["claude-mem:mem-search"], superdevNeverInlines: true },
+    contextPacket: ["narrowQuery", "timeWindow", "projectScope"],
+    output: { form: "recalled observations", evidence: ["providerInvoked", "recallIds", "verificationStatus"], mustBeTraceable: true },
+    failures: ["not-installed", "disabled", "invocation-error", "malformed-output", "partial-output"],
+    unavailable: "Proceed from talks/ state and session summaries alone, and say that cross-session recall was unavailable.",
+    // The critical authority rule for this provider.
+    noSubstitution: "Recall is NEVER authority. Every recalled fact must be verified against current artifacts before consequential use, and recall-sourced claims must be labelled with their verification status.",
+    privacy: { sends: "narrow query only", never: ["secrets", "PII", "whole-record dumps"], screened: true },
+    testsRef: "tests/integration/provider-contracts.test.mjs",
+  },
+  {
+    id: "frontend-design",
+    title: "Frontend Design",
+    identity: { delivery: DELIVERY.CLAUDE_PLUGIN, plugin: "frontend-design", marketplace: "claude-plugins-official", ref: "frontend-design@claude-plugins-official" },
+    ownership: "Externally owned by the claude-plugins-official marketplace. Superdev never reproduces its design methodology or aesthetic system.",
+    intents: ["frontend-direction", "component-implementation", "visual-design"],
+    detection: { kind: "claude-plugin-record", key: "frontend-design@claude-plugins-official" },
+    readiness: { kind: "skill-namespace", expect: "frontend-design:", note: "the loaded session exposes frontend-design:* skills" },
+    install: { marketplaceSource: { source: "github", repo: "anthropics/claude-plugins-official" }, command: "claude plugin install frontend-design@claude-plugins-official", verified: true },
+    consent: { required: true, class: "install-plugin", prompt: "Install the Frontend Design plugin from the claude-plugins-official marketplace?" },
+    invocation: { kind: "skill", pattern: "frontend-design:<skill>", examples: ["frontend-design:frontend-design"], superdevNeverInlines: true },
+    contextPacket: ["productContext", "userGoals", "designConstraints", "designSystemEvidence"],
+    output: { form: "design direction + implementation", evidence: ["providerInvoked", "artifactPaths"], mustBeTraceable: true },
+    failures: ["not-installed", "disabled", "incompatible-version", "invocation-error", "partial-output"],
+    unavailable: "Report that the design specialist was unavailable; implement only what the accepted design system already specifies, and do not invent visual direction.",
+    noSubstitution: "Superdev must not generate design direction and present it as the provider's, nor imitate its aesthetic methodology.",
+    privacy: { sends: "bounded design context", never: ["secrets", "PII", "customer data"], screened: true },
+    // Version was 'unknown' in the verified local install record - identity is
+    // confirmed, the version constraint is not. Reported honestly, never guessed.
+    versionResolution: "unresolved",
+    testsRef: "tests/integration/provider-contracts.test.mjs",
+  },
+  {
+    id: "impeccable",
+    title: "Impeccable",
+    identity: { delivery: DELIVERY.CLAUDE_PLUGIN, plugin: "impeccable", marketplace: "impeccable", ref: "impeccable@impeccable" },
+    ownership: "Externally owned (github pbakaus/impeccable). Superdev never reproduces its UI critique/refinement methodology.",
+    intents: ["ui-audit", "ui-polish", "design-critique", "accessibility-review"],
+    detection: { kind: "claude-plugin-record", key: "impeccable@impeccable" },
+    readiness: { kind: "skill-namespace", expect: "impeccable:", note: "the loaded session exposes impeccable:* skills" },
+    install: { marketplaceSource: { source: "github", repo: "pbakaus/impeccable" }, command: "claude plugin install impeccable@impeccable", verified: true },
+    consent: { required: true, class: "install-plugin", prompt: "Install the Impeccable plugin from pbakaus/impeccable?" },
+    invocation: { kind: "skill", pattern: "impeccable:<skill>", examples: ["impeccable:impeccable"], superdevNeverInlines: true },
+    contextPacket: ["surfaceUnderReview", "designSystemEvidence", "accessibilityRequirements", "knownConstraints"],
+    output: { form: "critique + concrete refinements", evidence: ["providerInvoked", "surfaceRefs"], mustBeTraceable: true },
+    failures: ["not-installed", "disabled", "incompatible-version", "invocation-error", "partial-output"],
+    unavailable: "Report that the UI specialist was unavailable and limit work to the accepted design system; do not improvise a critique framework.",
+    noSubstitution: "Superdev must not produce a UI critique and attribute it to Impeccable, nor imitate its refinement methodology.",
+    privacy: { sends: "surface + design constraints", never: ["secrets", "PII", "user data in screenshots"], screened: true },
+    testsRef: "tests/integration/provider-contracts.test.mjs",
+  },
+  {
+    id: "find-skills",
+    title: "Find Skills / skills.sh",
+    // Delivered as an agent skill; the ecosystem CLI is `skills` on npm.
+    identity: { delivery: DELIVERY.AGENT_SKILL, skill: "find-skills", cli: "skills", npm: "skills", ref: "find-skills (agent skill) + skills CLI" },
+    ownership: "Externally owned (the open agent skills ecosystem / skills.sh). Superdev never reimplements skill discovery or the package manager.",
+    intents: ["discover-capability", "install-skill"],
+    // COMPOSITE: the discovery skill and the ecosystem CLI are BOTH required -
+    // the skill without the CLI cannot install anything.
+    components: [
+      { id: "skill", kind: "agent-skill", skill: "find-skills", required: true },
+      { id: "cli", kind: "cli", cli: "skills", versionArgs: ["--version"], required: true },
+    ],
+    detection: { kind: "composite", skill: "find-skills", alsoCli: "skills" },
+    readiness: { kind: "cli-version", cli: "skills", args: ["--version"], note: "npx skills --version; the CLI is the ecosystem package manager" },
+    install: { npm: "skills", command: "npx skills add <skill>", verified: true, note: "skill discovery/installation is the provider's own flow" },
+    // The installation-flags rule is a hard safety boundary for this provider.
+    consent: { required: true, class: "install-skill", prompt: "Install a skill through the skills CLI?", forbiddenFlags: ["--all", "-y", "--yes"] },
+    invocation: { kind: "skill", pattern: "find-skills", examples: ["find-skills"], superdevNeverInlines: true },
+    contextPacket: ["capabilityGap", "intent", "constraints"],
+    output: { form: "candidate skills + install plan", evidence: ["providerInvoked", "candidateIds"], mustBeTraceable: true },
+    failures: ["not-installed", "misconfigured", "invocation-error", "malformed-output", "partial-output"],
+    unavailable: "State that skill discovery was unavailable and proceed with existing capabilities only; never fabricate a catalogue of skills.",
+    noSubstitution: "Superdev must not present its own guesses as ecosystem search results, and must never install with --all or a silent -y.",
+    privacy: { sends: "capability gap description", never: ["secrets", "PII", "proprietary code"], screened: true },
+    testsRef: "tests/integration/provider-contracts.test.mjs",
+  },
+  {
+    id: "task-observer",
+    title: "Task Observer",
+    identity: { delivery: DELIVERY.AGENT_SKILL, skill: "task-observer", repo: "rebelytics/one-skill-to-rule-them-all", ref: "task-observer (agent skill)" },
+    ownership: "Externally owned (github rebelytics/one-skill-to-rule-them-all). Superdev never reproduces its observation taxonomy or skill-extraction methodology.",
+    intents: ["observe-session", "capture-skill-opportunity"],
+    detection: { kind: "agent-skill", skill: "task-observer" },
+    readiness: { kind: "agent-skill-files", skill: "task-observer", expectFiles: ["SKILL.md"] },
+    install: { source: { source: "github", repo: "rebelytics/one-skill-to-rule-them-all" }, command: "npx skills add task-observer", verified: true },
+    consent: { required: true, class: "install-skill", prompt: "Install the Task Observer skill?", forbiddenFlags: ["--all", "-y", "--yes"] },
+    invocation: { kind: "skill", pattern: "task-observer", examples: ["task-observer"], superdevNeverInlines: true },
+    contextPacket: ["sessionObjective", "toolUsagePattern", "userCorrections"],
+    output: { form: "observation log entries", evidence: ["providerInvoked", "observationIds"], mustBeTraceable: true },
+    failures: ["not-installed", "misconfigured", "invocation-error", "partial-output", "malformed-output"],
+    unavailable: "Record session outcomes through Superdev's own session summaries and state that observation capture was unavailable.",
+    noSubstitution: "Superdev must not label its own session summary as Task Observer output or imitate its skill-extraction taxonomy.",
+    privacy: { sends: "session outcome signals", never: ["secrets", "PII", "model-private reasoning"], screened: true },
+    testsRef: "tests/integration/provider-contracts.test.mjs",
+  },
+  {
+    id: "envx",
+    title: "envx",
+    identity: { delivery: DELIVERY.CLI, cli: "envx", npm: "envx-cli", skill: "envx", ref: "envx-cli (CLI) + envx (agent skill)" },
+    ownership: "Externally owned (envx-cli). Superdev never reimplements secret encryption, decryption, or injection.",
+    intents: ["secret-management", "env-injection"],
+    // COMPOSITE: the CLI does the work, the skill carries the safe-usage
+    // contract. Either alone is only partially ready.
+    components: [
+      { id: "cli", kind: "cli", cli: "envx", versionArgs: ["--version"], required: true },
+      { id: "skill", kind: "agent-skill", skill: "envx", required: true },
+    ],
+    detection: { kind: "composite", cli: "envx", alsoSkill: "envx" },
+    readiness: { kind: "cli-version", cli: "envx", args: ["--version"] },
+    install: { npm: "envx-cli", command: "npm install -g envx-cli", verified: true, note: "the skill installs via `envx skill add`" },
+    consent: { required: true, class: "install-cli", prompt: "Install the envx CLI (envx-cli) globally?" },
+    invocation: { kind: "cli", pattern: "envx <command>", examples: ["envx run", "envx skill add"], superdevNeverInlines: true },
+    // The privacy boundary is the whole point of this provider.
+    contextPacket: ["stageName", "requiredVariableNames"],
+    output: { form: "marker presence / exit status only", evidence: ["providerInvoked", "stage"], mustBeTraceable: true },
+    failures: ["not-installed", "misconfigured", "unauthenticated", "invocation-error", "policy-blocked"],
+    unavailable: "Report that envx was unavailable and refuse to improvise secret handling; never read, print, or copy a decrypted secret.",
+    noSubstitution: "Superdev must NEVER decrypt, read, echo, or re-implement secret handling itself. It detects marker presence only.",
+    privacy: { sends: "variable NAMES only", never: ["secret values", "decrypted content", "passphrases"], screened: true, readsSecretValues: false },
+    testsRef: "tests/integration/provider-contracts.test.mjs",
+  },
+];
+
+/** Version policy, stated explicitly rather than implied.
+ *  No provider declares a minimum version today: Superdev integrates through
+ *  stable, documented surfaces (skill namespaces, CLI subcommands) and has no
+ *  verified evidence of a breaking floor. `minVersion` is therefore absent, and
+ *  detection reports versions WITHOUT claiming compatibility validation. Adding
+ *  a `minVersion` to a registry entry activates real enforcement (tested). */
+export const VERSION_POLICY = {
+  enforced: false,
+  statement: "No minimum version is asserted for any provider; detection reports the observed version and never implies a compatibility check that was not performed. Set `minVersion` on a registry entry to enforce one.",
+};
+
+export const PROVIDER_IDS = PROVIDERS.map((p) => p.id);
+export function getProvider(id) {
+  return PROVIDERS.find((p) => p.id === id) ?? null;
+}
+
+/** The 15 contract elements every provider entry must define. */
+export const CONTRACT_ELEMENTS = [
+  "identity", "ownership", "intents", "detection", "readiness", "install", "consent",
+  "invocation", "contextPacket", "output", "failures", "unavailable", "noSubstitution",
+  "privacy", "testsRef",
+];
+
+/** Which Superdev skill routes each intent to a provider (proactive routing). */
+export const INTENT_ROUTING = {
+  brainstorm: "superpowers", plan: "superpowers", "implement-tdd": "superpowers",
+  debug: "superpowers", review: "superpowers", finish: "superpowers",
+  recall: "claude-mem", "search-prior-work": "claude-mem",
+  "frontend-direction": "frontend-design", "component-implementation": "frontend-design", "visual-design": "frontend-design",
+  "ui-audit": "impeccable", "ui-polish": "impeccable", "design-critique": "impeccable", "accessibility-review": "impeccable",
+  "discover-capability": "find-skills", "install-skill": "find-skills",
+  "observe-session": "task-observer", "capture-skill-opportunity": "task-observer",
+  "secret-management": "envx", "env-injection": "envx",
+};

package/scripts/validate/packaging.mjs

@@ -0,0 +1,116 @@
+// Every path the published package's own code reaches must be inside the
+// published package.
+//
+// scripts/providers/detect.mjs was imported by src/cli.mjs and src/init/index.mjs
+// and was not listed in package.json's files array. So on every npm install of
+// superdev-cli, provider readiness reported "could not be determined: Cannot find
+// module", the init skill's step about checking readiness before relying on it
+// could never succeed, and doctor printed Pass beside the failure. It worked
+// everywhere except where users install it, because the plugin copy carries the
+// whole repository and the npm package carries an allowlist.
+//
+// Nothing caught it because nothing compared what the code imports against what
+// the package ships. The files array is edited by hand, and a missing entry is
+// invisible locally and fatal remotely, which is the exact shape of defect a
+// validator is for.
+
+import { join, posix, relative, sep } from "node:path";
+
+import { ERROR, WARNING, finding, importSpecifiers, isDirectory, readJson, readText, walk } from "./common.mjs";
+
+export const name = "packaging";
+
+const SCANNED_ROOTS = ["src", "scripts", "hooks"];
+
+const slash = (path) => path.split(sep).join("/");
+
+/**
+ * Would `npm pack` include this path, given the files array?
+ *
+ * Deliberately stricter than npm's own matching. A false finding costs somebody
+ * a reading; a missed one costs a release that fails in a stranger's terminal.
+ */
+export function packaged(patterns, path) {
+  // npm includes these whatever the files array says.
+  if (path === "package.json" || /^(README|LICENSE|LICENCE|NOTICE|CHANGELOG)/i.test(path)) return true;
+
+  let included = false;
+  for (const raw of patterns) {
+    const negated = raw.startsWith("!");
+    const pattern = negated ? raw.slice(1) : raw;
+    if (matches(pattern, path)) included = !negated;
+  }
+  return included;
+}
+
+const escape = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+function matches(pattern, path) {
+  if (pattern.endsWith("/")) return path.startsWith(pattern);
+  if (pattern.includes("*")) {
+    const source = pattern
+      .split("**").map((part) => part.split("*").map(escape).join("[^/]*"))
+      .join(".*");
+    return new RegExp(`^${source}$`).test(path);
+  }
+  return path === pattern || path.startsWith(`${pattern}/`);
+}
+
+export async function run(root) {
+  const findings = [];
+  const read = readJson(join(root, "package.json"));
+  if (read.error) {
+    findings.push(finding("PK-000", ERROR, "package.json", `cannot be read: ${read.error}`));
+    return { name, findings };
+  }
+  const manifest = read.value;
+  const patterns = manifest?.files;
+
+  if (!Array.isArray(patterns) || !patterns.length) {
+    findings.push(finding("PK-000", ERROR, "package.json",
+      "there is no files array, so the package would ship whatever happens to be in the directory"));
+    return { name, findings };
+  }
+
+  // The bin entry has to be in the package before anything else matters.
+  const bin = typeof manifest.bin === "string" ? manifest.bin : Object.values(manifest.bin ?? {})[0];
+  if (bin) {
+    const target = posix.normalize(String(bin).replace(/^\.\//, ""));
+    if (!packaged(patterns, target)) {
+      findings.push(finding("PK-001", ERROR, "package.json",
+        `bin points at ${target}, which the files array does not include, so the installed command would not exist`));
+    }
+  }
+
+  const files = SCANNED_ROOTS
+    .filter((dir) => isDirectory(join(root, dir)))
+    .flatMap((dir) => walk(join(root, dir)))
+    .filter((file) => file.endsWith(".mjs") || file.endsWith(".js"))
+    .map((file) => slash(relative(root, file)))
+    // Only shipped code can fail at runtime in somebody's install. A script that
+    // is deliberately repository-only may import whatever it likes.
+    .filter((path) => packaged(patterns, path) && !path.endsWith(".test.mjs"));
+
+  for (const path of files) {
+    const from = posix.dirname(path);
+    const seen = new Set();
+    for (const spec of importSpecifiers(readText(join(root, path)))) {
+      if (!spec.startsWith("./") && !spec.startsWith("../")) continue;
+      const target = posix.normalize(posix.join(from, spec));
+      if (seen.has(target)) continue;
+      seen.add(target);
+
+      if (!/\.(mjs|js|json|css|md)$/.test(target)) {
+        findings.push(finding("PK-003", WARNING, path,
+          `imports ${spec}, which names no file extension, so whether the package ships it cannot be decided here`));
+        continue;
+      }
+      if (!packaged(patterns, target)) {
+        findings.push(finding("PK-002", ERROR, path,
+          `imports ${target}, which package.json files does not include, so the published package cannot resolve it`));
+      }
+    }
+  }
+
+  return { name, findings };
+}

package/scripts/validate/skill-commands.mjs

@@ -15,7 +15,7 @@
 // about it.
 
 import { readFileSync, existsSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 import { ERROR, WARNING, finding, rel } from "./common.mjs";
 
@@ -175,6 +175,16 @@ export async function run(root) {
     }
   }
 
+  // A skill also tells an agent to run scripts by path, and a path is a claim
+  // about the repository exactly like a command name is.
+  //
+  // Nothing checked those, and five had been dead for as long as the database
+  // replaced the file-per-record engine they belonged to. The docs skill still
+  // documented a fourteen-command surface at scripts/talks/, and a shipped
+  // script imported three modules from it, so its mutation path could never run
+  // and failed advising the reader to do the thing they were already doing.
+  findings.push(...scriptPaths(root));
+
   // One finding per distinct claim: a flag documented in four places is one
   // wrong instruction repeated, but each file still needs fixing, so they are
   // kept separate and only exact duplicates within a file are collapsed.
@@ -188,3 +198,63 @@ export async function run(root) {
 
   return { name, findings: unique };
 }
+
+/**
+ * Every script a skill names by path, checked against the repository.
+ *
+ * Two shapes are read: `${CLAUDE_PLUGIN_ROOT}/...` in the prose an agent
+ * follows, and a relative import inside a script the skills ship. A path
+ * containing a placeholder such as `<cmd>` is a family rather than a file, and
+ * is reported only when its whole directory is missing, because that is the
+ * difference between "documented loosely" and "documented for something gone".
+ */
+function scriptPaths(root) {
+  const out = [];
+  const files = [];
+  const walk = (dir) => {
+    if (!existsSync(dir)) return;
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (/\.(md|mjs)$/.test(entry.name)) files.push(path);
+    }
+  };
+  walk(join(root, "skills"));
+  walk(join(root, "references"));
+
+  for (const file of files) {
+    const where = rel(root, file);
+    const text = readFileSync(file, "utf8");
+
+    for (const match of text.matchAll(/\$\{CLAUDE_PLUGIN_ROOT\}\/([A-Za-z0-9_./<>-]+\.mjs)/g)) {
+      const named = match[1];
+      if (named.includes("<")) {
+        // A family. Only its directory can be checked, and a missing directory
+        // means every member of the family is missing too.
+        const dir = named.slice(0, named.lastIndexOf("/"));
+        if (dir && !existsSync(join(root, dir))) {
+          out.push(finding("skill-script-dir-missing", ERROR, where,
+            `The skill tells an agent to run scripts under ${dir}/, and that directory does not exist.`));
+        }
+        continue;
+      }
+      if (!existsSync(join(root, named))) {
+        out.push(finding("skill-script-missing", ERROR, where,
+          `The skill tells an agent to run ${named}, and there is no such file.`));
+      }
+    }
+
+    // A shipped script importing something that is not there fails at the
+    // moment it is needed, which is later and more confusing than a bad path in
+    // prose.
+    if (!file.endsWith(".mjs")) continue;
+    for (const match of text.matchAll(/new URL\("(\.\.[A-Za-z0-9_./-]+\.mjs)"/g)) {
+      const target = resolve(dirname(file), match[1]);
+      if (!existsSync(target)) {
+        out.push(finding("skill-script-import-missing", ERROR, where,
+          `It imports ${match[1]}, which resolves to a file that does not exist.`));
+      }
+    }
+  }
+  return out;
+}

package/scripts/validate/validate-all.mjs

@@ -30,11 +30,12 @@ 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";
+import * as packaging from "./packaging.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,
+  style, privacy, imports, dependencies, noTests, footprint, dataModel, recordLinks, skillCommands, specification, packaging,
 ];
 
 const USAGE = `Usage: node validate-all.mjs [--root <path>] [--only <name,...>] [--json] [--out <file>] [--help]

package/skills/docs/SKILL.md

@@ -71,7 +71,7 @@ Templates live in `assets/templates/` (universal, provider-neutral). Capability
 
 ## 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).
+The record engine is the database, reached through the `superdev` command, and it is the only thing that writes a record: `superdev change record` for what moved in accepted scope, `superdev decision record` for a decision, `superdev question answer` for an owner question, `superdev assumption record` for a reversible answer, and `superdev docs generate` to rebuild the Markdown projection afterwards. Source material is taken in by `superdev init --brief <file>`, which screens it and records what it states. Never hand-assemble a record file: the Markdown under `talks/` is generated from the database and an edit to it is a proposal, reviewed with `superdev docs diff`.
 
 ## Pre-delivery verification checklist (every Docs operation, before claiming done)
 

package/skills/docs/references/change-tracking.md

@@ -59,4 +59,12 @@ Generated views (module inventory rollups, decision index, ownership rollups) ar
 
 ## 7. Engine commands
 
-Durable writes go through the record engine: append the change entry with `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/events.mjs" append --root <project> --event <file|-> --apply` (immutable, collision-safe, secret/reasoning-content rejected), map changed paths with `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/ownership.mjs" match`, and regenerate views with `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/index.mjs" rebuild --apply`. Generated views are never hand-edited - rebuild them.
+Durable writes go through the database, reached by the `superdev` command.
+Record what moved in accepted scope with
+`superdev change record --summary <what> --reason <why> --apply`, which names the
+records it moved and is refused without a reason. The activity trail behind it is
+append only, enforced by database triggers rather than by convention, and
+screening refuses a secret-shaped value before it can be stored. Regenerate the
+Markdown with `superdev docs generate --apply`. Generated files are never
+hand-edited: an edit becomes a proposal, read with `superdev docs diff` and taken
+in with `superdev docs accept`.

package/skills/docs/references/ingestion.md

@@ -40,13 +40,18 @@ Detect and keep visible until resolved: source vs source · source vs code · so
 
 ## 5. Engine commands
 
-The ingestion engine implements this contract deterministically - use it, never improvise its jobs: `node "${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/ingest.mjs" <op>`:
+Ingestion is `superdev init --brief <file>`, which reads the source, screens it for
+credential-shaped values before anything is stored, records what it states, and
+records what it does not state as an open question rather than a guess. The
+operations below describe that contract:
 
 - `ingest --source <rel> [--apply]` - intake, hashing, screening, revision registration (plan first; unchanged re-ingest is a structural no-op; changed content appends a new revision).
 - `propose --revision <SRC-..:rN> --proposals <file|-> [--apply]` - YOUR semantic claim/contradiction proposals, validated against the deterministic schema (category, six-label epistemic enum, span hash-verified against the revision; Confirmed requires verification evidence). Deterministic identity dedups and merges provenance.
 - `approve|reject --id <CLM-..> --approver <who> [--apply]` - drafts become accepted only here; open contradictions and load-bearing Contradicted/Unknown labels block approval.
 - `resolve --id <CTR-..> --authority <class> --evidence <e> [--apply]` - contradictions stay visible until explicitly resolved; re-ingest never closes them.
 - `verify` - re-verifies every stored provenance span against its recorded revision hash.
-- Owner questions and risk: `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/questions.mjs"` (packet contract enforced) and `node "${CLAUDE_PLUGIN_ROOT}/scripts/talks/risk.mjs" score`.
+- Owner questions: `superdev question list` and `superdev question answer <id>`. Risk
+  is carried per feature as its specification depth, set with
+  `superdev feature depth <id> <depth>` and enforced at acceptance.
 
 Standalone single-skill install: inventory and screening (dry-run) work; record mutation requires the plugin context and is refused with a documented checkpoint (`E_STANDALONE`) - never silently skipped. Inbox retention/commit policy belongs to the project; the engine never edits ignore files.

package/skills/docs/scripts/profile-detect.mjs

@@ -7,6 +7,7 @@
  * Exit codes: 0 detection completed (including "none"), 2 usage error.
  */
 import { parseArgs } from "node:util";
+import { execFileSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -90,6 +91,58 @@ function dirNames(dir) {
     .map((e) => e.name);
 }
 
+/**
+ * Markdown under a directory that Git is not ignoring, at most three levels down.
+ *
+ * The bare existence of a subdirectory used to count as documentation. A real
+ * repository had `docs/` holding nothing but `.DS_Store` and a git-ignored
+ * `docs/client-shared/` of material the client had sent in. That is input to a
+ * project, not a projection of one, and detection called it "documentation
+ * present matching no known profile" and routed a brand new repository to adopt,
+ * which refuses to initialize.
+ *
+ * Git's own ignore list is the right authority for "is this part of the
+ * repository": it is the file the user already maintains to say so. Without Git
+ * the scan simply keeps everything, which is the old behaviour minus the
+ * empty-directory case.
+ */
+function trackedMarkdown(root, dir) {
+  const found = markdownUnder(dir, 3);
+  const ignored = ignoredByGit(root, found);
+  return found.filter((file) => !ignored.has(file));
+}
+
+function markdownUnder(dir, depth) {
+  if (depth < 0 || !fs.existsSync(dir)) return [];
+  const found = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".")) continue;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...markdownUnder(full, depth - 1));
+    else if (entry.name.endsWith(".md")) found.push(full);
+  }
+  return found;
+}
+
+/** One `git check-ignore` for the whole list: a call per file is a call per file. */
+function ignoredByGit(root, files) {
+  if (!files.length || !fs.existsSync(path.join(root, ".git"))) return new Set();
+  try {
+    const out = execFileSync("git", ["-C", root, "check-ignore", "--stdin"], {
+      input: files.join("\n"),
+      encoding: "utf8",
+      stdio: ["pipe", "pipe", "ignore"],
+      timeout: 10000,
+    });
+    return new Set(out.split(/\r?\n/).filter(Boolean).map((line) => path.resolve(root, line)));
+  } catch (error) {
+    // Exit 1 means nothing matched, which is an answer, not a failure. Anything
+    // else means git could not tell us, and then nothing is treated as ignored.
+    if (error?.status === 1) return new Set();
+    return new Set();
+  }
+}
+
 const TYPE_FOLDERS = ["features", "apis", "api", "data", "database", "workflows", "schemas"];
 const DOCS_ROOT_CANDIDATES = ["docs/project", "docs", "documentation"];
 
@@ -143,8 +196,9 @@ export function detectProfile(root) {
       return { profile: "legacy-flat-docs", confidence: "medium", source: "structure", evidence, docsRoot: candidate };
     }
 
-    const mdFiles = fs.readdirSync(docsRoot).filter((f) => f.endsWith(".md"));
-    if (mdFiles.length || dirNames(docsRoot).length) {
+    // Markdown Git is keeping, not a directory that happens to be here.
+    const mdFiles = trackedMarkdown(root, docsRoot);
+    if (mdFiles.length) {
       evidence.push({ what: "documentation present matching no known profile", where: candidate });
       return { profile: "custom", confidence: "low", source: "structure", evidence, docsRoot: candidate };
     }

package/src/cli/product-map.mjs

@@ -163,9 +163,13 @@ export async function milestoneShow(root, id) {
   const { milestone, features } = found;
   // Both shapes are read: a plain string from before conditions could be
   // judged, and the object a judged condition is stored as now.
-  const exits = json(milestone.exit_conditions_json, []).map((c) =>
-    typeof c === "string" ? { condition: c, met: false, reading: null, check: null } : c);
+  const asCondition = (c) => (typeof c === "string" ? { condition: c, met: false, reading: null, check: null } : c);
+  const exits = json(milestone.exit_conditions_json, []).map(asCondition);
+  // Entry conditions were stored and never shown, so a milestone could be
+  // blocked from starting by something the reader had no way to see.
+  const entries = json(milestone.entry_conditions_json, []).map(asCondition);
   const met = exits.filter((c) => c.met).length;
+  const entryMet = entries.filter((c) => c.met).length;
   const done = features.filter((f) => ["complete", "delivered", "implemented"].includes(f.status)).length;
   return {
     data: found,
@@ -181,6 +185,10 @@ export async function milestoneShow(root, id) {
       // that decided it, and was being printed straight into a bullet, which
       // rendered twenty five of them as [object Object]. The control centre
       // normalises the same shape; the command line was never taught to.
+      entries.length
+        ? R.block(`Entry conditions (${entryMet} of ${entries.length} met)`,
+            entries.map((c) => `  [${c.met ? "met" : "not met"}] ${c.condition}`).join("\n"))
+        : null,
       R.block(`Exit conditions (${met} of ${exits.length} met)`, exits.length
         ? exits.map((c) => R.stitch([
             `  [${c.met ? "met" : "not met"}] ${c.condition}`,