feat(ms-ai-architect): Sesjon 16 — B3 ledger action-lag + merge_skills dry-run-planner
Spor B / B3 start. Operatør-gated dry-run for skill-livssyklus, merge først.
- decisions-io.mjs: additivt skill-nøklet `actions`-lag ved siden av urørt
URL-nøklet `decisions` (14 URL-tester urørt = regresjonsbevis). version=1,
loadDecisions backfiller manglende actions-nøkkel. Nye rene fn: actionKey
(merge symmetrisk på paret), isActionDecided, recordAction (no-mutate),
listActions. Policy A gjelder også actions.
- scripts/kb-eval/lib/skill-ops.mjs: ren planMergeSkills → {entry,diff,guardrail},
leser ingen disk, anvender INGENTING. Guardrail = ingen kuratert verdi tapt
(count-invariant + set-equality + kollisjons-deteksjon; ok=false ved klobring).
Impur skall loadSkillRefs/runMergePlan + CLI plan-skill-op.mjs (gated --write).
- Ekte eng↔infra dry-run: guardrail OK (34+153=187, 0 kollisjoner), 153 fil-flytt
+ 7 taksonomi-reassign + retire eng; 0 skriving til skills/, ledger uendret
(retning er operatør/judge-valg, ikke pushet gjennom gaten).
- TDD: test-decisions-actions (10) + test-skill-ops-merge (10, inkl. byte-for-byte
skills/-snapshot som no-write-bevis). kb-eval 40→50, kb-update 122→132.
Regresjon grønn: validate 239, kb-integrity 192/192.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
parent
ba597eb988
commit
f03a0e08b2
5 changed files with 672 additions and 4 deletions
170
scripts/kb-eval/lib/skill-ops.mjs
Normal file
170
scripts/kb-eval/lib/skill-ops.mjs
Normal file
|
|
@ -0,0 +1,170 @@
|
|||
// 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, existsSync, statSync } from 'node:fs';
|
||||
import { join, relative, sep } from 'node:path';
|
||||
import {
|
||||
loadDecisions,
|
||||
saveDecisions,
|
||||
recordAction,
|
||||
} from '../../kb-update/lib/decisions-io.mjs';
|
||||
|
||||
export const MERGE_OPERATION = 'merge_skills';
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 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 };
|
||||
}
|
||||
|
||||
// ---------------------------------------------------------------------------
|
||||
// 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;
|
||||
}
|
||||
94
scripts/kb-eval/plan-skill-op.mjs
Normal file
94
scripts/kb-eval/plan-skill-op.mjs
Normal file
|
|
@ -0,0 +1,94 @@
|
|||
#!/usr/bin/env node
|
||||
// plan-skill-op.mjs — Spor B / B3 CLI: GATED DRY-RUN for skill-lifecycle ops.
|
||||
//
|
||||
// Sesjon 16 ships merge_skills. The dry-run loads refs/descriptions/taxonomy
|
||||
// READ-ONLY, plans the merge, prints the full diff + guardrail, and with
|
||||
// --write records a PENDING entry in decisions.json (the operator gate's queue).
|
||||
// It NEVER writes under skills/ — the destructive apply is a separate approved
|
||||
// step. Verify after a run: `git status skills/` must be clean.
|
||||
//
|
||||
// Usage:
|
||||
// node scripts/kb-eval/plan-skill-op.mjs merge <absorber> <absorbed>
|
||||
// node scripts/kb-eval/plan-skill-op.mjs merge <absorber> <absorbed> --json
|
||||
// node scripts/kb-eval/plan-skill-op.mjs merge <absorber> <absorbed> --write [--date YYYY-MM-DD]
|
||||
|
||||
import { readFileSync, readdirSync, existsSync } from 'node:fs';
|
||||
import { join, dirname } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { splitFrontmatter, extractDescription } from './eval.mjs';
|
||||
import { loadTaxonomy } from '../kb-update/lib/taxonomy.mjs';
|
||||
import { runMergePlan } from './lib/skill-ops.mjs';
|
||||
|
||||
const __dirname = dirname(fileURLToPath(import.meta.url));
|
||||
const PLUGIN_ROOT = join(__dirname, '..', '..');
|
||||
const SKILLS_DIR = join(PLUGIN_ROOT, 'skills');
|
||||
const LEDGER_DATA_DIR = join(__dirname, '..', 'kb-update', 'data');
|
||||
const TAX_DATA_DIR = LEDGER_DATA_DIR;
|
||||
|
||||
/** Read the SKILL.md descriptions from disk (read-only). */
|
||||
function loadDescriptions() {
|
||||
const out = {};
|
||||
for (const e of readdirSync(SKILLS_DIR, { withFileTypes: true })) {
|
||||
if (!e.isDirectory()) continue;
|
||||
const md = join(SKILLS_DIR, e.name, 'SKILL.md');
|
||||
if (!existsSync(md)) continue;
|
||||
out[e.name] = extractDescription(splitFrontmatter(readFileSync(md, 'utf8')).frontmatter);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
function printPlan({ entry, diff, guardrail }) {
|
||||
const g = guardrail;
|
||||
console.log(`\nmerge_skills — DRY-RUN: ${entry.targets.absorbed} -> ${entry.targets.absorber}\n`);
|
||||
console.log(`Guardrail (ingen kuratert verdi tapt):`);
|
||||
console.log(` absorber-refs=${g.preCountAbsorber} absorbed-refs=${g.preCountAbsorbed} forventet post=${g.expectedPostCount} faktisk post=${g.postCount}`);
|
||||
console.log(` count-invariant=${g.countInvariant} set-equality=${g.setEquality} kollisjoner=${g.collisions.length ? g.collisions.join(', ') : '0'}`);
|
||||
console.log(` => ${g.ok ? 'OK (trygt å merge)' : 'FAILED (ville tapt/klobret innhold — blokkert)'}\n`);
|
||||
console.log(`Diff:`);
|
||||
console.log(` fil-flytt: ${diff.fileMoves.length} (alle ${entry.targets.absorbed}/references/* -> ${entry.targets.absorber}/references/*)`);
|
||||
if (diff.taxonomyReassignments.length) {
|
||||
console.log(` taksonomi-reassign:`);
|
||||
for (const t of diff.taxonomyReassignments) console.log(` • ${t.category}: ${t.from} -> ${t.to}`);
|
||||
}
|
||||
console.log(` retire: ${diff.retire}`);
|
||||
console.log(` description-reconciliation: MANUELL (planner auto-merger aldri semantisk scope)`);
|
||||
console.log(` ${entry.targets.absorber}: ${diff.descriptionReconciliation.absorber?.slice(0, 80) ?? '(mangler)'}…`);
|
||||
console.log(` ${entry.targets.absorbed}: ${diff.descriptionReconciliation.absorbed?.slice(0, 80) ?? '(mangler)'}…\n`);
|
||||
console.log(`Status: ${entry.status} (forslag — anvender INGENTING; krever operatør-godkjenning + apply-sesjon).\n`);
|
||||
}
|
||||
|
||||
function main() {
|
||||
const args = process.argv.slice(2);
|
||||
const op = args[0];
|
||||
const positional = args.filter((a) => !a.startsWith('--'));
|
||||
const jsonOut = args.includes('--json');
|
||||
const doWrite = args.includes('--write');
|
||||
const dateIdx = args.indexOf('--date');
|
||||
const decided_at = doWrite ? (dateIdx >= 0 ? args[dateIdx + 1] : new Date().toISOString().slice(0, 10)) : null;
|
||||
|
||||
if (op !== 'merge' || positional.length < 3) {
|
||||
console.error('Usage: node scripts/kb-eval/plan-skill-op.mjs merge <absorber> <absorbed> [--json] [--write [--date YYYY-MM-DD]]');
|
||||
process.exit(2);
|
||||
}
|
||||
const [, absorber, absorbed] = positional;
|
||||
|
||||
const result = runMergePlan(absorber, absorbed, {
|
||||
skillsDir: SKILLS_DIR,
|
||||
dataDir: LEDGER_DATA_DIR,
|
||||
write: doWrite,
|
||||
decided_at,
|
||||
descriptions: loadDescriptions(),
|
||||
categorySkill: loadTaxonomy(TAX_DATA_DIR).category_skill,
|
||||
});
|
||||
|
||||
if (jsonOut) {
|
||||
process.stdout.write(JSON.stringify(result) + '\n');
|
||||
return;
|
||||
}
|
||||
printPlan(result);
|
||||
if (doWrite) console.log(`(Pending merge_skills-entry skrevet til decisions.json — 0 skriving til skills/.)\n`);
|
||||
}
|
||||
|
||||
if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
|
||||
main();
|
||||
}
|
||||
Loading…
Add table
Add a link
Reference in a new issue