@entelligentsia/forgecli 0.11.2 → 0.15.0

package/dist/extensions/forgecli/skill-retriever.js

@@ -0,0 +1,246 @@
+// Skill retriever — FORGE-S24-T08.
+//
+// BM25-ranked retrieval over the project's skill corpus using `lunr.js`
+// (exact-pinned in package.json). Each retrieval emits one `skill_usage`
+// event per top-k hit with `retrieved: true` and a populated, [0,1]-clamped
+// `retrieval_score`. Conforms to the canonical event schema variant landed
+// in FORGE-S24-T01 (plugin v0.45.0).
+//
+// Iron Laws (forge-cli-engineer):
+//   IL2  — TypeScript + TypeBox. Schemas defined here; runtime input is
+//          validated by `Value.Parse(...)` at the public entry points.
+//   IL6  — No raw shell-string interpolation. `emitSkillUsageEvents` calls
+//          `spawnSync("node", [storeCli, "emit", sprintId, JSON.stringify(event)])`
+//          — argv array, no shell.
+//   IL7  — No silent continuation past failures. A non-zero `store-cli emit`
+//          exit increments the `failed` counter and the stderr text is
+//          forwarded to the caller in the returned result; nothing is
+//          swallowed.
+//   IL10 — This module is a primitive consumed by orchestrator code. The
+//          orchestrator/caller supplies the runtime attribution
+//          (model/provider/timestamps/durationMinutes) — never fabricated
+//          here.
+//
+// Scope boundary: this module owns ranking + emission. It does NOT crawl
+// the filesystem for skills; corpus construction (reading SKILL.md
+// frontmatter via `loaders/persona-skill-loader.ts`) is the caller's
+// responsibility. Keeping IO out of the retriever keeps the module
+// deterministic and trivially unit-testable.
+import { spawnSync } from "node:child_process";
+import lunr from "lunr";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { isSkillCurationEnabled } from "./skill-curation-flag.js";
+// ── Public schemas ───────────────────────────────────────────────────────
+/**
+ * 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 const RetrievableSkillSchema = Type.Object({
+    skillId: Type.String({ minLength: 1 }),
+    name: Type.String({ minLength: 1 }),
+    description: Type.String(),
+    frontmatter: Type.Record(Type.String(), Type.Unknown()),
+});
+export const RetrievalHitSchema = Type.Object({
+    skillId: Type.String({ minLength: 1 }),
+    score: Type.Number(),
+});
+/**
+ * Runtime attribution supplied by the caller (orchestrator).
+ * These are NEVER fabricated inside the retriever (IL10).
+ */
+export const EmitRuntimeSchema = Type.Object({
+    storeCli: Type.String({ minLength: 1 }),
+    cwd: Type.String({ minLength: 1 }),
+    sprintId: Type.String({ minLength: 1 }),
+    taskId: Type.String({ minLength: 1 }),
+    role: Type.String({ minLength: 1 }),
+    action: Type.String({ minLength: 1 }),
+    phase: Type.Optional(Type.String()),
+    iteration: Type.Optional(Type.Integer({ minimum: 1 })),
+    startTimestamp: Type.String({ format: "date-time" }),
+    endTimestamp: Type.String({ format: "date-time" }),
+    durationMinutes: Type.Number({ minimum: 0 }),
+    model: Type.String({ minLength: 1 }),
+    provider: Type.String({ minLength: 1 }),
+});
+/** Join indexable frontmatter fields (tags + name) into a single string. */
+function frontmatterText(fm) {
+    const parts = [];
+    if (typeof fm.name === "string")
+        parts.push(fm.name);
+    const tags = fm.tags;
+    if (Array.isArray(tags)) {
+        for (const t of tags)
+            if (typeof t === "string")
+                parts.push(t);
+    }
+    const aliases = fm.aliases;
+    if (Array.isArray(aliases)) {
+        for (const a of aliases)
+            if (typeof a === "string")
+                parts.push(a);
+    }
+    return parts.join(" ");
+}
+/**
+ * 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 function buildSkillIndex(corpus) {
+    for (const s of corpus)
+        Value.Parse(RetrievableSkillSchema, s);
+    const byRef = new Map();
+    for (const s of corpus)
+        byRef.set(s.skillId, s);
+    const index = lunr(function () {
+        this.ref("skillId");
+        this.field("name", { boost: 4 });
+        this.field("description", { boost: 2 });
+        this.field("frontmatter", { boost: 1 });
+        // Determinism: lunr's pipeline is deterministic by construction; we do
+        // not register custom plugins or randomised tokenisers.
+        for (const s of corpus) {
+            this.add({
+                skillId: s.skillId,
+                name: s.name,
+                description: s.description,
+                frontmatter: frontmatterText(s.frontmatter),
+            });
+        }
+    });
+    return { _index: index, _byRef: byRef };
+}
+// ── Retrieval ────────────────────────────────────────────────────────────
+/**
+ * Tokenise the query for lunr. We lower-case, strip non-alphanumerics, and
+ * drop empties. Avoids lunr's query-language operators (`:`, `^`, `~`,
+ * `+`, `-`, `*`) leaking from natural-language task descriptions.
+ */
+function safeQueryTokens(query) {
+    return query
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]+/g, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+}
+/**
+ * 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 function retrieveTopK(index, query, k) {
+    if (!Number.isInteger(k) || k <= 0) {
+        throw new Error(`retrieveTopK: k must be a positive integer, got ${k}`);
+    }
+    const tokens = safeQueryTokens(query);
+    if (tokens.length === 0)
+        return [];
+    let results;
+    try {
+        results = index._index.query((q) => {
+            for (const t of tokens) {
+                q.term(t, { usePipeline: true, boost: 1 });
+            }
+        });
+    }
+    catch {
+        // lunr throws on a small set of malformed inputs; treat as no hits
+        // rather than propagating an opaque error into the orchestrator.
+        return [];
+    }
+    const hits = [];
+    for (const r of results) {
+        if (hits.length >= k)
+            break;
+        if (!index._byRef.has(r.ref))
+            continue;
+        hits.push({ skillId: r.ref, score: r.score });
+    }
+    return hits;
+}
+// ── Emission ─────────────────────────────────────────────────────────────
+/**
+ * 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 function clampRetrievalScore(rawScore) {
+    if (!Number.isFinite(rawScore) || rawScore <= 0)
+        return 0;
+    const squashed = rawScore / (1 + rawScore);
+    if (squashed >= 1)
+        return 1;
+    return squashed;
+}
+/** Compose an ISO-compact timestamp segment for the eventId. */
+function isoCompact(iso) {
+    return iso.replace(/[-:.]/g, "").replace(/Z$/, "Z");
+}
+/**
+ * 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 function emitSkillUsageEvents(hits, runtime) {
+    // FORGE-S24-T12 — gated rollout. Default off ⇒ zero events, zero
+    // subprocess calls, byte-identical to pre-FORGE-S24 behaviour.
+    if (!isSkillCurationEnabled(runtime.cwd)) {
+        return { emitted: 0, failed: 0, stderrs: [] };
+    }
+    Value.Parse(EmitRuntimeSchema, runtime);
+    let emitted = 0;
+    let failed = 0;
+    const stderrs = [];
+    for (let i = 0; i < hits.length; i++) {
+        const hit = hits[i];
+        const eventId = `${isoCompact(runtime.startTimestamp)}_${runtime.taskId}_skill-retriever_skill_usage_${i}_${hit.skillId}`;
+        const event = {
+            eventId,
+            sprintId: runtime.sprintId,
+            taskId: runtime.taskId,
+            role: runtime.role,
+            action: runtime.action,
+            startTimestamp: runtime.startTimestamp,
+            endTimestamp: runtime.endTimestamp,
+            durationMinutes: runtime.durationMinutes,
+            model: runtime.model,
+            provider: runtime.provider,
+            type: "skill_usage",
+            skillId: hit.skillId,
+            retrieved: true,
+            used: false,
+            // No tool calls have happened yet at retrieval time. T09 (usage
+            // tracker) will later emit a follow-up event with the observed
+            // success rate.
+            tool_call_success_rate: 0,
+            retrieval_score: clampRetrievalScore(hit.score),
+        };
+        if (runtime.phase !== undefined)
+            event.phase = runtime.phase;
+        if (runtime.iteration !== undefined)
+            event.iteration = runtime.iteration;
+        const result = spawnSync("node", [runtime.storeCli, "emit", runtime.sprintId, JSON.stringify(event)], { cwd: runtime.cwd, encoding: "utf8" });
+        if (result.status === 0) {
+            emitted++;
+        }
+        else {
+            failed++;
+            const stderr = typeof result.stderr === "string" ? result.stderr : "";
+            stderrs.push(stderr);
+        }
+    }
+    return { emitted, failed, stderrs };
+}
+//# sourceMappingURL=skill-retriever.js.map

package/dist/extensions/forgecli/skill-retriever.js.map

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

package/dist/extensions/forgecli/skill-usage-tracker.d.ts

@@ -0,0 +1,91 @@
+import { type Static, Type } from "typebox";
+/**
+ * One skill that was previously retrieved (T08) and is now being evaluated
+ * for actual usage. `workflowSteps` is the list of declared step / tool /
+ * action names the skill's SKILL.md (or workflow doc) advertises — these
+ * are what we diff the trajectory against.
+ *
+ * Step matching is case-insensitive substring: a tool call's `name` matches
+ * a workflow step if the step (after lowercasing + whitespace collapse)
+ * appears anywhere in the tool call's name. This is intentionally permissive
+ * — declared steps are human-authored phrases ("store-cli query"), and tool
+ * call names may be qualified (`mcp__store__store-cli-query`). Misses bias
+ * toward `used: false`, which is the safer of the two error modes for a
+ * curation signal.
+ */
+export declare const RetrievedSkillForTrackingSchema: Type.TObject<{
+    skillId: Type.TString;
+    name: Type.TString;
+    workflowSteps: Type.TArray<Type.TString>;
+}>;
+export type RetrievedSkillForTracking = Static<typeof RetrievedSkillForTrackingSchema>;
+/** One observed tool invocation in the task's trajectory. */
+export declare const ToolCallObservationSchema: Type.TObject<{
+    name: Type.TString;
+}>;
+export type ToolCallObservation = Static<typeof ToolCallObservationSchema>;
+/**
+ * The observable trajectory of a closed task: the sequence of tool calls
+ * the agent made, plus the concatenated reasoning / assistant text the
+ * orchestrator captured. Both inputs are supplied by the caller — this
+ * module does not read transcripts itself.
+ */
+export declare const TaskTrajectorySchema: Type.TObject<{
+    toolCalls: Type.TArray<Type.TObject<{
+        name: Type.TString;
+    }>>;
+    reasoningText: Type.TString;
+}>;
+export type TaskTrajectory = Static<typeof TaskTrajectorySchema>;
+/**
+ * Runtime attribution supplied by the caller (orchestrator).
+ * These are NEVER fabricated inside the tracker (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[];
+}
+/** Why the classifier ruled `used: true`, or `"none"` when it ruled false. */
+export type UsageSignal = "overlap" | "reasoning" | "none";
+export interface UsageVerdict {
+    used: boolean;
+    signal: UsageSignal;
+    tool_call_success_rate: number;
+}
+/**
+ * Apply the FORGE-S24-T09 heuristic to a single retrieved skill against
+ * the observed task trajectory. Pure function — no IO, no allocation
+ * beyond return value.
+ */
+export declare function classifySkillUsage(skill: RetrievedSkillForTracking, trajectory: TaskTrajectory): UsageVerdict;
+/**
+ * Emit one `skill_usage` tracking event per retrieved skill via
+ * `node <storeCli> emit <sprintId> <json>`. Each event carries the
+ * classifier's `used` verdict and the observed `tool_call_success_rate`.
+ *
+ * `retrieval_score` is set to 0 — at tracking time, the score has already
+ * been emitted in the T08 retrieval event; this follow-up captures the
+ * usage signal only. (The schema requires the field to be present; it does
+ * not require it to be re-derived per emission.)
+ *
+ * Never throws on subprocess failure — the failure is surfaced via the
+ * returned counter and stderr text (IL7, explicit not silent).
+ */
+export declare function emitSkillUsageTrackingEvents(retrieved: readonly RetrievedSkillForTracking[], trajectory: TaskTrajectory, runtime: EmitRuntime): EmitResult;

