@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/skills/skill-review.js

@@ -0,0 +1,271 @@
+/**
+ * Skill-learning review — Brigade's behavior-change self-improvement pass.
+ *
+ * The self-improvement engine has two halves: distil the session into MEMORY,
+ * and distil reusable techniques into SKILLS. Brigade already does the first
+ * (the extraction sweep + `self-review.ts`). This is the second — the
+ * behavior-change half: on a cadence, a tool-LESS reviewer reflects on the
+ * session and proposes new SKILLS (named, reusable procedures); a deterministic
+ * apply-step writes them as `SKILL.md` files the agent discovers on its NEXT
+ * turn. So memory makes the agent know more; this makes it DO better.
+ *
+ * SECURITY — skills are AUTHORITY over behavior. Unlike memory (origin-isolated,
+ * recalled per-principal), a skill learned from one session changes how the
+ * agent acts for EVERY future turn. A channel peer must therefore NEVER author
+ * one (that would be behavior injection). The caller gates this to OWNER
+ * sessions; the apply-step additionally writes ONLY the agent's own workspace
+ * scope (never the cross-agent `managed` root) and reuses the `manage_skill`
+ * tool's path-containment + sanitisation rather than re-deriving them.
+ *
+ * Brigade-native shape (vs a forked tool-agent): a tool-less LLM emits a
+ * STRUCTURED proposal and a deterministic apply-step performs the writes — so
+ * the whole pass is unit-testable without a model or a running loop (the same
+ * shape as the extraction + consolidation sweeps). The reviewer is INJECTED.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { resolveSkillsDir } from "../../config/paths.js";
+import { createSubsystemLogger } from "../../logging/subsystem-logger.js";
+import { balancedObjects, makeIsolatedLlm } from "../memory/extract.js";
+import { appendSkillSection, isPathInside, mirrorSkillWrite, renderSkillTemplate, sanitizeSkillName, } from "../tools/manage-skill-tool.js";
+import { recordSkillCreated, recordSkillPatched } from "./skill-usage.js";
+const log = createSubsystemLogger("skills/review");
+/** Cadence — review skills once `itersSinceReview` reaches `interval`. The reviewer
+ *  nudges skills by activity count (memory by turn); the caller owns the counter.
+ *  `0` disables. Kept as a pure rule so it's testable in isolation. */
+export function shouldReviewSkills(itersSinceReview, interval) {
+    return interval > 0 && itersSinceReview >= interval;
+}
+/**
+ * The review prompt — "is there a REUSABLE skill here?" with
+ * anti-fragmentation discipline (most sessions yield none; never a one-off, an
+ * env-failure, or a negative tool claim). These filters are what stop the loop
+ * from flooding the library with narrow single-session entries.
+ */
+export const SKILL_REVIEW_PROMPT = [
+    "Review the conversation above and decide whether it produced a REUSABLE SKILL —",
+    "a named, repeatable technique, workflow, or convention worth not relearning.",
+    "Most sessions yield NONE; zero is the common, correct answer. Noise is worse than nothing.",
+    "",
+    "PREFER REFINING over creating. If a skill used THIS session (its SKILL.md appears",
+    "above) turned out to be missing a step, wrong, or could be sharper, PATCH it:",
+    'set "mode":"patch", reuse its EXACT name, and put ONLY the new section in "body"',
+    "(a pitfall, a step, a clarified trigger) — never restate the whole skill.",
+    "",
+    "CREATE a new skill (\"mode\":\"create\") ONLY when no existing one covers the class, and",
+    "only when ALL hold:",
+    "  • It's a CLASS of task that will recur — not a one-off narrative of what just happened.",
+    "  • It has a concrete, transferable procedure someone could follow next time.",
+    "  • It isn't already obvious to a capable agent.",
+    "Most sessions yield NOTHING; zero is the common, correct answer. Noise is worse than nothing.",
+    "",
+    "DO NOT propose a skill (create OR patch) for:",
+    '  • A single specific task with no reusable class (e.g. "fix issue #123").',
+    "  • Environment-dependent failures (a missing binary, an unconfigured key).",
+    '  • Negative claims about tools ("X is broken") — they ossify into refusals.',
+    "  • Transient errors that resolved within the session.",
+    "",
+    "Return STRICT JSON only — no prose, no markdown fences:",
+    '{"skills":[{"mode":"create|patch","name":"kebab-case-class-name","description":"one line: when to use this (create only)","body":"# Title + procedure (create), OR just the section to append (patch)","reason":"why this recurs"}]}',
+    'Use {"skills":[]} when nothing qualifies. Respond with ONLY the JSON object.',
+].join("\n");
+/**
+ * Parse the reviewer reply into proposals. Robust to prose-wrapping AND a leading
+ * stray object: scans every top-level balanced `{...}` and uses the FIRST that
+ * carries a `skills` array (same hardening as `parseExtractedFacts`). Never throws.
+ */
+export function parseSkillProposals(text) {
+    if (!text)
+        return [];
+    for (const block of balancedObjects(text)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(block);
+        }
+        catch {
+            continue;
+        }
+        if (!Array.isArray(parsed.skills))
+            continue;
+        const out = [];
+        for (const raw of parsed.skills) {
+            if (!raw || typeof raw !== "object")
+                continue;
+            const s = raw;
+            // description is optional (a patch needs none); name + body are required.
+            if (typeof s.name !== "string" || typeof s.body !== "string" || !s.name.trim() || !s.body.trim())
+                continue;
+            out.push({
+                name: s.name.trim(),
+                description: typeof s.description === "string" ? s.description.trim() : "",
+                body: s.body,
+                ...(typeof s.reason === "string" ? { reason: s.reason.trim() } : {}),
+                ...(s.mode === "patch" || s.mode === "create" ? { mode: s.mode } : {}),
+            });
+        }
+        return out;
+    }
+    return [];
+}
+/** Anti-fragmentation: one review can't flood the library with NEW skills. */
+const MAX_SKILLS_PER_REVIEW = 2;
+/** Patches don't add skills (and appendSkillSection dedups + size-caps), but bound
+ *  per-pass churn anyway. */
+const MAX_PATCHES_PER_REVIEW = 3;
+/**
+ * Run one skill-review pass and write any new skills to the agent's OWN
+ * workspace scope. Best-effort: a reviewer error / malformed return is a no-op,
+ * never throwing into the sweep. Dedups against existing skill names (the
+ * reviewer can neither clobber nor re-create), caps the number created per pass,
+ * and refuses anything whose resolved path escapes the agent's skills root.
+ *
+ * `agentId` selects the OWNER-workspace skills root; the caller MUST only invoke
+ * this for owner-origin sessions (a peer must not be able to author behavior).
+ */
+export async function runSkillReview(args) {
+    let proposals;
+    try {
+        proposals = await args.reviewer(SKILL_REVIEW_PROMPT, args.transcript);
+    }
+    catch {
+        return { created: [], patched: [], skipped: [], summary: "skill-review: skipped (reviewer error)" };
+    }
+    if (!Array.isArray(proposals) || proposals.length === 0) {
+        return { created: [], patched: [], skipped: [], summary: "skill-review: nothing to learn" };
+    }
+    const root = resolveSkillsDir(args.agentId);
+    const existing = existingSkillNames(root);
+    const created = [];
+    const patched = [];
+    const skipped = [];
+    for (const p of proposals) {
+        const safeName = sanitizeSkillName(p.name);
+        if (!safeName) {
+            skipped.push({ name: p.name, reason: "unsafe name" });
+            continue;
+        }
+        const skillDir = path.join(root, safeName);
+        // Defense in depth — same contain-check the manage_skill tool runs (both
+        // create AND patch): the resolved path MUST live inside the skills root.
+        if (!isPathInside(path.resolve(root), path.resolve(skillDir))) {
+            skipped.push({ name: safeName, reason: "path escapes scope" });
+            continue;
+        }
+        const skillFile = path.join(skillDir, "SKILL.md");
+        const exists = existing.has(safeName.toLowerCase());
+        // PATCH — refine an existing skill (the first-choice action). Appends
+        // the new section; dedups + size-caps live in appendSkillSection.
+        if (p.mode === "patch") {
+            if (!exists) {
+                skipped.push({ name: safeName, reason: "patch target does not exist" });
+                continue;
+            }
+            if (patched.length >= MAX_PATCHES_PER_REVIEW) {
+                skipped.push({ name: safeName, reason: "per-review patch cap reached" });
+                continue;
+            }
+            const res = appendSkillSection(skillFile, p.body);
+            if (!res.ok || res.content === undefined) {
+                skipped.push({ name: safeName, reason: res.reason ?? "patch failed" });
+                continue;
+            }
+            mirrorSkillWrite("agent", args.agentId, safeName, res.content);
+            recordSkillPatched(root, safeName);
+            patched.push(safeName);
+            log.info("skill-review refined a skill", { agentId: args.agentId, name: safeName });
+            continue;
+        }
+        // CREATE — a brand-new skill (capped for anti-fragmentation).
+        if (created.length >= MAX_SKILLS_PER_REVIEW) {
+            skipped.push({ name: safeName, reason: "per-review create cap reached" });
+            continue;
+        }
+        if (exists) {
+            skipped.push({ name: safeName, reason: "already exists (use mode=patch to refine)" });
+            continue;
+        }
+        const content = renderSkillTemplate({
+            name: safeName,
+            description: p.description,
+            body: p.body.trim(),
+        });
+        try {
+            fs.mkdirSync(skillDir, { recursive: true });
+            // `wx` — fail if SKILL.md already exists, so a race with the manage_skill
+            // tool (or a concurrent sweep) can never clobber a hand-authored skill.
+            fs.writeFileSync(skillFile, content, { encoding: "utf8", flag: "wx" });
+        }
+        catch (err) {
+            const raced = err?.code === "EEXIST";
+            // Non-race write fault (ENOSPC/EPERM/EROFS/…): the mkdir above may have
+            // just created an empty skillDir. Best-effort remove it so a SKILL.md-less
+            // orphan can't permanently block this name on a later pass.
+            if (!raced) {
+                try {
+                    fs.rmdirSync(skillDir);
+                }
+                catch {
+                    /* leave it — existingSkillNames now ignores SKILL.md-less dirs anyway */
+                }
+            }
+            skipped.push({ name: safeName, reason: raced ? "already exists" : "write failed" });
+            continue;
+        }
+        // Convex mirror (no-op in fs mode) so the skills table learns immediately,
+        // not only at the next gateway boot reconcile.
+        mirrorSkillWrite("agent", args.agentId, safeName, content);
+        // Mark it agent-created so the curator may age it out later if it never
+        // gets used (anchors the inactivity clock at creation).
+        recordSkillCreated(root, safeName);
+        existing.add(safeName.toLowerCase());
+        created.push(safeName);
+        log.info("skill-review learned a skill", { agentId: args.agentId, name: safeName });
+    }
+    const parts = [];
+    if (created.length)
+        parts.push(`learned ${created.length} (${created.join(", ")})`);
+    if (patched.length)
+        parts.push(`refined ${patched.length} (${patched.join(", ")})`);
+    return {
+        created,
+        patched,
+        skipped,
+        summary: parts.length ? `skill-review: ${parts.join("; ")}` : "skill-review: nothing durable to learn",
+    };
+}
+/** Existing skill directory names under a root, lowercased, for dedup. A dir
+ *  counts as a skill only if it has a SKILL.md (mirrors `onDiskSkillNames`), so a
+ *  bare/orphan directory never blocks a name — the create path's `wx` flag still
+ *  prevents clobbering a real skill. Missing root → empty set (no skills yet,
+ *  not an error). */
+function existingSkillNames(root) {
+    const out = new Set();
+    let entries;
+    try {
+        entries = fs.readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return out;
+    }
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith("."))
+            continue;
+        if (fs.existsSync(path.join(root, e.name, "SKILL.md")))
+            out.add(e.name.toLowerCase());
+    }
+    return out;
+}
+/**
+ * The production reviewer — a tool-less isolated LLM with {@link SKILL_REVIEW_PROMPT}
+ * pinned (the same one-shot, throwaway-transcript subagent the extraction +
+ * consolidation sweeps use), its reply parsed into proposals. One extra model
+ * call per skill-review fire (cadence-gated), never per turn.
+ */
+export function makeSkillReviewer(args) {
+    const llm = makeIsolatedLlm(SKILL_REVIEW_PROMPT, args);
+    return async (_prompt, transcript) => {
+        const reply = await llm(transcript);
+        return parseSkillProposals(reply);
+    };
+}
+//# sourceMappingURL=skill-review.js.map

