ms-ai-architect/scripts/kb-eval/lib/skill-ops.mjs

// skill-ops.mjs — Spor B / B3: skill-lifecycle operation PLANNERS (lag-4-analog
// at skill granularity). The pure core APPLIES NOTHING and reads no disk: it
// returns { entry, diff, guardrail }. The operator gate (decisions.json) records
// the PENDING entry; a later approved apply-session performs any skills/ mutation.
//
// Sesjon 16 ships merge_skills only (operator priority). sanitize/retire/create
// follow in S17+ as further planners that emit the same kind of gated entry.
//
// Inherited arkitektur-invariant: detection/verification/transformation never
// write to skills/ directly — only via the ledger after the operator gate.
// Destructive ops carry mandatory guardrails that PROVE curated value is
// preserved (ref-file count-invariant + set-equality) and refuse (ok=false)
// when two reference files would clobber on the same target path.

import { readdirSync, readFileSync, existsSync, statSync } from 'node:fs';
import { join, relative, basename, sep } from 'node:path';
import {
  loadDecisions,
  saveDecisions,
  recordAction,
} from '../../kb-update/lib/decisions-io.mjs';

export const MERGE_OPERATION = 'merge_skills';
export const SANITIZE_OPERATION = 'sanitize_skill';
export const RETIRE_OPERATION = 'retire_skill';

// ---------------------------------------------------------------------------
// Pure core — planMergeSkills
// ---------------------------------------------------------------------------

/**
 * Plan a skill merge: `absorbed` is retired into `absorber`. Pure; mutates
 * nothing; reads no disk. Reference identity is the references/-relative path
 * (e.g. "rag-architecture/x.md"): two files sharing that identity across the
 * two skills would clobber on merge — the guardrail catches that and fails.
 *
 * @param {string} absorber  skill that survives and receives all references
 * @param {string} absorbed  skill that is retired; its refs move under absorber
 * @param {{ skillRefs?: Record<string,string[]>, descriptions?: Record<string,string>,
 *           categorySkill?: Record<string,string>, decided_at?: string|null,
 *           note?: string }} [ctx]
 * @returns {{ entry: object, diff: object, guardrail: object }}
 */
export function planMergeSkills(absorber, absorbed, ctx = {}) {
  if (!absorber || !absorbed || absorber === absorbed) {
    throw new Error(`planMergeSkills: cannot merge a skill into itself (${absorber} / ${absorbed})`);
  }
  const skillRefs = ctx.skillRefs ?? {};
  const descriptions = ctx.descriptions ?? {};
  const categorySkill = ctx.categorySkill ?? {};

  const aRefs = skillRefs[absorber] ?? [];
  const bRefs = skillRefs[absorbed] ?? [];
  const aSet = new Set(aRefs);

  // Collision = a references-relative path present under BOTH skills. On merge
  // the absorbed copy would overwrite the absorber copy (or vice versa): a
  // silent loss of curated content. The guardrail must surface and reject it.
  const collisions = [...new Set(bRefs.filter((r) => aSet.has(r)))].sort();

  // Post-merge identity set = union of both ref sets by references-relative path.
  const postSet = new Set([...aRefs, ...bRefs]);
  const expectedPostCount = aRefs.length + bRefs.length; // no-loss target
  const postCount = postSet.size;
  const countInvariant = postCount === expectedPostCount; // holds iff no collision
  const setEquality = [...aSet, ...new Set(bRefs)].every((r) => postSet.has(r)) && collisions.length === 0;

  const guardrail = {
    method:
      'no curated value lost: postSet = union(absorber refs, absorbed refs) by references-relative path. ' +
      'count-invariant = postCount === absorber+absorbed (fails on collision); ' +
      'set-equality = every source ref survives AND no two map to the same target.',
    preCountAbsorber: aRefs.length,
    preCountAbsorbed: bRefs.length,
    expectedPostCount,
    postCount,
    countInvariant,
    setEquality,
    collisions,
    ok: countInvariant && setEquality && collisions.length === 0,
  };

  const fileMoves = bRefs.map((r) => ({
    from: `skills/${absorbed}/references/${r}`,
    to: `skills/${absorber}/references/${r}`,
  }));

  const taxonomyReassignments = Object.keys(categorySkill)
    .filter((category) => categorySkill[category] === absorbed)
    .sort()
    .map((category) => ({ category, from: absorbed, to: absorber }));

  const diff = {
    fileMoves,
    taxonomyReassignments,
    descriptionReconciliation: {
      absorber: descriptions[absorber] ?? null,
      absorbed: descriptions[absorbed] ?? null,
      note: 'Descriptions must be reconciled manually / by judge — the planner does not auto-merge semantic scope.',
    },
    retire: absorbed,
  };

  const entry = {
    operation_type: MERGE_OPERATION,
    status: 'pending',
    decided_at: ctx.decided_at ?? null, // never Date.now() in a pure lib
    targets: { absorber, absorbed },
    guardrail,
    note:
      ctx.note ??
      `Dry-run: merge ${absorbed} -> ${absorber} (${guardrail.ok ? 'guardrail OK' : 'GUARDRAIL FAILED'}). Applies nothing.`,
  };

  return { entry, diff, guardrail };
}

