@phamvuhoang/otto-core 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (78) hide show
  1. package/dist/cli-help.d.ts +7 -0
  2. package/dist/cli-help.d.ts.map +1 -1
  3. package/dist/cli-help.js +13 -1
  4. package/dist/cli-help.js.map +1 -1
  5. package/dist/eval-run.d.ts +16 -0
  6. package/dist/eval-run.d.ts.map +1 -1
  7. package/dist/eval-run.js +66 -1
  8. package/dist/eval-run.js.map +1 -1
  9. package/dist/eval.d.ts +8 -2
  10. package/dist/eval.d.ts.map +1 -1
  11. package/dist/eval.js +11 -0
  12. package/dist/eval.js.map +1 -1
  13. package/dist/index.d.ts +9 -2
  14. package/dist/index.d.ts.map +1 -1
  15. package/dist/index.js +8 -1
  16. package/dist/index.js.map +1 -1
  17. package/dist/loop.d.ts +4 -0
  18. package/dist/loop.d.ts.map +1 -1
  19. package/dist/loop.js +25 -6
  20. package/dist/loop.js.map +1 -1
  21. package/dist/memory-cli.d.ts +26 -0
  22. package/dist/memory-cli.d.ts.map +1 -0
  23. package/dist/memory-cli.js +78 -0
  24. package/dist/memory-cli.js.map +1 -0
  25. package/dist/memory.d.ts +163 -0
  26. package/dist/memory.d.ts.map +1 -0
  27. package/dist/memory.js +0 -0
  28. package/dist/memory.js.map +1 -0
  29. package/dist/render.d.ts +3 -0
  30. package/dist/render.d.ts.map +1 -1
  31. package/dist/render.js +40 -12
  32. package/dist/render.js.map +1 -1
  33. package/dist/risk.d.ts +7 -0
  34. package/dist/risk.d.ts.map +1 -1
  35. package/dist/risk.js +17 -0
  36. package/dist/risk.js.map +1 -1
  37. package/dist/run-bin.d.ts.map +1 -1
  38. package/dist/run-bin.js +7 -0
  39. package/dist/run-bin.js.map +1 -1
  40. package/dist/run-report.d.ts +57 -0
  41. package/dist/run-report.d.ts.map +1 -1
  42. package/dist/run-report.js.map +1 -1
  43. package/dist/runner.d.ts +4 -0
  44. package/dist/runner.d.ts.map +1 -1
  45. package/dist/runner.js.map +1 -1
  46. package/dist/runs-cli.d.ts +43 -0
  47. package/dist/runs-cli.d.ts.map +1 -0
  48. package/dist/runs-cli.js +96 -0
  49. package/dist/runs-cli.js.map +1 -0
  50. package/dist/safety-policy.d.ts +83 -0
  51. package/dist/safety-policy.d.ts.map +1 -0
  52. package/dist/safety-policy.js +143 -0
  53. package/dist/safety-policy.js.map +1 -0
  54. package/dist/skills-cli.d.ts +39 -0
  55. package/dist/skills-cli.d.ts.map +1 -0
  56. package/dist/skills-cli.js +137 -0
  57. package/dist/skills-cli.js.map +1 -0
  58. package/dist/skills.d.ts +195 -0
  59. package/dist/skills.d.ts.map +1 -0
  60. package/dist/skills.js +320 -0
  61. package/dist/skills.js.map +1 -0
  62. package/dist/stage-exec.d.ts.map +1 -1
  63. package/dist/stage-exec.js +31 -3
  64. package/dist/stage-exec.js.map +1 -1
  65. package/dist/taint.d.ts +32 -0
  66. package/dist/taint.d.ts.map +1 -0
  67. package/dist/taint.js +60 -0
  68. package/dist/taint.js.map +1 -0
  69. package/package.json +1 -1
  70. package/templates/apply-review.md +2 -0
  71. package/templates/ghafk-issue.md +2 -0
  72. package/templates/ghafk.md +2 -0
  73. package/templates/ghprompt-workflow.md +2 -0
  74. package/templates/governed-memory.md +58 -0
  75. package/templates/linearafk-issue.md +2 -0
  76. package/templates/linearafk.md +2 -0
  77. package/templates/prompt.md +2 -0
  78. package/templates/untrusted-content.md +23 -0
