@skillsmith/mcp-server 0.4.13 → 0.5.0

package/dist/src/audit/collision-detector.semantic.helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-detector.semantic.helpers.js","sourceRoot":"","sources":["../../../src/audit/collision-detector.semantic.helpers.ts"],"names":[],"mappings":"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"}

package/dist/src/audit/collision-detector.types.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @fileoverview Type vocabulary for the collision detector (SMI-4587 Wave 1 Step 1).
+ * @module @skillsmith/mcp-server/audit/collision-detector.types
+ *
+ * Re-exports the collision flag shapes from local-inventory.types and adds
+ * the InventoryAuditResult container. Public surface for Wave 2/3/4.
+ */
+import type { AuditId, CollisionId, ExactCollisionFlag, InventoryEntry } from '../utils/local-inventory.types.js';
+export type { AuditId, CollisionId, ExactCollisionFlag, InventoryEntry };
+/**
+ * Semantic-overlap collision (filled in by Wave 1 PR2 — Step 6 semantic pass).
+ * Type is stable now so the result-writer can reference the field.
+ */
+export interface SemanticCollisionFlag {
+    kind: 'semantic';
+    collisionId: CollisionId;
+    entryA: InventoryEntry;
+    entryB: InventoryEntry;
+    /** From `OverlapDetector.detectOverlap.overlapScore`. */
+    cosineScore: number;
+    overlappingPhrases: Array<{
+        phrase1: string;
+        phrase2: string;
+        similarity: number;
+    }>;
+    severity: 'warning';
+    reason: string;
+}
+/**
+ * Generic-token quality flag — Step 5 in the next PR plumbs this in via the
+ * existing `TriggerQualityEntry` from `skill-pack-audit.types.ts`. Aliased
+ * here to keep imports stable.
+ */
+export interface GenericTokenFlag {
+    kind: 'generic';
+    collisionId: CollisionId;
+    identifier: string;
+    entry: InventoryEntry;
+    matchedTokens: string[];
+    severity: 'warning';
+    reason: string;
+}
+/**
+ * Top-level result of `detectCollisions`. Contains the inventory snapshot
+ * + flags from each pass + summary metrics.
+ *
+ * Wave 1 PR1 (this PR) populates `auditId`, `inventory`, and
+ * `exactCollisions` only. `genericFlags` and `semanticCollisions` are empty
+ * arrays until subsequent PRs land Step 5 + Step 6.
+ */
+export interface InventoryAuditResult {
+    auditId: AuditId;
+    inventory: InventoryEntry[];
+    exactCollisions: ExactCollisionFlag[];
+    genericFlags: GenericTokenFlag[];
+    semanticCollisions: SemanticCollisionFlag[];
+    summary: {
+        totalEntries: number;
+        totalFlags: number;
+        errorCount: number;
+        warningCount: number;
+        durationMs: number;
+        passDurations: {
+            exact: number;
+            generic: number;
+            semantic: number;
+        };
+    };
+}
+//# sourceMappingURL=collision-detector.types.d.ts.map

package/dist/src/audit/collision-detector.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-detector.types.d.ts","sourceRoot":"","sources":["../../../src/audit/collision-detector.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,kBAAkB,EAClB,cAAc,EACf,MAAM,mCAAmC,CAAA;AAE1C,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,CAAA;AAExE;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,UAAU,CAAA;IAChB,WAAW,EAAE,WAAW,CAAA;IACxB,MAAM,EAAE,cAAc,CAAA;IACtB,MAAM,EAAE,cAAc,CAAA;IACtB,yDAAyD;IACzD,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,EAAE,KAAK,CAAC;QACxB,OAAO,EAAE,MAAM,CAAA;QACf,OAAO,EAAE,MAAM,CAAA;QACf,UAAU,EAAE,MAAM,CAAA;KACnB,CAAC,CAAA;IACF,QAAQ,EAAE,SAAS,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAA;IACf,WAAW,EAAE,WAAW,CAAA;IACxB,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,cAAc,CAAA;IACrB,aAAa,EAAE,MAAM,EAAE,CAAA;IACvB,QAAQ,EAAE,SAAS,CAAA;IACnB,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,SAAS,EAAE,cAAc,EAAE,CAAA;IAC3B,eAAe,EAAE,kBAAkB,EAAE,CAAA;IACrC,YAAY,EAAE,gBAAgB,EAAE,CAAA;IAChC,kBAAkB,EAAE,qBAAqB,EAAE,CAAA;IAC3C,OAAO,EAAE;QACP,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,UAAU,EAAE,MAAM,CAAA;QAClB,YAAY,EAAE,MAAM,CAAA;QACpB,UAAU,EAAE,MAAM,CAAA;QAClB,aAAa,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;KACpE,CAAA;CACF"}