// ---------------------------------------------------------------------------
// Pure core — planSanitizeSkill (remove ONLY dead content)
// ---------------------------------------------------------------------------

/**
 * Plan a skill sanitize: remove dead reference files (kb-integrity orphan /
 * dead-path) and NOTHING else. Pure; mutates nothing; reads no disk. The
 * binding guardrail (mirror of merge's collision rule) is that every removal
 * must be a flagged dead file — a request to remove a CURATED ref fails ok.
 * Dateless-but-curated files are NOT dead and are never removed here.
 *
 * @param {string} skill  skill whose dead content is pruned
 * @param {{ refs?: string[], orphans?: string[], removals?: string[],
 *           decided_at?: string|null, note?: string }} [ctx]
 *   refs      = all references-relative .md paths under the skill
 *   orphans   = references-relative paths kb-integrity flags as orphan/dead
 *   removals  = optional explicit removal list (default = all dead-in-skill)
 * @returns {{ entry: object, diff: object, guardrail: object }}
 */
export function planSanitizeSkill(skill, ctx = {}) {
  if (!skill) throw new Error('planSanitizeSkill: skill is required');
  const refs = ctx.refs ?? [];
  const orphans = ctx.orphans ?? [];
  const refSet = new Set(refs);
  const orphanSet = new Set(orphans);

  // Removable universe = dead files that actually exist under this skill.
  // Default removal = sanitize ALL dead content surfaced by kb-integrity.
  const deadInSkill = [...new Set(orphans.filter((r) => refSet.has(r)))].sort();
  const removals = [...new Set(ctx.removals ?? deadInSkill)].sort();

  // BINDING GUARDRAIL: a removal must be a kb-integrity-flagged dead file AND a
  // real file under the skill. Anything else would delete curated content.
  const illegalRemovals = removals.filter((r) => !orphanSet.has(r)).sort();
  const missingRemovals = removals.filter((r) => !refSet.has(r)).sort();

  const preCount = refs.length;
  const removalCount = removals.length;
  const curatedCount = refs.filter((r) => !orphanSet.has(r)).length;
  const postCount = preCount - removalCount;

  const guardrail = {
    method:
      'only kb-integrity-flagged orphan/dead-path files may be removed; curated refs are never touched. ' +
      'illegalRemovals = requested removals NOT in the dead-set (curated content) — must be empty. ' +
      'missingRemovals = removals absent from disk — must be empty. postCount = preCount - removals.',
    preCount,
    deadCount: deadInSkill.length,
    removalCount,
    curatedCount,
    postCount,
    illegalRemovals,
    missingRemovals,
    ok: illegalRemovals.length === 0 && missingRemovals.length === 0,
  };

  const diff = {
    removals: removals.map((r) => ({
      path: `skills/${skill}/references/${r}`,
      reason: 'orphan/dead-path: basename unreferenced by any agent or SKILL.md (kb-integrity)',
    })),
    retainedCount: curatedCount,
    note: 'Sanitize removes only dead content surfaced by kb-integrity. Curated references (incl. dateless) are preserved untouched.',
  };

  const entry = {
    operation_type: SANITIZE_OPERATION,
    status: 'pending',
    decided_at: ctx.decided_at ?? null, // never Date.now() in a pure lib
    targets: { skill },
    guardrail,
    note:
      ctx.note ??
      `Dry-run: sanitize ${skill} — remove ${removalCount} dead file(s) (${guardrail.ok ? 'guardrail OK' : 'GUARDRAIL FAILED'}). Applies nothing.`,
  };

  return { entry, diff, guardrail };
}

// ---------------------------------------------------------------------------
// Pure core — planRetireSkill (whole-skill retire WITH mandatory archival)
// ---------------------------------------------------------------------------