@@ -0,0 +1,143 @@
1
+ import { readFileSync } from "node:fs";
2
+ import { join } from "node:path";
3
+ /** The six rule lists, in declaration order — the single source of field names. */
4
+ const RULE_FIELDS = [
5
+ "allowedWriteRoots",
6
+ "blockedCommands",
7
+ "allowedNetworkDomains",
8
+ "secretPatterns",
9
+ "highRiskGlobs",
10
+ "approvalRequiredActions",
11
+ ];
12
+ /**
13
+ * The permissive default: every rule list empty, so a workspace with no
14
+ * `.otto/policy.json` behaves exactly as it does today (success metric #3).
15
+ */
16
+ export const DEFAULT_POLICY = Object.freeze({
17
+ allowedWriteRoots: [],
18
+ blockedCommands: [],
19
+ allowedNetworkDomains: [],
20
+ secretPatterns: [],
21
+ highRiskGlobs: [],
22
+ approvalRequiredActions: [],
23
+ });
24
+ /** Coerce one field of an untrusted parsed object into a string list. */
25
+ function stringList(raw) {
26
+ return Array.isArray(raw)
27
+ ? raw.filter((s) => typeof s === "string")
28
+ : [];
29
+ }
30
+ /**
31
+ * Normalize an untrusted parsed value into a {@link SafetyPolicy}, filling the
32
+ * permissive default for every missing/invalid field. Never throws: a
33
+ * non-object/array/null input → {@link DEFAULT_POLICY}; a non-array field → its
34
+ * default `[]`; non-string array elements are filtered. Always returns a fresh
35
+ * object with fresh arrays (never the shared frozen default reference).
36
+ */
37
+ export function parseSafetyPolicy(raw) {
38
+ const o = raw !== null && typeof raw === "object" && !Array.isArray(raw)
39
+ ? raw
40
+ : {};
41
+ const policy = {};
42
+ for (const field of RULE_FIELDS) {
43
+ policy[field] = stringList(o[field]);
44
+ }
45
+ return policy;
46
+ }
47
+ /**
48
+ * Deny-list check: a violation per {@link SafetyPolicy.blockedCommands} substring
49
+ * that appears in `command`. Empty list → no violations (DEFAULT_POLICY).
50
+ */
51
+ export function checkCommand(policy, command) {
52
+ return policy.blockedCommands
53
+ .filter((pattern) => command.includes(pattern))
54
+ .map((pattern) => ({
55
+ kind: "blocked-command",
56
+ subject: command,
57
+ message: `command matches blocked pattern "${pattern}"`,
58
+ }));
59
+ }
60
+ /** Strip trailing slashes so `src/` and `src` name the same root. */
61
+ function trimRoot(root) {
62
+ return root.replace(/\/+$/, "");
63
+ }
64
+ /**
65
+ * Allow-list check over workspace-relative {@link SafetyPolicy.allowedWriteRoots}:
66
+ * empty → unrestricted (no violations). Otherwise a single violation when `path`
67
+ * is neither equal to nor nested under any allowed root. A root of `.` (or empty
68
+ * after trimming) permits the whole workspace.
69
+ */
70
+ export function checkWritePath(policy, path) {
71
+ if (policy.allowedWriteRoots.length === 0)
72
+ return [];
73
+ const allowed = policy.allowedWriteRoots.some((raw) => {
74
+ const root = trimRoot(raw);
75
+ if (root === "" || root === ".")
76
+ return true;
77
+ return path === root || path.startsWith(root + "/");
78
+ });
79
+ return allowed
80
+ ? []
81
+ : [
82
+ {
83
+ kind: "write-root",
84
+ subject: path,
85
+ message: "path is outside every allowed write root",
86
+ },
87
+ ];
88
+ }
89
+ /**
90
+ * Allow-list check over {@link SafetyPolicy.allowedNetworkDomains}: empty →
91
+ * unrestricted. Otherwise a single violation when `domain` is neither an allowed
92
+ * domain nor a subdomain of one (case-insensitive).
93
+ */
94
+ export function checkNetworkDomain(policy, domain) {
95
+ if (policy.allowedNetworkDomains.length === 0)
96
+ return [];
97
+ const d = domain.toLowerCase();
98
+ const allowed = policy.allowedNetworkDomains.some((raw) => {
99
+ const a = raw.toLowerCase();
100
+ return d === a || d.endsWith("." + a);
101
+ });
102
+ return allowed
103
+ ? []
104
+ : [
105
+ {
106
+ kind: "network-domain",
107
+ subject: domain,
108
+ message: "domain is not in the allowed network domains",
109
+ },
110
+ ];
111
+ }
112
+ /**
113
+ * Flag check over {@link SafetyPolicy.approvalRequiredActions}: a violation when
114
+ * `action` exactly matches a listed action. Empty list → no violations.
115
+ */
116
+ export function checkApprovalRequired(policy, action) {
117
+ return policy.approvalRequiredActions.includes(action)
118
+ ? [
119
+ {
120
+ kind: "approval-required",
121
+ subject: action,
122
+ message: `action "${action}" requires human approval`,
123
+ },
124
+ ]
125
+ : [];
126
+ }
127
+ const POLICY_REL = join(".otto", "policy.json");
128
+ /**
129
+ * Read and normalize `.otto/policy.json` from a workspace. Absent or malformed
130
+ * file → {@link DEFAULT_POLICY} (never throws), so a missing/corrupt policy
131
+ * fails open to today's unrestricted behavior rather than blocking a run.
132
+ */
133
+ export function readSafetyPolicy(workspaceDir) {
134
+ let raw;
135
+ try {
136
+ raw = JSON.parse(readFileSync(join(workspaceDir, POLICY_REL), "utf8"));
137
+ }
138
+ catch {
139
+ return parseSafetyPolicy(undefined);
140
+ }
141
+ return parseSafetyPolicy(raw);
142
+ }
143
+ //# sourceMappingURL=safety-policy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"safety-policy.js","sourceRoot":"","sources":["../src/safety-policy.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,39 @@
1
+ import { type Skill, type SkillCandidate, type SkillMatch } from "./skills.js";
2
+ /**
3
+ * Injectable host surface for {@link runSkills} so the bin stays unit-testable
4
+ * without touching the real cwd/env or process stdio (mirrors `MemoryDeps`).
5
+ */
6
+ export type SkillsDeps = {
7
+ env: NodeJS.ProcessEnv;
8
+ cwd: string;
9
+ out: (msg: string) => void;
10
+ err: (msg: string) => void;
11
+ };
12
+ /**
13
+ * Render the skill inventory with each skill's DERIVED validation status, trust,
14
+ * and capabilities/scope. Pure (clock injected). `now` drives freshness.
15
+ */
16
+ export declare function formatSkillsReport(skills: Skill[], now?: Date): string;
17
+ /**
18
+ * Render a governance summary: how many skills are validated (auto-usable),
19
+ * unvalidated, or stale, and which are not yet usable. Pure (clock injected).
20
+ */
21
+ export declare function formatSkillsAudit(skills: Skill[], now?: Date): string;
22
+ /**
23
+ * Render a retrieval explanation: the ranked {@link SkillMatch}es for a set of
24
+ * changed paths, each with whether it is eligible and WHY (the issue's
25
+ * "inspect why a skill was selected" metric). Pure.
26
+ */
27
+ export declare function formatWhy(matches: SkillMatch[]): string;
28
+ /** Render the candidate skills suggested from repeated successful runs. Pure. */
29
+ export declare function formatCandidates(candidates: SkillCandidate[]): string;
30
+ /**
31
+ * Drive the read-only `otto-skills` command over `.otto/skills/`. Subcommands:
32
+ * `list` (default) inventories skills + derived status; `audit` summarizes
33
+ * usable/unvalidated/stale; `why <path>...` shows which skills retrieval would
34
+ * select for those changed paths and why; `candidates` suggests skills from
35
+ * repeated successful runs. Read-only — it never executes a skill's tests or
36
+ * mutates a package. Resolves to the process exit code (mirrors `runMemory`).
37
+ */
38
+ export declare function runSkills(argv: string[], deps?: SkillsDeps): Promise<number>;
39
+ //# sourceMappingURL=skills-cli.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skills-cli.d.ts","sourceRoot":"","sources":["../src/skills-cli.ts"],"names":[],"mappings":"AAGA,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;AAkBF;;;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,CAiBR;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAQvD;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,cAAc,EAAE,GAAG,MAAM,CAWrE;AAED;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE,UAAwB,GAC7B,OAAO,CAAC,MAAM,CAAC,CAiDjB"}
@@ -0,0 +1,137 @@
1
+ import { resolve } from "node:path";
2
+ import { listRunIds, readManifest } from "./run-report.js";
3
+ import { findSkillCandidates, readSkills, selectSkills, skillsDir, skillStatus, } from "./skills.js";
4
+ const defaultDeps = {
5
+ env: process.env,
6
+ cwd: process.cwd(),
7
+ out: (m) => process.stdout.write(`${m}\n`),
8
+ err: (m) => process.stderr.write(`${m}\n`),
9
+ };
10
+ const USAGE = "Usage: otto-skills <list|audit|candidates>\n" +
11
+ " otto-skills why <changed-path>...";
12
+ /** One-line scope label: the globs, or "(repo-wide)" when empty. */
13
+ function scopeLabel(skill) {
14
+ return skill.scope.length ? skill.scope.join(", ") : "(repo-wide)";
15
+ }
16
+ /**
17
+ * Render the skill inventory with each skill's DERIVED validation status, trust,
18
+ * and capabilities/scope. Pure (clock injected). `now` drives freshness.
19
+ */
20
+ export function formatSkillsReport(skills, now = new Date()) {
21
+ if (skills.length === 0) {
22
+ return "No skills yet. A skill is a .otto/skills/<name>/ package (skill.json + instructions.md).";
23
+ }
24
+ const lines = [];
25
+ for (const s of skills) {
26
+ const caps = s.capabilities.length ? s.capabilities.join(", ") : "(none)";
27
+ lines.push(`- ${s.name}@${s.version} [${skillStatus(s, now)}/${s.trust}] used ${s.useCount}x`);
28
+ lines.push(` capabilities: ${caps}`);
29
+ lines.push(` scope: ${scopeLabel(s)}`);
30
+ }
31
+ return lines.join("\n");
32
+ }
33
+ /**
34
+ * Render a governance summary: how many skills are validated (auto-usable),
35
+ * unvalidated, or stale, and which are not yet usable. Pure (clock injected).
36
+ */
37
+ export function formatSkillsAudit(skills, now = new Date()) {
38
+ const status = skills.map((s) => ({ s, st: skillStatus(s, now) }));
39
+ const count = (k) => status.filter((x) => x.st === k).length;
40
+ const lines = [];
41
+ lines.push(` total: ${skills.length}`);
42
+ lines.push(` validated: ${count("validated")}`);
43
+ lines.push(` unvalidated: ${count("unvalidated")}`);
44
+ lines.push(` stale: ${count("stale")}`);
45
+ const notUsable = status.filter((x) => x.st !== "validated");
46
+ lines.push("");
47
+ lines.push(`Not yet usable (${notUsable.length}):`);
48
+ if (notUsable.length === 0)
49
+ lines.push(" (none — all validated)");
50
+ for (const { s, st } of notUsable) {
51
+ lines.push(` - ${s.name} [${st}] (run its tests, then record a validating run)`);
52
+ }
53
+ return lines.join("\n");
54
+ }
55
+ /**
56
+ * Render a retrieval explanation: the ranked {@link SkillMatch}es for a set of
57
+ * changed paths, each with whether it is eligible and WHY (the issue's
58
+ * "inspect why a skill was selected" metric). Pure.
59
+ */
60
+ export function formatWhy(matches) {
61
+ if (matches.length === 0)
62
+ return "No skills to match.";
63
+ const lines = [];
64
+ for (const m of matches) {
65
+ lines.push(`- ${m.name} [${m.eligible ? "eligible" : "skip"}] score ${m.score}`);
66
+ for (const r of m.reasons)
67
+ lines.push(` · ${r}`);
68
+ }
69
+ return lines.join("\n");
70
+ }
71
+ /** Render the candidate skills suggested from repeated successful runs. Pure. */
72
+ export function formatCandidates(candidates) {
73
+ if (candidates.length === 0) {
74
+ return "No skill candidates: no successful workflow has repeated yet (need >= 2 runs of the same task).";
75
+ }
76
+ const lines = [];
77
+ for (const c of candidates) {
78
+ lines.push(`- ${c.suggestedName} (${c.count} successful runs)`);
79
+ lines.push(` signature: ${c.bin} / ${c.mode} / ${c.inputs || "(none)"}`);
80
+ lines.push(` runs: ${c.runIds.join(", ")}`);
81
+ }
82
+ return lines.join("\n");
83
+ }
84
+ /**
85
+ * Drive the read-only `otto-skills` command over `.otto/skills/`. Subcommands:
86
+ * `list` (default) inventories skills + derived status; `audit` summarizes
87
+ * usable/unvalidated/stale; `why <path>...` shows which skills retrieval would
88
+ * select for those changed paths and why; `candidates` suggests skills from
89
+ * repeated successful runs. Read-only — it never executes a skill's tests or
90
+ * mutates a package. Resolves to the process exit code (mirrors `runMemory`).
91
+ */
92
+ export async function runSkills(argv, deps = defaultDeps) {
93
+ const arg = argv[0];
94
+ if (arg === "-h" || arg === "--help") {
95
+ deps.out(USAGE);
96
+ return 0;
97
+ }
98
+ const known = ["list", "audit", "why", "candidates"];
99
+ if (arg !== undefined && !known.includes(arg)) {
100
+ deps.err(`Unknown subcommand '${arg}'.\n${USAGE}`);
101
+ return 1;
102
+ }
103
+ const workspaceDir = resolve(deps.env.OTTO_WORKSPACE ?? deps.cwd);
104
+ const skills = readSkills(workspaceDir);
105
+ if (arg === "why") {
106
+ const paths = argv.slice(1);
107
+ if (paths.length === 0) {
108
+ deps.err(`why needs at least one changed path.\n${USAGE}`);
109
+ return 1;
110
+ }
111
+ deps.out(formatWhy(selectSkills(skills, { changedPaths: paths })));
112
+ return 0;
113
+ }
114
+ if (arg === "candidates") {
115
+ const runs = listRunIds(workspaceDir)
116
+ .map((id) => readManifest(workspaceDir, id))
117
+ .filter((m) => m != null)
118
+ .map((m) => ({
119
+ runId: m.runId,
120
+ bin: m.bin,
121
+ mode: m.mode,
122
+ inputs: m.inputs,
123
+ exitReason: m.exitReason,
124
+ }));
125
+ deps.out(formatCandidates(findSkillCandidates(runs)));
126
+ return 0;
127
+ }
128
+ if (arg === "audit") {
129
+ deps.out(`Skills audit (${skillsDir(workspaceDir)})`);
130
+ deps.out(formatSkillsAudit(skills));
131
+ return 0;
132
+ }
133
+ deps.out(`Skills (${skillsDir(workspaceDir)})`);
134
+ deps.out(formatSkillsReport(skills));
135
+ return 0;
136
+ }
137
+ //# sourceMappingURL=skills-cli.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skills-cli.js","sourceRoot":"","sources":["../src/skills-cli.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,195 @@
1
+ import type { RunManifest } from "./run-report.js";
2
+ /**
3
+ * Skill extraction and reuse (issue #44 P5). A **skill** is a repo-local,
4
+ * versioned, validated procedure promoted from repeated successful trajectories
5
+ * — so future runs can retrieve a known workflow instead of re-planning it.
6
+ *
7
+ * Unlike a memory record (one JSON file), a skill is a **directory package**
8
+ * `.otto/skills/<name>/`: `skill.json` (this metadata) + `instructions.md` (the
9
+ * body), alongside optional scripts/tests. The `.otto/skills/` directory is the
10
+ * list — there is no central index, exactly like `.otto/runs/` and
11
+ * `.otto/memory/`. Pure fs + JSON, absent/malformed → safe defaults, never
12
+ * throws (mirrors `memory.ts`/`run-report.ts`).
13
+ *
14
+ * This module is a substrate: it is exported from `index.ts` and read by the
15
+ * read-only `otto-skills` bin, but **inert on the loop** — no run auto-selects or
16
+ * auto-applies a skill this slice, so a skill cannot regress a run. Retrieval,
17
+ * validation-gating, and candidate identification layer on top in later slices.
18
+ */
19
+ /** Coarse provenance band, mirroring {@link MemoryTrust}. */
20
+ export type SkillTrust = "trusted" | "unverified" | "deprecated";
21
+ /**
22
+ * Validation provenance: the successful run that last proved the skill works.
23
+ * "Require validation before a skill is used automatically" (the issue) is
24
+ * enforced by retrieval filtering on the DERIVED {@link skillStatus}, which is
25
+ * computed from these fields — not by the bin executing the skill's tests.
26
+ */
27
+ export type SkillValidation = {
28
+ /** Run id whose trajectory last validated this skill (absent = unvalidated). */
29
+ lastValidatedRun?: string;
30
+ /** When that validation happened (ISO). */
31
+ lastValidatedAt?: string;
32
+ };
33
+ /**
34
+ * One skill package's metadata, stored as `.otto/skills/<name>/skill.json`. The
35
+ * `instructions` body lives in the sibling `instructions.md` (or inline here as a
36
+ * fallback) and is loaded by {@link readSkill}.
37
+ */
38
+ export type Skill = {
39
+ /** Filesystem-safe package name; also the directory name. */
40
+ name: string;
41
+ /** Free-text version (semver-ish); default "0.0.0". */
42
+ version: string;
43
+ /** Declared capability tags (e.g. "release-flow") — a retrieval key. */
44
+ capabilities: string[];
45
+ /** Guardrails — e.g. risk classes the skill must not be applied to. */
46
+ constraints: string[];
47
+ /** File/module globs the skill applies to; empty = repo-wide. A retrieval key. */
48
+ scope: string[];
49
+ /** The instruction body (from `instructions.md`, else the inline fallback). */
50
+ instructions: string;
51
+ /** Named helper commands the package ships (name → command string). */
52
+ scripts: Record<string, string>;
53
+ /** Validation command(s) that prove the skill still works. */
54
+ tests: string[];
55
+ validation: SkillValidation;
56
+ trust: SkillTrust;
57
+ createdAt: string;
58
+ /** How many runs have consumed this skill. */
59
+ useCount: number;
60
+ /** Sliding revalidation window in days; past it a validated skill goes stale. */
61
+ revalidateAfterDays?: number;
62
+ };
63
+ /** Absolute path to the workspace's skills root (`.otto/skills`). */
64
+ export declare function skillsDir(workspaceDir: string): string;
65
+ /** Absolute path to one skill's package dir (`.otto/skills/<name>`). */
66
+ export declare function skillDir(workspaceDir: string, name: string): string;
67
+ /** Absolute path to a skill's metadata file (`.otto/skills/<name>/skill.json`). */
68
+ export declare function skillManifestPath(workspaceDir: string, name: string): string;
69
+ /** Absolute path to a skill's instructions body (`.../instructions.md`). */
70
+ export declare function skillInstructionsPath(workspaceDir: string, name: string): string;
71
+ /**
72
+ * Normalize free text into a filesystem-safe, git-branch-safe skill name:
73
+ * lowercase, every non-`[a-z0-9]` run collapsed to a single `-`, trimmed of
74
+ * leading/trailing `-`, capped at 48 chars. Mirrors `slugify`/`deriveTaskKey`.
75
+ */
76
+ export declare function toSkillName(raw: string): string;
77
+ /**
78
+ * Normalize an untrusted parsed `skill.json` value into a {@link Skill}, filling
79
+ * safe defaults for missing/invalid fields. Returns null when the input is not an
80
+ * object or lacks the required `name`, so a malformed package is skipped rather
81
+ * than crashing a read. `instructions` defaults to the inline value (if any);
82
+ * {@link readSkill} overrides it with the `instructions.md` body when present.
83
+ */
84
+ export declare function parseSkill(raw: unknown): Skill | null;
85
+ /**
86
+ * List the skill names present under `.otto/skills/` (the package sub-dirs),
87
+ * sorted. Absent/unreadable dir → `[]` (never throws). The directory is the
88
+ * list; a name here is not a guarantee its `skill.json` parses (use
89
+ * {@link readSkill}).
90
+ */
91
+ export declare function listSkillIds(workspaceDir: string): string[];
92
+ /**
93
+ * Read and normalize one skill package. Parses `skill.json`, then overrides
94
+ * `instructions` with the `instructions.md` body when that file exists. Absent or
95
+ * malformed `skill.json` → null (never throws).
96
+ */
97
+ export declare function readSkill(workspaceDir: string, name: string): Skill | null;
98
+ /** Read every skill package under `.otto/skills/`, skipping malformed ones. */
99
+ export declare function readSkills(workspaceDir: string): Skill[];
100
+ /**
101
+ * Write a skill package: `skill.json` (metadata, with `instructions` omitted) +
102
+ * `instructions.md` (the body). Creates `.otto/skills/<name>/`. The split keeps
103
+ * the body as a readable, diff-friendly markdown file rather than an escaped JSON
104
+ * string.
105
+ */
106
+ export declare function writeSkill(workspaceDir: string, skill: Skill): void;
107
+ /** True when a skill package directory with a `skill.json` exists. */
108
+ export declare function skillExists(workspaceDir: string, name: string): boolean;
109
+ /**
110
+ * Validation lifecycle (issue #44 slice 2). `unvalidated` = never proven by a
111
+ * run (so it must not be applied automatically); `validated` = a successful run
112
+ * proved it and it is within its freshness window; `stale` = it was validated but
113
+ * `revalidateAfterDays` have since elapsed and it needs re-proving.
114
+ */
115
+ export type SkillStatus = "validated" | "unvalidated" | "stale";
116
+ /**
117
+ * Derive a skill's validation status from its recorded validation + freshness
118
+ * policy at `now`. A skill with no `validation.lastValidatedRun` is `unvalidated`;
119
+ * one validated but past its `revalidateAfterDays` window (measured from
120
+ * `lastValidatedAt`) is `stale`; otherwise `validated`. Unparseable timestamps
121
+ * are ignored rather than treated as expired (mirrors `memoryStatus`). Pure —
122
+ * the retrieval gate uses this so only `validated` skills are auto-eligible.
123
+ */
124
+ export declare function skillStatus(skill: Skill, now?: Date): SkillStatus;
125
+ /**
126
+ * Return a copy of the skill marked validated by a successful `runId` at `now`.
127
+ * Pure — the input is not mutated; the caller writes it back to persist the
128
+ * validation (recording a validation is a run's job, never the read-only bin's).
129
+ */
130
+ export declare function recordValidation(skill: Skill, runId: string, now?: Date): Skill;
131
+ /**
132
+ * Minimal path-glob match: `**` spans path separators, `*` spans a single
133
+ * segment, `?` one char. Used for a skill's scope globs against changed paths.
134
+ */
135
+ export declare function globMatch(glob: string, path: string): boolean;
136
+ /** Context a retrieval is scored against (issue #44 slice 3). */
137
+ export type SkillMatchContext = {
138
+ /** The iteration's changed paths — drives scope + risk-class matching. */
139
+ changedPaths?: string[];
140
+ /** A required capability tag the caller is looking for. */
141
+ capability?: string;
142
+ /** Injectable clock for deterministic validation-freshness scoring. */
143
+ now?: Date;
144
+ };
145
+ /**
146
+ * One skill's retrieval verdict: whether it is auto-eligible (validated AND not
147
+ * excluded by a constraint), a relevance `score`, and human `reasons[]` — so the
148
+ * operator can inspect *why* a skill was (or was not) selected (the issue's
149
+ * "users can inspect why a skill was selected" metric).
150
+ */
151
+ export type SkillMatch = {
152
+ name: string;
153
+ eligible: boolean;
154
+ score: number;
155
+ reasons: string[];
156
+ };
157
+ /**
158
+ * Rank skills for the current task. Retrieval is by **declared capability**,
159
+ * **touched files** (scope globs vs. changed paths), and **task risk** (a skill
160
+ * whose constraints forbid the change's risk class is excluded) — the three keys
161
+ * the issue names. Only `validated` skills are auto-`eligible` (validation before
162
+ * use); unvalidated/stale skills are still returned, flagged not-eligible with a
163
+ * reason, so the bin can show the full picture. Sorted eligible-first, then score
164
+ * desc, then name. Pure — no I/O, deterministic.
165
+ */
166
+ export declare function selectSkills(skills: Skill[], ctx?: SkillMatchContext): SkillMatch[];
167
+ /** The run fields candidate identification needs (a subset of {@link RunManifest}). */
168
+ export type CandidateRun = Pick<RunManifest, "runId" | "bin" | "mode" | "inputs" | "exitReason">;
169
+ /**
170
+ * A repeated successful workflow worth promoting into a skill (issue #44 slice
171
+ * 4): the runs that share it, and a suggested package name. It is only a
172
+ * *suggestion* — extraction stays a maintainer action, never auto-promoted.
173
+ */
174
+ export type SkillCandidate = {
175
+ /** Stable grouping signature `<bin>::<mode>::<inputs>`. */
176
+ signature: string;
177
+ bin: string;
178
+ mode: string;
179
+ inputs: string;
180
+ /** A filesystem-safe skill name suggestion derived from the signature. */
181
+ suggestedName: string;
182
+ /** Run ids of the successful runs sharing this signature, chronological. */
183
+ runIds: string[];
184
+ count: number;
185
+ };
186
+ /**
187
+ * Identify candidate skills from recorded runs: group **successful** runs
188
+ * (`exitReason` ∈ {complete, done}) by their `<bin>::<mode>::<inputs>` signature
189
+ * and surface every signature seen `minCount` (default 2) or more times. A
190
+ * conservative, deterministic heuristic — the same task succeeding repeatedly is
191
+ * the strongest signal that it is worth turning into a reusable procedure. Pure;
192
+ * no model call, no auto-promotion. Sorted by count desc, then signature.
193
+ */
194
+ export declare function findSkillCandidates(runs: CandidateRun[], minCount?: number): SkillCandidate[];
195
+ //# sourceMappingURL=skills.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"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"}