vigiles 9.0.0 → 10.0.0

package/dist/cli.js

@@ -34,6 +34,7 @@ const optimize_js_1 = require("./optimize.js");
 const audit_score_js_1 = require("./audit-score.js");
 const audit_prompts_js_1 = require("./audit-prompts.js");
 const audit_html_js_1 = require("./audit-html.js");
+const audit_serve_js_1 = require("./audit-serve.js");
 const audit_report_js_1 = require("./audit-report.js");
 const adoptability_js_1 = require("./adoptability.js");
 const compile_js_1 = require("./core/compile.js");
@@ -140,6 +141,14 @@ function printErrors(specFile, errors) {
         console.log(`::error file=${specFile}::${err.message}`);
     }
 }
+/** Non-blocking advisories — printed, but never fail the compile. */
+function printWarnings(specFile, warnings) {
+    for (const w of warnings) {
+        const pathInfo = w.path ? ` (${w.path})` : "";
+        console.log(`  ⚠ [${w.type}] ${w.message}${pathInfo}`);
+        console.log(`::warning file=${specFile}::${w.message}`);
+    }
+}
 // ---------------------------------------------------------------------------
 // Commands
 // ---------------------------------------------------------------------------
@@ -238,7 +247,7 @@ function writeInstructionMirrors(primaryOutput, harnesses) {
 /** Compile a declarative SkillSpec → SKILL.md. */
 function compileSkillToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_js_1.compileSkill)(spec, {
+    const { markdown, errors, warnings } = (0, compile_js_1.compileSkill)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         // The SKILL.md frontmatter profile comes from the resolved harness — a Codex
@@ -248,16 +257,18 @@ function compileSkillToFile(spec, specPath, dialect) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
+        printWarnings(specPath, warnings);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
     printErrors(specPath, errors);
+    printWarnings(specPath, warnings);
     return false;
 }
 /** Compile a subagent spec → agents/<name>.md (with its result-contract section). */
 function compileAgentToFile(spec, specPath, dialect) {
     const outputPath = specPath.replace(/\.spec\.ts$/, "");
-    const { markdown, errors } = (0, compile_js_1.compileAgent)(spec, {
+    const { markdown, errors, warnings } = (0, compile_js_1.compileAgent)(spec, {
         basePath: process.cwd(),
         specFile: specPath,
         dialect,
@@ -265,10 +276,12 @@ function compileAgentToFile(spec, specPath, dialect) {
     (0, node_fs_1.writeFileSync)((0, node_path_1.resolve)(process.cwd(), outputPath), markdown);
     if (errors.length === 0) {
         console.log(`\n✓ ${specPath} → ${outputPath}`);
+        printWarnings(specPath, warnings);
         return true;
     }
     console.log(`\n✗ ${specPath} — ${String(errors.length)} error(s)`);
     printErrors(specPath, errors);
+    printWarnings(specPath, warnings);
     return false;
 }
 /**
@@ -819,8 +832,26 @@ function verifyFrontmatterRules(filePath, silent, exclude, linterOptions) {
     };
 }
 /**
- * Verify inline `<!-- vigiles:enforce -->` comments and `vigiles:` YAML
- * frontmatter in instruction files that aren't managed by a spec.
+ * Frontmatter mode (Level 1 — a `vigiles:` YAML block) is DISABLED in lint:
+ * KEPT IN CODE (`src/core/frontmatter.ts`, `verifyFrontmatterRules`,
+ * `vigiles generate schema`), but INERT — lint no longer reads or verifies a
+ * `vigiles:` block, so it never fires and never fails a build.
+ *
+ * WHY disabled-not-removed: the three-rung adoption ladder (inline / frontmatter
+ * / typed spec) collapsed to TWO on-ramps — inline comments (the zero-TS floor)
+ * and the typed `.spec.ts` (the source of truth). Frontmatter mode was the
+ * weakest middle rung and an undocumented-but-live surface that muddied the
+ * spec-first story (it literally confused a review). With ~no users to break,
+ * gating it off makes lint coherent (verify compiled output + inline marks +
+ * specs, nothing else) while preserving the code so the decision is reversible:
+ * flip this to `true` to re-enable. See `research/pre-release-focus.md` and the
+ * parked note in `docs/markdown-mode.md`.
+ */
+const FRONTMATTER_MODE_ENABLED = false;
+/**
+ * Verify inline `<!-- vigiles:enforce -->` comments (and, when
+ * {@link FRONTMATTER_MODE_ENABLED}, `vigiles:` YAML frontmatter) in instruction
+ * files that aren't managed by a spec.
  *
  * Spec mode is the source of truth when it exists, so a literal
  * `<!-- vigiles:enforce ... -->` snippet that survived into compiled
@@ -861,9 +892,13 @@ function verifyMarkdownModeRules(files, silent, config) {
         const inline = verifyInlineRules(filePath, silent, linterOptions);
         totals.inlineErrors += inline.errorCount;
         totals.inlineRules += inline.ruleCount;
-        const fm = verifyFrontmatterRules(filePath, silent, new Set(inline.ruleNames), linterOptions);
-        totals.frontmatterErrors += fm.errorCount;
-        totals.frontmatterRules += fm.ruleCount;
+        // Frontmatter mode is DISABLED (kept in code, inert in lint) — a `vigiles:`
+        // block is ignored, never verified. See FRONTMATTER_MODE_ENABLED.
+        if (FRONTMATTER_MODE_ENABLED) {
+            const fm = verifyFrontmatterRules(filePath, silent, new Set(inline.ruleNames), linterOptions);
+            totals.frontmatterErrors += fm.errorCount;
+            totals.frontmatterRules += fm.ruleCount;
+        }
     }
     if (!silent &&
         files.length > 0 &&
@@ -1219,6 +1254,100 @@ function targetHasHash(absPath) {
  * target by `setupPillar1`. The full onboarding (both layers, deps, CI, plugin)
  * is `setup()`.
  */
+/** Classify an adoption target by its path: a `SKILL.md` is a skill, a file under
+ * an `agents/` dir is a subagent, everything else is an instruction file. Used to
+ * pick the right adopt function so `init --target=skills/x/SKILL.md` (the
+ * per-surface path the audit report points at) makes a `skill()`/`agent()` spec. */
+function surfaceKind(target) {
+    if (/^SKILL\.md$/i.test((0, node_path_1.basename)(target)))
+        return "skill";
+    if (/(^|[/\\])agents[/\\]/.test(target))
+        return "agent";
+    return "instruction";
+}
+function logAdoptedSurface(target, specPath, label, unmappedKeys) {
+    const note = unmappedKeys.length > 0
+        ? ` (review the // NOTE — unmapped frontmatter: ${unmappedKeys.join(", ")})`
+        : "";
+    console.log(`Adopted ${label} ${target} → ${specPath}${note}. ` +
+        `Run \`vigiles compile\` and review the diff.`);
+}
+/** Discover existing skill (`skills/<x>/SKILL.md`) and subagent (`agents/<x>.md`)
+ * surfaces — under the bare or `.claude/` roots — that don't yet have a spec, so
+ * bare `vigiles init` creates a spec for EVERY surface it can, not just the
+ * instruction file. Shallow (top-level only) so it never walks node_modules or a
+ * vendored plugin. CC paths are intentional here — `init` is the one composition
+ * point allowed to know them (see adapter-aware-lint-rules). */
+function discoverAdoptableSurfaces(cwd) {
+    const out = [];
+    const unspecced = (rel) => (0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, rel)) &&
+        !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(cwd, `${rel}.spec.ts`));
+    for (const root of ["skills", ".claude/skills"]) {
+        const abs = (0, node_path_1.resolve)(cwd, root);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
+            const rel = `${root}/${e.name}/SKILL.md`;
+            if (e.isDirectory() && unspecced(rel))
+                out.push(rel);
+        }
+    }
+    for (const root of ["agents", ".claude/agents"]) {
+        const abs = (0, node_path_1.resolve)(cwd, root);
+        if (!(0, node_fs_1.existsSync)(abs))
+            continue;
+        for (const e of (0, node_fs_1.readdirSync)(abs, { withFileTypes: true })) {
+            const rel = `${root}/${e.name}`;
+            if (e.isFile() && e.name.endsWith(".md") && unspecced(rel))
+                out.push(rel);
+        }
+    }
+    return out;
+}
+/** The full adoptable-surface list `audit` reports: the instruction file (when it
+ * exists hand-written, no spec) PLUS every skill/subagent surface without a spec.
+ * Same notion `init` adopts; surfaced in the AuditReport + the terminal nudge so
+ * the report's "Create spec" / "Create all specs" affordances have their paths.
+ * Composition-root only — CC paths are intentional here (like discoverAdoptableSurfaces). */
+function discoverAdoptableForAudit(root, instructionFile) {
+    const out = [];
+    const instrAbs = (0, node_path_1.resolve)(root, instructionFile);
+    if ((0, node_fs_1.existsSync)(instrAbs) &&
+        !targetHasHash(instrAbs) &&
+        !(0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, `${instructionFile}.spec.ts`))) {
+        out.push(instructionFile);
+    }
+    out.push(...discoverAdoptableSurfaces(root));
+    return out;
+}
+/** The terminal "adoptable surfaces" nudge — N un-spec'd surfaces + the create-all
+ * command and up to ~5 per-surface commands (then "+K more"). "" when nothing to
+ * adopt (a fully spec-managed repo says nothing). */
+function formatAdoptableNudge(surfaces) {
+    if (surfaces.length === 0)
+        return "";
+    const n = surfaces.length;
+    const lines = [
+        `ℹ ${String(n)} surface${n === 1 ? "" : "s"} not yet spec-managed — create specs with \`npx vigiles init\``,
+        `  (or one at a time: \`npx vigiles init --target=<path>\`)`,
+    ];
+    const shown = surfaces.slice(0, 5);
+    for (const s of shown)
+        lines.push(`    • npx vigiles init --target=${s}`);
+    const more = n - shown.length;
+    if (more > 0)
+        lines.push(`    • +${String(more)} more`);
+    return lines.join("\n");
+}
+/** A small, terse behavioral nudge — the deterministic read can't tell whether a
+ * skill actually FIRES. "" when there are no model-invocable skills. */
+function formatTriggerNudge(triggerableSkills) {
+    if (triggerableSkills <= 0)
+        return "";
+    const n = triggerableSkills;
+    return (`ℹ Do your ${String(n)} skill${n === 1 ? "" : "s"} actually fire? The deterministic read can't tell — ` +
+        `run \`audit\` interactively to measure, or test with \`measureTriggerRate\` (vigiles/testing).`);
+}
 function scaffoldSpec(args) {
     const targetFlag = args.find((a) => a.startsWith("--target="));
     const target = targetFlag ? targetFlag.split("=")[1] : "CLAUDE.md";
@@ -1237,11 +1366,24 @@ function scaffoldSpec(args) {
     const targetAbs = (0, node_path_1.resolve)(process.cwd(), target);
     if ((0, node_fs_1.existsSync)(targetAbs) && !targetHasHash(targetAbs)) {
         const md = (0, node_fs_1.readFileSync)(targetAbs, "utf-8");
-        const { source, tier, sectionCount } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target));
         (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(specAbs), { recursive: true });
-        (0, node_fs_1.writeFileSync)(specAbs, source);
-        console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
-            `Run \`vigiles compile\` and review the diff; the \`/strengthen\` skill upgrades prose to verified rules.`);
+        const kind = surfaceKind(target);
+        if (kind === "skill") {
+            const { source, unmappedKeys } = (0, adopt_js_1.adoptSkill)(md, (0, node_path_1.basename)((0, node_path_1.dirname)(target)));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            logAdoptedSurface(target, specPath, "skill", unmappedKeys);
+        }
+        else if (kind === "agent") {
+            const { source, unmappedKeys } = (0, adopt_js_1.adoptAgent)(md, (0, node_path_1.basename)(target, ".md"));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            logAdoptedSurface(target, specPath, "subagent", unmappedKeys);
+        }
+        else {
+            const { source, tier, sectionCount } = (0, adopt_js_1.adoptMarkdown)(md, (0, node_path_1.basename)(target));
+            (0, node_fs_1.writeFileSync)(specAbs, source);
+            console.log(`Adopted ${target} → ${specPath} (${tier}, ${String(sectionCount)} section${sectionCount === 1 ? "" : "s"}). ` +
+                `Run \`vigiles compile\` and review the diff; the \`/strengthen\` skill upgrades prose to verified rules.`);
+        }
         return;
     }
     // The compiled output is derived from the spec FILE path; the spec's `target`
@@ -1768,9 +1910,15 @@ async function setupPillar1(detected, targetValue, harnesses) {
     // An explicit --target is honoured as-is; otherwise collapse a CLAUDE.md⇄
     // AGENTS.md mirror (symlink or synced) to one canonical spec, then redirect
     // into a sync tool's source slot when one would own the output.
-    const targets = targetValue
+    const instructionTargets = targetValue
         ? determineTargets(detected, targetValue, harnesses)
         : redirectSyncToolTargets(cwd, collapseMirroredTargets(determineTargets(detected, targetValue, harnesses), (0, compose_js_1.detectInstructionMirror)(cwd)));
+    // Bare `init` (no explicit --target) also adopts every existing skill +
+    // subagent surface — "create all the specs it can", not just the instruction
+    // file. An explicit --target stays scoped to that one surface.
+    const targets = targetValue
+        ? instructionTargets
+        : [...instructionTargets, ...discoverAdoptableSurfaces(cwd)];
     // Create specs. An existing hand-written target is faithfully ADOPTED into a
     // spec (scaffoldSpec() does the convert), not clobbered with a blank one — so the
     // compile below reproduces it (the user reviews the diff). A greenfield target
@@ -3217,6 +3365,7 @@ function printUsage(command) {
     console.log("  vigiles audit [dir...]          Lighthouse for your harness — a LOCAL report: rings + what's broken + fixes (a deterministic read; 2+ dirs → leaderboard)");
     console.log("                                 writes vigiles-report.html + vigiles-report.json (--no-html/--no-json) · --json for machine output. NOT a CI step — use `vigiles lint` in CI.");
     console.log("                                 the executing checks (run your hooks · live MCP · do skills fire?) run only interactively — `audit` asks once (remembered); automation uses the vigiles/testing API");
+    console.log("                                 --serve opens a LIVE local report whose buttons create specs in one click (own repo only; loopback + token-guarded) · --no-serve to skip the prompt");
     console.log("  vigiles test [files...]        Run *.harness.mjs deterministic harness tests");
     console.log("  vigiles eval [files...]        Run *.eval.mjs real-model harness evals (--trials=N, --min=N, --no-skip)");
     console.log("  vigiles scaffold-test [dir]    Generate a starter test for each untested skill/agent/hook (--write, --json)");
@@ -4073,6 +4222,63 @@ function writeAuditHtml(report) {
         console.log(`\n⚠ skipped vigiles-report.html: ${e instanceof Error ? e.message : String(e)}`);
     }
 }
+/**
+ * Start the live (`--serve`) adoption server: render the report with a per-run
+ * token, serve it on loopback, and run `init` in-process when a button POSTs. The
+ * security model lives in src/audit-serve.ts (token + Origin + allowlist). Blocks
+ * until the user stops it (Ctrl-C or the page's Done). Own-repo only — the caller
+ * gates this via decideServeGate, so adopt always writes into the current repo.
+ */
+async function runAuditServe(report, adoptable, cliErr) {
+    const token = (0, audit_serve_js_1.newToken)();
+    const surfaces = new Set((adoptable?.surfaces ?? []).map((s) => s.path));
+    let html;
+    try {
+        html = (0, audit_html_js_1.renderAuditHtml)(report, { token });
+    }
+    catch (e) {
+        console.log(`\n⚠ can't serve the live report: ${cliErr(e)}`);
+        return;
+    }
+    const adoptOne = (target) => {
+        try {
+            scaffoldSpec(["--target=" + target]); // in-process; writes into cwd (own repo)
+            return Promise.resolve({
+                ok: true,
+                message: `created spec for ${target}`,
+            });
+        }
+        catch (e) {
+            return Promise.resolve({ ok: false, message: cliErr(e) });
+        }
+    };
+    console.log("\n  Live report — create specs with one click. Ctrl-C to stop.\n");
+    await (0, audit_serve_js_1.serveAudit)({
+        token,
+        surfaces,
+        html,
+        runAdopt: adoptOne,
+        runAdoptAll: () => {
+            try {
+                for (const p of surfaces)
+                    scaffoldSpec(["--target=" + p]);
+                return Promise.resolve({
+                    ok: true,
+                    message: `created ${String(surfaces.size)} spec(s)`,
+                });
+            }
+            catch (e) {
+                return Promise.resolve({ ok: false, message: cliErr(e) });
+            }
+        },
+        onListening: (url) => {
+            console.log(`  ${url}`);
+            if (process.stdout.isTTY)
+                openBestEffort(url);
+        },
+    });
+    console.log("\n✓ live report closed");
+}
 /**
  * Run the model trigger tier with no `--prompts`: auto-generate diverse probe
  * prompts from each skill's description and measure trigger-rate (recall +
@@ -4097,19 +4303,54 @@ async function runAutoTrigger(dir, report, adapter, args) {
     if (!json) {
         console.log("\nℹ auto-generated probe prompts from skill descriptions (pass --prompts=<file> for a curated set).");
     }
+    const model = flagValue(args, "--model");
     const trigger = await (0, scan_behavioral_js_1.probePluginTriggers)(dir, promptSet, {
         minPrompts: audit_prompts_js_1.AUTO_RECALL_COUNT,
         minDistance: audit_prompts_js_1.AUTO_MIN_DISTANCE,
-        model: flagValue(args, "--model"),
+        model,
         harness,
         // Discover candidates with the resolved adapter's layout/dialect — a Codex
         // repo's skills live under the Codex layout, not the default CC one.
         layout: adapter.layout,
         dialect: adapter.dialect,
     });
-    console.log(json
-        ? JSON.stringify({ trigger }, null, 2)
-        : "\n" + (0, scan_behavioral_js_1.formatBehavioralReport)(trigger));
+    // Second behavioral eval (same consent): the selection-collision matrix — does
+    // one skill HIJACK a sibling's prompt? This is the MEASURED confirmation of the
+    // deterministic description-overlap proxy (the Triggering ring flags look-alikes;
+    // this proves the wrong one actually fires). Only meaningful with ≥2 model-
+    // invocable skills (a lone skill can't collide); reuses the same auto prompts.
+    const collisions = skills.length >= 2
+        ? await (0, scan_behavioral_js_1.measurePluginSelection)(dir, promptSet, { model, harness })
+        : null;
+    // Third behavioral eval (same consent): adversarial-gate — do enforcement-gate
+    // skills HOLD when the agent is told to violate them? Auto-derives its own
+    // attacks; a no-op (no model calls) when the plugin declares no gate skills.
+    const gates = await (0, scan_behavioral_js_1.measureGateAdversarial)(dir, {
+        model,
+        harness,
+        layout: adapter.layout,
+        dialect: adapter.dialect,
+    });
+    // Show the gate section when gate skills were DETECTED — even if the eval
+    // couldn't RUN (a Codex audit, or no `claude` CLI) it returns available:false
+    // with empty results, and `formatGateReport` renders the "unavailable" note.
+    // The consent prompt already advertised these gate skills, so a skipped check
+    // must be reported LOUDLY, never silently omitted as if there were none.
+    const hasGates = gates.results.length > 0 || (0, scan_behavioral_js_1.detectGateSkills)(report.skills).length > 0;
+    if (json) {
+        console.log(JSON.stringify({
+            trigger,
+            ...(collisions ? { collisions } : {}),
+            ...(hasGates ? { gates } : {}),
+        }, null, 2));
+    }
+    else {
+        console.log("\n" + (0, scan_behavioral_js_1.formatBehavioralReport)(trigger));
+        if (collisions)
+            console.log("\n" + (0, scan_behavioral_js_1.formatSelectionReport)(collisions));
+        if (hasGates)
+            console.log("\n" + (0, scan_behavioral_js_1.formatGateReport)(gates));
+    }
 }
 /**
  * The ONE read-vs-run decision for a single-plugin `audit`. A plain `audit` is a
@@ -4159,7 +4400,17 @@ function buildExecuteDisclosure(s, harness) {
     if (s.hasMcp)
         lines.push("  · start your MCP servers — connects to their backends");
     if (s.triggerableSkills > 0) {
-        lines.push(`  · measure whether skills fire (${triggerCostWording(harness)})`);
+        // ≥2 model-invocable skills also get the selection-collision matrix (does one
+        // skill hijack a sibling's prompt) — disclose it so the consent stays honest.
+        const what = s.triggerableSkills >= 2
+            ? "measure whether skills fire and collide"
+            : "measure whether skills fire";
+        lines.push(`  · ${what} (${triggerCostWording(harness)})`);
+    }
+    if (s.gateSkills > 0) {
+        // The adversarial-gate eval runs the FULL (unstubbed) skill — the most
+        // expensive check — so disclose it separately when gate skills are present.
+        lines.push(`  · test whether ${String(s.gateSkills)} enforcement-gate skill${s.gateSkills === 1 ? "" : "s"} hold under pressure — runs the full skill (${triggerCostWording(harness)})`);
     }
     if (s.adoptableRefs) {
         lines.push(`  · draft + verify your instruction file's references (${triggerCostWording(harness)})`);
@@ -4339,7 +4590,10 @@ async function main() {
                 // through to a misleading "empty machine / no structural issues" report
                 // (obra/superpowers-marketplace, anthropics/claude-plugins-community).
                 if (json) {
-                    console.log(JSON.stringify(market, null, 2));
+                    console.log(JSON.stringify((0, audit_report_js_1.buildMarketplaceReport)(market, {
+                        vigilesVersion: getVersion(),
+                        dir: (0, node_path_1.resolve)(dirs[0]),
+                    }), null, 2));
                 }
                 else {
                     console.log(`Marketplace "${market.name}": ${String(market.total)} plugin(s), all external ` +
@@ -4355,7 +4609,12 @@ async function main() {
                 const text = args.includes("--md")
                     ? (0, leaderboard_js_1.formatLeaderboardMarkdown)(scores)
                     : (0, leaderboard_js_1.formatLeaderboard)(scores);
-                console.log(json ? JSON.stringify(scores, null, 2) : text);
+                console.log(json
+                    ? JSON.stringify((0, audit_report_js_1.buildLeaderboardReport)(scores, {
+                        vigilesVersion: getVersion(),
+                        dir: (0, node_path_1.resolve)(dirs[0]),
+                    }), null, 2)
+                    : text);
             }
             else {
                 const root = (0, node_path_1.resolve)(targets[0]);
@@ -4383,9 +4642,15 @@ async function main() {
                 // HTML renders, `--json` emits, and (later) a hosted dashboard ingests.
                 // Built ONCE; the rings + fix list are read off it. Pure deterministic —
                 // nothing executes to produce it.
+                // Surfaces that exist but aren't spec-managed yet — the same notion
+                // `init` adopts (layout-driven instruction file + skill/subagent sweep).
+                // Surfaced in the AuditReport (the report's "Create spec" command-emit
+                // buttons read it) and the terminal nudge below.
+                const adoptableSurfaces = discoverAdoptableForAudit(root, adapter.layout.instructionFile);
                 const auditReport = (0, audit_report_js_1.buildAuditReport)(report, {
                     harness: adapter.name,
                     vigilesVersion: getVersion(),
+                    adoptableSurfaces,
                 });
                 const sc = auditReport.score;
                 const plan = (0, optimize_js_1.optimize)(report);
@@ -4404,6 +4669,18 @@ async function main() {
                     const fixes = (0, optimize_js_1.formatRecommendations)(plan);
                     if (fixes)
                         console.log("\n" + fixes);
+                    // Adoption nudge: surfaces that exist but aren't spec-managed yet, with
+                    // the create-all + per-surface `init` commands (the JSON carries the
+                    // data in `adoptable` instead — the terminal stays human-readable).
+                    const adoptNudge = formatAdoptableNudge(adoptableSurfaces);
+                    if (adoptNudge)
+                        console.log("\n" + adoptNudge);
+                    // A small behavioral nudge — the deterministic read can't tell whether
+                    // skills actually FIRE; point at the interactive measure + the API.
+                    const fireNudge = formatTriggerNudge(report.skills.filter((s) => s.hasDescription && !s.userInvoked)
+                        .length);
+                    if (fireNudge)
+                        console.log("\n" + fireNudge);
                 }
                 // ONE read-vs-run decision for the EXECUTING checks (live MCP + skill
                 // firing). A plain `audit` is a deterministic READ; these run only on
@@ -4415,6 +4692,7 @@ async function main() {
                 const surfaces = {
                     hasMcp: report.mcp && !isForeign,
                     triggerableSkills: report.skills.filter((s) => s.hasDescription && !s.userInvoked).length,
+                    gateSkills: (0, scan_behavioral_js_1.detectGateSkills)(report.skills).length,
                     adoptableRefs: adapter.name === "claude-code" &&
                         (0, node_fs_1.existsSync)((0, node_path_1.resolve)(root, adapter.layout.instructionFile)),
                 };
@@ -4501,17 +4779,36 @@ async function main() {
                 const finalReport = adoptabilityResult
                     ? { ...auditReport, adoptability: adoptabilityResult }
                     : auditReport;
-                // The shareable HTML report — written by default (--no-html to skip), and
-                // opened best-effort only for a human at a TTY (never spawn a browser for
-                // an agent / CI run).
-                if (!json && !args.includes("--no-html")) {
-                    writeAuditHtml(finalReport);
-                }
                 // The versioned JSON artifact — the upload/CI boundary (a hosted dashboard
                 // ingests this). Written by default in the human path; --no-json to skip.
                 if (!json && !args.includes("--no-json")) {
                     writeAuditJson(finalReport);
                 }
+                // The HTML report has two deliveries. STATIC (default): write the
+                // shareable file whose buttons copy the `init` command. LIVE (`--serve`,
+                // or a TTY "yes"): start a loopback server whose buttons run `init` for
+                // you. The gate keeps the default a terminating, headless-safe read and
+                // restricts the write-server to your own repo (decideServeGate).
+                const serveGate = (0, audit_serve_js_1.decideServeGate)({
+                    serveFlag: args.includes("--serve"),
+                    noServeFlag: args.includes("--no-serve"),
+                    json,
+                    isTTY: process.stdout.isTTY && process.stdin.isTTY,
+                    ownRepo: !isForeign,
+                    adoptableCount: finalReport.adoptable?.surfaces.length ?? 0,
+                });
+                let serveLive = serveGate === "serve";
+                if (serveGate === "ask") {
+                    const ans = (await askOnce("\nOpen the live report to create specs with one click? [y/N] ")).toLowerCase();
+                    serveLive = ans === "y" || ans === "yes";
+                }
+                const errMsg = (e) => e instanceof Error ? e.message : String(e);
+                if (serveLive) {
+                    await runAuditServe(finalReport, finalReport.adoptable, errMsg);
+                }
+                else if (!json && !args.includes("--no-html")) {
+                    writeAuditHtml(finalReport);
+                }
             }
             break;
         }

package/dist/core/adopt.d.ts

@@ -18,6 +18,7 @@
  * vs `enforce()` is deliberately NOT guessed here — that cross-referencing is
  * `strengthen`'s separate, later job; adoption is lossless transcription.
  */
+import { type SkillSpec, type AgentSpec } from "./spec.js";
 export type AdoptTier = "structured" | "raw";
 export interface AdoptResult {
     /** Generated `.spec.ts` source (compiles back to ~the original file). */
@@ -62,4 +63,31 @@ export declare function adoptToSpec(markdown: string, target: string): AdoptedSp
  * (the deliverable `init` writes).
  */
 export declare function adoptMarkdown(markdown: string, target: string): AdoptResult;
+export interface AdoptSurfaceResult {
+    /** Generated `.spec.ts` source. */
+    source: string;
+    kind: "skill" | "agent";
+    /**
+     * The parsed spec object the source builds — exposed so a round-trip test can
+     * feed it straight to `compileSkill`/`compileAgent` without evaluating the
+     * generated TS (the same split as `adoptToSpec`/`renderSpecSource`).
+     */
+    spec: SkillSpec | AgentSpec;
+    /**
+     * Frontmatter keys present in the source that the typed spec has no field for
+     * — emitted as a `// NOTE:` comment in the source so nothing is lost silently.
+     */
+    unmappedKeys: string[];
+}
+/**
+ * Adopt an existing SKILL.md into a `skill()` spec. The body is carried verbatim
+ * (skills are freeform markdown — `##` headings stay in the body), so a clean
+ * skill round-trips below the integrity header.
+ *
+ * @param markdown the SKILL.md content
+ * @param dirName  the skill's directory name — the CC fallback for `name` when
+ *   frontmatter omits it
+ */
+export declare function adoptSkill(markdown: string, dirName: string): AdoptSurfaceResult;
+export declare function adoptAgent(markdown: string, fileBase: string): AdoptSurfaceResult;
 //# sourceMappingURL=adopt.d.ts.map