package/dist/src/audit/collision-detector.types.js

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Type vocabulary for the collision detector (SMI-4587 Wave 1 Step 1).
+ * @module @skillsmith/mcp-server/audit/collision-detector.types
+ *
+ * Re-exports the collision flag shapes from local-inventory.types and adds
+ * the InventoryAuditResult container. Public surface for Wave 2/3/4.
+ */
+export {};
+//# sourceMappingURL=collision-detector.types.js.map

package/dist/src/audit/collision-detector.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collision-detector.types.js","sourceRoot":"","sources":["../../../src/audit/collision-detector.types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/src/audit/edit-applier.d.ts

@@ -0,0 +1,64 @@
+/**
+ * @fileoverview Edit-applier — file-mutation path for `RecommendedEdit` (SMI-4589 Wave 3 Step 5).
+ * @module @skillsmith/mcp-server/audit/edit-applier
+ *
+ * `applyRecommendedEdit` mutates a SKILL.md or CLAUDE.md file in-place
+ * after the per-template gate has cleared. The mutation flow:
+ *
+ *   1. Registry guard — reject `pattern`s not in `APPLY_TEMPLATE_REGISTRY`.
+ *   2. Stale-before guard — verify file content at `lineRange` matches
+ *      the recorded `before` snippet byte-for-byte.
+ *   3. Backup — `createProseBackup(filePath, 'prose-edit')`.
+ *   4. Atomic write — write to `<filePath>.tmp` then `fs.rename`.
+ *   5. Ledger append — `appendOverride` + `writeLedger` (Wave 2 PR #1).
+ *   6. Return `EditApplyResult` with the inline revert summary
+ *      (decision #10).
+ *
+ * Per-template gate (ratified 2026-05-01): `APPLY_TEMPLATE_REGISTRY` is
+ * a literal allowlist containing only `'add_domain_qualifier'` in v1
+ * (4.10/5 from GPT-5.4 reviewer-#2 scoring). Synthetic edits with
+ * `pattern: 'narrow_scope'` or `'reword_trigger_verb'` are rejected with
+ * `error: 'edit.template_not_in_apply_registry'` and mutate nothing —
+ * the regression guard test asserts this. SMI-4593 reauthors the failing
+ * templates; when their bodies clear the per-template gate, that issue
+ * extends this allowlist.
+ *
+ * Plan: docs/internal/implementation/smi-4589-edit-suggester.md §5.
+ */
+import type { EditApplyResult } from './edit-applier.types.js';
+import type { EditTemplatePattern, RecommendedEdit } from './edit-suggester.types.js';
+/**
+ * Allowlist of template patterns whose `apply_with_confirmation` mode is
+ * registered for file mutation. Per the per-template gate ratified
+ * 2026-05-01, only `add_domain_qualifier` (4.10/5) ships in v1.
+ *
+ * SMI-4593 extends this set when the failing templates clear the gate
+ * post-reauthoring. Plan §6 mandates plan-review verifies this set
+ * matches `goal_6.per_template_gate.verdicts` PASS templates exactly.
+ *
+ * Type-narrow: declared as `ReadonlySet<EditTemplatePattern>` so the
+ * runtime check can't drift from the type union.
+ */
+export declare const APPLY_TEMPLATE_REGISTRY: ReadonlySet<EditTemplatePattern>;
+export interface ApplyRecommendedEditOptions {
+    /**
+     * FK into `~/.skillsmith/audits/<auditId>/result.json`. Persisted in
+     * the ledger entry so revert can re-derive the original collision
+     * context.
+     */
+    auditId: string;
+    /**
+     * Apply mode. Only `'apply_with_confirmation'` triggers mutation; any
+     * other value is rejected by registry guard ahead of mutation. The
+     * argument is preserved for forward-compat with v2 LLM-driven mode.
+     */
+    mode: 'apply_with_confirmation';
+}
+/**
+ * Apply a `RecommendedEdit` to disk. The agent calls this after
+ * surfacing the edit + receiving user confirmation. Atomic — failure
+ * before mutation leaves the file untouched; failure during mutation
+ * leaves the original file in place via tmp-file + rename semantics.
+ */
+export declare function applyRecommendedEdit(edit: RecommendedEdit, opts: ApplyRecommendedEditOptions): Promise<EditApplyResult>;
+//# sourceMappingURL=edit-applier.d.ts.map

