@skillsmith/mcp-server 0.4.13 → 0.5.0

package/dist/src/audit/install-preflight.d.ts

@@ -0,0 +1,99 @@
+/**
+ * @fileoverview Install pre-flight namespace check (SMI-4588 Wave 2 Step 5, PR #3).
+ * @module @skillsmith/mcp-server/audit/install-preflight
+ *
+ * Detects namespace collisions between an in-flight install candidate and
+ * the user's existing local inventory BEFORE any side effects. Returns both
+ * a non-blocking `warnings[]` shape (for `power_user` / `governance` modes)
+ * AND a blocking `pendingCollision` envelope (for `preventative` mode). The
+ * mode gate lives in the install.ts caller — this module is pure detection
+ * + suggestion generation + audit-history persistence.
+ *
+ * Plan §3 + §Step 5 + Edits 2/3/6/7.
+ *
+ * Inventory contract (Edit 7):
+ *   - `existingInventory` — pre-candidate snapshot, passed to
+ *     `generateSuggestionChain` (chain self-collides at tier 1 otherwise).
+ *   - `augmentedInventory` — existing + the synthesized candidate, passed to
+ *     `detectCollisions`. Filtering to flags involving the candidate keeps
+ *     pre-existing collisions from re-surfacing on every install.
+ *
+ * Failure model (Edit 2):
+ *   - Pre-flight scanner failure (ledger malformed unrecoverably, fs error,
+ *     unexpected throw) is ALWAYS non-blocking. The caller treats `warnings:
+ *     [], pendingCollision: null` as a degraded-but-clean pass and proceeds
+ *     with the install.
+ *
+ * Edit 6 — `readLedger()` may throw `namespace.ledger.version_unsupported`.
+ * The pre-flight catches it and degrades to non-blocking; bubbling would
+ * brick installs after a ledger downgrade.
+ */
+import type { AuditId, InventoryEntry } from './collision-detector.types.js';
+import type { NamespaceWarning, PendingCollision } from './namespace-audit.types.js';
+import type { AuditMode, Tier } from '@skillsmith/core/config/audit-mode';
+/**
+ * One synthesized candidate skill being considered for install. The
+ * pre-flight builds an `InventoryEntry` for it so the existing
+ * `detectCollisions` pipeline can compare it against the user's inventory.
+ */
+export interface CandidateSkill {
+    /** Skill identifier post-install (e.g. `"code-helper"`). */
+    identifier: string;
+    /**
+     * Path the skill WILL occupy post-install. The pre-flight runs before
+     * the install touches disk, so this is a projected path used for
+     * suggestion-chain `authorPath` derivation. Real on-disk state is not
+     * inspected here.
+     */
+    projectedSourcePath: string;
+    /** Optional Skillsmith manifest skillId (`<author>/<name>`). */
+    skillId?: string | null;
+    /** Optional `meta.author` slug (`anthropic`) — flows to suggestion chain. */
+    author?: string | null;
+    /** Optional `meta.tags` for the suggestion-chain tag fallback. */
+    tags?: string[];
+    /** Optional `meta.description` (round-tripped for audit-history). */
+    description?: string;
+    /**
+     * Pack-domain hint (e.g. `codehelper`) used at chain tier 2/3. The install
+     * caller derives this from the registry response or manifest; pre-flight
+     * passes it through unchanged.
+     */
+    packDomain?: string | null;
+}
+export interface RunInstallPreflightInput {
+    /** Pre-candidate snapshot of `~/.claude/{skills,commands,agents}` + CLAUDE.md. */
+    existingInventory: ReadonlyArray<InventoryEntry>;
+    /** Synthesized candidate skill being considered for install. */
+    candidate: CandidateSkill;
+    /** Resolved audit mode (`'preventative'` blocks install in caller). */
+    mode: AuditMode;
+    /** Subscription tier (drives default mode for the inner detector run). */
+    tier: Tier;
+}
+export interface RunInstallPreflightResult {
+    /** Non-blocking warnings (`power_user` / `governance` mode shape). */
+    warnings: NamespaceWarning[];
+    /**
+     * Blocking envelope for `preventative` mode. Populated only when at
+     * least one candidate-related collision is detected. Caller decides
+     * whether to surface it based on `mode`.
+     */
+    pendingCollision: PendingCollision | null;
+    /**
+     * ULID written to audit history. Bubbled explicitly per Edit 7 so the
+     * install caller does not re-derive it for telemetry / ledger linkage.
+     */
+    auditId: AuditId;
+}
+/**
+ * Run the install pre-flight. Pure function over `existingInventory` +
+ * `candidate`; emits an audit-history entry as a side effect so the agent's
+ * later `apply_namespace_rename` call can re-derive context via `auditId`.
+ *
+ * Failure model: any unexpected throw inside this function returns the
+ * degraded shape (`warnings: []`, `pendingCollision: null`, fresh
+ * `auditId`) — the install MUST proceed when the detector breaks (Edit 2).
+ */
+export declare function runInstallPreflight(input: RunInstallPreflightInput): Promise<RunInstallPreflightResult>;
+//# sourceMappingURL=install-preflight.d.ts.map