package/dist/agents/skills/skill-review.js.map

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

package/dist/agents/skills/skill-usage.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Skill usage telemetry + provenance — the substrate the skill CURATOR reads to
+ * decide lifecycle (Brigade-native skill-usage telemetry).
+ *
+ * A sidecar `.usage.json` next to a skills root, keyed by skill name. Records
+ * when a skill was created, how often it's been USED (a `read` of its SKILL.md,
+ * detected off-hot-path in the gateway sweep), and its lifecycle state. The
+ * curator anchors aging on the latest real activity (`lastUsedAt`), falling back
+ * to `createdAt` so a brand-new skill isn't archived on sight.
+ *
+ * Design:
+ *   - Sidecar, not SKILL.md frontmatter — keeps operational telemetry out of the
+ *     user-/model-authored skill content.
+ *   - Atomic write (tmp + rename); every mutation is BEST-EFFORT (a broken
+ *     sidecar never breaks the underlying tool call or the sweep).
+ *   - Provenance gate: only skills explicitly marked `createdBy:"agent"` (set on
+ *     `manage_skill create` + the skill-review auto-learner) are curator-managed.
+ *     A hand-dropped SKILL.md is never auto-archived — it has no record.
+ *   - Injectable clock (`now` ms) so the curator + telemetry are deterministic in
+ *     tests, exactly like the FactStore clock seam.
+ *
+ * Lifecycle states: active (default) → stale (unused > staleAfter) → archived
+ * (unused > archiveAfter; the skill dir is moved aside by the curator). `pinned`
+ * is an orthogonal opt-out from all auto-transitions.
+ */
+export type SkillState = "active" | "stale" | "archived";
+export declare const SKILL_STATE_ACTIVE: SkillState;
+export declare const SKILL_STATE_STALE: SkillState;
+export declare const SKILL_STATE_ARCHIVED: SkillState;
+export interface SkillUsageRecord {
+    /** "agent" ⇒ created by manage_skill / the auto-learner ⇒ curator-managed.
+     *  Absent ⇒ a hand-authored skill the curator must never touch. */
+    createdBy?: "agent";
+    createdAt: string;
+    useCount: number;
+    lastUsedAt: string | null;
+    /** Times the skill was refined in place (a patch is also "activity"). */
+    patchCount: number;
+    state: SkillState;
+    pinned: boolean;
+    archivedAt: string | null;
+}
+export type SkillUsageMap = Record<string, SkillUsageRecord>;
+/** Read the whole sidecar. Missing / corrupt → empty map (never throws). */
+export declare function loadUsage(skillsRoot: string): SkillUsageMap;
+/** Write the sidecar atomically. Best-effort — a failure is logged, not thrown. */
+export declare function saveUsage(skillsRoot: string, data: SkillUsageMap): void;
+/** Mark a skill as agent-created (manage_skill / auto-learner) ⇒ curator-managed.
+ *  Anchors `createdAt` the first time so the inactivity clock starts now. */
+export declare function recordSkillCreated(skillsRoot: string, name: string, nowMs?: number): void;
+/** Bump use_count + lastUsedAt — the curator's reactivation/aging signal. Called
+ *  from the sweep when a skill's SKILL.md was read this window. Pure telemetry:
+ *  the lifecycle FLIP (stale → active) is left to the curator's transition pass
+ *  (record-only here; the curator reactivates). */
+export declare function recordSkillUse(skillsRoot: string, name: string, nowMs?: number): void;
+/** Bump patchCount + lastUsedAt — a refinement is also activity, so a patched
+ *  skill resets its staleness clock (the curator won't age out a skill we keep
+ *  improving). Called by the manage_skill patch action + the skill-review patcher. */
+export declare function recordSkillPatched(skillsRoot: string, name: string, nowMs?: number): void;
+export declare function setSkillState(skillsRoot: string, name: string, state: SkillState, nowMs?: number): void;
+export declare function setSkillPinned(skillsRoot: string, name: string, pinned: boolean, nowMs?: number): void;
+/** Drop a skill's record entirely — called when the skill is deleted. */
+export declare function forgetSkill(skillsRoot: string, name: string): void;
+/** The newest real-activity anchor for aging: lastUsedAt, falling back to
+ *  createdAt (so a never-used skill ages from creation, not epoch). Returns ms. */
+export declare function activityAnchorMs(rec: SkillUsageRecord): number;
+export interface CurationCandidate {
+    name: string;
+    record: SkillUsageRecord;
+}
+/**
+ * Curator-managed candidates: skills present on disk under `skillsRoot` whose
+ * record is marked `createdBy:"agent"`. Hand-authored skills (no record / no
+ * agent flag) are excluded — the curator never archives what the operator wrote
+ * by hand. `state` is read from the record (defaults active).
+ */
+export declare function listCurationCandidates(skillsRoot: string, nowMs?: number): CurationCandidate[];
+/** Skill directory names directly under a root (one level; ignores dotfiles like
+ *  `.usage.json` / `.archive`). A dir counts as a skill only if it has SKILL.md. */
+export declare function onDiskSkillNames(skillsRoot: string): string[];
+//# sourceMappingURL=skill-usage.d.ts.map