package/dist/src/audit/edit-applier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-applier.d.ts","sourceRoot":"","sources":["../../../src/audit/edit-applier.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAOH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAC9D,OAAO,KAAK,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAErF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,uBAAuB,EAAE,WAAW,CAAC,mBAAmB,CACb,CAAA;AAExD,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;OAIG;IACH,IAAI,EAAE,yBAAyB,CAAA;CAChC;AAED;;;;;GAKG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,2BAA2B,GAChC,OAAO,CAAC,eAAe,CAAC,CA2I1B"}

package/dist/src/audit/edit-applier.js

@@ -0,0 +1,233 @@
+/**
+ * @fileoverview Edit-applier — file-mutation path for `RecommendedEdit` (SMI-4589 Wave 3 Step 5).
+ * @module @skillsmith/mcp-server/audit/edit-applier
+ *
+ * `applyRecommendedEdit` mutates a SKILL.md or CLAUDE.md file in-place
+ * after the per-template gate has cleared. The mutation flow:
+ *
+ *   1. Registry guard — reject `pattern`s not in `APPLY_TEMPLATE_REGISTRY`.
+ *   2. Stale-before guard — verify file content at `lineRange` matches
+ *      the recorded `before` snippet byte-for-byte.
+ *   3. Backup — `createProseBackup(filePath, 'prose-edit')`.
+ *   4. Atomic write — write to `<filePath>.tmp` then `fs.rename`.
+ *   5. Ledger append — `appendOverride` + `writeLedger` (Wave 2 PR #1).
+ *   6. Return `EditApplyResult` with the inline revert summary
+ *      (decision #10).
+ *
+ * Per-template gate (ratified 2026-05-01): `APPLY_TEMPLATE_REGISTRY` is
+ * a literal allowlist containing only `'add_domain_qualifier'` in v1
+ * (4.10/5 from GPT-5.4 reviewer-#2 scoring). Synthetic edits with
+ * `pattern: 'narrow_scope'` or `'reword_trigger_verb'` are rejected with
+ * `error: 'edit.template_not_in_apply_registry'` and mutate nothing —
+ * the regression guard test asserts this. SMI-4593 reauthors the failing
+ * templates; when their bodies clear the per-template gate, that issue
+ * extends this allowlist.
+ *
+ * Plan: docs/internal/implementation/smi-4589-edit-suggester.md §5.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs/promises';
+import { appendOverride, readLedger, writeLedger } from './namespace-overrides.js';
+import { createProseBackup } from '../tools/install.conflict-helpers.js';
+/**
+ * Allowlist of template patterns whose `apply_with_confirmation` mode is
+ * registered for file mutation. Per the per-template gate ratified
+ * 2026-05-01, only `add_domain_qualifier` (4.10/5) ships in v1.
+ *
+ * SMI-4593 extends this set when the failing templates clear the gate
+ * post-reauthoring. Plan §6 mandates plan-review verifies this set
+ * matches `goal_6.per_template_gate.verdicts` PASS templates exactly.
+ *
+ * Type-narrow: declared as `ReadonlySet<EditTemplatePattern>` so the
+ * runtime check can't drift from the type union.
+ */
+export const APPLY_TEMPLATE_REGISTRY = new Set(['add_domain_qualifier']);
+/**
+ * Apply a `RecommendedEdit` to disk. The agent calls this after
+ * surfacing the edit + receiving user confirmation. Atomic — failure
+ * before mutation leaves the file untouched; failure during mutation
+ * leaves the original file in place via tmp-file + rename semantics.
+ */
+export async function applyRecommendedEdit(edit, opts) {
+    // 1. Registry guard. Synthetic edits constructed by tests with a
+    //    failing-template pattern hit this first — no I/O before reject.
+    if (!APPLY_TEMPLATE_REGISTRY.has(edit.pattern)) {
+        return {
+            success: false,
+            collisionId: edit.collisionId,
+            pattern: edit.pattern,
+            filePath: edit.filePath,
+            backupPath: '',
+            ledgerEntryId: '',
+            summary: '',
+            error: {
+                kind: 'edit.template_not_in_apply_registry',
+                pattern: edit.pattern,
+                message: `Template pattern "${edit.pattern}" is not in APPLY_TEMPLATE_REGISTRY; cannot apply. Render in 'manual_review' mode only.`,
+            },
+        };
+    }
+    // 2. Stale-before guard. Read the file and verify the snippet at
+    //    lineRange matches byte-for-byte. Any drift → reject.
+    let fileContent;
+    try {
+        fileContent = await fs.readFile(edit.filePath, 'utf-8');
+    }
+    catch (err) {
+        return failFsError(edit, `read failed: ${err.message}`);
+    }
+    const fileLines = fileContent.split('\n');
+    const startIdx = edit.lineRange.start - 1;
+    const endIdx = edit.lineRange.end - 1;
+    if (startIdx < 0 || endIdx >= fileLines.length || startIdx > endIdx) {
+        return staleBeforeError(edit, 'line range out of bounds');
+    }
+    const onDiskSnippet = fileLines.slice(startIdx, endIdx + 1).join('\n');
+    if (onDiskSnippet !== edit.before) {
+        return staleBeforeError(edit, 'before snippet mismatch');
+    }
+    // 3. Backup BEFORE any mutation. Failure here aborts — never mutate
+    //    without a recoverable backup.
+    let backupPath;
+    try {
+        const backup = await createProseBackup(edit.filePath, 'prose-edit');
+        backupPath = backup.backupPath;
+    }
+    catch (err) {
+        return {
+            success: false,
+            collisionId: edit.collisionId,
+            pattern: edit.pattern,
+            filePath: edit.filePath,
+            backupPath: '',
+            ledgerEntryId: '',
+            summary: '',
+            error: {
+                kind: 'edit.backup_failed',
+                reason: err.message,
+                message: `Backup failed for ${edit.filePath}; file not mutated.`,
+            },
+        };
+    }
+    // 4. Atomic write — splice in the after-snippet at lineRange, write
+    //    to <filePath>.<random>.tmp, fs.rename.
+    const newLines = [
+        ...fileLines.slice(0, startIdx),
+        ...edit.after.split('\n'),
+        ...fileLines.slice(endIdx + 1),
+    ];
+    const newContent = newLines.join('\n');
+    const tmpSuffix = crypto.randomBytes(6).toString('hex');
+    const tmpPath = `${edit.filePath}.${tmpSuffix}.tmp`;
+    try {
+        await fs.writeFile(tmpPath, newContent, 'utf-8');
+        await fs.rename(tmpPath, edit.filePath);
+    }
+    catch (err) {
+        // Best-effort tmp cleanup; ENOENT is fine.
+        try {
+            await fs.rm(tmpPath, { force: true });
+        }
+        catch {
+            /* swallow */
+        }
+        return {
+            success: false,
+            collisionId: edit.collisionId,
+            pattern: edit.pattern,
+            filePath: edit.filePath,
+            backupPath,
+            ledgerEntryId: '',
+            summary: '',
+            error: {
+                kind: 'edit.fs_error',
+                reason: err.message,
+                message: `File mutation failed for ${edit.filePath}; backup retained at ${backupPath}.`,
+            },
+        };
+    }
+    // 5. Ledger append. We piggyback on the namespace-overrides ledger
+    //    (Wave 2 PR #1) — same last-write-wins atomic semantics. The
+    //    `kind` field accepts only `InventoryKind` values; we encode the
+    //    prose-edit case via `originalIdentifier` = filename + lineRange
+    //    marker so revert can locate the entry by `auditId`.
+    const ledger = await readLedger();
+    const lineMarker = `lines:${edit.lineRange.start}-${edit.lineRange.end}`;
+    const updated = appendOverride(ledger, {
+        skillId: null,
+        // SMI-4589 carve-out: prose edits target SKILL.md / CLAUDE.md, not
+        // a renamed inventory artifact. We tag the kind by best-fit
+        // inventory match — `claude_md_rule` for CLAUDE.md edits, `skill`
+        // for SKILL.md edits — to keep the existing ledger union
+        // unchanged. Wave 4 / SMI-4590 may extend the union with a
+        // `'prose_edit'` discriminator if revert ergonomics demand it.
+        kind: edit.category === 'claude_md_trigger_overlap' ? 'claude_md_rule' : 'skill',
+        originalIdentifier: `${edit.filePath}:${lineMarker}`,
+        renamedTo: `${edit.filePath}:${lineMarker}:prose-edit`,
+        originalPath: edit.filePath,
+        renamedPath: edit.filePath,
+        auditId: opts.auditId,
+        reason: edit.rationale,
+    });
+    if (updated !== ledger) {
+        await writeLedger(updated);
+    }
+    const ledgerEntryId = updated === ledger ? '' : (updated.overrides[updated.overrides.length - 1]?.id ?? '');
+    // 6. Return success with the inline revert summary literal.
+    return {
+        success: true,
+        collisionId: edit.collisionId,
+        pattern: edit.pattern,
+        filePath: edit.filePath,
+        backupPath,
+        ledgerEntryId,
+        summary: buildSummary(edit.filePath, edit.lineRange, opts.auditId),
+    };
+}
+/**
+ * Inline revert-summary literal (decision #10). Mirrors Wave 2's UX —
+ * `sklx audit revert <auditId>` is a Wave 4 (SMI-4590) command surface;
+ * if Wave 4 hasn't shipped at the time this fires, the summary remains
+ * user-facing copy and the command is a no-op until SMI-4590 lands.
+ */
+function buildSummary(filePath, lineRange, auditId) {
+    // Always emit `start-end` form even on single-line ranges. The Wave 4
+    // CLI surface (`sklx audit revert`) parses the range; a stable two-
+    // number form simplifies the parser and matches the literal copy in
+    // the plan §5: `"Edited <file> lines <range>. To undo: ..."`.
+    const range = `${lineRange.start}-${lineRange.end}`;
+    return `Edited ${filePath} lines ${range}. To undo: sklx audit revert ${auditId}`;
+}
+function staleBeforeError(edit, reason) {
+    return {
+        success: false,
+        collisionId: edit.collisionId,
+        pattern: edit.pattern,
+        filePath: edit.filePath,
+        backupPath: '',
+        ledgerEntryId: '',
+        summary: '',
+        error: {
+            kind: 'edit.stale_before',
+            filePath: edit.filePath,
+            message: `Before snippet mismatch for ${edit.filePath} at lines ${edit.lineRange.start}-${edit.lineRange.end} (${reason}). Re-run detection.`,
+        },
+    };
+}
+function failFsError(edit, reason) {
+    return {
+        success: false,
+        collisionId: edit.collisionId,
+        pattern: edit.pattern,
+        filePath: edit.filePath,
+        backupPath: '',
+        ledgerEntryId: '',
+        summary: '',
+        error: {
+            kind: 'edit.fs_error',
+            reason,
+            message: `File access failed for ${edit.filePath}: ${reason}`,
+        },
+    };
+}
+//# sourceMappingURL=edit-applier.js.map