package/dist/src/audit/install-preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-preflight.d.ts","sourceRoot":"","sources":["../../../src/audit/install-preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAGH,OAAO,KAAK,EACV,OAAO,EAKP,cAAc,EAEf,MAAM,+BAA+B,CAAA;AACtC,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAA;AAEpF,OAAO,KAAK,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,oCAAoC,CAAA;AAOzE;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,4DAA4D;IAC5D,UAAU,EAAE,MAAM,CAAA;IAClB;;;;;OAKG;IACH,mBAAmB,EAAE,MAAM,CAAA;IAC3B,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,qEAAqE;IACrE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAC3B;AAED,MAAM,WAAW,wBAAwB;IACvC,kFAAkF;IAClF,iBAAiB,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;IAChD,gEAAgE;IAChE,SAAS,EAAE,cAAc,CAAA;IACzB,uEAAuE;IACvE,IAAI,EAAE,SAAS,CAAA;IACf,0EAA0E;IAC1E,IAAI,EAAE,IAAI,CAAA;CACX;AAED,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,QAAQ,EAAE,gBAAgB,EAAE,CAAA;IAC5B;;;;OAIG;IACH,gBAAgB,EAAE,gBAAgB,GAAG,IAAI,CAAA;IACzC;;;OAGG;IACH,OAAO,EAAE,OAAO,CAAA;CACjB;AA4KD;;;;;;;;GAQG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,wBAAwB,GAC9B,OAAO,CAAC,yBAAyB,CAAC,CAgHpC"}

package/dist/src/audit/install-preflight.js

