@phamvuhoang/otto-core 0.13.0 → 0.15.0

package/dist/skills-cli.js

@@ -0,0 +1,137 @@
+import { resolve } from "node:path";
+import { listRunIds, readManifest } from "./run-report.js";
+import { findSkillCandidates, readSkills, selectSkills, skillsDir, skillStatus, } from "./skills.js";
+const defaultDeps = {
+    env: process.env,
+    cwd: process.cwd(),
+    out: (m) => process.stdout.write(`${m}\n`),
+    err: (m) => process.stderr.write(`${m}\n`),
+};
+const USAGE = "Usage: otto-skills <list|audit|candidates>\n" +
+    "       otto-skills why <changed-path>...";
+/** One-line scope label: the globs, or "(repo-wide)" when empty. */
+function scopeLabel(skill) {
+    return skill.scope.length ? skill.scope.join(", ") : "(repo-wide)";
+}
+/**
+ * Render the skill inventory with each skill's DERIVED validation status, trust,
+ * and capabilities/scope. Pure (clock injected). `now` drives freshness.
+ */
+export function formatSkillsReport(skills, now = new Date()) {
+    if (skills.length === 0) {
+        return "No skills yet. A skill is a .otto/skills/<name>/ package (skill.json + instructions.md).";
+    }
+    const lines = [];
+    for (const s of skills) {
+        const caps = s.capabilities.length ? s.capabilities.join(", ") : "(none)";
+        lines.push(`- ${s.name}@${s.version}  [${skillStatus(s, now)}/${s.trust}]  used ${s.useCount}x`);
+        lines.push(`    capabilities: ${caps}`);
+        lines.push(`    scope:        ${scopeLabel(s)}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Render a governance summary: how many skills are validated (auto-usable),
+ * unvalidated, or stale, and which are not yet usable. Pure (clock injected).
+ */
+export function formatSkillsAudit(skills, now = new Date()) {
+    const status = skills.map((s) => ({ s, st: skillStatus(s, now) }));
+    const count = (k) => status.filter((x) => x.st === k).length;
+    const lines = [];
+    lines.push(`  total:        ${skills.length}`);
+    lines.push(`  validated:    ${count("validated")}`);
+    lines.push(`  unvalidated:  ${count("unvalidated")}`);
+    lines.push(`  stale:        ${count("stale")}`);
+    const notUsable = status.filter((x) => x.st !== "validated");
+    lines.push("");
+    lines.push(`Not yet usable (${notUsable.length}):`);
+    if (notUsable.length === 0)
+        lines.push("  (none — all validated)");
+    for (const { s, st } of notUsable) {
+        lines.push(`  - ${s.name}  [${st}]  (run its tests, then record a validating run)`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Render a retrieval explanation: the ranked {@link SkillMatch}es for a set of
+ * changed paths, each with whether it is eligible and WHY (the issue's
+ * "inspect why a skill was selected" metric). Pure.
+ */
+export function formatWhy(matches) {
+    if (matches.length === 0)
+        return "No skills to match.";
+    const lines = [];
+    for (const m of matches) {
+        lines.push(`- ${m.name}  [${m.eligible ? "eligible" : "skip"}]  score ${m.score}`);
+        for (const r of m.reasons)
+            lines.push(`    · ${r}`);
+    }
+    return lines.join("\n");
+}
+/** Render the candidate skills suggested from repeated successful runs. Pure. */
+export function formatCandidates(candidates) {
+    if (candidates.length === 0) {
+        return "No skill candidates: no successful workflow has repeated yet (need >= 2 runs of the same task).";
+    }
+    const lines = [];
+    for (const c of candidates) {
+        lines.push(`- ${c.suggestedName}  (${c.count} successful runs)`);
+        lines.push(`    signature: ${c.bin} / ${c.mode} / ${c.inputs || "(none)"}`);
+        lines.push(`    runs:      ${c.runIds.join(", ")}`);
+    }
+    return lines.join("\n");
+}
+/**
+ * Drive the read-only `otto-skills` command over `.otto/skills/`. Subcommands:
+ * `list` (default) inventories skills + derived status; `audit` summarizes
+ * usable/unvalidated/stale; `why <path>...` shows which skills retrieval would
+ * select for those changed paths and why; `candidates` suggests skills from
+ * repeated successful runs. Read-only — it never executes a skill's tests or
+ * mutates a package. Resolves to the process exit code (mirrors `runMemory`).
+ */
+export async function runSkills(argv, deps = defaultDeps) {
+    const arg = argv[0];
+    if (arg === "-h" || arg === "--help") {
+        deps.out(USAGE);
+        return 0;
+    }
+    const known = ["list", "audit", "why", "candidates"];
+    if (arg !== undefined && !known.includes(arg)) {
+        deps.err(`Unknown subcommand '${arg}'.\n${USAGE}`);
+        return 1;
+    }
+    const workspaceDir = resolve(deps.env.OTTO_WORKSPACE ?? deps.cwd);
+    const skills = readSkills(workspaceDir);
+    if (arg === "why") {
+        const paths = argv.slice(1);
+        if (paths.length === 0) {
+            deps.err(`why needs at least one changed path.\n${USAGE}`);
+            return 1;
+        }
+        deps.out(formatWhy(selectSkills(skills, { changedPaths: paths })));
+        return 0;
+    }
+    if (arg === "candidates") {
+        const runs = listRunIds(workspaceDir)
+            .map((id) => readManifest(workspaceDir, id))
+            .filter((m) => m != null)
+            .map((m) => ({
+            runId: m.runId,
+            bin: m.bin,
+            mode: m.mode,
+            inputs: m.inputs,
+            exitReason: m.exitReason,
+        }));
+        deps.out(formatCandidates(findSkillCandidates(runs)));
+        return 0;
+    }
+    if (arg === "audit") {
+        deps.out(`Skills audit (${skillsDir(workspaceDir)})`);
+        deps.out(formatSkillsAudit(skills));
+        return 0;
+    }
+    deps.out(`Skills (${skillsDir(workspaceDir)})`);
+    deps.out(formatSkillsReport(skills));
+    return 0;
+}
+//# sourceMappingURL=skills-cli.js.map

package/dist/skills-cli.js.map

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

package/dist/skills.d.ts

@@ -0,0 +1,195 @@
+import type { RunManifest } from "./run-report.js";
+/**
+ * Skill extraction and reuse (issue #44 P5). A **skill** is a repo-local,
+ * versioned, validated procedure promoted from repeated successful trajectories
+ * — so future runs can retrieve a known workflow instead of re-planning it.
+ *
+ * Unlike a memory record (one JSON file), a skill is a **directory package**
+ * `.otto/skills/<name>/`: `skill.json` (this metadata) + `instructions.md` (the
+ * body), alongside optional scripts/tests. The `.otto/skills/` directory is the
+ * list — there is no central index, exactly like `.otto/runs/` and
+ * `.otto/memory/`. Pure fs + JSON, absent/malformed → safe defaults, never
+ * throws (mirrors `memory.ts`/`run-report.ts`).
+ *
+ * This module is a substrate: it is exported from `index.ts` and read by the
+ * read-only `otto-skills` bin, but **inert on the loop** — no run auto-selects or
+ * auto-applies a skill this slice, so a skill cannot regress a run. Retrieval,
+ * validation-gating, and candidate identification layer on top in later slices.
+ */
+/** Coarse provenance band, mirroring {@link MemoryTrust}. */
+export type SkillTrust = "trusted" | "unverified" | "deprecated";
+/**
+ * Validation provenance: the successful run that last proved the skill works.
+ * "Require validation before a skill is used automatically" (the issue) is
+ * enforced by retrieval filtering on the DERIVED {@link skillStatus}, which is
+ * computed from these fields — not by the bin executing the skill's tests.
+ */
+export type SkillValidation = {
+    /** Run id whose trajectory last validated this skill (absent = unvalidated). */
+    lastValidatedRun?: string;
+    /** When that validation happened (ISO). */
+    lastValidatedAt?: string;
+};
+/**
+ * One skill package's metadata, stored as `.otto/skills/<name>/skill.json`. The
+ * `instructions` body lives in the sibling `instructions.md` (or inline here as a
+ * fallback) and is loaded by {@link readSkill}.
+ */
+export type Skill = {
+    /** Filesystem-safe package name; also the directory name. */
+    name: string;
+    /** Free-text version (semver-ish); default "0.0.0". */
+    version: string;
+    /** Declared capability tags (e.g. "release-flow") — a retrieval key. */
+    capabilities: string[];
+    /** Guardrails — e.g. risk classes the skill must not be applied to. */
+    constraints: string[];
+    /** File/module globs the skill applies to; empty = repo-wide. A retrieval key. */
+    scope: string[];
+    /** The instruction body (from `instructions.md`, else the inline fallback). */
+    instructions: string;
+    /** Named helper commands the package ships (name → command string). */
+    scripts: Record<string, string>;
+    /** Validation command(s) that prove the skill still works. */
+    tests: string[];
+    validation: SkillValidation;
+    trust: SkillTrust;
+    createdAt: string;
+    /** How many runs have consumed this skill. */
+    useCount: number;
+    /** Sliding revalidation window in days; past it a validated skill goes stale. */
+    revalidateAfterDays?: number;
+};
+/** Absolute path to the workspace's skills root (`.otto/skills`). */
+export declare function skillsDir(workspaceDir: string): string;
+/** Absolute path to one skill's package dir (`.otto/skills/<name>`). */
+export declare function skillDir(workspaceDir: string, name: string): string;
+/** Absolute path to a skill's metadata file (`.otto/skills/<name>/skill.json`). */
+export declare function skillManifestPath(workspaceDir: string, name: string): string;
+/** Absolute path to a skill's instructions body (`.../instructions.md`). */
+export declare function skillInstructionsPath(workspaceDir: string, name: string): string;
+/**
+ * Normalize free text into a filesystem-safe, git-branch-safe skill name:
+ * lowercase, every non-`[a-z0-9]` run collapsed to a single `-`, trimmed of
+ * leading/trailing `-`, capped at 48 chars. Mirrors `slugify`/`deriveTaskKey`.
+ */
+export declare function toSkillName(raw: string): string;
+/**
+ * Normalize an untrusted parsed `skill.json` value into a {@link Skill}, filling
+ * safe defaults for missing/invalid fields. Returns null when the input is not an
+ * object or lacks the required `name`, so a malformed package is skipped rather
+ * than crashing a read. `instructions` defaults to the inline value (if any);
+ * {@link readSkill} overrides it with the `instructions.md` body when present.
+ */
+export declare function parseSkill(raw: unknown): Skill | null;
+/**
+ * List the skill names present under `.otto/skills/` (the package sub-dirs),
+ * sorted. Absent/unreadable dir → `[]` (never throws). The directory is the
+ * list; a name here is not a guarantee its `skill.json` parses (use
+ * {@link readSkill}).
+ */
+export declare function listSkillIds(workspaceDir: string): string[];
+/**
+ * Read and normalize one skill package. Parses `skill.json`, then overrides
+ * `instructions` with the `instructions.md` body when that file exists. Absent or
+ * malformed `skill.json` → null (never throws).
+ */
+export declare function readSkill(workspaceDir: string, name: string): Skill | null;
+/** Read every skill package under `.otto/skills/`, skipping malformed ones. */
+export declare function readSkills(workspaceDir: string): Skill[];
+/**
+ * Write a skill package: `skill.json` (metadata, with `instructions` omitted) +
+ * `instructions.md` (the body). Creates `.otto/skills/<name>/`. The split keeps
+ * the body as a readable, diff-friendly markdown file rather than an escaped JSON
+ * string.
+ */
+export declare function writeSkill(workspaceDir: string, skill: Skill): void;
+/** True when a skill package directory with a `skill.json` exists. */
+export declare function skillExists(workspaceDir: string, name: string): boolean;
+/**
+ * Validation lifecycle (issue #44 slice 2). `unvalidated` = never proven by a
+ * run (so it must not be applied automatically); `validated` = a successful run
+ * proved it and it is within its freshness window; `stale` = it was validated but
+ * `revalidateAfterDays` have since elapsed and it needs re-proving.
+ */
+export type SkillStatus = "validated" | "unvalidated" | "stale";
+/**
+ * Derive a skill's validation status from its recorded validation + freshness
+ * policy at `now`. A skill with no `validation.lastValidatedRun` is `unvalidated`;
+ * one validated but past its `revalidateAfterDays` window (measured from
+ * `lastValidatedAt`) is `stale`; otherwise `validated`. Unparseable timestamps
+ * are ignored rather than treated as expired (mirrors `memoryStatus`). Pure —
+ * the retrieval gate uses this so only `validated` skills are auto-eligible.
+ */
+export declare function skillStatus(skill: Skill, now?: Date): SkillStatus;
+/**
+ * Return a copy of the skill marked validated by a successful `runId` at `now`.
+ * Pure — the input is not mutated; the caller writes it back to persist the
+ * validation (recording a validation is a run's job, never the read-only bin's).
+ */
+export declare function recordValidation(skill: Skill, runId: string, now?: Date): Skill;
+/**
+ * Minimal path-glob match: `**` spans path separators, `*` spans a single
+ * segment, `?` one char. Used for a skill's scope globs against changed paths.
+ */
+export declare function globMatch(glob: string, path: string): boolean;
+/** Context a retrieval is scored against (issue #44 slice 3). */
+export type SkillMatchContext = {
+    /** The iteration's changed paths — drives scope + risk-class matching. */
+    changedPaths?: string[];
+    /** A required capability tag the caller is looking for. */
+    capability?: string;
+    /** Injectable clock for deterministic validation-freshness scoring. */
+    now?: Date;
+};
+/**
+ * One skill's retrieval verdict: whether it is auto-eligible (validated AND not
+ * excluded by a constraint), a relevance `score`, and human `reasons[]` — so the
+ * operator can inspect *why* a skill was (or was not) selected (the issue's
+ * "users can inspect why a skill was selected" metric).
+ */
+export type SkillMatch = {
+    name: string;
+    eligible: boolean;
+    score: number;
+    reasons: string[];
+};
+/**
+ * Rank skills for the current task. Retrieval is by **declared capability**,
+ * **touched files** (scope globs vs. changed paths), and **task risk** (a skill
+ * whose constraints forbid the change's risk class is excluded) — the three keys
+ * the issue names. Only `validated` skills are auto-`eligible` (validation before
+ * use); unvalidated/stale skills are still returned, flagged not-eligible with a
+ * reason, so the bin can show the full picture. Sorted eligible-first, then score
+ * desc, then name. Pure — no I/O, deterministic.
+ */
+export declare function selectSkills(skills: Skill[], ctx?: SkillMatchContext): SkillMatch[];
+/** The run fields candidate identification needs (a subset of {@link RunManifest}). */
+export type CandidateRun = Pick<RunManifest, "runId" | "bin" | "mode" | "inputs" | "exitReason">;
+/**
+ * A repeated successful workflow worth promoting into a skill (issue #44 slice
+ * 4): the runs that share it, and a suggested package name. It is only a
+ * *suggestion* — extraction stays a maintainer action, never auto-promoted.
+ */
+export type SkillCandidate = {
+    /** Stable grouping signature `<bin>::<mode>::<inputs>`. */
+    signature: string;
+    bin: string;
+    mode: string;
+    inputs: string;
+    /** A filesystem-safe skill name suggestion derived from the signature. */
+    suggestedName: string;
+    /** Run ids of the successful runs sharing this signature, chronological. */
+    runIds: string[];
+    count: number;
+};
+/**
+ * Identify candidate skills from recorded runs: group **successful** runs
+ * (`exitReason` ∈ {complete, done}) by their `<bin>::<mode>::<inputs>` signature
+ * and surface every signature seen `minCount` (default 2) or more times. A
+ * conservative, deterministic heuristic — the same task succeeding repeatedly is
+ * the strongest signal that it is worth turning into a reusable procedure. Pure;
+ * no model call, no auto-promotion. Sorted by count desc, then signature.
+ */
+export declare function findSkillCandidates(runs: CandidateRun[], minCount?: number): SkillCandidate[];
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAEnD;;;;;;;;;;;;;;;;GAgBG;AAEH,6DAA6D;AAC7D,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,YAAY,GAAG,YAAY,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,gFAAgF;IAChF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,2CAA2C;IAC3C,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,KAAK,GAAG;IAClB,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAC;IACb,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,uEAAuE;IACvE,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,kFAAkF;IAClF,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,+EAA+E;IAC/E,YAAY,EAAE,MAAM,CAAC;IACrB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,8DAA8D;IAC9D,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,UAAU,EAAE,eAAe,CAAC;IAC5B,KAAK,EAAE,UAAU,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,QAAQ,EAAE,MAAM,CAAC;IACjB,iFAAiF;IACjF,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B,CAAC;AAYF,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wEAAwE;AACxE,wBAAgB,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED,4EAA4E;AAC5E,wBAAgB,qBAAqB,CACnC,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,MAAM,GACX,MAAM,CAER;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM/C;AA8BD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,KAAK,GAAG,IAAI,CA6BrD;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,EAAE,CAS3D;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,CAoB1E;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,GAAG,KAAK,EAAE,CAOxD;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CASnE;AAED,sEAAsE;AACtE,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAEvE;AAED;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,aAAa,GAAG,OAAO,CAAC;AAWhE;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,GAAE,IAAiB,GAAG,WAAW,CAS7E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,KAAK,EACZ,KAAK,EAAE,MAAM,EACb,GAAG,GAAE,IAAiB,GACrB,KAAK,CAKP;AAOD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAO7D;AAED,iEAAiE;AACjE,MAAM,MAAM,iBAAiB,GAAG;IAC9B,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,OAAO,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,KAAK,EAAE,EACf,GAAG,GAAE,iBAAsB,GAC1B,UAAU,EAAE,CA8Dd;AAED,uFAAuF;AACvF,MAAM,MAAM,YAAY,GAAG,IAAI,CAC7B,WAAW,EACX,OAAO,GAAG,KAAK,GAAG,MAAM,GAAG,QAAQ,GAAG,YAAY,CACnD,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,aAAa,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAIF;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,YAAY,EAAE,EACpB,QAAQ,SAAI,GACX,cAAc,EAAE,CAyBlB"}

package/dist/skills.js

@@ -0,0 +1,320 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { classifyRisk } from "./risk.js";
+const TRUSTS = new Set([
+    "trusted",
+    "unverified",
+    "deprecated",
+]);
+const SKILLS_REL = join(".otto", "skills");
+const MANIFEST_FILE = "skill.json";
+const INSTRUCTIONS_FILE = "instructions.md";
+/** Absolute path to the workspace's skills root (`.otto/skills`). */
+export function skillsDir(workspaceDir) {
+    return join(workspaceDir, SKILLS_REL);
+}
+/** Absolute path to one skill's package dir (`.otto/skills/<name>`). */
+export function skillDir(workspaceDir, name) {
+    return join(skillsDir(workspaceDir), name);
+}
+/** Absolute path to a skill's metadata file (`.otto/skills/<name>/skill.json`). */
+export function skillManifestPath(workspaceDir, name) {
+    return join(skillDir(workspaceDir, name), MANIFEST_FILE);
+}
+/** Absolute path to a skill's instructions body (`.../instructions.md`). */
+export function skillInstructionsPath(workspaceDir, name) {
+    return join(skillDir(workspaceDir, name), INSTRUCTIONS_FILE);
+}
+/**
+ * Normalize free text into a filesystem-safe, git-branch-safe skill name:
+ * lowercase, every non-`[a-z0-9]` run collapsed to a single `-`, trimmed of
+ * leading/trailing `-`, capped at 48 chars. Mirrors `slugify`/`deriveTaskKey`.
+ */
+export function toSkillName(raw) {
+    return raw
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+}
+function stringArray(raw) {
+    return Array.isArray(raw)
+        ? raw.filter((s) => typeof s === "string")
+        : [];
+}
+function stringRecord(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(raw)) {
+        if (typeof v === "string")
+            out[k] = v;
+    }
+    return out;
+}
+function parseValidation(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return {};
+    const o = raw;
+    const v = {};
+    if (typeof o.lastValidatedRun === "string") {
+        v.lastValidatedRun = o.lastValidatedRun;
+    }
+    if (typeof o.lastValidatedAt === "string") {
+        v.lastValidatedAt = o.lastValidatedAt;
+    }
+    return v;
+}
+/**
+ * Normalize an untrusted parsed `skill.json` value into a {@link Skill}, filling
+ * safe defaults for missing/invalid fields. Returns null when the input is not an
+ * object or lacks the required `name`, so a malformed package is skipped rather
+ * than crashing a read. `instructions` defaults to the inline value (if any);
+ * {@link readSkill} overrides it with the `instructions.md` body when present.
+ */
+export function parseSkill(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw))
+        return null;
+    const o = raw;
+    if (typeof o.name !== "string" || o.name.length === 0)
+        return null;
+    return {
+        name: o.name,
+        version: typeof o.version === "string" ? o.version : "0.0.0",
+        capabilities: stringArray(o.capabilities),
+        constraints: stringArray(o.constraints),
+        scope: stringArray(o.scope),
+        instructions: typeof o.instructions === "string" ? o.instructions : "",
+        scripts: stringRecord(o.scripts),
+        tests: stringArray(o.tests),
+        validation: parseValidation(o.validation),
+        trust: typeof o.trust === "string" && TRUSTS.has(o.trust)
+            ? o.trust
+            : "unverified",
+        createdAt: typeof o.createdAt === "string" ? o.createdAt : new Date(0).toISOString(),
+        useCount: typeof o.useCount === "number" && Number.isFinite(o.useCount)
+            ? o.useCount
+            : 0,
+        ...(typeof o.revalidateAfterDays === "number" &&
+            Number.isFinite(o.revalidateAfterDays)
+            ? { revalidateAfterDays: o.revalidateAfterDays }
+            : {}),
+    };
+}
+/**
+ * List the skill names present under `.otto/skills/` (the package sub-dirs),
+ * sorted. Absent/unreadable dir → `[]` (never throws). The directory is the
+ * list; a name here is not a guarantee its `skill.json` parses (use
+ * {@link readSkill}).
+ */
+export function listSkillIds(workspaceDir) {
+    try {
+        return readdirSync(skillsDir(workspaceDir), { withFileTypes: true })
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Read and normalize one skill package. Parses `skill.json`, then overrides
+ * `instructions` with the `instructions.md` body when that file exists. Absent or
+ * malformed `skill.json` → null (never throws).
+ */
+export function readSkill(workspaceDir, name) {
+    let skill;
+    try {
+        skill = parseSkill(JSON.parse(readFileSync(skillManifestPath(workspaceDir, name), "utf8")));
+    }
+    catch {
+        return null;
+    }
+    if (!skill)
+        return null;
+    try {
+        const body = readFileSync(skillInstructionsPath(workspaceDir, name), "utf8");
+        skill = { ...skill, instructions: body };
+    }
+    catch {
+        // No instructions.md sidecar — keep the inline (or empty) instructions.
+    }
+    return skill;
+}
+/** Read every skill package under `.otto/skills/`, skipping malformed ones. */
+export function readSkills(workspaceDir) {
+    const skills = [];
+    for (const name of listSkillIds(workspaceDir)) {
+        const s = readSkill(workspaceDir, name);
+        if (s)
+            skills.push(s);
+    }
+    return skills;
+}
+/**
+ * Write a skill package: `skill.json` (metadata, with `instructions` omitted) +
+ * `instructions.md` (the body). Creates `.otto/skills/<name>/`. The split keeps
+ * the body as a readable, diff-friendly markdown file rather than an escaped JSON
+ * string.
+ */
+export function writeSkill(workspaceDir, skill) {
+    const dir = skillDir(workspaceDir, skill.name);
+    mkdirSync(dir, { recursive: true });
+    const { instructions, ...meta } = skill;
+    writeFileSync(join(dir, MANIFEST_FILE), JSON.stringify(meta, null, 2) + "\n");
+    writeFileSync(join(dir, INSTRUCTIONS_FILE), instructions);
+}
+/** True when a skill package directory with a `skill.json` exists. */
+export function skillExists(workspaceDir, name) {
+    return existsSync(skillManifestPath(workspaceDir, name));
+}
+const DAY_MS = 24 * 60 * 60 * 1000;
+/** Parse an ISO timestamp to epoch ms; unparseable → null (never throws). */
+function epoch(iso) {
+    if (typeof iso !== "string")
+        return null;
+    const t = Date.parse(iso);
+    return Number.isNaN(t) ? null : t;
+}
+/**
+ * Derive a skill's validation status from its recorded validation + freshness
+ * policy at `now`. A skill with no `validation.lastValidatedRun` is `unvalidated`;
+ * one validated but past its `revalidateAfterDays` window (measured from
+ * `lastValidatedAt`) is `stale`; otherwise `validated`. Unparseable timestamps
+ * are ignored rather than treated as expired (mirrors `memoryStatus`). Pure —
+ * the retrieval gate uses this so only `validated` skills are auto-eligible.
+ */
+export function skillStatus(skill, now = new Date()) {
+    if (!skill.validation.lastValidatedRun)
+        return "unvalidated";
+    if (skill.revalidateAfterDays !== undefined) {
+        const since = epoch(skill.validation.lastValidatedAt);
+        if (since !== null && now.getTime() - since > skill.revalidateAfterDays * DAY_MS) {
+            return "stale";
+        }
+    }
+    return "validated";
+}
+/**
+ * Return a copy of the skill marked validated by a successful `runId` at `now`.
+ * Pure — the input is not mutated; the caller writes it back to persist the
+ * validation (recording a validation is a run's job, never the read-only bin's).
+ */
+export function recordValidation(skill, runId, now = new Date()) {
+    return {
+        ...skill,
+        validation: { lastValidatedRun: runId, lastValidatedAt: now.toISOString() },
+    };
+}
+/** Escape regex metacharacters outside the glob wildcards we handle. */
+function escapeRe(s) {
+    return s.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Minimal path-glob match: `**` spans path separators, `*` spans a single
+ * segment, `?` one char. Used for a skill's scope globs against changed paths.
+ */
+export function globMatch(glob, path) {
+    const re = escapeRe(glob)
+        .replace(/\*\*/g, "") // placeholder so the next step won't touch it
+        .replace(/\*/g, "[^/]*")
+        .replace(//g, ".*")
+        .replace(/\?/g, ".");
+    return new RegExp(`^${re}$`).test(path);
+}
+/**
+ * Rank skills for the current task. Retrieval is by **declared capability**,
+ * **touched files** (scope globs vs. changed paths), and **task risk** (a skill
+ * whose constraints forbid the change's risk class is excluded) — the three keys
+ * the issue names. Only `validated` skills are auto-`eligible` (validation before
+ * use); unvalidated/stale skills are still returned, flagged not-eligible with a
+ * reason, so the bin can show the full picture. Sorted eligible-first, then score
+ * desc, then name. Pure — no I/O, deterministic.
+ */
+export function selectSkills(skills, ctx = {}) {
+    const assessment = ctx.changedPaths && ctx.changedPaths.length > 0
+        ? classifyRisk(ctx.changedPaths)
+        : null;
+    const matches = skills.map((skill) => {
+        const reasons = [];
+        let score = 0;
+        let eligible = true;
+        const status = skillStatus(skill, ctx.now);
+        if (status !== "validated") {
+            eligible = false;
+            reasons.push(`not eligible: ${status} (validation required before auto-use)`);
+        }
+        if (assessment) {
+            const forbidden = skill.constraints.some((c) => c.toLowerCase().includes(assessment.class));
+            if (forbidden) {
+                eligible = false;
+                reasons.push(`excluded by constraint for risk class "${assessment.class}"`);
+            }
+        }
+        if (ctx.capability) {
+            if (skill.capabilities.includes(ctx.capability)) {
+                score += 2;
+                reasons.push(`declares capability "${ctx.capability}"`);
+            }
+            else {
+                reasons.push(`does not declare capability "${ctx.capability}"`);
+            }
+        }
+        if (ctx.changedPaths && ctx.changedPaths.length > 0) {
+            if (skill.scope.length === 0) {
+                score += 1;
+                reasons.push("repo-wide (no scope restriction)");
+            }
+            else {
+                const hit = ctx.changedPaths.filter((p) => skill.scope.some((g) => globMatch(g, p)));
+                if (hit.length > 0) {
+                    score += 2;
+                    reasons.push(`scope matches changed file(s): ${hit.join(", ")}`);
+                }
+                else {
+                    reasons.push("scope does not match the changed files");
+                }
+            }
+        }
+        return { name: skill.name, eligible, score, reasons };
+    });
+    return matches.sort((a, b) => Number(b.eligible) - Number(a.eligible) ||
+        b.score - a.score ||
+        a.name.localeCompare(b.name));
+}
+const SUCCESS_REASONS = new Set(["complete", "done"]);
+/**
+ * Identify candidate skills from recorded runs: group **successful** runs
+ * (`exitReason` ∈ {complete, done}) by their `<bin>::<mode>::<inputs>` signature
+ * and surface every signature seen `minCount` (default 2) or more times. A
+ * conservative, deterministic heuristic — the same task succeeding repeatedly is
+ * the strongest signal that it is worth turning into a reusable procedure. Pure;
+ * no model call, no auto-promotion. Sorted by count desc, then signature.
+ */
+export function findSkillCandidates(runs, minCount = 2) {
+    const groups = new Map();
+    for (const r of runs) {
+        if (r.exitReason == null || !SUCCESS_REASONS.has(r.exitReason))
+            continue;
+        const signature = `${r.bin}::${r.mode}::${r.inputs}`;
+        (groups.get(signature) ?? groups.set(signature, []).get(signature)).push(r);
+    }
+    const candidates = [];
+    for (const [signature, group] of groups) {
+        if (group.length < minCount)
+            continue;
+        const { bin, mode, inputs } = group[0];
+        candidates.push({
+            signature,
+            bin,
+            mode,
+            inputs,
+            suggestedName: toSkillName(`${mode}-${inputs}`) || toSkillName(mode),
+            runIds: group.map((r) => r.runId).sort(),
+            count: group.length,
+        });
+    }
+    return candidates.sort((a, b) => b.count - a.count || a.signature.localeCompare(b.signature));
+}
+//# sourceMappingURL=skills.js.map