@entelligentsia/forgecli 0.11.3 → 0.19.0

package/dist/extensions/forgecli/skill-curator-subagent.js

@@ -0,0 +1,342 @@
+// Per-task curator subagent — FORGE-S24-T10.
+//
+// At task close, the orchestrator hands a trajectory summary, the retrieved
+// skills' bodies (from T08), and the task outcome to a curator subagent. The
+// curator returns zero or more enhancement proposals (insert / update / delete
+// of skill artifacts). This module:
+//
+//   1. Composes a task body that explicitly asks for proposals in a fenced
+//      ```json [...] block, with the canonical proposal schema embedded.
+//   2. Dispatches via `runForgeSubagent` (Iron Law 10 — fresh in-process pi
+//      session, isolated context, persona-only context loader).
+//   3. Parses zero or more proposals from the final assistant output, dropping
+//      any item that fails TypeBox schema validation.
+//   4. Dedupes by `{op, target_path, sha256(diff_body)}` (mirrors T07's drain
+//      key — collisions never reach the sprint-close batch).
+//   5. Writes the deduped batch to `.forge/enhancement-proposals/queue/<sprintId>/<taskId>-<ts>.json`
+//      (T07 layout) only when there is at least one proposal — zero noise on
+//      empty curator runs. If the canonical path already exists, the curator
+//      retries with a fresh `-N` suffix on the ts (append-only invariant —
+//      queue files are never overwritten).
+//
+// What this module DOES NOT do:
+//   - Emit phase events. The orchestrator (caller — `run-task.ts`,
+//     `fix-bug.ts`, gated behind FORGE-S24-T12 feature flag) is responsible
+//     for the Slice 2 contract: composing & emitting the canonical phase
+//     event from runtime telemetry. The curator subagent NEVER calls
+//     `store-cli emit` (IL10 / telemetry-actor-split).
+//   - Write to `forge/forge/meta/skills/` or `.forge/skills/`. The queue
+//     file is the sole sink. (TASK_PROMPT Acceptance Criterion 5.)
+//   - Decide WHEN task-close is. The caller invokes this at task close.
+//
+// Iron Laws (forge-cli-engineer):
+//   IL1  — code only under forge-cli/src/extensions/forgecli/
+//   IL2  — TypeScript + TypeBox; runtime input validated by Value.Parse.
+//   IL6  — no shell-string interpolation (no subprocess here; runForgeSubagent
+//          owns its spawn discipline).
+//   IL7  — failures return a typed result; subagent error surfaces in the
+//          returned record.
+//   IL10 — orchestrator dispatch via runForgeSubagent; this module emits
+//          ZERO phase events; the orchestrator owns runtime attribution and
+//          event emission after this function returns.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as crypto from "node:crypto";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { getFinalOutput, runForgeSubagent, } from "./forge-subagent.js";
+import { isSkillCurationEnabled } from "./skill-curation-flag.js";
+// ── Public schemas ────────────────────────────────────────────────────────
+/**
+ * One retrieved skill (T08 output) supplied to the curator as context.
+ * `body` is the actual SKILL.md text the agent was shown during the task —
+ * the curator reads it to decide whether the skill needs updating.
+ */
+export const RetrievedSkillBodySchema = Type.Object({
+    skillId: Type.String({ minLength: 1 }),
+    name: Type.String({ minLength: 1 }),
+    body: Type.String(),
+});
+export const TaskOutcomeSchema = Type.Object({
+    verdict: Type.Union([
+        Type.Literal("approved"),
+        Type.Literal("revision"),
+        Type.Literal("failed"),
+        Type.Literal("aborted"),
+    ]),
+    notes: Type.Optional(Type.String()),
+});
+export const CuratorInputSchema = Type.Object({
+    sprintId: Type.String({ minLength: 1 }),
+    taskId: Type.String({ minLength: 1 }),
+    cwd: Type.String({ minLength: 1 }),
+    ts: Type.String({ minLength: 1 }),
+    trajectorySummary: Type.String(),
+    retrievedSkills: Type.Array(RetrievedSkillBodySchema),
+    outcome: TaskOutcomeSchema,
+});
+/**
+ * The enhancement proposal schema accepted by this module — mirrors
+ * `forge/forge/schemas/proposal.schema.json` (the queue-drain contract).
+ * `op` is restricted to the canonical three-op enum; other fields are
+ * passed through verbatim if present.
+ *
+ * Strict on required keys (so malformed items are dropped), permissive on
+ * optional keys (so the curator can supply rationale, sourceFrictionIds,
+ * generated_at, etc., without us re-enumerating the entire schema here).
+ */
+const ProposalSchema = Type.Object({
+    op: Type.Union([
+        Type.Literal("insert_skill"),
+        Type.Literal("update_skill"),
+        Type.Literal("delete_skill"),
+    ]),
+    target_path: Type.String({ minLength: 1 }),
+    diff_body: Type.String(),
+    // Optional pass-through fields (kept minimal — extra unknown keys are
+    // also allowed; we use additionalProperties: true to let the curator
+    // supply rationale / sourceFrictionIds / generated_at / sprintId).
+    rationale: Type.Optional(Type.String()),
+    sourceFrictionIds: Type.Optional(Type.Array(Type.String())),
+    generated_at: Type.Optional(Type.String()),
+    sprintId: Type.Optional(Type.String()),
+    proposalId: Type.Optional(Type.String()),
+}, { additionalProperties: true });
+// ── Task-body composition ─────────────────────────────────────────────────
+/**
+ * Compose the first user message for the curator subagent. The body embeds
+ * the trajectory summary, retrieved-skill bodies, and task outcome, and
+ * instructs the curator to return zero or more proposals in a fenced JSON
+ * block. The schema is described inline so the curator does not need to
+ * read an external file.
+ */
+export function composeCuratorTask(input) {
+    const lines = [];
+    lines.push(`# Skill-curator task — ${input.taskId}`);
+    lines.push("");
+    lines.push("You are reviewing one closed Forge task to decide whether any retrieved", "skill should be inserted, updated, or deleted based on what the agent", "actually did. Output zero or more enhancement proposals — empty is fine", "when nothing useful was learned.", "");
+    lines.push("## Sprint / Task");
+    lines.push(`- sprintId: ${input.sprintId}`);
+    lines.push(`- taskId:   ${input.taskId}`);
+    lines.push(`- verdict:  ${input.outcome.verdict}`);
+    if (input.outcome.notes) {
+        lines.push(`- notes:    ${input.outcome.notes}`);
+    }
+    lines.push("");
+    lines.push("## Trajectory summary");
+    lines.push(input.trajectorySummary || "(none)");
+    lines.push("");
+    lines.push("## Retrieved skills (the agent was shown these)");
+    if (input.retrievedSkills.length === 0) {
+        lines.push("(none)");
+    }
+    else {
+        for (const s of input.retrievedSkills) {
+            lines.push(`### ${s.name} (skillId: ${s.skillId})`);
+            lines.push("```");
+            lines.push(s.body);
+            lines.push("```");
+            lines.push("");
+        }
+    }
+    lines.push("## Output format");
+    lines.push("Return a single fenced ```json``` block containing a JSON array.", "Each array element is one proposal with these required keys:", "  - op:          one of \"insert_skill\" | \"update_skill\" | \"delete_skill\"", "  - target_path: repository-relative path (e.g. forge/skills/engineer-skills.md)", "  - diff_body:   unified-diff body, or full file body for inserts;", "                 may be empty string for delete_skill", "Optional keys: rationale, sourceFrictionIds, generated_at, sprintId.", "", "If there is nothing to propose, emit an empty array `[]`.", "Do NOT write any file yourself. Do NOT call store-cli or emit events.", "Your output is consumed by the orchestrator, which writes the queue file.");
+    return lines.join("\n");
+}
+// ── Output parsing ────────────────────────────────────────────────────────
+/**
+ * Pull zero or more proposals from the curator's final assistant text.
+ * Strategy: try fenced ```json blocks first (the requested format), then
+ * fall back to a bare JSON array scan. Items that fail TypeBox validation
+ * are dropped — the failure mode for ill-formed proposals is silent
+ * exclusion, not exception, because the curator's output is best-effort.
+ */
+export function parseProposalsFromOutput(text) {
+    if (typeof text !== "string" || text.length === 0)
+        return [];
+    const candidates = [];
+    // 1. Fenced ```json blocks (preferred).
+    const fenceRe = /```(?:json|JSON)\s*([\s\S]*?)```/g;
+    let m;
+    while ((m = fenceRe.exec(text)) !== null) {
+        const inner = m[1].trim();
+        const parsed = tryParseJsonArray(inner);
+        if (parsed)
+            candidates.push(...parsed);
+    }
+    // 2. Fallback: scan for a bare JSON array if no fenced block produced
+    //    items. Cheap heuristic — find the first `[` and try to parse from
+    //    there to the matching `]`.
+    if (candidates.length === 0) {
+        const start = text.indexOf("[");
+        if (start >= 0) {
+            // Greedy: try the substring from `[` to the last `]`.
+            const end = text.lastIndexOf("]");
+            if (end > start) {
+                const inner = text.slice(start, end + 1);
+                const parsed = tryParseJsonArray(inner);
+                if (parsed)
+                    candidates.push(...parsed);
+            }
+        }
+    }
+    const out = [];
+    for (const c of candidates) {
+        if (Value.Check(ProposalSchema, c)) {
+            out.push(c);
+        }
+    }
+    return out;
+}
+function tryParseJsonArray(s) {
+    try {
+        const v = JSON.parse(s);
+        return Array.isArray(v) ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+// ── Dedupe ────────────────────────────────────────────────────────────────
+/**
+ * Mirror T07's `dedupeKey`: composite of op, target_path, sha256(diff_body).
+ * First-seen-wins.
+ */
+function dedupeKey(p) {
+    const h = crypto
+        .createHash("sha256")
+        .update(p.diff_body ?? "", "utf8")
+        .digest("hex");
+    return `${p.op}|${p.target_path}|${h}`;
+}
+function dedupeProposals(items) {
+    const seen = new Set();
+    const out = [];
+    for (const p of items) {
+        const k = dedupeKey(p);
+        if (seen.has(k))
+            continue;
+        seen.add(k);
+        out.push(p);
+    }
+    return out;
+}
+// ── Queue write ───────────────────────────────────────────────────────────
+/**
+ * Compute the canonical queue file path. T07 layout:
+ *   <cwd>/.forge/enhancement-proposals/queue/<sprintId>/<taskId>-<ts>.json
+ *
+ * If the canonical path already exists, suffix `-1`, `-2`, … until a free
+ * slot is found. Caller never overwrites an existing file (append-only).
+ */
+function chooseQueuePath(input) {
+    const dir = path.join(input.cwd, ".forge", "enhancement-proposals", "queue", input.sprintId);
+    const base = `${input.taskId}-${input.ts}`;
+    let candidate = path.join(dir, `${base}.json`);
+    let n = 1;
+    while (fs.existsSync(candidate)) {
+        candidate = path.join(dir, `${base}-${n}.json`);
+        n++;
+    }
+    return candidate;
+}
+function writeQueueFile(filePath, proposals) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(proposals, null, 2), "utf8");
+}
+// ── Curator persona ───────────────────────────────────────────────────────
+/**
+ * Inline curator persona. We do NOT add a file under
+ * `forge/forge/meta/personas/` (Iron Law 1 — forge-cli only). The persona
+ * system prompt is small and self-contained; it tells the LLM to act as a
+ * skill curator and reiterates the output format and the no-write rule.
+ *
+ * The persona is exported so tests can introspect it; in production the
+ * defaultCuratorPersona() factory is consumed by runSkillCurator.
+ */
+export function defaultCuratorPersona() {
+    const systemPrompt = [
+        "You are the Forge **skill curator**.",
+        "",
+        "Your sole job is to look at one closed task — the trajectory summary,",
+        "the skills the agent was shown, and the outcome — and propose zero or",
+        "more enhancement proposals (insert / update / delete of skill artifacts).",
+        "",
+        "Hard rules:",
+        "  - You NEVER write files yourself. Output proposals only.",
+        "  - You NEVER call store-cli, emit events, or invoke tools that mutate",
+        "    `.forge/store/`, `forge/skills/`, or `forge/meta/`.",
+        "  - You return your proposals as a single fenced ```json``` block",
+        "    containing a JSON array. Empty array `[]` is a valid answer.",
+        "  - Each proposal MUST have: op, target_path, diff_body.",
+        "    op ∈ { insert_skill, update_skill, delete_skill }.",
+        "  - Be conservative: empty array beats a noisy or speculative proposal.",
+    ].join("\n");
+    return {
+        name: "skill-curator",
+        description: "Forge per-task skill curator",
+        // Persona-only context (no extensions/skills/prompts) — read & write are
+        // not needed; we don't pass `tools` so pi's defaults apply, but the
+        // system prompt forbids writes. Caller may override.
+        systemPrompt,
+        filePath: "<inline:skill-curator>",
+    };
+}
+// ── Main entry ────────────────────────────────────────────────────────────
+/**
+ * Run the per-task curator subagent and write its proposals to the
+ * enhancement-proposals queue. Always returns a typed result; never throws
+ * on subagent failure (IL7).
+ *
+ * Caller (orchestrator) is responsible for:
+ *   - assembling `retrievedSkills` from the T08 retriever's output;
+ *   - assembling `trajectorySummary` from the task transcript;
+ *   - emitting the canonical phase event AFTER this call returns,
+ *     using its own captured runtime telemetry (Slice 2 contract).
+ */
+export async function runSkillCurator(input) {
+    // FORGE-S24-T12 — gated rollout. Default off ⇒ no subagent dispatch,
+    // no queue file write. Returns success with `written: 0` so the
+    // orchestrator's caller sees the same "no proposals" outcome as a
+    // flag-on run that produced an empty proposal list.
+    if (!isSkillCurationEnabled(input.cwd)) {
+        return { exitCode: 0, written: 0 };
+    }
+    Value.Parse(CuratorInputSchema, input);
+    const persona = defaultCuratorPersona();
+    const task = composeCuratorTask(input);
+    let subResult;
+    try {
+        subResult = await runForgeSubagent({
+            persona,
+            task,
+            cwd: input.cwd,
+            exportTag: `${input.taskId}__skill-curator`,
+        });
+    }
+    catch (err) {
+        const e = err;
+        return {
+            exitCode: 1,
+            written: 0,
+            errorMessage: e.message ?? "runForgeSubagent threw",
+        };
+    }
+    if (subResult.exitCode !== 0) {
+        return {
+            exitCode: 1,
+            written: 0,
+            errorMessage: subResult.errorMessage ?? subResult.stopReason ?? "subagent failed",
+        };
+    }
+    const finalText = getFinalOutput(subResult.messages);
+    const proposals = parseProposalsFromOutput(finalText);
+    const deduped = dedupeProposals(proposals);
+    if (deduped.length === 0) {
+        return { exitCode: 0, written: 0 };
+    }
+    const queueFile = chooseQueuePath(input);
+    writeQueueFile(queueFile, deduped);
+    return { exitCode: 0, written: deduped.length, queueFile };
+}
+//# sourceMappingURL=skill-curator-subagent.js.map