package/dist/agents/skills/skill-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-usage.d.ts","sourceRoot":"","sources":["../../../src/agents/skills/skill-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AASH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,CAAC;AACzD,eAAO,MAAM,kBAAkB,EAAE,UAAqB,CAAC;AACvD,eAAO,MAAM,iBAAiB,EAAE,UAAoB,CAAC;AACrD,eAAO,MAAM,oBAAoB,EAAE,UAAuB,CAAC;AAE3D,MAAM,WAAW,gBAAgB;IAChC;uEACmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,yEAAyE;IACzE,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,UAAU,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC;AAsB7D,4EAA4E;AAC5E,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAkB3D;AAED,mFAAmF;AACnF,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,GAAG,IAAI,CAUvE;AAsBD;6EAC6E;AAC7E,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,IAAI,CAMrG;AAED;;;mDAGmD;AACnD,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,IAAI,CAKjG;AAED;;sFAEsF;AACtF,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,IAAI,CAKrG;AAED,wBAAgB,aAAa,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,GAAE,MAAmB,GAAG,IAAI,CAMnH;AAED,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,GAAE,MAAmB,GAAG,IAAI,CAIlH;AAED,yEAAyE;AACzE,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAWlE;AAED;mFACmF;AACnF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,gBAAgB,GAAG,MAAM,CAI9D;AAED,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,gBAAgB,CAAC;CACzB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,GAAE,MAAmB,GAAG,iBAAiB,EAAE,CAU1G;AAED;oFACoF;AACpF,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAa7D"}

