@skillit/core 1.5.0 → 2.0.0

package/dist/refine/config-source.js.map

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

package/dist/refine/index.d.ts

@@ -3,5 +3,9 @@ export * from './select-targets.js';
 export { refineSkill } from './loop.js';
 export type { ScoreSkill } from './loop.js';
 export { insertJsDocTag } from './jsdoc-edit.js';
-export { upsertJsDocTag, readJsDocTags } from './ast-edit.js';
+export { upsertJsDocTag, upsertPropertyJsDocTag, readJsDocTags } from './ast-edit.js';
+export { ConfigRefineSource } from './config-source.js';
+export type { ConfigRefineSourceOptions } from './config-source.js';
+export { stripScope, findNearestPackageDir, readPackageMetadata } from './package-metadata.js';
+export type { PackageMetadata } from './package-metadata.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/refine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/refine/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/refine/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,YAAY,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAC/F,YAAY,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/refine/index.js

@@ -2,5 +2,7 @@ export * from './types.js';
 export * from './select-targets.js';
 export { refineSkill } from './loop.js';
 export { insertJsDocTag } from './jsdoc-edit.js';
-export { upsertJsDocTag, readJsDocTags } from './ast-edit.js';
+export { upsertJsDocTag, upsertPropertyJsDocTag, readJsDocTags } from './ast-edit.js';
+export { ConfigRefineSource } from './config-source.js';
+export { stripScope, findNearestPackageDir, readPackageMetadata } from './package-metadata.js';
 //# sourceMappingURL=index.js.map

package/dist/refine/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/refine/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/refine/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAExC,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAExD,OAAO,EAAE,UAAU,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/refine/jsdoc-edit.d.ts

@@ -1,4 +1,11 @@
 import type { RefineTag } from './types.js';
-/** @deprecated internal alias — use upsertJsDocTag. Kept for callers/tests. */
+/**
+ * @deprecated internal alias — use {@link upsertJsDocTag}. Kept for callers/tests.
+ *
+ * @remarks
+ * A thin pass-through to {@link upsertJsDocTag} with identical parameters and
+ * behaviour; retained only so existing callers and tests that import the old
+ * name keep compiling. New code should call {@link upsertJsDocTag} directly.
+ */
 export declare function insertJsDocTag(source: string, exportName: string, tag: RefineTag, content: string): string;
 //# sourceMappingURL=jsdoc-edit.d.ts.map