/**
 * Plan a whole-skill retire: archive every reference file + SKILL.md, then
 * remove the skills/ directory. Pure; mutates nothing; reads no disk. Archival
 * is MANDATORY — the binding guardrail refuses a hard-delete request (ok=false)
 * so curated content is never destroyed without a recoverable copy.
 *
 * @param {string} skill  skill to retire
 * @param {{ refs?: string[], categorySkill?: Record<string,string>,
 *           archiveDir?: string, hardDelete?: boolean,
 *           decided_at?: string|null, note?: string }} [ctx]
 * @returns {{ entry: object, diff: object, guardrail: object }}
 */
export function planRetireSkill(skill, ctx = {}) {
  if (!skill) throw new Error('planRetireSkill: skill is required');
  const refs = ctx.refs ?? [];
  const categorySkill = ctx.categorySkill ?? {};
  const hardDelete = ctx.hardDelete === true;
  // Hard delete is refused -> no archive destination; otherwise default to a
  // recoverable archive path under archive/skills/<skill>.
  const archiveDir = hardDelete ? null : (ctx.archiveDir ?? `archive/skills/${skill}`);

  const archiveMoves = archiveDir
    ? [
        { from: `skills/${skill}/SKILL.md`, to: `${archiveDir}/SKILL.md` },
        ...refs.map((r) => ({
          from: `skills/${skill}/references/${r}`,
          to: `${archiveDir}/references/${r}`,
        })),
      ]
    : [];
  const expectedArchiveCount = refs.length + 1; // refs + SKILL.md
  const archivedCount = archiveMoves.length;

  // Categories this skill owns lose their owner on retire — manual reassignment.
  const taxonomyOrphaned = Object.keys(categorySkill)
    .filter((c) => categorySkill[c] === skill)
    .sort()
    .map((c) => ({ category: c, wasOwner: skill, note: 'owner removed — reassign manually' }));

  const guardrail = {
    method:
      'whole-skill retire requires archival — every reference file + SKILL.md is MOVED to archive/, never hard-deleted. ' +
      'ok iff an archive destination is set AND archivedCount === refCount + 1 (SKILL.md). A hard-delete request is refused.',
    refCount: refs.length,
    expectedArchiveCount,
    archivedCount,
    archiveDir,
    hardDeleteRequested: hardDelete,
    ok: Boolean(archiveDir) && archivedCount === expectedArchiveCount && !hardDelete,
  };

  const diff = {
    archiveMoves,
    removeSkillDir: `skills/${skill}`,
    taxonomyOrphaned,
    note: 'Retire archives the entire skill, then removes its skills/ directory. Categories it owned need manual reassignment.',
  };

  const entry = {
    operation_type: RETIRE_OPERATION,
    status: 'pending',
    decided_at: ctx.decided_at ?? null, // never Date.now() in a pure lib
    targets: { skill },
    guardrail,
    note:
      ctx.note ??
      `Dry-run: retire ${skill} — archive ${expectedArchiveCount} file(s) to ${archiveDir ?? '(none)'} ` +
        `(${guardrail.ok ? 'guardrail OK' : 'GUARDRAIL FAILED — hard delete refused'}). Applies nothing.`,
  };

  return { entry, diff, guardrail };
}

// ---------------------------------------------------------------------------
// Impure shell — read-only disk load + gated ledger write
// ---------------------------------------------------------------------------

/** Recursively list references/-relative .md paths (POSIX separators) under one skill. */
function listSkillRefs(refDir) {
  const out = [];
  if (!existsSync(refDir)) return out;
  const walk = (dir) => {
    for (const e of readdirSync(dir, { withFileTypes: true })) {
      const p = join(dir, e.name);
      if (e.isDirectory()) walk(p);
      else if (e.isFile() && e.name.endsWith('.md')) out.push(relative(refDir, p).split(sep).join('/'));
    }
  };
  walk(refDir);
  return out.sort();
}

/**
 * Read-only: { skill -> [references-relative .md paths] } for every skill dir
 * that has a references/ folder.
 * @param {string} skillsDir absolute path to the skills/ root
 * @returns {Record<string,string[]>}
 */
export function loadSkillRefs(skillsDir) {
  const out = {};
  for (const e of readdirSync(skillsDir, { withFileTypes: true })) {
    if (!e.isDirectory()) continue;
    const refDir = join(skillsDir, e.name, 'references');
    if (existsSync(refDir) && statSync(refDir).isDirectory()) out[e.name] = listSkillRefs(refDir);
  }
  return out;
}