@@ -0,0 +1,320 @@
+/**
+ * @fileoverview Install pre-flight namespace check (SMI-4588 Wave 2 Step 5, PR #3).
+ * @module @skillsmith/mcp-server/audit/install-preflight
+ *
+ * Detects namespace collisions between an in-flight install candidate and
+ * the user's existing local inventory BEFORE any side effects. Returns both
+ * a non-blocking `warnings[]` shape (for `power_user` / `governance` modes)
+ * AND a blocking `pendingCollision` envelope (for `preventative` mode). The
+ * mode gate lives in the install.ts caller — this module is pure detection
+ * + suggestion generation + audit-history persistence.
+ *
+ * Plan §3 + §Step 5 + Edits 2/3/6/7.
+ *
+ * Inventory contract (Edit 7):
+ *   - `existingInventory` — pre-candidate snapshot, passed to
+ *     `generateSuggestionChain` (chain self-collides at tier 1 otherwise).
+ *   - `augmentedInventory` — existing + the synthesized candidate, passed to
+ *     `detectCollisions`. Filtering to flags involving the candidate keeps
+ *     pre-existing collisions from re-surfacing on every install.
+ *
+ * Failure model (Edit 2):
+ *   - Pre-flight scanner failure (ledger malformed unrecoverably, fs error,
+ *     unexpected throw) is ALWAYS non-blocking. The caller treats `warnings:
+ *     [], pendingCollision: null` as a degraded-but-clean pass and proceeds
+ *     with the install.
+ *
+ * Edit 6 — `readLedger()` may throw `namespace.ledger.version_unsupported`.
+ * The pre-flight catches it and degrades to non-blocking; bubbling would
+ * brick installs after a ledger downgrade.
+ */
+import { detectCollisions } from './collision-detector.js';
+import { newAuditId, writeAuditHistory } from './audit-history.js';
+import { generateSuggestionChain } from './suggestion-chain.js';
+import { runEditSuggester } from './edit-suggester.js';
+/**
+ * Synthesize an `InventoryEntry` for the candidate skill. Mirrors the
+ * shape `scanLocalInventory` produces for `~/.claude/skills/*`.
+ */
+function synthesizeCandidateEntry(candidate) {
+    return {
+        kind: 'skill',
+        source_path: candidate.projectedSourcePath,
+        identifier: candidate.identifier,
+        triggerSurface: [candidate.identifier],
+        meta: {
+            author: candidate.author ?? undefined,
+            tags: candidate.tags,
+            description: candidate.description,
+        },
+    };
+}
+/**
+ * Filter detector flags to those that involve the candidate skill. The
+ * user has already accepted any pre-existing collisions; only newly
+ * introduced ones surface at install time.
+ */
+function flagInvolvesCandidate(flag, candidatePath) {
+    if (flag.kind === 'exact') {
+        return flag.entries.some((e) => e.source_path === candidatePath);
+    }
+    if (flag.kind === 'generic') {
+        return flag.entry.source_path === candidatePath;
+    }
+    // semantic
+    return flag.entryA.source_path === candidatePath || flag.entryB.source_path === candidatePath;
+}
+/**
+ * Find the inventory entry on the OTHER side of a flag — the entry the
+ * candidate collides with. Used when constructing `RenameSuggestion`
+ * shapes whose `entry` field points at the candidate (so the apply path
+ * mutates the candidate, not the existing entry).
+ */
+function candidateEntryFromFlag(flag, candidatePath) {
+    if (flag.kind === 'exact') {
+        return flag.entries.find((e) => e.source_path === candidatePath) ?? null;
+    }
+    if (flag.kind === 'generic') {
+        return flag.entry;
+    }
+    return flag.entryA.source_path === candidatePath ? flag.entryA : flag.entryB;
+}
+/**
+ * Pick the apply-action for the candidate based on its kind. The candidate
+ * is always synthesized as `kind: 'skill'`; this stays a switch so future
+ * candidate kinds (commands, agents added at install time) are supported.
+ */
+function actionForEntry(entry) {
+    switch (entry.kind) {
+        case 'command':
+            return 'rename_command_file';
+        case 'agent':
+            return 'rename_agent_file';
+        case 'skill':
+        case 'claude_md_rule':
+        default:
+            return 'rename_skill_dir_and_frontmatter';
+    }
+}
+/**
+ * Build a `RenameSuggestion` for the candidate, picking the first
+ * non-colliding chain candidate as `suggested`. Falls back to chain
+ * candidate[0] when all collide (the agent surfaces the chain via
+ * `pendingCollision.suggestionChain`).
+ */
+function buildCandidateSuggestion(args) {
+    const chain = generateSuggestionChain({
+        token: args.candidate.identifier,
+        author: args.candidate.author ?? null,
+        packDomain: args.candidate.packDomain ?? null,
+        tagFallback: args.candidate.tags?.[0] ?? null,
+        authorPath: args.candidate.projectedSourcePath,
+        existingInventory: args.existingInventory,
+    });
+    // First non-colliding candidate, or fall back to first slot when all
+    // collide (caller surfaces `chainExhausted` separately).
+    const lowercaseInventory = new Set(args.existingInventory.map((e) => e.identifier.toLowerCase()));
+    const firstFree = chain.candidates.find((c) => !lowercaseInventory.has(c.toLowerCase()));
+    const suggested = firstFree ?? chain.candidates[0] ?? args.candidate.identifier;
+    const reason = buildReason(args.flag, args.candidate.projectedSourcePath);
+    return {
+        suggestion: {
+            collisionId: args.flag.collisionId,
+            entry: args.candidateEntry,
+            currentName: args.candidate.identifier,
+            suggested,
+            applyAction: actionForEntry(args.candidateEntry),
+            reason,
+        },
+        chain: chain.candidates,
+        exhausted: chain.exhausted,
+    };
+}
+function buildReason(flag, candidatePath) {
+    if (flag.kind === 'exact') {
+        // Exclude the candidate from the rendered list so the message reads
+        // as "X collides with the existing entries", not "X collides with X
+        // and the existing entries".
+        const others = flag.entries
+            .filter((e) => e.source_path !== candidatePath)
+            .map((e) => `${e.kind}:${e.identifier}`)
+            .join(', ');
+        return `exact collision with ${others}`;
+    }
+    if (flag.kind === 'generic') {
+        return `generic-token flag (${flag.matchedTokens.join(', ')})`;
+    }
+    return `semantic overlap (cosine ${flag.cosineScore.toFixed(2)}) with ${flag.entryB.identifier}`;
+}
+/**
+ * Filter out the candidate skill's own prior on-disk presence from the
+ * inventory snapshot.
+ *
+ * On reinstall (`force: true`), `scanLocalInventory` returns an entry for
+ * the already-installed skill at `<projectedSourcePath>/SKILL.md`. If we
+ * left it in `existingInventory`, the augmented inventory would contain
+ * both the prior entry AND the synthesized candidate with the same
+ * `identifier`, and `detectExactCollisions` would surface a false-positive
+ * "namespace collision" that blocks reinstall in `preventative` mode.
+ *
+ * The reinstall flow is owned by `install.conflict.ts` (three-way merge,
+ * backup, force semantics). Pre-flight is for *new* namespace conflicts
+ * with *other* skills, not for the candidate's own prior copy.
+ */
+function excludeSelfReinstall(existing, candidate) {
+    const candidateDir = candidate.projectedSourcePath;
+    const candidateIdentifier = candidate.identifier.toLowerCase();
+    return existing.filter((entry) => {
+        if (entry.kind !== 'skill')
+            return true;
+        if (entry.identifier.toLowerCase() !== candidateIdentifier)
+            return true;
+        // Skill entries' source_path is `<dir>/SKILL.md`; match by parent dir.
+        // Also accept exact-equality for forward-compat with future synthesis
+        // shapes that may use the directory path directly.
+        if (entry.source_path === candidateDir)
+            return false;
+        if (entry.source_path.startsWith(`${candidateDir}/`))
+            return false;
+        return true;
+    });
+}
+/**
+ * Run the install pre-flight. Pure function over `existingInventory` +
+ * `candidate`; emits an audit-history entry as a side effect so the agent's
+ * later `apply_namespace_rename` call can re-derive context via `auditId`.
+ *
+ * Failure model: any unexpected throw inside this function returns the
+ * degraded shape (`warnings: []`, `pendingCollision: null`, fresh
+ * `auditId`) — the install MUST proceed when the detector breaks (Edit 2).
+ */
+export async function runInstallPreflight(input) {
+    const { existingInventory, candidate, mode, tier } = input;
+    // Allocate the audit id up front so the degraded path returns a valid
+    // ULID even when the inner detector throws before producing a result.
+    const auditId = newAuditId();
+    let inventoryWithoutSelf;
+    let augmentedInventory;
+    let result;
+    try {
+        // Exclude the candidate's own prior on-disk copy (reinstall) so the
+        // detector doesn't surface it as a namespace collision against itself.
+        inventoryWithoutSelf = excludeSelfReinstall(existingInventory, candidate);
+        const candidateEntry = synthesizeCandidateEntry(candidate);
+        augmentedInventory = [...inventoryWithoutSelf, candidateEntry];
+        result = await detectCollisions(augmentedInventory, {
+            auditId,
+            tier,
+            auditModeOverride: mode,
+        });
+    }
+    catch (err) {
+        // Edit 2: pre-flight failure is always non-blocking. Log + degrade.
+        // The catch covers `excludeSelfReinstall` (rejects non-iterable
+        // inputs), `synthesizeCandidateEntry`, the spread, AND
+        // `detectCollisions`. Any pre-flight failure → install proceeds.
+        console.warn(`[install-preflight] detector failed (${err.message}); degrading to non-blocking pass`);
+        return { warnings: [], pendingCollision: null, auditId };
+    }
+    // Filter to flags involving the candidate. Pre-existing collisions are
+    // out of scope at install time.
+    const allFlags = [
+        ...result.exactCollisions,
+        ...result.genericFlags,
+        ...result.semanticCollisions,
+    ];
+    const candidateFlags = allFlags.filter((f) => flagInvolvesCandidate(f, candidate.projectedSourcePath));
+    if (candidateFlags.length === 0) {
+        // Clean candidate. Persist the audit history (zero-flag run) so the
+        // agent's later inspection by auditId still resolves; absence of an
+        // audit file would be ambiguous.
+        await tryWriteAuditHistory(result);
+        return { warnings: [], pendingCollision: null, auditId };
+    }
+    // SMI-4589 Wave 3: run the edit-suggester over the audit result (which
+    // already contains the candidate-augmented inventory). We attach the
+    // matching edit to each semantic NamespaceWarning by collisionId. Edge
+    // cases:
+    //   - Edit-suggester throws → log + degrade to no edits (preserves the
+    //     non-blocking install contract per Wave 2 Edit 2). Failure of the
+    //     edit surface MUST NOT brick the install pre-flight.
+    //   - Non-semantic warnings (`exact`, `generic`) never carry a
+    //     recommendedEdit — the suggester only runs over semanticCollisions.
+    const editsByCollisionId = await collectRecommendedEdits(result);
+    // Build a NamespaceWarning + suggestion-chain for each candidate-related
+    // flag. We surface the first flag's chain in `pendingCollision` (the
+    // dominant collision); all flags surface in `warnings[]`.
+    const warnings = [];
+    let pendingCollision = null;
+    for (let i = 0; i < candidateFlags.length; i++) {
+        const flag = candidateFlags[i];
+        const candidateEntry = candidateEntryFromFlag(flag, candidate.projectedSourcePath);
+        if (!candidateEntry)
+            continue;
+        const built = buildCandidateSuggestion({
+            flag,
+            candidate,
+            candidateEntry,
+            // Pass the self-excluded snapshot so the chain doesn't treat the
+            // candidate's own prior install (during a force-reinstall) as a
+            // colliding entry — that would force `chainExhausted: true` on
+            // every reinstall.
+            existingInventory: inventoryWithoutSelf,
+        });
+        const recommendedEdit = editsByCollisionId.get(flag.collisionId);
+        warnings.push({
+            collisionId: flag.collisionId,
+            kind: flag.kind,
+            severity: 'warning',
+            message: buildWarningMessage(flag, candidate, built.suggestion.suggested),
+            suggestion: built.suggestion,
+            auditId,
+            recommendedEdit,
+        });
+        // First candidate-flag becomes the pendingCollision envelope.
+        if (i === 0) {
+            pendingCollision = {
+                auditId,
+                suggestedRename: built.suggestion,
+                suggestionChain: built.chain,
+                chainExhausted: built.exhausted,
+                remediationHint: "call apply_namespace_rename({ auditId, action: 'apply' }) then re-invoke install_skill",
+            };
+        }
+    }
+    await tryWriteAuditHistory(result);
+    return { warnings, pendingCollision, auditId };
+}
+function buildWarningMessage(flag, candidate, suggested) {
+    const reason = buildReason(flag, candidate.projectedSourcePath);
+    return `Namespace ${flag.kind} collision installing "${candidate.identifier}": ${reason}. Suggested rename: "${suggested}".`;
+}
+/**
+ * SMI-4589 Wave 3: collect recommended edits indexed by collisionId.
+ * Edit-suggester failure degrades silently to an empty map — the
+ * non-blocking install contract from Wave 2 Edit 2 extends here.
+ */
+async function collectRecommendedEdits(result) {
+    try {
+        const recommendedEdits = await runEditSuggester(result);
+        return new Map(recommendedEdits.map((e) => [e.collisionId, e]));
+    }
+    catch (err) {
+        console.warn(`[install-preflight] edit-suggester failed (${err.message}); proceeding without prose edits`);
+        return new Map();
+    }
+}
+/**
+ * Persist the audit history. Errors here are logged + swallowed — pre-flight
+ * is non-blocking (Edit 2), and a missing audit file degrades the agent's
+ * later `apply_namespace_rename` lookup but does not break install.
+ */
+async function tryWriteAuditHistory(result) {
+    try {
+        await writeAuditHistory(result);
+    }
+    catch (err) {
+        console.warn(`[install-preflight] writeAuditHistory failed (${err.message}); auditId will be unrecoverable but install proceeds`);
+    }
+}
+//# sourceMappingURL=install-preflight.js.map