package/dist/agents/skills/skill-usage.js

@@ -0,0 +1,208 @@
+/**
+ * Skill usage telemetry + provenance — the substrate the skill CURATOR reads to
+ * decide lifecycle (Brigade-native skill-usage telemetry).
+ *
+ * A sidecar `.usage.json` next to a skills root, keyed by skill name. Records
+ * when a skill was created, how often it's been USED (a `read` of its SKILL.md,
+ * detected off-hot-path in the gateway sweep), and its lifecycle state. The
+ * curator anchors aging on the latest real activity (`lastUsedAt`), falling back
+ * to `createdAt` so a brand-new skill isn't archived on sight.
+ *
+ * Design:
+ *   - Sidecar, not SKILL.md frontmatter — keeps operational telemetry out of the
+ *     user-/model-authored skill content.
+ *   - Atomic write (tmp + rename); every mutation is BEST-EFFORT (a broken
+ *     sidecar never breaks the underlying tool call or the sweep).
+ *   - Provenance gate: only skills explicitly marked `createdBy:"agent"` (set on
+ *     `manage_skill create` + the skill-review auto-learner) are curator-managed.
+ *     A hand-dropped SKILL.md is never auto-archived — it has no record.
+ *   - Injectable clock (`now` ms) so the curator + telemetry are deterministic in
+ *     tests, exactly like the FactStore clock seam.
+ *
+ * Lifecycle states: active (default) → stale (unused > staleAfter) → archived
+ * (unused > archiveAfter; the skill dir is moved aside by the curator). `pinned`
+ * is an orthogonal opt-out from all auto-transitions.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createSubsystemLogger } from "../../logging/subsystem-logger.js";
+const log = createSubsystemLogger("skills/usage");
+export const SKILL_STATE_ACTIVE = "active";
+export const SKILL_STATE_STALE = "stale";
+export const SKILL_STATE_ARCHIVED = "archived";
+function usageFilePath(skillsRoot) {
+    return path.join(skillsRoot, ".usage.json");
+}
+function iso(nowMs) {
+    return new Date(nowMs).toISOString();
+}
+function emptyRecord(nowMs) {
+    return {
+        createdAt: iso(nowMs),
+        useCount: 0,
+        lastUsedAt: null,
+        patchCount: 0,
+        state: SKILL_STATE_ACTIVE,
+        pinned: false,
+        archivedAt: null,
+    };
+}
+/** Read the whole sidecar. Missing / corrupt → empty map (never throws). */
+export function loadUsage(skillsRoot) {
+    let raw;
+    try {
+        raw = fs.readFileSync(usageFilePath(skillsRoot), "utf8");
+    }
+    catch {
+        return {};
+    }
+    try {
+        const data = JSON.parse(raw);
+        if (!data || typeof data !== "object" || Array.isArray(data))
+            return {};
+        const clean = {};
+        for (const [k, v] of Object.entries(data)) {
+            if (v && typeof v === "object" && !Array.isArray(v))
+                clean[k] = v;
+        }
+        return clean;
+    }
+    catch {
+        return {};
+    }
+}
+/** Write the sidecar atomically. Best-effort — a failure is logged, not thrown. */
+export function saveUsage(skillsRoot, data) {
+    const p = usageFilePath(skillsRoot);
+    try {
+        fs.mkdirSync(path.dirname(p), { recursive: true });
+        const tmp = `${p}.tmp-${process.pid}-${Date.now()}`;
+        fs.writeFileSync(tmp, JSON.stringify(data, null, 2), "utf8");
+        fs.renameSync(tmp, p);
+    }
+    catch (err) {
+        log.warn("skill usage save failed", { error: err instanceof Error ? err.message : String(err) });
+    }
+}
+/** Backfill any missing fields so callers can index an old/partial record. */
+function backfill(rec, nowMs) {
+    const base = emptyRecord(nowMs);
+    return { ...base, ...rec };
+}
+/** Load → apply mutator in place → save. Best-effort; never throws. */
+function mutate(skillsRoot, name, nowMs, fn) {
+    if (!name)
+        return;
+    try {
+        const data = loadUsage(skillsRoot);
+        const rec = backfill(data[name] ?? emptyRecord(nowMs), nowMs);
+        fn(rec);
+        data[name] = rec;
+        saveUsage(skillsRoot, data);
+    }
+    catch (err) {
+        log.warn("skill usage mutate failed", { name, error: err instanceof Error ? err.message : String(err) });
+    }
+}
+/** Mark a skill as agent-created (manage_skill / auto-learner) ⇒ curator-managed.
+ *  Anchors `createdAt` the first time so the inactivity clock starts now. */
+export function recordSkillCreated(skillsRoot, name, nowMs = Date.now()) {
+    mutate(skillsRoot, name, nowMs, (rec) => {
+        rec.createdBy = "agent";
+        // Keep the original createdAt if a record already existed; emptyRecord
+        // already stamped now for a fresh one.
+    });
+}
+/** Bump use_count + lastUsedAt — the curator's reactivation/aging signal. Called
+ *  from the sweep when a skill's SKILL.md was read this window. Pure telemetry:
+ *  the lifecycle FLIP (stale → active) is left to the curator's transition pass
+ *  (record-only here; the curator reactivates). */
+export function recordSkillUse(skillsRoot, name, nowMs = Date.now()) {
+    mutate(skillsRoot, name, nowMs, (rec) => {
+        rec.useCount += 1;
+        rec.lastUsedAt = iso(nowMs);
+    });
+}
+/** Bump patchCount + lastUsedAt — a refinement is also activity, so a patched
+ *  skill resets its staleness clock (the curator won't age out a skill we keep
+ *  improving). Called by the manage_skill patch action + the skill-review patcher. */
+export function recordSkillPatched(skillsRoot, name, nowMs = Date.now()) {
+    mutate(skillsRoot, name, nowMs, (rec) => {
+        rec.patchCount = (rec.patchCount ?? 0) + 1;
+        rec.lastUsedAt = iso(nowMs);
+    });
+}
+export function setSkillState(skillsRoot, name, state, nowMs = Date.now()) {
+    mutate(skillsRoot, name, nowMs, (rec) => {
+        rec.state = state;
+        if (state === SKILL_STATE_ARCHIVED)
+            rec.archivedAt = iso(nowMs);
+        else if (state === SKILL_STATE_ACTIVE)
+            rec.archivedAt = null;
+    });
+}
+export function setSkillPinned(skillsRoot, name, pinned, nowMs = Date.now()) {
+    mutate(skillsRoot, name, nowMs, (rec) => {
+        rec.pinned = pinned;
+    });
+}
+/** Drop a skill's record entirely — called when the skill is deleted. */
+export function forgetSkill(skillsRoot, name) {
+    if (!name)
+        return;
+    try {
+        const data = loadUsage(skillsRoot);
+        if (name in data) {
+            delete data[name];
+            saveUsage(skillsRoot, data);
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+}
+/** The newest real-activity anchor for aging: lastUsedAt, falling back to
+ *  createdAt (so a never-used skill ages from creation, not epoch). Returns ms. */
+export function activityAnchorMs(rec) {
+    const t = rec.lastUsedAt ?? rec.createdAt;
+    const ms = Date.parse(t);
+    return Number.isFinite(ms) ? ms : 0;
+}
+/**
+ * Curator-managed candidates: skills present on disk under `skillsRoot` whose
+ * record is marked `createdBy:"agent"`. Hand-authored skills (no record / no
+ * agent flag) are excluded — the curator never archives what the operator wrote
+ * by hand. `state` is read from the record (defaults active).
+ */
+export function listCurationCandidates(skillsRoot, nowMs = Date.now()) {
+    const data = loadUsage(skillsRoot);
+    const onDisk = onDiskSkillNames(skillsRoot);
+    const out = [];
+    for (const name of onDisk) {
+        const rec = data[name];
+        if (!rec || rec.createdBy !== "agent")
+            continue; // only agent-created are managed
+        out.push({ name, record: backfill(rec, nowMs) });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Skill directory names directly under a root (one level; ignores dotfiles like
+ *  `.usage.json` / `.archive`). A dir counts as a skill only if it has SKILL.md. */
+export function onDiskSkillNames(skillsRoot) {
+    let entries;
+    try {
+        entries = fs.readdirSync(skillsRoot, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const names = [];
+    for (const e of entries) {
+        if (!e.isDirectory() || e.name.startsWith("."))
+            continue;
+        if (fs.existsSync(path.join(skillsRoot, e.name, "SKILL.md")))
+            names.push(e.name);
+    }
+    return names;
+}
+//# sourceMappingURL=skill-usage.js.map

package/dist/agents/skills/skill-usage.js.map

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

package/dist/agents/skills/status.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Skill status reporter — the diagnostic surface behind the `skills.status`
+ * RPC. Built by walking the same discovery roots the per-turn assembler
+ * walks, then projecting each candidate skill (eligible OR not) into a
+ * stable wire shape so the operator can see WHY a skill was hidden:
+ *
+ *   - `eligible: false` + `missing.{bins,anyBins,env,config}` populated
+ *     → skill failed an os/bins/env/config requirement
+ *   - `eligible: false` + `blockedByAllowlist: true`
+ *     → per-agent `cfg.agents.<id>.skills` (or `defaults.skills`) hides it
+ *   - `eligible: false` + `disabled: true`
+ *     → operator turned the skill off via `cfg.skills.entries[<name>].enabled`
+ *
+ * Brand-scrubbed analogue of the reference codebase's `skills-status.ts` +
+ * the `skills.status` gateway method. Brigade omits the install-option
+ * picker (no ClawHub-style remote registry yet); the per-skill `install`
+ * field is reserved for the SkillInstallSpec block authored in SKILL.md
+ * frontmatter and is intentionally undefined for hand-authored skills.
+ */
+import type { BrigadeConfig } from "../../config/io.js";
+/** Per-requirement diagnostics — what the skill declared + what is missing. */
+export interface SkillStatusRequirements {
+    os?: string[];
+    bins?: string[];
+    anyBins?: string[];
+    env?: string[];
+    config?: string[];
+}
+/** One row of the `skills.status` report. */
+export interface SkillStatusEntry {
+    name: string;
+    description: string;
+    source: string;
+    filePath: string;
+    /** True when `cfg.skills.entries[<name>].enabled === false`. */
+    disabled: boolean;
+    /** True when the per-agent / defaults allowlist excludes this skill. */
+    blockedByAllowlist: boolean;
+    /** True when os/bins/env/config + allowlist + disabled all pass. */
+    eligible: boolean;
+    /** Verbatim requirements declared in the skill's SKILL.md frontmatter. */
+    requirements: SkillStatusRequirements;
+    /** Subset of `requirements` that is NOT satisfied on this host. */
+    missing: SkillStatusRequirements;
+}
+export interface SkillStatusReport {
+    workspaceDir: string;
+    managedSkillsDir: string;
+    skills: SkillStatusEntry[];
+}
+export interface BuildSkillStatusReportArgs {
+    workspaceDir: string;
+    config: BrigadeConfig;
+    /** Optional agent id — used to resolve the effective skill allowlist. */
+    agentId?: string;
+    /** Override host platform (tests). */
+    platform?: string;
+    /** Override env (tests). */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Build a full status report for the supplied workspace + config. Walks every
+ * known scan root, dedupes by name (highest precedence wins, matching the
+ * runtime discovery order), and projects each candidate to a wire-stable
+ * `SkillStatusEntry`. Used by the `skills.status` RPC.
+ */
+export declare function buildSkillStatusReport(args: BuildSkillStatusReportArgs): SkillStatusReport;
+//# sourceMappingURL=status.d.ts.map