package/dist/extensions/forgecli/skill-usage-tracker.js

@@ -0,0 +1,224 @@
+// Skill usage tracker — FORGE-S24-T09.
+//
+// After a task completes, diff the actual tool-call sequence against each
+// retrieved skill's declared workflow steps and emit a follow-up `skill_usage`
+// event per retrieved skill with `used: true | false` and a populated
+// `tool_call_success_rate`. Conforms to the canonical `skill_usage` event
+// schema variant landed in FORGE-S24-T01 (plugin v0.45.0).
+//
+// Heuristic (per FORGE-S24-T09 acceptance criteria):
+//   - Skill name appears in agent reasoning text                  → used: true
+//   - ≥2 distinct workflow steps overlap with executed tool calls → used: true
+//   - Otherwise                                                    → used: false
+//
+// `tool_call_success_rate` is the fraction of the skill's declared workflow
+// steps that were observed in the trajectory (distinct overlaps / total
+// steps), clamped to [0,1]. For skills with no declared steps, the rate is 0.
+//
+// Iron Laws (forge-cli-engineer):
+//   IL2  — TypeScript + TypeBox. Runtime input is validated by `Value.Parse`
+//          at the public emission entry point.
+//   IL6  — No raw shell-string interpolation. `emitSkillUsageTrackingEvents`
+//          calls `spawnSync("node", [storeCli, "emit", sprintId, JSON.stringify(event)])`
+//          — argv array, no shell.
+//   IL7  — No silent continuation past failures. A non-zero `store-cli emit`
+//          exit increments the `failed` counter and the stderr text is
+//          forwarded to the caller in the returned result; nothing is
+//          swallowed.
+//   IL10 — This module runs in **orchestrator context** (telemetry-actor
+//          split — see `engineering/architecture/telemetry-actor-split.md`).
+//          The orchestrator/caller supplies the runtime attribution
+//          (model/provider/timestamps/durationMinutes) — never fabricated
+//          here. The subagent NEVER invokes this tracker directly.
+//
+// Scope boundary: this module owns classification + emission. It does NOT
+// crawl the filesystem for skills, parse subagent transcripts, or decide
+// when "task close" is. The caller (Orchestrator handler — `run-task.ts`,
+// `fix-bug.ts`, gated behind FORGE-S24-T12 feature flag) assembles the
+// retrieved-skill list, trajectory, and runtime attribution, then invokes
+// `emitSkillUsageTrackingEvents`.
+import { spawnSync } from "node:child_process";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+import { isSkillCurationEnabled } from "./skill-curation-flag.js";
+// ── Public schemas ───────────────────────────────────────────────────────
+/**
+ * One skill that was previously retrieved (T08) and is now being evaluated
+ * for actual usage. `workflowSteps` is the list of declared step / tool /
+ * action names the skill's SKILL.md (or workflow doc) advertises — these
+ * are what we diff the trajectory against.
+ *
+ * Step matching is case-insensitive substring: a tool call's `name` matches
+ * a workflow step if the step (after lowercasing + whitespace collapse)
+ * appears anywhere in the tool call's name. This is intentionally permissive
+ * — declared steps are human-authored phrases ("store-cli query"), and tool
+ * call names may be qualified (`mcp__store__store-cli-query`). Misses bias
+ * toward `used: false`, which is the safer of the two error modes for a
+ * curation signal.
+ */
+export const RetrievedSkillForTrackingSchema = Type.Object({
+    skillId: Type.String({ minLength: 1 }),
+    name: Type.String({ minLength: 1 }),
+    workflowSteps: Type.Array(Type.String()),
+});
+/** One observed tool invocation in the task's trajectory. */
+export const ToolCallObservationSchema = Type.Object({
+    name: Type.String({ minLength: 1 }),
+});
+/**
+ * The observable trajectory of a closed task: the sequence of tool calls
+ * the agent made, plus the concatenated reasoning / assistant text the
+ * orchestrator captured. Both inputs are supplied by the caller — this
+ * module does not read transcripts itself.
+ */
+export const TaskTrajectorySchema = Type.Object({
+    toolCalls: Type.Array(ToolCallObservationSchema),
+    reasoningText: Type.String(),
+});
+/**
+ * Runtime attribution supplied by the caller (orchestrator).
+ * These are NEVER fabricated inside the tracker (IL10).
+ */
+export const EmitRuntimeSchema = Type.Object({
+    storeCli: Type.String({ minLength: 1 }),
+    cwd: Type.String({ minLength: 1 }),
+    sprintId: Type.String({ minLength: 1 }),
+    taskId: Type.String({ minLength: 1 }),
+    role: Type.String({ minLength: 1 }),
+    action: Type.String({ minLength: 1 }),
+    phase: Type.Optional(Type.String()),
+    iteration: Type.Optional(Type.Integer({ minimum: 1 })),
+    startTimestamp: Type.String({ format: "date-time" }),
+    endTimestamp: Type.String({ format: "date-time" }),
+    durationMinutes: Type.Number({ minimum: 0 }),
+    model: Type.String({ minLength: 1 }),
+    provider: Type.String({ minLength: 1 }),
+});
+// ── Classification ───────────────────────────────────────────────────────
+/** Lowercase + collapse whitespace; safe for substring comparison. */
+function normalize(s) {
+    return s.toLowerCase().replace(/\s+/g, " ").trim();
+}
+/**
+ * Count the number of distinct declared workflow steps that appear in the
+ * observed tool-call sequence (case-insensitive substring). A step that
+ * matches multiple tool calls is counted once.
+ */
+function countStepOverlap(steps, toolCalls) {
+    if (steps.length === 0 || toolCalls.length === 0)
+        return 0;
+    const observed = toolCalls.map((c) => normalize(c.name));
+    let hits = 0;
+    for (const step of steps) {
+        const needle = normalize(step);
+        if (needle.length === 0)
+            continue;
+        if (observed.some((o) => o.includes(needle)))
+            hits++;
+    }
+    return hits;
+}
+/**
+ * Apply the FORGE-S24-T09 heuristic to a single retrieved skill against
+ * the observed task trajectory. Pure function — no IO, no allocation
+ * beyond return value.
+ */
+export function classifySkillUsage(skill, trajectory) {
+    const overlap = countStepOverlap(skill.workflowSteps, trajectory.toolCalls);
+    const totalSteps = skill.workflowSteps.length;
+    let rate = 0;
+    if (totalSteps > 0) {
+        const raw = overlap / totalSteps;
+        if (!Number.isFinite(raw) || raw < 0)
+            rate = 0;
+        else if (raw > 1)
+            rate = 1;
+        else
+            rate = raw;
+    }
+    // Signal 1: skill name appears in agent reasoning. The reasoning text is
+    // normalised the same way as steps so casing/whitespace doesn't cause
+    // false negatives.
+    const reasoning = normalize(trajectory.reasoningText);
+    const skillNeedle = normalize(skill.name);
+    const mentionedInReasoning = skillNeedle.length > 0 && reasoning.includes(skillNeedle);
+    // Signal 2: ≥2 distinct workflow steps overlapped with executed tool calls.
+    const overlapStrong = overlap >= 2;
+    if (overlapStrong) {
+        return { used: true, signal: "overlap", tool_call_success_rate: rate };
+    }
+    if (mentionedInReasoning) {
+        return { used: true, signal: "reasoning", tool_call_success_rate: rate };
+    }
+    return { used: false, signal: "none", tool_call_success_rate: rate };
+}
+// ── Emission ─────────────────────────────────────────────────────────────
+/** Compose an ISO-compact timestamp segment for the eventId. */
+function isoCompact(iso) {
+    return iso.replace(/[-:.]/g, "").replace(/Z$/, "Z");
+}
+/**
+ * Emit one `skill_usage` tracking event per retrieved skill via
+ * `node <storeCli> emit <sprintId> <json>`. Each event carries the
+ * classifier's `used` verdict and the observed `tool_call_success_rate`.
+ *
+ * `retrieval_score` is set to 0 — at tracking time, the score has already
+ * been emitted in the T08 retrieval event; this follow-up captures the
+ * usage signal only. (The schema requires the field to be present; it does
+ * not require it to be re-derived per emission.)
+ *
+ * Never throws on subprocess failure — the failure is surfaced via the
+ * returned counter and stderr text (IL7, explicit not silent).
+ */
+export function emitSkillUsageTrackingEvents(retrieved, trajectory, runtime) {
+    // FORGE-S24-T12 — gated rollout. Default off ⇒ no classification, no
+    // events, no subprocess.
+    if (!isSkillCurationEnabled(runtime.cwd)) {
+        return { emitted: 0, failed: 0, stderrs: [] };
+    }
+    Value.Parse(EmitRuntimeSchema, runtime);
+    Value.Parse(TaskTrajectorySchema, trajectory);
+    for (const s of retrieved)
+        Value.Parse(RetrievedSkillForTrackingSchema, s);
+    let emitted = 0;
+    let failed = 0;
+    const stderrs = [];
+    for (let i = 0; i < retrieved.length; i++) {
+        const skill = retrieved[i];
+        const verdict = classifySkillUsage(skill, trajectory);
+        const eventId = `${isoCompact(runtime.startTimestamp)}_${runtime.taskId}_skill-usage-tracker_skill_usage_${i}_${skill.skillId}`;
+        const event = {
+            eventId,
+            sprintId: runtime.sprintId,
+            taskId: runtime.taskId,
+            role: runtime.role,
+            action: runtime.action,
+            startTimestamp: runtime.startTimestamp,
+            endTimestamp: runtime.endTimestamp,
+            durationMinutes: runtime.durationMinutes,
+            model: runtime.model,
+            provider: runtime.provider,
+            type: "skill_usage",
+            skillId: skill.skillId,
+            retrieved: true,
+            used: verdict.used,
+            tool_call_success_rate: verdict.tool_call_success_rate,
+            retrieval_score: 0,
+        };
+        if (runtime.phase !== undefined)
+            event.phase = runtime.phase;
+        if (runtime.iteration !== undefined)
+            event.iteration = runtime.iteration;
+        const result = spawnSync("node", [runtime.storeCli, "emit", runtime.sprintId, JSON.stringify(event)], { cwd: runtime.cwd, encoding: "utf8" });
+        if (result.status === 0) {
+            emitted++;
+        }
+        else {
+            failed++;
+            const stderr = typeof result.stderr === "string" ? result.stderr : "";
+            stderrs.push(stderr);
+        }
+    }
+    return { emitted, failed, stderrs };
+}
+//# sourceMappingURL=skill-usage-tracker.js.map