package/dist/src/audit/edit-applier.js.map

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

package/dist/src/audit/edit-applier.types.d.ts

@@ -0,0 +1,72 @@
+/**
+ * @fileoverview Type vocabulary for the edit-applier (SMI-4589 Wave 3 Step 5).
+ * @module @skillsmith/mcp-server/audit/edit-applier.types
+ *
+ * Mirrors `ApplyRenameResult` (Wave 2 PR #2) so heterogeneous suggestion
+ * lists (rename + edit) can be displayed uniformly by Wave 4's MCP tool
+ * surface. The error union is purpose-narrow — prose-edit failures don't
+ * include any rename-engine codes.
+ *
+ * Plan: docs/internal/implementation/smi-4589-edit-suggester.md §5.
+ */
+import type { CollisionId } from './collision-detector.types.js';
+import type { EditTemplatePattern } from './edit-suggester.types.js';
+/**
+ * Discriminated errors surfaced by `applyRecommendedEdit`. Callers
+ * `switch` on `kind` rather than parsing the message string.
+ */
+export type EditApplyError = {
+    /** Edit's source template is not in the apply registry allowlist. */
+    kind: 'edit.template_not_in_apply_registry';
+    pattern: EditTemplatePattern;
+    message: string;
+} | {
+    /**
+     * The file content at `lineRange` no longer matches the recorded
+     * `before` snippet — file changed under us between detector run
+     * and apply call. The agent should re-run detection and surface
+     * the fresh suggestion.
+     */
+    kind: 'edit.stale_before';
+    filePath: string;
+    message: string;
+} | {
+    kind: 'edit.backup_failed';
+    reason: string;
+    message: string;
+} | {
+    kind: 'edit.fs_error';
+    reason: string;
+    message: string;
+};
+/**
+ * Result of applying a `RecommendedEdit`. `success === false` populates
+ * `error`; `success === true` populates `backupPath`, `ledgerEntryId`,
+ * and the inline revert summary text.
+ */
+export interface EditApplyResult {
+    success: boolean;
+    collisionId: CollisionId;
+    /** Pattern that produced the edit (for log-grep + telemetry). */
+    pattern: EditTemplatePattern;
+    /** Absolute path to the mutated file. */
+    filePath: string;
+    /**
+     * Backup directory created by `createProseBackup`. Empty string on
+     * failure. Backup is retained until the 30-day GC sweep.
+     */
+    backupPath: string;
+    /** ULID of the appended ledger entry (`ovr_…`). Empty string on failure. */
+    ledgerEntryId: string;
+    /**
+     * Inline revert summary (decision #10). Literal text on success:
+     *
+     *   `"Edited <file> lines <range>. To undo: sklx audit revert <auditId>"`
+     *
+     * Empty string on failure.
+     */
+    summary: string;
+    /** Discriminated error on failure; `undefined` on success. */
+    error?: EditApplyError;
+}
+//# sourceMappingURL=edit-applier.types.d.ts.map