package/dist/src/audit/install-preflight.js.map

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

package/dist/src/audit/namespace-audit.types.d.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview Shared namespace-audit type vocabulary (SMI-4588 Wave 2 Step 1, PR #1).
+ * @module @skillsmith/mcp-server/audit/namespace-audit.types
+ *
+ * `NamespaceWarning` and `PendingCollision` live here — not in
+ * `tools/install.types.ts` and not in `audit/install-preflight.ts` — to break
+ * the `tools → audit → tools` cycle that would otherwise form between
+ * `install-preflight.ts` (which constructs them) and `install.types.ts`
+ * (which embeds them in `InstallResult`). The shared file is depended on by
+ * both sides; neither side depends on the other.
+ *
+ * Wave 2 plan §4 + Edit 3 — placed in Step 1 so PRs #3/#4 import without
+ * rework.
+ *
+ * `RenameSuggestion` is imported from `./rename-engine.types.js` (PR #2). The
+ * PR #1 forward-declaration shim has been retired now that the canonical
+ * type ships alongside the rename engine.
+ */
+import type { CollisionId } from './collision-detector.types.js';
+import type { RenameSuggestion } from './rename-engine.types.js';
+import type { RecommendedEdit } from './edit-suggester.types.js';
+/**
+ * A non-blocking namespace collision surfaced by the install pre-flight
+ * (Wave 2 PR #3). `power_user` and `governance` modes return one of these
+ * per detected collision in `InstallResult.warnings[]`; the agent surfaces
+ * the suggestion to the user but the install still proceeds.
+ */
+export interface NamespaceWarning {
+    /** Stable across audit runs — derived via `deriveCollisionId`. */
+    collisionId: CollisionId;
+    /** Matches the source collision flag's `kind`. */
+    kind: 'exact' | 'generic' | 'semantic';
+    /** Always `'warning'` — `NamespaceWarning` never blocks install. */
+    severity: 'warning';
+    /** User-facing message (rendered verbatim to the agent). */
+    message: string;
+    /**
+     * Suggested rename for the agent to surface. Constructed by
+     * `generateRenameSuggestions` (Wave 2 PR #2). Walking the suggestion
+     * chain is the agent's job — `suggestion` is the first non-colliding
+     * candidate.
+     */
+    suggestion: RenameSuggestion;
+    /**
+     * FK to the audit history written by `runInstallPreflight` (PR #3). Lets
+     * a later `apply_namespace_rename` call (Wave 4) re-read the original
+     * suggestion without re-running detection.
+     */
+    auditId: string;
+    /**
+     * SMI-4589 Wave 3: optional prose-edit recommendation surfaced for
+     * `description_overlap` semantic collisions. The agent surfaces the
+     * `RecommendedEdit` alongside the rename suggestion; rename may not
+     * be the right remediation when descriptions semantically overlap.
+     *
+     * Per the per-template gate ratified 2026-05-01, only
+     * `add_domain_qualifier`-pattern edits populate this field in v1.
+     * `kind: 'exact'` and `kind: 'generic'` warnings never carry a
+     * recommended edit (they're text-identifier collisions, not prose).
+     */
+    recommendedEdit?: RecommendedEdit;
+}
+/**
+ * Blocking-mode envelope for `audit_mode: 'preventative'` installs (Wave 2
+ * PR #3, decision #2). When pre-flight detects a collision, `install_skill`
+ * returns `installComplete: false` plus this envelope. The agent calls
+ * `apply_namespace_rename({ auditId, action: 'apply' })` (Wave 4) and then
+ * re-invokes `install_skill`.
+ *
+ * The `suggestionChain[]` carries up to 3 ordered candidates per
+ * decision #11; the agent walks the chain and picks the first non-colliding
+ * one. `chainExhausted` is `true` when all 3 collide and the agent must
+ * escalate to the human via `customName`.
+ */
+export interface PendingCollision {
+    /** ULID — passed back to `apply_namespace_rename`. */
+    auditId: string;
+    /**
+     * First non-colliding candidate from `generateSuggestionChain`. The agent
+     * surfaces this to the user as the recommended rename.
+     */
+    suggestedRename: RenameSuggestion;
+    /**
+     * Up to 3 candidates from `generateSuggestionChain` (decision #11). The
+     * agent has the full chain so it can present alternatives without
+     * re-querying.
+     */
+    suggestionChain: string[];
+    /**
+     * `true` when all 3 chain candidates collide. The agent must escalate to
+     * the human and call `apply_namespace_rename({ customName: '…' })`.
+     */
+    chainExhausted: boolean;
+    /**
+     * Human-readable remediation hint, e.g.
+     * `"call apply_namespace_rename({ auditId, action: 'apply' }) then re-invoke install_skill"`.
+     */
+    remediationHint: string;
+}
+//# sourceMappingURL=namespace-audit.types.d.ts.map

package/dist/src/audit/namespace-audit.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-audit.types.d.ts","sourceRoot":"","sources":["../../../src/audit/namespace-audit.types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAA;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAA;AAMhE;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,WAAW,EAAE,WAAW,CAAA;IACxB,kDAAkD;IAClD,IAAI,EAAE,OAAO,GAAG,SAAS,GAAG,UAAU,CAAA;IACtC,oEAAoE;IACpE,QAAQ,EAAE,SAAS,CAAA;IACnB,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAA;IACf;;;;;OAKG;IACH,UAAU,EAAE,gBAAgB,CAAA;IAC5B;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAA;IACf;;;;;;;;;;OAUG;IACH,eAAe,CAAC,EAAE,eAAe,CAAA;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,gBAAgB;IAC/B,sDAAsD;IACtD,OAAO,EAAE,MAAM,CAAA;IACf;;;OAGG;IACH,eAAe,EAAE,gBAAgB,CAAA;IACjC;;;;OAIG;IACH,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB;;;OAGG;IACH,cAAc,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,eAAe,EAAE,MAAM,CAAA;CACxB"}

package/dist/src/audit/namespace-audit.types.js

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Shared namespace-audit type vocabulary (SMI-4588 Wave 2 Step 1, PR #1).
+ * @module @skillsmith/mcp-server/audit/namespace-audit.types
+ *
+ * `NamespaceWarning` and `PendingCollision` live here — not in
+ * `tools/install.types.ts` and not in `audit/install-preflight.ts` — to break
+ * the `tools → audit → tools` cycle that would otherwise form between
+ * `install-preflight.ts` (which constructs them) and `install.types.ts`
+ * (which embeds them in `InstallResult`). The shared file is depended on by
+ * both sides; neither side depends on the other.
+ *
+ * Wave 2 plan §4 + Edit 3 — placed in Step 1 so PRs #3/#4 import without
+ * rework.
+ *
+ * `RenameSuggestion` is imported from `./rename-engine.types.js` (PR #2). The
+ * PR #1 forward-declaration shim has been retired now that the canonical
+ * type ships alongside the rename engine.
+ */
+export {};
+//# sourceMappingURL=namespace-audit.types.js.map

package/dist/src/audit/namespace-audit.types.js.map

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

package/dist/src/audit/namespace-overrides.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @fileoverview Atomic reader/writer for the namespace-overrides ledger
+ *               (SMI-4588 Wave 2 Step 1, PR #1).
+ * @module @skillsmith/mcp-server/audit/namespace-overrides
+ *
+ * Persists `~/.skillsmith/namespace-overrides.json` — the load-bearing
+ * artifact that makes consumer-side namespace renames durable across pack
+ * version bumps. Conceptually equivalent to git's `rerere` but for
+ * namespace identifiers.
+ *
+ * Atomicity: every write goes through `<path>.tmp` + `fs.rename`. On read,
+ * a missing file degrades gracefully to an empty ledger; malformed JSON
+ * surfaces as a typed `namespace.ledger.malformed` discriminator (the
+ * caller decides whether to log + reset, never silently). A
+ * higher-than-supported `version` returns
+ * `namespace.ledger.version_unsupported` rather than a silent empty
+ * ledger — see plan §2 Edit 6.
+ *
+ * Concurrent-write boundary: last-write-wins on a single Node event loop
+ * via `<path>.tmp` + `fs.rename`. Multi-process scenarios (two MCP
+ * instances on the same machine) can lose one write under a tight race;
+ * documented as a known limitation in the plan. If multi-process safety
+ * becomes load-bearing, a future revision adds advisory locking via
+ * `proper-lockfile`.
+ */
+import { type OverrideRecord, type OverridesLedger, type ReadLedgerResult } from './namespace-overrides.types.js';
+export interface LedgerPathOptions {
+    /** Override the ledger path (default `~/.skillsmith/namespace-overrides.json`). */
+    ledgerPath?: string;
+}
+/**
+ * Read the ledger from disk and return a tagged union. Missing file →
+ * `{ kind: 'ok', ledger: <empty> }`. Malformed JSON →
+ * `{ kind: 'namespace.ledger.malformed', reason }`. `version > CURRENT_VERSION`
+ * → `{ kind: 'namespace.ledger.version_unsupported', found, expected }`.
+ *
+ * Callers that want the simpler "read or empty" semantics should use
+ * `readLedger()` (below) which collapses the discriminator.
+ */
+export declare function readLedgerResult(opts?: LedgerPathOptions): Promise<ReadLedgerResult>;
+/**
+ * Convenience wrapper: returns the ledger directly, collapsing the
+ * `malformed` branch to an empty ledger plus a `console.warn`. Higher-
+ * version files still bubble a thrown error — silently empty-ing a
+ * higher-version ledger would corrupt forward-compat (plan §2 Edit 6).
+ *
+ * For callers that need the typed discriminator, use `readLedgerResult`.
+ */
+export declare function readLedger(opts?: LedgerPathOptions): Promise<OverridesLedger>;
+/**
+ * Write the ledger atomically: `<path>.tmp` + `fs.rename`. Creates the
+ * parent directory on first run with `recursive: true` (mirrors
+ * audit-history.ts E-MISS-2 fix).
+ */
+export declare function writeLedger(ledger: OverridesLedger, opts?: LedgerPathOptions): Promise<void>;
+/**
+ * Pure helper: append a new override to a ledger and return a new copy.
+ * Original ledger is not mutated. The caller is responsible for
+ * persisting the result via `writeLedger` (separation of concerns —
+ * tests can build ledgers without touching disk).
+ *
+ * Idempotency: if an override with the same
+ * `(skillId, kind, originalIdentifier, renamedTo)` quadruple already
+ * exists, the input is returned unchanged. The caller can detect the
+ * no-op by reference equality (`appended === ledger`).
+ */
+export declare function appendOverride(ledger: OverridesLedger, override: Omit<OverrideRecord, 'id' | 'appliedAt'>): OverridesLedger;
+/**
+ * Pure lookup: find an override by `(skillId, kind, originalIdentifier)`.
+ * `skillId` may be omitted for local/unregistered artifacts; in that case
+ * only `kind` + `originalIdentifier` are matched. Returns the first match
+ * or `null`.
+ */
+export declare function findOverride(ledger: OverridesLedger, query: {
+    skillId?: string | null;
+    kind?: OverrideRecord['kind'];
+    originalIdentifier: string;
+}): OverrideRecord | null;
+//# sourceMappingURL=namespace-overrides.d.ts.map

package/dist/src/audit/namespace-overrides.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespace-overrides.d.ts","sourceRoot":"","sources":["../../../src/audit/namespace-overrides.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AASH,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,gCAAgC,CAAA;AAgBvC,MAAM,WAAW,iBAAiB;IAChC,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAUD;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CA6D9F;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,IAAI,GAAE,iBAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CA0BvF;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,eAAe,EACvB,IAAI,GAAE,iBAAsB,GAC3B,OAAO,CAAC,IAAI,CAAC,CA4Bf;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,eAAe,EACvB,QAAQ,EAAE,IAAI,CAAC,cAAc,EAAE,IAAI,GAAG,WAAW,CAAC,GACjD,eAAe,CAkBjB;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,MAAM,EAAE,eAAe,EACvB,KAAK,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,IAAI,CAAC,EAAE,cAAc,CAAC,MAAM,CAAC,CAAC;IAAC,kBAAkB,EAAE,MAAM,CAAA;CAAE,GAC5F,cAAc,GAAG,IAAI,CAQvB"}