/**
 * Drive a merge dry-run against real disk: load refs read-only, plan the merge,
 * and (only with write:true) record the PENDING entry in decisions.json. Writes
 * NOTHING under skills/ — the destructive apply is a separate approved step.
 * @param {string} absorber
 * @param {string} absorbed
 * @param {{ skillsDir: string, dataDir: string, write?: boolean, decided_at?: string|null,
 *           descriptions?: Record<string,string>, categorySkill?: Record<string,string> }} opts
 * @returns {{ entry: object, diff: object, guardrail: object }}
 */
export function runMergePlan(absorber, absorbed, opts) {
  const { skillsDir, dataDir, write = false, decided_at = null, descriptions, categorySkill } = opts;
  const skillRefs = loadSkillRefs(skillsDir);
  const result = planMergeSkills(absorber, absorbed, { skillRefs, descriptions, categorySkill, decided_at });
  if (write) {
    const ledger = recordAction(loadDecisions(dataDir), result.entry);
    saveDecisions(ledger, dataDir);
  }
  return result;
}

/**
 * Read-only: { skill -> [references-relative dead paths] }. A reference is
 * "dead" iff its basename appears in NO agent file and NO SKILL.md — exactly
 * kb-integrity's orphan semantics (grep -l basename over agents/ + SKILL.md).
 * @param {string} skillsDir absolute path to the skills/ root
 * @param {string} [agentsDir] absolute path to the agents/ dir (optional)
 * @returns {Record<string,string[]>}
 */
export function loadSkillOrphans(skillsDir, agentsDir) {
  const skillRefs = loadSkillRefs(skillsDir);
  // Build the reference haystack: every agent file + every SKILL.md body.
  let haystack = '';
  if (agentsDir && existsSync(agentsDir)) {
    for (const e of readdirSync(agentsDir, { withFileTypes: true })) {
      if (e.isFile() && e.name.endsWith('.md')) haystack += readFileSync(join(agentsDir, e.name), 'utf8') + '\n';
    }
  }
  for (const skill of Object.keys(skillRefs)) {
    const md = join(skillsDir, skill, 'SKILL.md');
    if (existsSync(md)) haystack += readFileSync(md, 'utf8') + '\n';
  }
  const out = {};
  for (const [skill, refs] of Object.entries(skillRefs)) {
    out[skill] = refs.filter((r) => !haystack.includes(basename(r)));
  }
  return out;
}

/**
 * Drive a sanitize dry-run against real disk: load refs + orphans read-only,
 * plan the removal, and (only with write:true) record the PENDING entry in
 * decisions.json. Writes NOTHING under skills/.
 * @param {string} skill
 * @param {{ skillsDir: string, agentsDir?: string, dataDir: string, write?: boolean,
 *           decided_at?: string|null, removals?: string[] }} opts
 * @returns {{ entry: object, diff: object, guardrail: object }}
 */
export function runSanitizePlan(skill, opts) {
  const { skillsDir, agentsDir, dataDir, write = false, decided_at = null, removals } = opts;
  const refs = loadSkillRefs(skillsDir)[skill] ?? [];
  const orphans = loadSkillOrphans(skillsDir, agentsDir)[skill] ?? [];
  const result = planSanitizeSkill(skill, { refs, orphans, removals, decided_at });
  if (write) {
    saveDecisions(recordAction(loadDecisions(dataDir), result.entry), dataDir);
  }
  return result;
}

/**
 * Drive a retire dry-run against real disk: load refs read-only, plan the
 * whole-skill archive+removal, and (only with write:true) record the PENDING
 * entry in decisions.json. Writes NOTHING under skills/.
 * @param {string} skill
 * @param {{ skillsDir: string, dataDir: string, write?: boolean, decided_at?: string|null,
 *           archiveDir?: string, hardDelete?: boolean, categorySkill?: Record<string,string> }} opts
 * @returns {{ entry: object, diff: object, guardrail: object }}
 */
export function runRetirePlan(skill, opts) {
  const { skillsDir, dataDir, write = false, decided_at = null, archiveDir, hardDelete, categorySkill } = opts;
  const refs = loadSkillRefs(skillsDir)[skill] ?? [];
  const result = planRetireSkill(skill, { refs, categorySkill, archiveDir, hardDelete, decided_at });
  if (write) {
    saveDecisions(recordAction(loadDecisions(dataDir), result.entry), dataDir);
  }
  return result;
}