package/dist/src/audit/edit-applier.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-applier.types.d.ts","sourceRoot":"","sources":["../../../src/audit/edit-applier.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AAEpE;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,qEAAqE;IACrE,IAAI,EAAE,qCAAqC,CAAA;IAC3C,OAAO,EAAE,mBAAmB,CAAA;IAC5B,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE;;;;;OAKG;IACH,IAAI,EAAE,mBAAmB,CAAA;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,IAAI,EAAE,oBAAoB,CAAA;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,GACD;IACE,IAAI,EAAE,eAAe,CAAA;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAEL;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,OAAO,CAAA;IAChB,WAAW,EAAE,WAAW,CAAA;IACxB,iEAAiE;IACjE,OAAO,EAAE,mBAAmB,CAAA;IAC5B,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,aAAa,EAAE,MAAM,CAAA;IACrB;;;;;;OAMG;IACH,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,KAAK,CAAC,EAAE,cAAc,CAAA;CACvB"}

package/dist/src/audit/edit-applier.types.js

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Type vocabulary for the edit-applier (SMI-4589 Wave 3 Step 5).
+ * @module @skillsmith/mcp-server/audit/edit-applier.types
+ *
+ * Mirrors `ApplyRenameResult` (Wave 2 PR #2) so heterogeneous suggestion
+ * lists (rename + edit) can be displayed uniformly by Wave 4's MCP tool
+ * surface. The error union is purpose-narrow — prose-edit failures don't
+ * include any rename-engine codes.
+ *
+ * Plan: docs/internal/implementation/smi-4589-edit-suggester.md §5.
+ */
+export {};
+//# sourceMappingURL=edit-applier.types.js.map

package/dist/src/audit/edit-applier.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-applier.types.js","sourceRoot":"","sources":["../../../src/audit/edit-applier.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/src/audit/edit-suggester.d.ts

@@ -0,0 +1,63 @@
+/**
+ * @fileoverview Edit-suggester core (SMI-4589 Wave 3 Steps 2-3).
+ * @module @skillsmith/mcp-server/audit/edit-suggester
+ *
+ * Takes the semantic-collision flags from Wave 1's `InventoryAuditResult`
+ * and produces `RecommendedEdit[]` — templated, deterministic prose-edit
+ * suggestions. No LLM calls. No fuzziness.
+ *
+ * Per-template gate (ratified 2026-05-01): v1 ships only
+ * `add_domain_qualifier` (4.10/5 from GPT-5.4 reviewer-#2 scoring). The
+ * other two templates (`narrow_scope` 1.70/5, `reword_trigger_verb`
+ * 2.35/5) FAILED the gate and are NOT shipped in any form — neither as
+ * auto-apply nor as `manual_review`. They route to SMI-4593 for
+ * reauthoring. Test cases 2-3 in `edit-suggester.test.ts` assert empty
+ * output for collisions that would have matched those failing templates,
+ * guarding against accidental re-registration before the gate clears.
+ *
+ * Dispatch pattern (plan §1):
+ *   1. Walk `result.semanticCollisions[]`, collect unique file paths
+ *      across the surviving template's `applies()` checks.
+ *   2. `await Promise.all(uniqueFilePaths.map(fs.readFile))` — single
+ *      parallel read phase. Latency budget is linear in unique-files,
+ *      not templates × collisions.
+ *   3. Iterate flags; for each, walk templates pre-sorted by descending
+ *      `priority`; first `applies()` true wins; `generate()` is
+ *      synchronous over the cached `fileContent`.
+ *   4. Filter null results (template matched but generate() couldn't
+ *      synthesize a valid edit — e.g. file content drifted).
+ *
+ * Plan: docs/internal/implementation/smi-4589-edit-suggester.md §1, §Steps 2-3.
+ */
+import type { InventoryAuditResult } from './collision-detector.types.js';
+import type { EditTemplate, EditTemplatePattern, RecommendedEdit } from './edit-suggester.types.js';
+/**
+ * Run the edit-suggester over an `InventoryAuditResult`'s semantic
+ * collisions. Returns `RecommendedEdit[]` — one per flag that matches a
+ * registered template AND whose template successfully synthesized a
+ * non-empty edit.
+ *
+ * Order of returned edits: same as `result.semanticCollisions[]` input
+ * order. Tests assert this stability so PR diffs in the audit-report
+ * markdown are deterministic.
+ *
+ * I/O: reads each unique referenced file ONCE, in parallel, before
+ * iterating templates. Templates see only `fileContent` strings, not
+ * paths — keeps templates pure and unit-testable without fixtures on
+ * disk.
+ *
+ * Failure model: any per-flag template error (fileRead failure, snippet
+ * locate failure, `generate()` returning null) skips that flag silently.
+ * The other flags still produce edits. An empty
+ * `result.semanticCollisions[]` short-circuits with no I/O.
+ */
+export declare function runEditSuggester(result: InventoryAuditResult, opts?: {
+    templateOverrides?: ReadonlyArray<EditTemplate>;
+}): Promise<RecommendedEdit[]>;
+/**
+ * Public registry-key accessor. Re-exports the pattern strings so the
+ * apply-path registry (`edit-applier.ts`) can import a single source of
+ * truth instead of stringly-typed literals.
+ */
+export declare const V1_TEMPLATE_PATTERNS: ReadonlyArray<EditTemplatePattern>;
+//# sourceMappingURL=edit-suggester.d.ts.map

package/dist/src/audit/edit-suggester.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edit-suggester.d.ts","sourceRoot":"","sources":["../../../src/audit/edit-suggester.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAIH,OAAO,KAAK,EAAE,oBAAoB,EAAyB,MAAM,+BAA+B,CAAA;AAChG,OAAO,KAAK,EAAE,YAAY,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAqGnG;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,oBAAoB,EAC5B,IAAI,CAAC,EAAE;IAAE,iBAAiB,CAAC,EAAE,aAAa,CAAC,YAAY,CAAC,CAAA;CAAE,GACzD,OAAO,CAAC,eAAe,EAAE,CAAC,CA8D5B;AA8HD;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,mBAAmB,CAEnE,CAAA"}