feat(ms-ai-architect): Sesjon 19 — B3 merge-apply (cross-skill + taksonomi-persist) [skip-docs]

Merge-apply = den tyngste destruktive op-en: eksekver en operatør-godkjent
merge_skills-entry → faktisk cross-skill skills/-mutasjon. Tre mekanismer
som sanitize/retire ikke trengte: kuratert relokasjon (ikke arkiv),
taksonomi-persistering, retire-av-absorbert.

- taxonomy.mjs (ny persist): saveTaxonomy (atomisk .tmp+rename, speiler
  saveDecisions) + ren applyCategoryReassignments (repointer KUN der eier
  === from; absent/allerede-flyttet = no-op). Lag-0 er normalt read-only;
  ENESTE writer = gated merge-apply.
- applyApprovedAction merge-gren (skill-ops.mjs): re-plan fersk → revalidér
  (kollisjon → guardrail.ok=false → abort) → flytt absorbed-refs → absorber
  (moveFile; flyttingen ER bevaringen set-equality beviser) → persister
  taksonomi-repoint fra FERSK plan (drift-sikker) → arkivér absorbed-SKILL.md
  FØR rmdir → flipp ledger approved→applied. Description-forsoning forblir
  MANUELL (planner-kontrakt: apply rører aldri absorber-SKILL.md).
  archiveMove→moveFile (generisk: arkiv + kuratert flytt).
- CLI apply-skill-op.mjs merge <absorber> <absorbed> — lookup via actionKey
  (merge_skills:<sortert par>); default PREVIEW, --apply = dobbel-gate.

TDD, tmpdir-fixtures: 0 ekte skills/-mutasjon. Ny test-skill-ops-merge-apply
(7) + 2 taksonomi-tester; fjernet foreldet merge-throws fra S18-fila. Tester:
kb-eval 78→84, kb-update 137→139; validate 239 · kb-integrity 192/192 uendret.
eval --json deterministisk uendret (K10 eng+infra FAIL, øvrige PASS).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-06-20 20:54:13 +02:00
commit de3a9a483b
6 changed files with 434 additions and 55 deletions

View file