package/dist/refine/jsdoc-edit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-edit.d.ts","sourceRoot":"","sources":["../../src/refine/jsdoc-edit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAER"}
+{"version":3,"file":"jsdoc-edit.d.ts","sourceRoot":"","sources":["../../src/refine/jsdoc-edit.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,SAAS,EACd,OAAO,EAAE,MAAM,GACd,MAAM,CAER"}

package/dist/refine/jsdoc-edit.js

@@ -1,5 +1,12 @@
 import { upsertJsDocTag } from './ast-edit.js';
-/** @deprecated internal alias — use upsertJsDocTag. Kept for callers/tests. */
+/**
+ * @deprecated internal alias — use {@link upsertJsDocTag}. Kept for callers/tests.
+ *
+ * @remarks
+ * A thin pass-through to {@link upsertJsDocTag} with identical parameters and
+ * behaviour; retained only so existing callers and tests that import the old
+ * name keep compiling. New code should call {@link upsertJsDocTag} directly.
+ */
 export function insertJsDocTag(source, exportName, tag, content) {
     return upsertJsDocTag(source, exportName, tag, content);
 }

package/dist/refine/jsdoc-edit.js.map

@@ -1 +1 @@
-{"version":3,"file":"jsdoc-edit.js","sourceRoot":"","sources":["../../src/refine/jsdoc-edit.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,+EAA+E;AAC/E,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,UAAkB,EAClB,GAAc,EACd,OAAe;IAEf,OAAO,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC"}
+{"version":3,"file":"jsdoc-edit.js","sourceRoot":"","sources":["../../src/refine/jsdoc-edit.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,MAAc,EACd,UAAkB,EAClB,GAAc,EACd,OAAe;IAEf,OAAO,cAAc,CAAC,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,OAAO,CAAC,CAAC;AAC1D,CAAC"}

package/dist/refine/loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/refine/loop.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAGV,aAAa,EACb,YAAY,EAEb,MAAM,YAAY,CAAC;AAEpB,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,kBAAkB,CAAC;AAavE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,aAAa,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAE,GAChD,OAAO,CAAC,YAAY,CAAC,CA0FvB"}
+{"version":3,"file":"loop.d.ts","sourceRoot":"","sources":["../../src/refine/loop.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtE,OAAO,KAAK,EAGV,aAAa,EACb,YAAY,EAEb,MAAM,YAAY,CAAC;AAEpB,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,kBAAkB,CAAC;AAwBvE,wBAAsB,WAAW,CAC/B,IAAI,EAAE,aAAa,GAAG;IAAE,UAAU,CAAC,EAAE,UAAU,CAAA;CAAE,GAChD,OAAO,CAAC,YAAY,CAAC,CAuGvB"}

package/dist/refine/loop.js

@@ -5,14 +5,24 @@ import { selectWorkItems } from './select-targets.js';
 const DEFAULT_PASSING_GRADES = ['A'];
 const DEFAULT_MAX_ITERATIONS = 5;
 const DEFAULT_ITEMS_PER_ITERATION = 5;
-function defaultScore(source) {
+function defaultScore() {
     return (skill) => {
-        const audit = auditSkill(skill, source.auditContext(skill));
+        const audit = auditSkill(skill);
         return estimateSkillJudgeScore(audit, skill);
     };
 }
+/**
+ * Total work items currently available across all improvements (uncapped), used
+ * as the loop's "backlog" signal. Reuses {@link selectWorkItems} so it counts
+ * exactly what would become work — i.e. improvements with a parseable tag and
+ * targets. Shrinks as config options get tagged; stays flat when the model is
+ * stuck re-drafting the same still-failing targets.
+ */
+function countAvailableWork(improvements) {
+    return selectWorkItems(improvements, Number.POSITIVE_INFINITY).length;
+}
 export async function refineSkill(opts) {
-    const { source, model, passingGrades = DEFAULT_PASSING_GRADES, maxIterations = DEFAULT_MAX_ITERATIONS, itemsPerIteration = DEFAULT_ITEMS_PER_ITERATION, onIteration, scoreSkill = defaultScore(source) } = opts;
+    const { source, model, passingGrades = DEFAULT_PASSING_GRADES, maxIterations = DEFAULT_MAX_ITERATIONS, itemsPerIteration = DEFAULT_ITEMS_PER_ITERATION, onIteration, scoreSkill = defaultScore() } = opts;
     const passingSet = new Set(passingGrades);
     const iterations = [];
     let skill = await source.extract();
@@ -22,9 +32,19 @@ export async function refineSkill(opts) {
         return finished('passed', skill, estimate, iterations, guidance);
     }
     let prevTotal = estimate.total;
+    let prevAvailable = countAvailableWork(estimate.improvements);
     for (let i = 0; i < maxIterations; i++) {
-        // Plateau: if this isn't the last allowed iteration and score hasn't improved, stop early.
-        if (i > 0 && i < maxIterations - 1 && estimate.total <= prevTotal) {
+        const available = countAvailableWork(estimate.improvements);
+        // Plateau: stop early when the score has stalled — but NOT while we're still
+        // burning down a backlog of work. Per-option config coverage targets become
+        // score-neutral once the routing thresholds (W7/W8/W9) pass, yet each
+        // iteration still documents more options; a pure score check would halt that
+        // mid-surface. Only plateau when the score is flat AND the available-work
+        // pool is not shrinking (the genuinely-stuck case the check exists to catch).
+        if (i > 0 &&
+            i < maxIterations - 1 &&
+            estimate.total <= prevTotal &&
+            available >= prevAvailable) {
             return finished('plateau', skill, estimate, iterations, guidance);
         }
         const workItems = selectWorkItems(estimate.improvements, itemsPerIteration);
@@ -74,6 +94,7 @@ export async function refineSkill(opts) {
         }
         await source.applyFixes(fixes);
         prevTotal = estimate.total;
+        prevAvailable = available;
         skill = await source.extract();
         estimate = scoreSkill(skill);
         const iteration = { iteration: i + 1, estimate, workItems, fixes };

package/dist/refine/loop.js.map

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

package/dist/refine/package-metadata.d.ts

@@ -0,0 +1,28 @@
+import type { ParsedReadme } from '../audit-types.js';
+/** Package metadata read from a package dir (package.json fields + parsed README). */
+export interface PackageMetadata {
+    /** Scope-stripped package name. */
+    packageName?: string;
+    packageDescription?: string;
+    keywords?: string[];
+    repository?: string;
+    readme?: ParsedReadme;
+}
+/** Strip a leading `@scope/` from a package name. */
+export declare function stripScope(name: string): string;
+/**
+ * Walk up from `startDir` (inclusive) up to `maxDepth` parents looking for a
+ * directory containing a `package.json`. Returns the dir, or undefined.
+ *
+ * @param startDir - Directory to start the upward search from (searched first).
+ * @param maxDepth - Maximum number of parent directories to ascend (default 5).
+ * @returns The nearest directory containing a `package.json`, or `undefined`
+ *   when none is found within `maxDepth` levels (or the filesystem root is hit).
+ */
+export declare function findNearestPackageDir(startDir: string, maxDepth?: number): Promise<string | undefined>;
+/**
+ * Read package.json fields + `parseReadme(README.md)` from `pkgDir`. Never
+ * throws — unreadable/absent files yield unset fields.
+ */
+export declare function readPackageMetadata(pkgDir: string): Promise<PackageMetadata>;
+//# sourceMappingURL=package-metadata.d.ts.map

package/dist/refine/package-metadata.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-metadata.d.ts","sourceRoot":"","sources":["../../src/refine/package-metadata.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,sFAAsF;AACtF,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAID,qDAAqD;AACrD,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAG/C;AAED;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,QAAQ,SAAoB,GAC3B,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAa7B;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAuBlF"}

package/dist/refine/package-metadata.js

@@ -0,0 +1,64 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { parseReadme } from '../readme-parser.js';
+const DEFAULT_MAX_DEPTH = 5;
+/** Strip a leading `@scope/` from a package name. */
+export function stripScope(name) {
+    const slash = name.indexOf('/');
+    return name.startsWith('@') && slash !== -1 ? name.slice(slash + 1) : name;
+}
+/**
+ * Walk up from `startDir` (inclusive) up to `maxDepth` parents looking for a
+ * directory containing a `package.json`. Returns the dir, or undefined.
+ *
+ * @param startDir - Directory to start the upward search from (searched first).
+ * @param maxDepth - Maximum number of parent directories to ascend (default 5).
+ * @returns The nearest directory containing a `package.json`, or `undefined`
+ *   when none is found within `maxDepth` levels (or the filesystem root is hit).
+ */
+export async function findNearestPackageDir(startDir, maxDepth = DEFAULT_MAX_DEPTH) {
+    let dir = startDir;
+    for (let i = 0; i <= maxDepth; i++) {
+        try {
+            await readFile(join(dir, 'package.json'), 'utf8');
+            return dir;
+        }
+        catch {
+            const parent = dirname(dir);
+            if (parent === dir)
+                break;
+            dir = parent;
+        }
+    }
+    return undefined;
+}
+/**
+ * Read package.json fields + `parseReadme(README.md)` from `pkgDir`. Never
+ * throws — unreadable/absent files yield unset fields.
+ */
+export async function readPackageMetadata(pkgDir) {
+    const meta = {};
+    try {
+        const pkg = JSON.parse(await readFile(join(pkgDir, 'package.json'), 'utf8'));
+        if (pkg.name)
+            meta.packageName = stripScope(pkg.name);
+        if (pkg.description)
+            meta.packageDescription = pkg.description;
+        if (Array.isArray(pkg.keywords))
+            meta.keywords = pkg.keywords;
+        const repo = typeof pkg.repository === 'string' ? pkg.repository : pkg.repository?.url;
+        if (repo)
+            meta.repository = repo;
+    }
+    catch {
+        /* no/invalid package.json */
+    }
+    try {
+        meta.readme = parseReadme(await readFile(join(pkgDir, 'README.md'), 'utf8'));
+    }
+    catch {
+        /* no README */
+    }
+    return meta;
+}
+//# sourceMappingURL=package-metadata.js.map

package/dist/refine/package-metadata.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-metadata.js","sourceRoot":"","sources":["../../src/refine/package-metadata.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAC5C,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAalD,MAAM,iBAAiB,GAAG,CAAC,CAAC;AAE5B,qDAAqD;AACrD,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAgB,EAChB,QAAQ,GAAG,iBAAiB;IAE5B,IAAI,GAAG,GAAG,QAAQ,CAAC;IACnB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAC;YAClD,OAAO,GAAG,CAAC;QACb,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,MAAM,KAAK,GAAG;gBAAE,MAAM;YAC1B,GAAG,GAAG,MAAM,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,MAAc;IACtD,MAAM,IAAI,GAAoB,EAAE,CAAC;IACjC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAK1E,CAAC;QACF,IAAI,GAAG,CAAC,IAAI;YAAE,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACtD,IAAI,GAAG,CAAC,WAAW;YAAE,IAAI,CAAC,kBAAkB,GAAG,GAAG,CAAC,WAAW,CAAC;QAC/D,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC;YAAE,IAAI,CAAC,QAAQ,GAAG,GAAG,CAAC,QAAQ,CAAC;QAC9D,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC;QACvF,IAAI,IAAI;YAAE,IAAI,CAAC,UAAU,GAAG,IAAI,CAAC;IACnC,CAAC;IAAC,MAAM,CAAC;QACP,6BAA6B;IAC/B,CAAC;IACD,IAAI,CAAC;QACH,IAAI,CAAC,MAAM,GAAG,WAAW,CAAC,MAAM,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/E,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/refine/select-targets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"select-targets.d.ts","sourceRoot":"","sources":["../../src/refine/select-targets.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI5D,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAYlE;AAED,wBAAgB,eAAe,CAC7B,YAAY,EAAE,SAAS,qBAAqB,EAAE,EAC9C,KAAK,EAAE,MAAM,GACZ,cAAc,EAAE,CAYlB"}
+{"version":3,"file":"select-targets.d.ts","sourceRoot":"","sources":["../../src/refine/select-targets.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AACzD,OAAO,KAAK,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAI5D,wBAAgB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAYlE;AAED,wBAAgB,eAAe,CAC7B,YAAY,EAAE,SAAS,qBAAqB,EAAE,EAC9C,KAAK,EAAE,MAAM,GACZ,cAAc,EAAE,CAoClB"}

package/dist/refine/select-targets.js

@@ -14,17 +14,42 @@ export function parseTag(suggestion) {
     return valid.has(tag) ? tag : undefined;
 }
 export function selectWorkItems(improvements, limit) {
-    const items = [];
+    // Group an improvement's targets together, preserving target order, then rank
+    // the groups by points descending.
+    const groups = [];
     for (const imp of improvements) {
         const tag = parseTag(imp.suggestion);
         if (!tag)
             continue;
-        const targets = imp.targets ?? [];
-        for (const target of targets) {
-            items.push({ toolName: target.name, tag, improvement: imp });
+        const group = (imp.targets ?? []).map((target) => ({
+            toolName: target.name,
+            tag,
+            improvement: imp
+        }));
+        if (group.length > 0)
+            groups.push(group);
+    }
+    groups.sort((a, b) => b[0].improvement.points - a[0].improvement.points);
+    // Round-robin across groups rather than draining the highest-points group
+    // first: take the Nth target of every group before any (N+1)th. A bounded
+    // iteration then spreads across ALL still-failing tags, so a tag with many
+    // completeness targets (e.g. `@pitfalls` on a wide config surface) can't
+    // monopolize the slice and starve `@useWhen`/`@avoidWhen` — which, before the
+    // first of those is ever drafted, let the loop's score plateau stop early with
+    // those dimensions still failing. With one target per group this is identical
+    // to the old points-descending order.
+    const items = [];
+    const maxLen = groups.reduce((m, g) => Math.max(m, g.length), 0);
+    for (let round = 0; round < maxLen && items.length < limit; round++) {
+        for (const group of groups) {
+            const item = group[round];
+            if (item) {
+                items.push(item);
+                if (items.length >= limit)
+                    break;
+            }
         }
     }
-    items.sort((a, b) => b.improvement.points - a.improvement.points);
-    return items.slice(0, limit);
+    return items;
 }
 //# sourceMappingURL=select-targets.js.map

package/dist/refine/select-targets.js.map

@@ -1 +1 @@
-{"version":3,"file":"select-targets.js","sourceRoot":"","sources":["../../src/refine/select-targets.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB,MAAM,UAAU,QAAQ,CAAC,UAAkB;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAc,CAAC;IAClC,MAAM,KAAK,GAA2B,IAAI,GAAG,CAAC;QAC5C,SAAS;QACT,WAAW;QACX,UAAU;QACV,SAAS;QACT,SAAS;KACV,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,YAA8C,EAC9C,KAAa;IAEb,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC;QAClC,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,CAAC;QAC/D,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAClE,OAAO,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AAC/B,CAAC"}
+{"version":3,"file":"select-targets.js","sourceRoot":"","sources":["../../src/refine/select-targets.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,GAAG,QAAQ,CAAC;AAExB,MAAM,UAAU,QAAQ,CAAC,UAAkB;IACzC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK;QAAE,OAAO,SAAS,CAAC;IAC7B,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAc,CAAC;IAClC,MAAM,KAAK,GAA2B,IAAI,GAAG,CAAC;QAC5C,SAAS;QACT,WAAW;QACX,UAAU;QACV,SAAS;QACT,SAAS;KACV,CAAC,CAAC;IACH,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,SAAS,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,YAA8C,EAC9C,KAAa;IAEb,8EAA8E;IAC9E,mCAAmC;IACnC,MAAM,MAAM,GAAuB,EAAE,CAAC;IACtC,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QACrC,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,OAAO,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YACjD,QAAQ,EAAE,MAAM,CAAC,IAAI;YACrB,GAAG;YACH,WAAW,EAAE,GAAG;SACjB,CAAC,CAAC,CAAC;QACJ,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAE,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAE3E,0EAA0E;IAC1E,0EAA0E;IAC1E,2EAA2E;IAC3E,yEAAyE;IACzE,8EAA8E;IAC9E,+EAA+E;IAC/E,8EAA8E;IAC9E,sCAAsC;IACtC,MAAM,KAAK,GAAqB,EAAE,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACjE,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,MAAM,IAAI,KAAK,CAAC,MAAM,GAAG,KAAK,EAAE,KAAK,EAAE,EAAE,CAAC;QACpE,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,IAAI,EAAE,CAAC;gBACT,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACjB,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK;oBAAE,MAAM;YACnC,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/refine/types.d.ts

@@ -1,4 +1,4 @@
-import type { ExtractedSkill, SkillJudgeEstimate, ActionableImprovement, AuditContext } from '../index.js';
+import type { ExtractedSkill, SkillJudgeEstimate, ActionableImprovement } from '../index.js';
 export type RefineTag = 'useWhen' | 'avoidWhen' | 'pitfalls' | 'remarks' | 'example';
 export interface DraftRequest {
     toolName: string;
@@ -30,11 +30,38 @@ export interface ModelClient {
     draft(req: DraftRequest): Promise<string>;
     review(req: ReviewRequest): Promise<ReviewResult>;
 }
+/**
+ * Where an audit/judge target's enrichment surface lives on disk, so a caller
+ * (e.g. the agent-bootstrap slash command) can jump straight to the declaration
+ * instead of re-deriving the file from `sourceModule`.
+ */
+export interface TargetLocation {
+    /** Absolute or repo-relative path to the file holding the declaration. */
+    file: string;
+    /** The declaration name to anchor the edit on (export name, interface, or option key). */
+    declName: string;
+    /** Dot-path into a config type when the target is a single option (e.g. `components.prefix`). */
+    propertyPath?: string;
+}
 export interface RefineSource {
     extract(): Promise<ExtractedSkill>;
-    auditContext(skill: ExtractedSkill): AuditContext;
     applyFixes(fixes: readonly DraftedFix[]): Promise<void>;
     guidance?(): string | Promise<string>;
+    /**
+     * Resolve an improvement target (`{file, name, kind}` from `ActionableImprovement.targets`)
+     * to a concrete on-disk location. Optional — a source that cannot resolve a
+     * given target returns `undefined`. Used by `skillit audit --json` and the
+     * agent-bootstrap loop.
+     *
+     * The return is a union of sync and async: config/typedoc resolve synchronously,
+     * but cli and mcp(build) must read source files, so they return a `Promise`.
+     * Callers `await` the result (awaiting a non-Promise is a no-op).
+     */
+    resolveTargetLocation?(target: {
+        name: string;
+        kind: string;
+        file?: string;
+    }): TargetLocation | undefined | Promise<TargetLocation | undefined>;
 }
 export interface RefineWorkItem {
     toolName: string;

package/dist/refine/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/refine/types.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EACd,kBAAkB,EAClB,qBAAqB,EACrB,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,MAAM,MAAM,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;AAErF,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,SAAS,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,cAAc,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,aAAa,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,SAAS,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC1C,MAAM,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,IAAI,OAAO,CAAC,cAAc,CAAC,CAAC;IACnC,YAAY,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,CAAC;IAClD,UAAU,CAAC,KAAK,EAAE,SAAS,UAAU,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,QAAQ,CAAC,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,SAAS,CAAC;IACf,WAAW,EAAE,qBAAqB,CAAC;CACpC;AAED,MAAM,MAAM,gBAAgB,GAAG,QAAQ,GAAG,gBAAgB,GAAG,iBAAiB,GAAG,SAAS,CAAC;AAE3F,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,SAAS,EAAE,SAAS,cAAc,EAAE,CAAC;IACrC,KAAK,EAAE,SAAS,UAAU,EAAE,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,WAAW,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC,kBAAkB,CAAC,OAAO,CAAC,CAAC,CAAC;IAC3D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,IAAI,CAAC;CACpD;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,SAAS,eAAe,EAAE,CAAC;IACvC,UAAU,EAAE,cAAc,CAAC;IAC3B,aAAa,EAAE,kBAAkB,CAAC;IAClC,MAAM,EAAE,OAAO,CAAC;IAChB,aAAa,EAAE,gBAAgB,CAAC;IAChC,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/refine/types.ts"],"names":[],"mappings":"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"}

package/dist/renderer.js

@@ -259,7 +259,7 @@ function renderRouterSkill(skills, opts) {
         return {
             short: s.name.replace(/^@[^/]+\//, ''),
             peerName: toSkillName(s.name),
-            desc: s.packageDescription || s.description || '',
+            desc: s.description || s.packageDescription || '',
             remarks: s.remarks || '',
             useWhens: s.useWhen ?? [],
             avoidWhens: s.avoidWhen ?? [],
@@ -384,13 +384,16 @@ function renderSkillMd(skill, skillName, opts, refManifest) {
         sections.push(opts.bodyPrefix);
     }
     sections.push(`# ${skill.name}`);
-    // Package description as body intro
-    if (skill.packageDescription) {
-        sections.push(skill.packageDescription);
-    }
-    else if (skill.description) {
+    // Surface description as body intro. `description` is the skill's render
+    // headline (a config source puts its config-specific blurb here); the literal
+    // package.json `packageDescription` is audit-only metadata, used here only as
+    // a last-resort fallback.
+    if (skill.description) {
         sections.push(skill.description);
     }
+    else if (skill.packageDescription) {
+        sections.push(skill.packageDescription);
+    }
     // @remarks from @packageDocumentation — architectural context, trade-offs, mental models
     if (skill.remarks) {
         sections.push(skill.remarks);
@@ -842,8 +845,10 @@ function buildRefManifest(basePath, references) {
     return manifest;
 }
 function buildDescription(skill) {
-    // Description = package.json tagline + short WHEN clause + domain keywords.
-    const desc = skill.packageDescription || skill.description || `API reference for ${skill.name}`;
+    // Description = surface tagline + short WHEN clause + domain keywords. Prefer
+    // the render headline (`description`); `packageDescription` is audit-only and
+    // serves only as a fallback.
+    const desc = skill.description || skill.packageDescription || `API reference for ${skill.name}`;
     const parts = [desc];
     // Add a short scenario-based WHEN from @useWhen (first item only, truncated to 80 chars)
     if (skill.useWhen && skill.useWhen.length > 0) {