package/dist/extensions/forgecli/skill-usage-tracker.js.map

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

package/dist/extensions/forgecli/store-resolver.d.ts

@@ -36,3 +36,21 @@ export declare function suffixMatch(toolDir: string, cwd: string, kind: "task" |
  *   5. NLP fallback → store-cli nlp "<query>"
  */
 export declare function resolveEntityRef(arg: string, toolDir: string, cwd: string, opts?: ResolveOptions): Promise<ResolverHit | null>;
+export interface ResolveToCanonicalIdOptions {
+    /** Which entity types to search. Defaults to a single-element set matching `kind`. */
+    entityTypes?: Set<string>;
+    /** Command label used in error messages (e.g. "forge:run-task"). */
+    commandLabel?: string;
+}
+/**
+ * Resolve a raw user arg to a canonical entity ID string.
+ *
+ * 1. If the arg is already a canonical ID that resolves directly → return it.
+ * 2. If the arg is an unprefixed ID (e.g. "S22-T03") → suffix-match or
+ *    prefix-normalize to the canonical form → return it.
+ * 3. If the arg is ambiguous → prompt the user (or hard-fail in non-interactive).
+ * 4. If the arg cannot be resolved → emit an actionable error and return null.
+ */
+export declare function resolveToCanonicalId(arg: string, toolDir: string, cwd: string, kind: "task" | "sprint" | "bug" | "feature", opts: ResolveToCanonicalIdOptions & {
+    ctx?: ExtensionCommandContext;
+}): Promise<string | null>;