@phamvuhoang/otto-core 0.25.0 → 0.27.0

package/dist/skill-validation.js

@@ -0,0 +1,376 @@
+import { createHash } from "node:crypto";
+import { parseFrontmatter } from "./external-skills.js";
+import { toSkillName } from "./skills.js";
+/** sha256 of a skill's instruction body, hex. The hash domain matches the */
+/** imported-package checksum in `external-skills.ts` so drift compares cleanly. */
+export function skillChecksum(instructions) {
+    return createHash("sha256").update(instructions).digest("hex");
+}
+/**
+ * Map one capability tag to the stage it scopes to, or null when it does not
+ * imply a specific stage (a general capability → afk-safe, not stage-scoped).
+ * Mirrors the P18 stage capability tags in the roadmap.
+ */
+const CAPABILITY_STAGE = new Map([
+    ["planning", "plan"],
+    ["roadmap-planning", "plan"],
+    ["prd", "plan"],
+    ["prioritization", "plan"],
+    ["problem-framing", "plan"],
+    ["discovery", "plan"],
+    ["tdd", "implement"],
+    ["coding", "implement"],
+    ["refactor", "implement"],
+    ["code-review", "review"],
+    ["review", "review"],
+    ["security", "review"],
+    ["structural", "review"],
+    ["reporting", "report"],
+    ["report", "report"],
+    ["journal", "journal"],
+    ["context-engineering", "tool-output"],
+    ["compression", "tool-output"],
+]);
+/** The stages a skill's capabilities imply (sorted, de-duplicated). */
+function impliedStages(capabilities) {
+    const stages = new Set();
+    for (const cap of capabilities) {
+        const stage = CAPABILITY_STAGE.get(cap.toLowerCase());
+        if (stage)
+            stages.add(stage);
+    }
+    return [...stages].sort();
+}
+/**
+ * Derive a {@link SkillCompatibility} class from a validation report (issue
+ * #134), as a priority ladder: an error-severity finding → `blocked` (cannot be
+ * applied anywhere); an interactive hard stop → `interactive-only` (needs a human,
+ * so AFK-unsafe even when otherwise valid); capabilities that imply specific
+ * stages → `stage-scoped` (with the stage list); otherwise `afk-safe`. Pure.
+ */
+export function classifyCompatibility(report) {
+    if (report.findings.some((f) => f.severity === "error")) {
+        return { compatibility: "blocked", stages: [] };
+    }
+    if (report.findings.some((f) => f.rule === "interactive-hard-stop")) {
+        return { compatibility: "interactive-only", stages: [] };
+    }
+    const stages = impliedStages(report.capabilities);
+    if (stages.length > 0) {
+        return { compatibility: "stage-scoped", stages };
+    }
+    return { compatibility: "afk-safe", stages: [] };
+}
+/**
+ * Static manifest/schema lint. Checks the structural invariants a usable skill
+ * package must hold: a filesystem-safe name, a non-empty instruction body, at
+ * least one capability (the retrieval key), and a set version. Returns one
+ * finding per broken rule; a well-formed manifest yields `[]`.
+ */
+export function lintManifest(skill) {
+    const findings = [];
+    if (toSkillName(skill.name) !== skill.name) {
+        findings.push({
+            kind: "manifest",
+            severity: "error",
+            rule: "name-slug",
+            message: `name "${skill.name}" is not a filesystem-safe slug`,
+            remediation: `rename the package to "${toSkillName(skill.name)}"`,
+        });
+    }
+    if (skill.instructions.trim().length === 0) {
+        findings.push({
+            kind: "manifest",
+            severity: "error",
+            rule: "empty-instructions",
+            message: "the skill has no instruction body",
+            remediation: "add the procedure to instructions.md",
+        });
+    }
+    if (skill.capabilities.length === 0) {
+        findings.push({
+            kind: "manifest",
+            severity: "warn",
+            rule: "no-capabilities",
+            message: "no capabilities declared — retrieval cannot key on this skill",
+            remediation: "declare capability tags (e.g. planning, tdd, code-review)",
+        });
+    }
+    if (skill.version === "0.0.0" || skill.version.trim().length === 0) {
+        findings.push({
+            kind: "manifest",
+            severity: "warn",
+            rule: "unversioned",
+            message: `version "${skill.version}" looks unset`,
+            remediation: "set a real version so drift and revalidation can be tracked",
+        });
+    }
+    return findings;
+}
+/**
+ * Extract the skill's effective capabilities: the manifest `capabilities` plus
+ * any declared in a leading frontmatter block in the instruction body (skill
+ * packs often carry `capabilities:` there). De-duplicated, manifest order first.
+ */
+export function extractCapabilities(skill) {
+    const out = [...skill.capabilities];
+    const { fields } = parseFrontmatter(skill.instructions);
+    const raw = fields.capabilities;
+    if (raw) {
+        for (const cap of raw
+            .replace(/^\[|\]$/g, "")
+            .split(",")
+            .map((s) => s.trim().replace(/^["']|["']$/g, ""))
+            .filter((s) => s.length > 0)) {
+            if (!out.includes(cap))
+                out.push(cap);
+        }
+    }
+    return out;
+}
+/**
+ * License/provenance check. For an imported skill (has `provenance`): the
+ * upstream ref must be pinned and a license declared, and when an explicit
+ * `--source` is given it must match the recorded source. For a repo-authored
+ * skill (no provenance) there is nothing external to check — but asserting a
+ * `--source` against it is an error, since it was never imported.
+ */
+export function checkProvenance(skill, source) {
+    const findings = [];
+    const p = skill.provenance;
+    if (!p) {
+        if (source !== undefined) {
+            findings.push({
+                kind: "provenance",
+                severity: "error",
+                rule: "not-imported",
+                message: `--source "${source}" was given but "${skill.name}" is repo-authored (no provenance)`,
+                remediation: "drop --source, or import the skill via otto-skills sync",
+            });
+        }
+        return findings;
+    }
+    if (source !== undefined && p.source !== source) {
+        findings.push({
+            kind: "provenance",
+            severity: "error",
+            rule: "source-mismatch",
+            message: `--source "${source}" does not match recorded source "${p.source}"`,
+            remediation: `validate with --source ${p.source}, or re-import from ${source}`,
+        });
+    }
+    if (!p.upstreamRef) {
+        findings.push({
+            kind: "provenance",
+            severity: "warn",
+            rule: "unpinned-ref",
+            message: `imported "${skill.name}" has no pinned upstream ref`,
+            remediation: "pin the source: otto-skills sources add <name> <url> --ref <sha-or-tag>",
+        });
+    }
+    if (!p.license) {
+        findings.push({
+            kind: "provenance",
+            severity: "warn",
+            rule: "missing-license",
+            message: `imported "${skill.name}" declares no license`,
+            remediation: "add a license: field to the upstream SKILL.md and re-sync",
+        });
+    }
+    return findings;
+}
+const RISK_PATTERNS = [
+    // Unsafe shell advice — destructive or self-elevating commands.
+    {
+        rule: "unsafe-shell",
+        severity: "error",
+        re: /\brm\s+-[a-z]*[rf][a-z]*\s+(?:-[a-z]+\s+)*(?:\/|~|\$\w|\*)/i,
+        message: (h) => `destructive delete in shell advice: "${h.trim()}"`,
+        remediation: "scope deletes to a named path; never rm -rf / ~ or $VAR",
+    },
+    {
+        rule: "unsafe-shell",
+        severity: "error",
+        re: /\b(?:curl|wget)\b[^\n|]*\|\s*(?:sudo\s+)?(?:ba|z|da|)sh\b/i,
+        message: (h) => `pipes a download straight into a shell: "${h.trim()}"`,
+        remediation: "download, inspect, then run — never pipe a fetch into a shell",
+    },
+    {
+        rule: "unsafe-shell",
+        severity: "error",
+        re: /\bsudo\s+\S+/i,
+        message: (h) => `requires elevated privileges: "${h.trim()}"`,
+        remediation: "AFK runs unprivileged; remove sudo and operate in the workspace",
+    },
+    {
+        rule: "unsafe-shell",
+        severity: "error",
+        re: /\bchmod\s+(?:-[a-z]+\s+)*777\b/i,
+        message: (h) => `world-writable permissions: "${h.trim()}"`,
+        remediation: "grant least-privilege permissions instead of 777",
+    },
+    // Secret handling — printing/echoing/logging credentials.
+    {
+        rule: "secret-handling",
+        severity: "error",
+        re: /\b(?:echo|print|printf|cat|log|paste|export)\b[^\n]{0,40}\b(?:[A-Z0-9_]*(?:SECRET|PASSWORD|API[_-]?KEY|TOKEN|CREDENTIAL)[A-Z0-9_]*)\b/i,
+        message: (h) => `exposes a secret: "${h.trim()}"`,
+        remediation: "never echo/log secrets; read them from the environment only",
+    },
+    // Network use — fetch commands that AFK policy may forbid.
+    {
+        rule: "network-use",
+        severity: "warn",
+        re: /\b(?:curl|wget|nc|netcat|ssh|scp|telnet)\s+\S+/i,
+        message: (h) => `performs network I/O: "${h.trim()}"`,
+        remediation: "AFK network is policy-scoped; declare needed domains in .otto/policy.json or avoid the call",
+    },
+    // Interactive hard stops — block AFK, mark the skill interactive-only.
+    {
+        rule: "interactive-hard-stop",
+        severity: "warn",
+        re: /\b(?:ask|prompt|wait for|confirm with|check with|get approval from)\b[^\n]{0,20}\b(?:the\s+)?(?:user|human|operator|reviewer)\b|\bdo not proceed until\b|\bSTOP and (?:ask|wait)\b|\bwait for (?:confirmation|approval|input)\b/i,
+        message: (h) => `requires human interaction: "${h.trim()}"`,
+        remediation: "provide an autonomous default for AFK, or classify the skill interactive-only",
+    },
+    // Unsupported tool assumptions — GUI/IDE/browser the AFK runtime lacks.
+    {
+        rule: "unsupported-tool",
+        severity: "warn",
+        re: /\b(?:open your browser|in your IDE|open .{0,20}in (?:vs ?code|the editor)|click (?:the|on)|drag and drop|take a screenshot)\b/i,
+        message: (h) => `assumes an interactive tool the AFK runtime lacks: "${h.trim()}"`,
+        remediation: "replace GUI/IDE steps with CLI/file operations",
+    },
+    // Conflicting hierarchy — attempts to overrule repo policy / prior context.
+    {
+        rule: "conflicting-hierarchy",
+        severity: "error",
+        re: /\b(?:ignore|disregard|override|bypass|forget)\b[^\n]{0,30}\b(?:previous|prior|above|all)?\s*(?:instructions?|system prompt|repo policy|safety|policy|agents\.md|rules?)\b/i,
+        message: (h) => `tries to overrule the instruction hierarchy: "${h.trim()}"`,
+        remediation: "skills are advisory; remove overrule language — repo policy and stage contracts win",
+    },
+];
+/**
+ * Scan a skill's instruction body for the six P17 risk categories (issue #133):
+ * unsafe shell advice, secret handling, network use, interactive hard stops,
+ * unsupported tool assumptions, and conflicting hierarchy (a skill trying to
+ * overrule repo policy). Each finding names the exact matched phrase and a
+ * remediation. Pure, deterministic, conservative — benign guidance yields `[]`.
+ */
+export function scanInstructionRisks(instructions) {
+    const findings = [];
+    for (const p of RISK_PATTERNS) {
+        const m = p.re.exec(instructions);
+        if (m) {
+            findings.push({
+                kind: "risk",
+                severity: p.severity,
+                rule: p.rule,
+                message: p.message(m[0]),
+                remediation: p.remediation,
+            });
+        }
+    }
+    return findings;
+}
+/**
+ * The standard drills from the roadmap (issue #135): a Superpowers planning/TDD
+ * drill (the methodology must be usable, not interactive-only/blocked), a PM
+ * roadmap/PRD drill (must scope to the plan stage), and a review drill (a review
+ * skill must not try to overrule repo policy).
+ */
+export const STANDARD_DRILLS = [
+    {
+        name: "planning-tdd-usable",
+        description: "a planning/TDD skill must be applicable, not interactive-only or blocked",
+        appliesTo: ["planning", "tdd"],
+        expectClassIn: ["afk-safe", "stage-scoped"],
+        forbidRules: [],
+    },
+    {
+        name: "pm-roadmap-prd-stage-scoped",
+        description: "a PM roadmap/PRD skill must scope to a stage (plan), not be blocked",
+        appliesTo: ["roadmap-planning", "prd"],
+        expectClassIn: ["stage-scoped", "afk-safe"],
+        forbidRules: [],
+    },
+    {
+        name: "review-respects-policy",
+        description: "a review skill must not try to overrule repo policy",
+        appliesTo: ["code-review", "review"],
+        expectClassIn: ["stage-scoped", "afk-safe"],
+        forbidRules: ["conflicting-hierarchy"],
+    },
+];
+/**
+ * Run behavior drills against a validation report (issue #135). A drill applies
+ * when the skill declares one of its `appliesTo` capabilities; an applied drill
+ * passes when the report's class is in `expectClassIn` and none of its
+ * `forbidRules` fired. A non-applicable drill is reported `applied: false,
+ * passed: true` so it never blocks an unrelated skill. Pure, deterministic.
+ */
+export function runDrills(report, drills = STANDARD_DRILLS) {
+    const caps = new Set(report.capabilities.map((c) => c.toLowerCase()));
+    return drills.map((drill) => {
+        const applied = drill.appliesTo.some((c) => caps.has(c.toLowerCase()));
+        if (!applied) {
+            return {
+                drill: drill.name,
+                applied: false,
+                passed: true,
+                detail: "not in scope",
+            };
+        }
+        const classOk = drill.expectClassIn.includes(report.compatibility);
+        const firedForbidden = drill.forbidRules.filter((r) => report.findings.some((f) => f.rule === r));
+        const passed = classOk && firedForbidden.length === 0;
+        const detail = passed
+            ? `class ${report.compatibility} accepted`
+            : !classOk
+                ? `class ${report.compatibility} not in {${drill.expectClassIn.join(", ")}}`
+                : `forbidden finding(s): ${firedForbidden.join(", ")}`;
+        return { drill: drill.name, applied: true, passed, detail };
+    });
+}
+/**
+ * Whether a statically-validated skill must be revalidated before reuse (issue
+ * #135). True when the skill carries a recorded `instructionsChecksum` (it was
+ * validated) but its current body no longer hashes to it — the skill drifted
+ * (e.g. an upstream re-sync changed it) since the gate last ran. A skill that was
+ * never statically validated has nothing to revalidate, so this is false. Pure.
+ */
+export function needsRevalidation(skill) {
+    const recorded = skill.validation.instructionsChecksum;
+    if (!recorded)
+        return false;
+    return skillChecksum(skill.instructions) !== recorded;
+}
+/**
+ * Run the full static gate over one skill and aggregate the result: manifest
+ * lint, capability extraction, provenance check (#132), instruction-risk scan
+ * (#133), derived compatibility class (#134), and behavior drills (#135). `ok` is
+ * false when any `error`-severity finding fired OR an applicable drill failed.
+ * Pure — the caller decides whether to persist or print the report.
+ */
+export function validateSkill(skill, opts = {}) {
+    const findings = [
+        ...lintManifest(skill),
+        ...checkProvenance(skill, opts.source),
+        ...scanInstructionRisks(skill.instructions),
+    ];
+    const base = {
+        skill: skill.name,
+        capabilities: extractCapabilities(skill),
+        findings,
+        ok: !findings.some((f) => f.severity === "error"),
+        compatibility: "afk-safe",
+        stages: [],
+        checksum: skillChecksum(skill.instructions),
+        drills: [],
+    };
+    const { compatibility, stages } = classifyCompatibility(base);
+    const drills = runDrills({ ...base, compatibility, stages });
+    const ok = base.ok && drills.every((d) => d.passed);
+    return { ...base, compatibility, stages, drills, ok };
+}
+//# sourceMappingURL=skill-validation.js.map

package/dist/skill-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-validation.js","sourceRoot":"","sources":["../src/skill-validation.ts"],"names":[],"mappings":"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"}

package/dist/skills-cli.d.ts

@@ -1,4 +1,6 @@
 import { type ExternalAuditFinding, type ExternalSkillSource, type SyncPlan } from "./external-skills.js";
+import { type SkillValidationReport } from "./skill-validation.js";
+import { type SkillRouteResult } from "./skill-routing.js";
 import { type Skill, type SkillCandidate, type SkillMatch } from "./skills.js";
 /**
  * Injectable host surface for {@link runSkills} so the bin stays unit-testable
@@ -26,12 +28,24 @@ export declare function formatSkillsAudit(skills: Skill[], now?: Date): string;
  * "inspect why a skill was selected" metric). Pure.
  */
 export declare function formatWhy(matches: SkillMatch[]): string;
+/**
+ * Render the stage-routing explanation (issue #140 P18): which validated skills
+ * would be injected into `stageName` and why, plus the char-budget accounting —
+ * so a user can reproduce the runtime selection from the CLI alone. Pure.
+ */
+export declare function formatWhyStage(stageName: string, result: SkillRouteResult): string;
 /** Render the candidate skills suggested from repeated successful runs. Pure. */
 export declare function formatCandidates(candidates: SkillCandidate[]): string;
 /** Render the configured external sources, sorted. Pure. */
 export declare function formatSources(sources: ExternalSkillSource[]): string;
 /** Render a sync plan; `dryRun` flips the header between preview and applied. Pure. */
 export declare function formatSyncPlan(plan: SyncPlan, dryRun: boolean): string;
+/**
+ * Render a skill validation report (issue #113 P17): the extracted capabilities,
+ * each finding with its severity/rule/message/remediation, and a pass/fail line.
+ * Pure — the bin decides the exit code from `report.ok`.
+ */
+export declare function formatValidationReport(report: SkillValidationReport): string;
 /** Render the external-registry audit findings. Pure. */
 export declare function formatExternalAudit(findings: ExternalAuditFinding[]): string;
 /**

package/dist/skills-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skills-cli.d.ts","sourceRoot":"","sources":["../src/skills-cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAUL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAExB,KAAK,QAAQ,EACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAOL,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAqBF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,KAAK,EAAE,EACf,GAAG,GAAE,IAAiB,GACrB,MAAM,CAcR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,KAAK,EAAE,EACf,GAAG,GAAE,IAAiB,GACrB,MAAM,CAmBR;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAUvD;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,CAWrE;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAWpE;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAqBtE;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAK5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,UAAwB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAuEjB"}
+{"version":3,"file":"skills-cli.d.ts","sourceRoot":"","sources":["../src/skills-cli.ts"],"names":[],"mappings":"AAEA,OAAO,EAUL,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EAExB,KAAK,QAAQ,EACd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAGL,KAAK,qBAAqB,EAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAuB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAChF,OAAO,EAUL,KAAK,KAAK,EACV,KAAK,cAAc,EACnB,KAAK,UAAU,EAChB,MAAM,aAAa,CAAC;AAErB;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B,CAAC;AAuBF;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,KAAK,EAAE,EACf,GAAG,GAAE,IAAiB,GACrB,MAAM,CAcR;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,KAAK,EAAE,EACf,GAAG,GAAE,IAAiB,GACrB,MAAM,CA6BR;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAUvD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,gBAAgB,GACvB,MAAM,CAkBR;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,CAWrE;AAED,4DAA4D;AAC5D,wBAAgB,aAAa,CAAC,OAAO,EAAE,mBAAmB,EAAE,GAAG,MAAM,CAWpE;AAED,uFAAuF;AACvF,wBAAgB,cAAc,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,CAqBtE;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,CA8B5E;AAED,yDAAyD;AACzD,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,oBAAoB,EAAE,GAAG,MAAM,CAK5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,UAAwB,GAC7B,OAAO,CAAC,MAAM,CAAC,CA8HjB"}

package/dist/skills-cli.js

@@ -1,7 +1,9 @@
 import { resolve } from "node:path";
 import { addSource, applySync, auditExternal, importedChecksum, planSync, readLock, readSources, removeSource, writeSources, } from "./external-skills.js";
 import { listRunIds, readManifest } from "./run-report.js";
-import { findSkillCandidates, readSkills, selectSkills, skillsDir, skillStatus, } from "./skills.js";
+import { needsRevalidation, validateSkill, } from "./skill-validation.js";
+import { routeSkillsForStage } from "./skill-routing.js";
+import { findSkillCandidates, readSkill, readSkills, recordStaticValidation, selectSkills, skillsDir, skillStatus, writeSkill, } from "./skills.js";
 const defaultDeps = {
     env: process.env,
     cwd: process.cwd(),
@@ -10,6 +12,8 @@ const defaultDeps = {
 };
 const USAGE = "Usage: otto-skills <list|audit|candidates>\n" +
     "       otto-skills why <changed-path>...\n" +
+    "       otto-skills why --stage <stage> [--changed <path>...]\n" +
+    "       otto-skills validate <skill> [--source <name>]\n" +
     "       otto-skills sources <list|add|remove> ...\n" +
     "       otto-skills sync [--dry-run]\n" +
     "       otto-skills audit --external";
@@ -54,6 +58,16 @@ export function formatSkillsAudit(skills, now = new Date()) {
     for (const { s, st } of notUsable) {
         lines.push(`  - ${s.name}  [${st}]  (run its tests, then record a validating run)`);
     }
+    // Body-drift detection (issue #135): a statically-validated skill whose body
+    // changed since the gate ran must be revalidated before it is reused.
+    const drifted = skills.filter(needsRevalidation);
+    lines.push("");
+    lines.push(`Needs revalidation — body drifted (${drifted.length}):`);
+    if (drifted.length === 0)
+        lines.push("  (none)");
+    for (const s of drifted) {
+        lines.push(`  - ${s.name}  (re-run: otto-skills validate ${s.name})`);
+    }
     return lines.join("\n");
 }
 /**
@@ -72,6 +86,29 @@ export function formatWhy(matches) {
     }
     return lines.join("\n");
 }
+/**
+ * Render the stage-routing explanation (issue #140 P18): which validated skills
+ * would be injected into `stageName` and why, plus the char-budget accounting —
+ * so a user can reproduce the runtime selection from the CLI alone. Pure.
+ */
+export function formatWhyStage(stageName, result) {
+    const lines = [
+        `Stage '${stageName}' (family: ${result.family ?? "unknown"}) — skill routing:`,
+    ];
+    if (result.verdicts.length === 0) {
+        lines.push("  No skills installed.");
+        return lines.join("\n");
+    }
+    for (const v of result.verdicts) {
+        const tag = v.selected ? "selected" : v.eligible ? "eligible" : "skip";
+        lines.push(`- ${v.name}  [${tag}]  score ${v.score}`);
+        for (const r of v.reasons)
+            lines.push(`    · ${r}`);
+    }
+    lines.push("");
+    lines.push(`budget: ${result.usedChars}/${result.budgetChars} chars used by ${result.selected.length} selected skill(s)`);
+    return lines.join("\n");
+}
 /** Render the candidate skills suggested from repeated successful runs. Pure. */
 export function formatCandidates(candidates) {
     if (candidates.length === 0) {
@@ -116,6 +153,40 @@ export function formatSyncPlan(plan, dryRun) {
     }
     return lines.join("\n");
 }
+/**
+ * Render a skill validation report (issue #113 P17): the extracted capabilities,
+ * each finding with its severity/rule/message/remediation, and a pass/fail line.
+ * Pure — the bin decides the exit code from `report.ok`.
+ */
+export function formatValidationReport(report) {
+    const scope = report.compatibility === "stage-scoped" && report.stages.length
+        ? ` (${report.stages.join(", ")})`
+        : "";
+    const lines = [
+        `Validating skill '${report.skill}'`,
+        `  capabilities: ${report.capabilities.length ? report.capabilities.join(", ") : "(none)"}`,
+        `  compatibility: ${report.compatibility}${scope}`,
+    ];
+    if (report.findings.length === 0) {
+        lines.push("  no findings");
+    }
+    else {
+        for (const f of report.findings) {
+            lines.push(`  [${f.severity}] ${f.rule}: ${f.message}`);
+            lines.push(`      → ${f.remediation}`);
+        }
+    }
+    const applied = report.drills.filter((d) => d.applied);
+    if (applied.length > 0) {
+        lines.push("  drills:");
+        for (const d of applied) {
+            lines.push(`    ${d.passed ? "pass" : "FAIL"}  ${d.drill}: ${d.detail}`);
+        }
+    }
+    lines.push("");
+    lines.push(report.ok ? "PASS (no blocking errors)" : "FAIL (blocking errors present)");
+    return lines.join("\n");
+}
 /** Render the external-registry audit findings. Pure. */
 export function formatExternalAudit(findings) {
     if (findings.length === 0)
@@ -143,7 +214,15 @@ export async function runSkills(argv, deps = defaultDeps) {
         deps.out(USAGE);
         return 0;
     }
-    const known = ["list", "audit", "why", "candidates", "sources", "sync"];
+    const known = [
+        "list",
+        "audit",
+        "why",
+        "validate",
+        "candidates",
+        "sources",
+        "sync",
+    ];
     if (arg !== undefined && !known.includes(arg)) {
         deps.err(`Unknown subcommand '${arg}'.\n${USAGE}`);
         return 1;
@@ -162,14 +241,54 @@ export async function runSkills(argv, deps = defaultDeps) {
     }
     const skills = readSkills(workspaceDir);
     if (arg === "why") {
-        const paths = argv.slice(1);
+        const rest = argv.slice(1);
+        const stage = flagValue(rest, "--stage");
+        if (stage) {
+            // P18: route validated skills for a concrete stage (with optional --changed
+            // paths for scope scoring), explaining the runtime selection.
+            const changedIdx = rest.indexOf("--changed");
+            const changed = changedIdx >= 0
+                ? rest.slice(changedIdx + 1).filter((a) => !a.startsWith("--"))
+                : [];
+            const result = routeSkillsForStage(skills, {
+                stageName: stage,
+                changedPaths: changed,
+            });
+            deps.out(formatWhyStage(stage, result));
+            return 0;
+        }
+        const paths = rest;
         if (paths.length === 0) {
-            deps.err(`why needs at least one changed path.\n${USAGE}`);
+            deps.err(`why needs at least one changed path (or --stage <stage>).\n${USAGE}`);
             return 1;
         }
         deps.out(formatWhy(selectSkills(skills, { changedPaths: paths })));
         return 0;
     }
+    if (arg === "validate") {
+        const rest = argv.slice(1);
+        const name = rest.find((a) => !a.startsWith("--"));
+        if (!name) {
+            deps.err(`validate needs a skill name.\n${USAGE}`);
+            return 1;
+        }
+        const skill = readSkill(workspaceDir, name);
+        if (!skill) {
+            deps.err(`No skill named '${name}' under ${skillsDir(workspaceDir)}.`);
+            return 1;
+        }
+        const source = flagValue(rest, "--source");
+        const report = validateSkill(skill, source ? { source } : {});
+        deps.out(formatValidationReport(report));
+        // Persist the static-gate outcome (issue #134). Recording a class does NOT
+        // make the skill eligible — selection stays a separate concern (P18).
+        writeSkill(workspaceDir, recordStaticValidation(skill, {
+            compatibility: report.compatibility,
+            stages: report.stages,
+            checksum: report.checksum,
+        }));
+        return report.ok ? 0 : 1;
+    }
     if (arg === "candidates") {
         const runs = listRunIds(workspaceDir)
             .map((id) => readManifest(workspaceDir, id))