package/dist/extensions/forgecli/skill-curator-subagent.js.map

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

package/dist/extensions/forgecli/skill-retriever.d.ts

@@ -0,0 +1,84 @@
+import lunr from "lunr";
+import { type Static, Type } from "typebox";
+/**
+ * One skill in the retrieval corpus. `frontmatter` is the parsed YAML head
+ * of the SKILL.md file (matches `loaders/persona-skill-loader.ts` Skill shape
+ * for `frontmatter` field). Only `description` plus selected frontmatter
+ * fields are indexed — the body is intentionally excluded to keep the index
+ * small and keyword-focused.
+ */
+export declare const RetrievableSkillSchema: Type.TObject<{
+    skillId: Type.TString;
+    name: Type.TString;
+    description: Type.TString;
+    frontmatter: Type.TRecord<"^.*$", Type.TUnknown>;
+}>;
+export type RetrievableSkill = Static<typeof RetrievableSkillSchema>;
+export declare const RetrievalHitSchema: Type.TObject<{
+    skillId: Type.TString;
+    score: Type.TNumber;
+}>;
+export type RetrievalHit = Static<typeof RetrievalHitSchema>;
+/**
+ * Runtime attribution supplied by the caller (orchestrator).
+ * These are NEVER fabricated inside the retriever (IL10).
+ */
+export declare const EmitRuntimeSchema: Type.TObject<{
+    storeCli: Type.TString;
+    cwd: Type.TString;
+    sprintId: Type.TString;
+    taskId: Type.TString;
+    role: Type.TString;
+    action: Type.TString;
+    phase: Type.TOptional<Type.TString>;
+    iteration: Type.TOptional<Type.TInteger>;
+    startTimestamp: Type.TString;
+    endTimestamp: Type.TString;
+    durationMinutes: Type.TNumber;
+    model: Type.TString;
+    provider: Type.TString;
+}>;
+export type EmitRuntime = Static<typeof EmitRuntimeSchema>;
+export interface EmitResult {
+    emitted: number;
+    failed: number;
+    stderrs: string[];
+}
+/**
+ * Opaque handle returned by `buildSkillIndex`. Internally pairs the lunr
+ * index with the corpus so `retrieveTopK` can return the original skillIds.
+ */
+export interface SkillIndex {
+    readonly _index: lunr.Index;
+    readonly _byRef: Map<string, RetrievableSkill>;
+}
+/**
+ * Build a BM25 index over the supplied corpus. Indexed fields:
+ *   - `name`        (boost 4) — the skill identifier itself
+ *   - `description` (boost 2) — primary intent text
+ *   - `frontmatter` (boost 1) — tags / aliases
+ *
+ * lunr's default scoring is Okapi BM25.
+ */
+export declare function buildSkillIndex(corpus: readonly RetrievableSkill[]): SkillIndex;
+/**
+ * Return the top-k skills by BM25 score for the given query. Deterministic
+ * for fixed (corpus, query) pairs. Returns `[]` when no token in the query
+ * is present in any indexed field.
+ */
+export declare function retrieveTopK(index: SkillIndex, query: string, k: number): RetrievalHit[];
+/**
+ * Clamp a raw BM25 score into the [0,1] window required by the event
+ * schema (`retrieval_score`). BM25 scores are unbounded above; we apply
+ * `s / (1 + s)` so the relative ordering is preserved while the absolute
+ * value is monotonically squashed into (0,1). Negative scores (lunr never
+ * produces these in practice) clamp to 0.
+ */
+export declare function clampRetrievalScore(rawScore: number): number;
+/**
+ * Emit one `skill_usage` event per supplied hit via
+ * `node <storeCli> emit <sprintId> <json>`. Returns the (emitted, failed)
+ * counts. Never throws on subprocess failure — the failure is surfaced via
+ * the returned counter and stderr text (IL7 — explicit, not silent).
+ */
+export declare function emitSkillUsageEvents(hits: readonly RetrievalHit[], runtime: EmitRuntime): EmitResult;