@ -2,27 +2,30 @@
// apply-skill-op.mjs — Spor B / B3 (Sesjon 18) CLI: the DESTRUCTIVE apply-path.
//
// Executes an operator-APPROVED (status:approved) skill-lifecycle entry from
// decisions.json into a real skills/ mutation. Single-skill ops only this
// session: sanitize_skill + retire_skill (merge_skills is staged to S19).
// decisions.json into a real skills/ mutation: sanitize_skill + retire_skill
// (single-skill, S18) and merge_skills (cross-skill, S19). create_skill comes last.
//
// Two gates, in order: (1) the entry must already be status:approved in the
// ledger (the operator's sign-off on a prior `plan-skill-op … --write` dry-run);
// (2) this CLI mutates skills/ ONLY with --apply. Without --apply it is a PREVIEW
// that re-plans from fresh disk, revalidates (drift-safe), and mutates nothing.
//
// Apply archives every file under archive/ BEFORE removing it, then flips the
// ledger entry approved -> applied. Verify before/after: `git status`.
// sanitize/retire archive every file under archive/ BEFORE removing it. merge
// RELOCATES the absorbed skill's references under the absorber, persists the
// taxonomy ownership repoint, then archives the absorbed SKILL.md + removes its
// dir. Apply flips the ledger entry approved -> applied. Verify: `git status`.
//
// Usage:
// node scripts/kb-eval/apply-skill-op.mjs list
// node scripts/kb-eval/apply-skill-op.mjs sanitize <skill> [--apply] [--date YYYY-MM-DD]
// node scripts/kb-eval/apply-skill-op.mjs retire <skill> [--apply] [--date YYYY-MM-DD]
// node scripts/kb-eval/apply-skill-op.mjs merge <absorber> <absorbed> [--apply] [--date YYYY-MM-DD]
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { loadTaxonomy } from '../kb-update/lib/taxonomy.mjs';
import { loadDecisions, listActions, actionKey } from '../kb-update/lib/decisions-io.mjs';
import { applyApprovedAction, SANITIZE_OPERATION, RETIRE_OPERATION } from './lib/skill-ops.mjs';
import { applyApprovedAction, SANITIZE_OPERATION, RETIRE_OPERATION, MERGE_OPERATION } from './lib/skill-ops.mjs';
const __dirname = dirname(fileURLToPath(import.meta.url));
const PLUGIN_ROOT = join(__dirname, '..', '..');
@ -30,13 +33,14 @@ const SKILLS_DIR = join(PLUGIN_ROOT, 'skills');
const AGENTS_DIR = join(PLUGIN_ROOT, 'agents');
const LEDGER_DATA_DIR = join(__dirname, '..', 'kb-update', 'data');
const OP_BY_VERB = { sanitize: SANITIZE_OPERATION, retire: RETIRE_OPERATION };
const OP_BY_VERB = { sanitize: SANITIZE_OPERATION, retire: RETIRE_OPERATION, merge: MERGE_OPERATION };
const USAGE =
'Usage:\n' +
' node scripts/kb-eval/apply-skill-op.mjs list\n' +
' node scripts/kb-eval/apply-skill-op.mjs sanitize <skill> [--apply] [--date YYYY-MM-DD]\n' +
' node scripts/kb-eval/apply-skill-op.mjs retire <skill> [--apply] [--date YYYY-MM-DD]';
' node scripts/kb-eval/apply-skill-op.mjs retire <skill> [--apply] [--date YYYY-MM-DD]\n' +
' node scripts/kb-eval/apply-skill-op.mjs merge <absorber> <absorbed> [--apply] [--date YYYY-MM-DD]';
/** List approved actions awaiting apply (operator's apply queue). */
function listApproved() {
@ -54,24 +58,38 @@ function listApproved() {
console.log('');
}
function printResult(res, verb, skill, apply) {
function printResult(res, verb, label, apply) {
const r = res.revalidate;
console.log(`\n${verb}_skill${apply ? 'APPLY' : 'PREVIEW'}: ${skill}\n`);
console.log(`\n${verb}${apply ? 'APPLY' : 'PREVIEW'}: ${label}\n`);
console.log(`Revalidering (mot fersk disk):`);
console.log(` fersk-guardrail-ok=${r.freshOk} drift=${r.drift} => ${r.ok ? 'OK' : 'BLOKKERT'}`);
if (r.reason) console.log(` grunn: ${r.reason}`);
if (!res.applied) {
if (res.preview && r.ok) {
const d = res.plan?.diff ?? {};
const n = verb === 'sanitize' ? (d.removals?.length ?? 0) : (d.archiveMoves?.length ?? 0);
console.log(`\n Ville arkivert+fjernet ${n} fil(er). Kjør på nytt med --apply for å eksekvere.`);
if (verb === 'merge') {
console.log(
`\n Ville flyttet ${d.fileMoves?.length ?? 0} ref-fil(er) -> absorber, reassignet ` +
`${d.taxonomyReassignments?.length ?? 0} kategori(er), arkivert absorbed-SKILL.md. ` +
`Kjør på nytt med --apply for å eksekvere.`,
);
} else {
const n = verb === 'sanitize' ? (d.removals?.length ?? 0) : (d.archiveMoves?.length ?? 0);
console.log(`\n Ville arkivert+fjernet ${n} fil(er). Kjør på nytt med --apply for å eksekvere.`);
}
}
console.log(`\nStatus: INGEN mutasjon utført.${res.preview && r.ok ? '' : ' (revalidering blokkerte eller ingen --apply.)'}\n`);
return;
}
const rep = res.report;
console.log(`\nUtført:`);
console.log(` arkivert: ${rep.moves} fil(er) -> archive/`);
if (rep.op === MERGE_OPERATION) {
console.log(` flyttet: ${rep.refMoves} ref-fil(er) -> absorber`);
console.log(` taksonomi: ${rep.taxonomyReassignments} kategori(er) reassignet + persistert`);
if (rep.archivedSkillMd) console.log(` arkivert: ${rep.archivedSkillMd}`);
} else {
console.log(` arkivert: ${rep.moves} fil(er) -> archive/`);
}
if (rep.removedDir) console.log(` fjernet katalog: ${rep.removedDir}`);
console.log(` ledger: ${actionKey({ operation_type: rep.op, targets: rep.target })} -> ${rep.ledgerStatus}`);
console.log(`\nStatus: APPLIED. Verifiser med 'git status' og re-kjør validate/kb-integrity/kb-eval.\n`);
@ -88,14 +106,31 @@ function main() {
const decided_at = dateIdx >= 0 ? args[dateIdx + 1] : new Date().toISOString().slice(0, 10);
const op = OP_BY_VERB[verb];
if (!op || positional.length < 2) {
if (!op) {
console.error(USAGE);
process.exit(2);
}
const skill = positional[1];
// Resolve targets + ledger key per op arity (merge takes two skills).
let targets, label;
if (op === MERGE_OPERATION) {
if (positional.length < 3) {
console.error(USAGE);
process.exit(2);
}
targets = { absorber: positional[1], absorbed: positional[2] };
label = `${targets.absorbed} -> ${targets.absorber}`;
} else {
if (positional.length < 2) {
console.error(USAGE);
process.exit(2);
}
targets = { skill: positional[1] };
label = positional[1];
}
const key = actionKey({ operation_type: op, targets });
const led = loadDecisions(LEDGER_DATA_DIR);
const key = `${op}:${skill}`;
const entry = led.actions?.[key];
if (!entry) {
console.error(`Fant ingen ledger-handling "${key}". Kjør 'apply-skill-op.mjs list' for å se godkjente.`);
@ -106,16 +141,19 @@ function main() {
process.exit(1);
}
// retire + merge both consult the taxonomy (owned-category awareness / repoint).
const needsTaxonomy = op === RETIRE_OPERATION || op === MERGE_OPERATION;
const res = applyApprovedAction(entry, {
pluginRoot: PLUGIN_ROOT,
skillsDir: SKILLS_DIR,
agentsDir: AGENTS_DIR,
dataDir: LEDGER_DATA_DIR,
taxonomyDataDir: LEDGER_DATA_DIR,
apply,
decided_at: apply ? decided_at : null,
categorySkill: op === RETIRE_OPERATION ? loadTaxonomy(LEDGER_DATA_DIR).category_skill : undefined,
categorySkill: needsTaxonomy ? loadTaxonomy(LEDGER_DATA_DIR).category_skill : undefined,
});
printResult(res, verb, skill, apply);
printResult(res, verb, label, apply);
}
if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {

View file

@ -22,6 +22,7 @@ import {
actionKey,
setActionStatus,
} from '../../kb-update/lib/decisions-io.mjs';
import { loadTaxonomy, saveTaxonomy, applyCategoryReassignments } from '../../kb-update/lib/taxonomy.mjs';
export const MERGE_OPERATION = 'merge_skills';
export const SANITIZE_OPERATION = 'sanitize_skill';
@ -398,16 +399,23 @@ export function runRetirePlan(skill, opts) {
}
// ===========================================================================
// Apply-path (Sesjon 18) — the DESTRUCTIVE frontier. An operator-approved
// ledger entry is executed into a real skills/ mutation. Single-skill ops only
// (sanitize/retire); merge-apply is staged to S19 (needs taxonomy persistence).
// Apply-path (Sesjon 1819) — the DESTRUCTIVE frontier. An operator-approved
// ledger entry is executed into a real skills/ mutation. Single-skill ops
// (sanitize/retire) shipped in S18; merge-apply (cross-skill, the heaviest op)
// in S19. create_skill (dvelende) comes last.
//
// Invariants:
// - Idempotent revalidation: re-plan from FRESH disk and refuse unless the
// fresh guardrail is ok AND deep-equals the approved snapshot (no drift).
// - Archive BEFORE delete: every removal is a rename skills/… -> archive/…,
// which moves (archives) and removes atomically; retire then rmdir's the
// - Archive BEFORE delete: a removal is a rename skills/… -> archive/…, which
// moves (archives) and removes atomically; retire/merge then rmdir the
// emptied skill directory last.
// - Merge preserves curated value by RELOCATION, not archival: the absorbed
// skill's references move under the absorber (the guardrail's set-equality
// made real on disk), the taxonomy's category ownership is repointed +
// persisted, and only the now-empty absorbed shell (SKILL.md) is archived.
// Description reconciliation stays MANUAL (planner contract): merge-apply
// never edits the absorber's SKILL.md.
// ===========================================================================
/**
@ -433,37 +441,48 @@ export function revalidateApply(approvedEntry, freshResult) {
return { ok: reasons.length === 0, drift, freshOk, reason: reasons.length ? reasons.join('; ') : null };
}
/** Archive a single file: mkdir -p the destination dir, then rename (atomic move). */
function archiveMove(absFrom, absTo) {
/** Move a single file: mkdir -p the destination dir, then rename (atomic). Used
* both for archival (skills/ -> archive/) and curated relocation (merge). */
function moveFile(absFrom, absTo) {
mkdirSync(dirname(absTo), { recursive: true });
renameSync(absFrom, absTo);
}
/**
* Execute an operator-approved single-skill op into a real skills/ mutation.
* Execute an operator-approved skill-lifecycle op into a real skills/ mutation.
* Re-plans from fresh disk, revalidates (drift-safe), and only with apply:true
* performs the move(s) archiving every file under archive/ BEFORE removing it,
* then (retire) removing the emptied skill dir. On success the ledger entry is
* mutates. Single-skill ops (sanitize/retire) archive every file under archive/
* BEFORE removing it, then (retire) drop the emptied skill dir. merge_skills
* RELOCATES the absorbed skill's references under the absorber (preservation),
* persists the taxonomy's category-ownership reassignment, then archives the
* absorbed shell (SKILL.md) + removes its dir. On success the ledger entry is
* flipped approved -> applied. apply:false is a preview that mutates nothing.
*
* @param {object} approvedEntry ledger entry with status:'approved'
* @param {{ pluginRoot: string, skillsDir: string, agentsDir?: string, dataDir: string,
* apply?: boolean, decided_at?: string|null, categorySkill?: Record<string,string> }} opts
* taxonomyDataDir?: string, apply?: boolean, decided_at?: string|null,
* categorySkill?: Record<string,string> }} opts
* taxonomyDataDir where domain-taxonomy.json lives (merge persist); defaults to dataDir.
* @returns {{ applied: boolean, preview?: boolean, revalidate: object, plan?: object, report?: object }}
*/
export function applyApprovedAction(approvedEntry, opts) {
const { pluginRoot, skillsDir, agentsDir, dataDir, apply = false, decided_at = null, categorySkill } = opts;
const {
pluginRoot, skillsDir, agentsDir, dataDir, taxonomyDataDir,
apply = false, decided_at = null, categorySkill,
} = opts;
const op = approvedEntry?.operation_type;
const target = approvedEntry?.targets ?? {};
// 1. Re-plan from fresh disk (read-only) for the supported single-skill ops.
// 1. Re-plan from fresh disk (read-only) for the supported ops.
let fresh;
if (op === SANITIZE_OPERATION) {
fresh = runSanitizePlan(target.skill, { skillsDir, agentsDir, dataDir, write: false });
} else if (op === RETIRE_OPERATION) {
fresh = runRetirePlan(target.skill, { skillsDir, dataDir, write: false, categorySkill });
} else if (op === MERGE_OPERATION) {
fresh = runMergePlan(target.absorber, target.absorbed, { skillsDir, dataDir, write: false, categorySkill });
} else {
throw new Error(`applyApprovedAction: unsupported operation_type "${op}" — S18 applies sanitize/retire only (merge staged to S19)`);
throw new Error(`applyApprovedAction: unsupported operation_type "${op}" — applies sanitize/retire/merge only (create_skill staged later)`);
}
// 2. Idempotent revalidation against fresh disk — refuse on any failure.
@ -472,16 +491,52 @@ export function applyApprovedAction(approvedEntry, opts) {
return { applied: false, preview: !apply, revalidate, plan: fresh };
}
// 3. Build the move list (archive destination = archive/ + repo-relative path).
// 3a. merge — curated RELOCATION (not archival) + taxonomy persist + shell archive.
if (op === MERGE_OPERATION) {
const { absorber, absorbed } = target;
// Relocate every absorbed reference under the absorber — the move IS the
// preservation the guardrail's set-equality proved.
for (const m of fresh.diff.fileMoves) moveFile(join(pluginRoot, m.from), join(pluginRoot, m.to));
// Persist taxonomy ownership repoint (absorbed -> absorber). Reassignments
// come from the FRESH plan, so this stays drift-safe by construction.
const taxDir = taxonomyDataDir ?? dataDir;
const reassignments = fresh.diff.taxonomyReassignments;
if (reassignments.length) {
saveTaxonomy(applyCategoryReassignments(loadTaxonomy(taxDir), reassignments), taxDir);
}
// Archive the now-empty absorbed shell (SKILL.md) BEFORE removing its dir.
let archivedSkillMd = null;
if (existsSync(join(pluginRoot, `skills/${absorbed}/SKILL.md`))) {
archivedSkillMd = `archive/skills/${absorbed}/SKILL.md`;
moveFile(join(pluginRoot, `skills/${absorbed}/SKILL.md`), join(pluginRoot, archivedSkillMd));
}
const removedDir = `skills/${absorbed}`;
rmSync(join(pluginRoot, removedDir), { recursive: true, force: true });
// Flip the ledger entry approved -> applied (gated write; audit record kept).
saveDecisions(setActionStatus(loadDecisions(dataDir), actionKey(approvedEntry), 'applied', decided_at), dataDir);
return {
applied: true,
revalidate,
report: {
op, target,
refMoves: fresh.diff.fileMoves.length,
taxonomyReassignments: reassignments.length,
archivedSkillMd,
removedDir,
ledgerStatus: 'applied',
},
};
}
// 3b. sanitize/retire — archive (rename) every file FIRST, then (retire) drop the dir.
const moves =
op === SANITIZE_OPERATION
? fresh.diff.removals.map((r) => ({ from: r.path, to: join('archive', r.path) }))
: fresh.diff.archiveMoves.map((m) => ({ from: m.from, to: m.to }));
// 4. Execute: archive (rename) every file FIRST, then (retire) drop the dir.
const archived = [];
for (const m of moves) {
archiveMove(join(pluginRoot, m.from), join(pluginRoot, m.to));
moveFile(join(pluginRoot, m.from), join(pluginRoot, m.to));
archived.push(m.to);
}
let removedDir = null;
@ -490,7 +545,7 @@ export function applyApprovedAction(approvedEntry, opts) {
rmSync(join(pluginRoot, removedDir), { recursive: true, force: true });
}
// 5. Flip the ledger entry approved -> applied (gated write; audit record kept).
// Flip the ledger entry approved -> applied (gated write; audit record kept).
const key = actionKey(approvedEntry);
saveDecisions(setActionStatus(loadDecisions(dataDir), key, 'applied', decided_at), dataDir);

View file

@ -4,7 +4,7 @@
// skill/category owns content, and update priority. poll-sitemaps,
// discover-new-urls and report-changes READ this instead of embedding copies.
import { readFileSync } from 'node:fs';
import { readFileSync, writeFileSync, renameSync, existsSync, mkdirSync } from 'node:fs';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
@ -21,6 +21,41 @@ export function loadTaxonomy(dataDir = DEFAULT_DATA_DIR) {
return JSON.parse(readFileSync(path, 'utf8'));
}
/**
* Save the domain taxonomy atomically (write to .tmp, then rename) mirrors
* saveDecisions. The taxonomy is lag-0 truth and is normally read-only; the ONE
* writer is the gated merge-apply path (Sesjon 19), which repoints category
* ownership from an absorbed skill to its absorber. Detection scripts must NOT
* import this.
* @param {object} tax taxonomy object to persist
* @param {string} [dataDir]
*/
export function saveTaxonomy(tax, dataDir = DEFAULT_DATA_DIR) {
if (!existsSync(dataDir)) mkdirSync(dataDir, { recursive: true });
const path = join(dataDir, 'domain-taxonomy.json');
const tmp = path + '.tmp';
writeFileSync(tmp, JSON.stringify(tax, null, 2) + '\n', 'utf8');
renameSync(tmp, path);
}
/**
* Repoint category ownership for a skill merge. Pure returns a new taxonomy,
* mutates nothing. For each { category, from, to }, the category's owner is
* changed to `to` ONLY when it currently equals `from` (defensive: a category
* already repointed, or absent, is a no-op never clobbered). All other fields
* survive untouched.
* @param {object} tax
* @param {Array<{category: string, from: string, to: string}>} reassignments
* @returns {object} new taxonomy
*/
export function applyCategoryReassignments(tax, reassignments) {
const next = { ...tax.category_skill };
for (const { category, from, to } of reassignments) {
if (next[category] === from) next[category] = to;
}
return { ...tax, category_skill: next };
}
/**
* Target sitemap child-name prefixes to scan/poll.
* @param {object} tax