workflow-toolkit 1.0.1

package/scripts/installer/engine.js

@@ -0,0 +1,254 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { TextDecoder } from 'node:util';
+
+export const WORKFLOW_VERSION = '1.0.1';
+export const LAYERS = ['core', 'quality', 'extras'];
+export const DEPENDENCIES = { core: [], quality: ['core'], extras: ['core'] };
+export const BLOCK_LAYERS = ['core', 'quality'];
+export const WORKFLOW_GITIGNORE_ENTRIES = ['.wtk.toml', '.claude/agents/', '.codex/agents/', '.cursor/agents/', '!.wtk-deep-review/', '.wtk-deep-review/*', '!.wtk-deep-review/learnings.md', 'graft/', 'graphify-out/', '.repository-intelligence/'];
+export const LEGACY_WORKFLOW_GITIGNORE_ENTRIES = ['.specs/features/', '!.deep-review/', '.deep-review/*', '!.deep-review/learnings.md'];
+export const WORKFLOW_SEARCHIGNORE_ENTRIES = ['!graft/', 'graft/.cache/', 'graft/.graph/', 'graphify-out/', '.repository-intelligence/'];
+export const RUNTIME_PATHS = ['claude', 'codex', 'cursor'].flatMap((provider) => ['planner', 'implementer', 'verifier', 'explorer', 'deep-reviewer', 'designer'].map((role) => `.${provider}/agents/${role}.${provider === 'codex' ? 'toml' : 'md'}`));
+export const KNOWLEDGE_DESTINATIONS = {
+  'AGENTS.md': { destination: 'docs/product/AGENT-CONTEXT.md', reason: 'Consumer-authored instructions require manual review.' },
+  'CLAUDE.md': { destination: 'docs/product/AGENT-CONTEXT.md', reason: 'Consumer-authored instructions require manual review.' },
+  'knowledge/AGENTS.md': { destination: 'knowledge/wiki/index.md', reason: 'Consumer-authored knowledge requires manual review.' },
+  'knowledge/raw/README.md': { destination: 'knowledge/wiki/research/index.md', reason: 'Consumer-authored knowledge requires manual review.' },
+};
+
+export const LAYER_PATHS = {
+  core: ['docs/toolkit/guidelines', 'docs/toolkit/README.md', 'docs/toolkit/repository-intelligence.md', 'docs/toolkit/decisions.md', 'docs/toolkit/guidelines.md', 'docs/toolkit/loop.md', 'docs/toolkit/purpose.md', 'docs/toolkit/reviews.md', 'knowledge/AGENTS.md', 'knowledge/raw/README.md', '.agents/skills/wtk', '.agents/skills/wtk-lean', '.agents/skills/wtk-discover', '.agents/skills/wtk-plan', '.agents/skills/wtk-implement', '.agents/skills/wtk-config', '.agents/skills/wtk-knowledge-check', '.agents/skills/wtk-ship', '.agents/skills/ponytail'],
+  quality: ['.agents/skills/wtk-deep-review', '.agents/skills/wtk-qa', '.agents/skills/wtk-qa-plan', '.agents/skills/wtk-qa-execute'],
+  extras: ['.agents/skills/ponytail-audit', '.agents/skills/ponytail-debt', '.agents/skills/ponytail-gain', '.agents/skills/ponytail-help', '.agents/skills/ponytail-review', '.agents/skills/prompt-review'],
+};
+export const CLAUDE_SKILL_LINKS = {
+  core: ['wtk', 'wtk-lean', 'wtk-discover', 'wtk-plan', 'wtk-implement', 'wtk-config', 'wtk-knowledge-check', 'wtk-ship', 'ponytail'],
+  quality: ['wtk-deep-review', 'wtk-qa', 'wtk-qa-plan', 'wtk-qa-execute'],
+  extras: ['ponytail-audit', 'ponytail-debt', 'ponytail-gain', 'ponytail-help', 'ponytail-review', 'prompt-review'],
+};
+export const LAYER_MISSING_PATHS = { core: ['.wtk.toml.example'], quality: [], extras: [] };
+export const CONSUMER_MISSING_SOURCES = {
+  'docs/product/AGENT-CONTEXT.md': 'templates/adoption/product/AGENT-CONTEXT.md',
+  'knowledge/wiki/index.md': 'templates/adoption/knowledge/wiki/index.md',
+  'knowledge/wiki/log.md': 'templates/adoption/knowledge/wiki/log.md',
+  ...Object.fromEntries(['domain', 'product', 'architecture', 'design', 'decisions', 'research', 'open-questions'].map((group) => [`knowledge/wiki/${group}/index.md`, `templates/adoption/knowledge/wiki/${group}/index.md`])),
+};
+export const RETIRABLE_WORKFLOW_DIRS = ['.agents/skills/workflow-spec-driven/', '.agents/skills/workflow-config/', '.agents/skills/wspecify/', '.agents/skills/wdesign/', '.agents/skills/wtasks/', '.agents/skills/wimplement/', '.agents/skills/wverify/', '.agents/skills/wreview/', '.agents/skills/wqa/', '.agents/skills/autonomous/', '.agents/skills/deep-review/', '.agents/skills/qa-plan/', '.agents/skills/qa-execute/', '.agents/skills/ponytail-audit/', '.agents/skills/ponytail-debt/', '.agents/skills/ponytail-gain/', '.agents/skills/ponytail-help/', '.agents/skills/ponytail-review/', '.agents/skills/wtk-verify/', '.agents/skills/wtk-review/', 'docs/guidelines/', 'docs/workflow/', 'templates/agents/', 'templates/adoption/agents/', 'tools/knowledge/src/', 'tools/shared/src/'];
+export const RETIRABLE_WORKFLOW_FILES = ['tools/ad-index.py', 'tools/orca_assisted_probe.py', 'tools/qa_parallel_pilot.py', 'tools/resource_lock.py', 'docs/toolkit/guidelines/GATES.md', 'docs/toolkit/guidelines/VERIFICATION-EVIDENCE.md', 'docs/toolkit/guidelines/TEST-CONTRACT.md', 'docs/toolkit/guidelines/BRANCHING.md', 'docs/toolkit/guidelines/ARTIFACT-LIFECYCLE.md'];
+
+export class InstallerError extends Error {}
+const fail = (message) => { throw new InstallerError(message); };
+const asRoot = (root) => path.resolve(root);
+const posix = (value) => value.split(path.sep).join('/');
+const decodeUtf8 = (value, label) => { try { return new TextDecoder('utf-8', { fatal: true }).decode(value); } catch (error) { fail(`${label} is not valid UTF-8: ${error.message}`); } };
+const semver = (value) => value.split('.').map(Number);
+export const sha256 = (value) => crypto.createHash('sha256').update(value).digest('hex');
+
+export function validateRelative(relative) {
+  if (typeof relative !== 'string' || !relative || path.posix.isAbsolute(relative) || relative.split('/').some((part) => !part || part === '.' || part === '..') || posix(relative) !== relative) fail(`manifest path is unsafe: ${relative}`);
+  return relative;
+}
+
+export function safePath(root, relative, label = 'path') {
+  validateRelative(relative);
+  const base = asRoot(root);
+  const target = path.join(base, ...relative.split('/'));
+  let current = base;
+  for (const part of relative.split('/')) {
+    current = path.join(current, part);
+    if (fs.existsSync(current) && fs.lstatSync(current).isSymbolicLink()) fail(`${label} ${relative} uses symlink ${posix(path.relative(base, current))}`);
+    if (current !== target && fs.existsSync(current) && !fs.lstatSync(current).isDirectory()) fail(`${label} parent ${posix(path.relative(base, current))} must be a directory`);
+  }
+  if (fs.existsSync(target) && !fs.lstatSync(target).isFile()) fail(`${label} ${relative} must be a file`);
+  return target;
+}
+
+function sourceFiles(root, relative) {
+  const source = path.join(root, ...relative.split('/'));
+  if (!fs.existsSync(source)) fail(`workflow source is missing: ${relative}`);
+  const stat = fs.lstatSync(source);
+  if (stat.isSymbolicLink()) fail(`workflow source is a symlink: ${relative}`);
+  if (stat.isFile()) return [relative];
+  const result = [];
+  const walk = (directory) => {
+    for (const entry of fs.readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (entry.name === '__pycache__' || entry.name.endsWith('.pyc')) continue;
+      const full = path.join(directory, entry.name);
+      const rel = posix(path.relative(root, full));
+      if (entry.isSymbolicLink()) fail(`workflow source is a symlink: ${rel}`);
+      if (entry.isDirectory()) walk(full); else if (entry.isFile()) result.push(rel);
+    }
+  };
+  walk(source);
+  return result;
+}
+
+export function resolveModules(values) {
+  const raw = Array.isArray(values) ? values : String(values).split(',');
+  const selected = new Set(raw.map((item) => String(item).trim()).filter(Boolean));
+  if (selected.has('full')) { selected.delete('full'); LAYERS.forEach((item) => selected.add(item)); }
+  const unknown = [...selected].filter((item) => !LAYERS.includes(item));
+  if (unknown.length) fail(`unknown module(s): ${unknown.sort().join(', ')}`);
+  if (!selected.size) fail('select at least one module');
+  let changed = true;
+  while (changed) { changed = false; for (const module of [...selected]) for (const dependency of DEPENDENCIES[module]) if (!selected.has(dependency)) { selected.add(dependency); changed = true; } }
+  return LAYERS.filter((module) => selected.has(module));
+}
+
+export function requestedModules(values) {
+  const raw = Array.isArray(values) ? values : String(values).split(',');
+  const selected = new Set(raw.map((item) => String(item).trim()).filter(Boolean));
+  if (!selected.size || [...selected].some((item) => item !== 'full' && !LAYERS.includes(item)) || (selected.has('full') && selected.size > 1)) fail('modules must be core, quality, extras, or full');
+  return selected.has('full') ? [...LAYERS] : LAYERS.filter((module) => selected.has(module));
+}
+
+function catalog(root, modules) {
+  const entries = new Map();
+  for (const module of modules) for (const item of [...LAYER_PATHS[module], ...LAYER_MISSING_PATHS[module]]) for (const relative of sourceFiles(root, item)) {
+    const prior = entries.get(relative); if (prior && !prior.includes(module)) prior.push(module); else if (!prior) entries.set(relative, [module]);
+  }
+  if (modules.includes('core')) for (const [destination, source] of Object.entries(CONSUMER_MISSING_SOURCES)) { sourceFiles(root, source); entries.set(destination, ['core']); }
+  return entries;
+}
+
+function adoptedBytes(relative, source) { return relative === 'docs/toolkit/README.md' ? Buffer.from(source.toString().split(/(?<=\n)/).filter((line) => !line.includes('(pack.md)')).join('')) : source; }
+
+function emptyManifest() { return { schema: 1, workflow_version: WORKFLOW_VERSION, layers: [], files: {}, blocks: {} }; }
+function validHash(value, label, allowNull = false) { if (allowNull && value === null) return; if (typeof value !== 'string' || !/^[0-9a-f]{64}$/.test(value)) fail(`manifest ${label} must be a lowercase SHA-256 hash`); }
+export function loadManifest(root) {
+  const target = safePath(root, '.my-workflow/adoption.json', 'manifest');
+  if (!fs.existsSync(target)) return emptyManifest();
+  let data; try { data = JSON.parse(decodeUtf8(fs.readFileSync(target), 'adoption manifest')); } catch (error) { fail(`invalid adoption manifest: ${error.message}`); }
+  if (!data || typeof data !== 'object' || Array.isArray(data) || Object.keys(data).sort().join() !== 'blocks,files,layers,schema,workflow_version') fail('adoption manifest has an unsupported schema');
+  if (data.schema !== 1 || typeof data.workflow_version !== 'string' || !/^(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})\.(0|[1-9]\d{0,8})$/.test(data.workflow_version) || semver(data.workflow_version)[0] > semver(WORKFLOW_VERSION)[0] || semver(data.workflow_version)[0] === semver(WORKFLOW_VERSION)[0] && (semver(data.workflow_version)[1] > semver(WORKFLOW_VERSION)[1] || semver(data.workflow_version)[1] === semver(WORKFLOW_VERSION)[1] && semver(data.workflow_version)[2] > semver(WORKFLOW_VERSION)[2])) fail('adoption manifest schema must be version 1; workflow version is newer than the installer');
+  if (!Array.isArray(data.layers) || data.layers.some((module) => !LAYERS.includes(module)) || data.layers.join() !== [...new Set(data.layers)].sort((a, b) => LAYERS.indexOf(a) - LAYERS.indexOf(b)).join()) fail('manifest layers must be unique and catalog-ordered');
+  if (data.layers.length && JSON.stringify(resolveModules(data.layers)) !== JSON.stringify(data.layers)) fail('manifest layers must include every fixed dependency');
+  if (!data.files || typeof data.files !== 'object' || Array.isArray(data.files) || !data.blocks || typeof data.blocks !== 'object' || Array.isArray(data.blocks)) fail('manifest files and blocks must be objects');
+  for (const [relative, record] of Object.entries(data.files)) {
+    validateRelative(relative); if (!record || typeof record !== 'object' || Object.keys(record).sort().join() !== 'installed_sha256,layer,ownership,source_sha256') fail(`manifest file record is invalid: ${relative}`);
+    if (!LAYERS.includes(record.layer) || !['managed', 'consumer'].includes(record.ownership)) fail(`manifest file record has invalid ownership/layer: ${relative}`);
+    validHash(record.source_sha256, `source_sha256 for ${relative}`); if (record.ownership === 'consumer' && record.installed_sha256 !== null) fail(`manifest installed_sha256 for ${relative} must be null for consumer ownership`); validHash(record.installed_sha256, `installed_sha256 for ${relative}`, record.ownership === 'consumer');
+  }
+  for (const [key, record] of Object.entries(data.blocks)) { const [relative, module] = key.split(/:(?=[^:]+$)/); validateRelative(relative); if (!['AGENTS.md', 'CLAUDE.md'].includes(relative) || !BLOCK_LAYERS.includes(module) || !data.layers.includes(module) || (relative === 'CLAUDE.md' && module !== 'core') || !record || Object.keys(record).join() !== 'sha256') fail(`manifest block record is invalid: ${key}`); validHash(record.sha256, `block ${key}`); }
+  return data;
+}
+
+function record(module, ownership, source, installed) { return { layer: module, ownership, source_sha256: sha256(source), installed_sha256: installed === null ? null : sha256(installed) }; }
+function isProvider(relative) { return relative.startsWith('.agents/skills/wtk-config/assets/agents/'); }
+function isRetirable(relative) { return RETIRABLE_WORKFLOW_FILES.includes(relative) || RETIRABLE_WORKFLOW_DIRS.some((root) => relative.startsWith(root)); }
+
+function blockSpan(text, module) {
+  const start = `<!-- my-workflow:${module}:start -->`, end = `<!-- my-workflow:${module}:end -->`;
+  const valid = /^<!-- my-workflow:(?:core|quality):(?:start|end) -->$/;
+  if (text.split(/\r?\n/).some((line) => line.includes('my-workflow:') && !valid.test(line.trim()))) fail(`managed ${module} block is duplicated or altered`);
+  const starts = [...text.matchAll(new RegExp(start.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'))]; const ends = [...text.matchAll(new RegExp(end.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'g'))];
+  if (!starts.length && !ends.length) return null; if (starts.length !== 1 || ends.length !== 1 || starts[0].index > ends[0].index) fail(`managed ${module} block is incomplete or nested`);
+  return [starts[0].index, ends[0].index + end.length];
+}
+function blockContent(sourceRoot, module, filename) {
+  const body = filename === 'CLAUDE.md' ? '@AGENTS.md' : fs.readFileSync(path.join(sourceRoot, 'templates/adoption/agents', `${module}.md`), 'utf8').trimEnd();
+  return `<!-- my-workflow:${module}:start -->\n${body}\n<!-- my-workflow:${module}:end -->`;
+}
+export function composeBlocks(sourceRoot, root, modules, manifest) {
+  const outputs = {}, blocks = { ...manifest.blocks }, conflicts = [];
+  for (const filename of ['AGENTS.md', 'CLAUDE.md']) {
+    const target = safePath(root, filename, 'managed instruction'); const exists = fs.existsSync(target); let rendered = exists ? decodeUtf8(fs.readFileSync(target), `${filename} instruction`) : filename === 'AGENTS.md' ? decodeUtf8(fs.readFileSync(path.join(sourceRoot, filename)), `${filename} package source`) : '';
+    for (const module of (filename === 'AGENTS.md' ? BLOCK_LAYERS : ['core'])) if (modules.includes(module)) {
+      let span; try { span = blockSpan(rendered, module); } catch { conflicts.push(`${filename}:${module}`); continue; }
+      const block = blockContent(sourceRoot, module, filename); const key = `${filename}:${module}`;
+      if (span) { if (manifest.blocks[key] && sha256(Buffer.from(rendered.slice(span[0], span[1]))) !== manifest.blocks[key].sha256) { conflicts.push(key); continue; } rendered = rendered.slice(0, span[0]) + block + rendered.slice(span[1]); }
+      else { if (rendered && !rendered.endsWith('\n')) rendered += '\n'; if (rendered) rendered += '\n'; rendered += block + '\n'; }
+      blocks[key] = { sha256: sha256(Buffer.from(block)) };
+    }
+    if (Buffer.from(rendered).compare(exists ? fs.readFileSync(target) : Buffer.alloc(0)) !== 0) outputs[filename] = Buffer.from(rendered);
+  }
+  return { outputs, blocks, conflicts };
+}
+
+function mergeIgnore(existing, entries, remove = []) { const lines = (existing ? existing.toString() : '').split(/\r?\n/).filter((line) => line && !remove.includes(line) && !entries.includes(line)); return Buffer.from([...lines, ...entries, ''].join('\n')); }
+function sourceBytes(root, relative) { return fs.readFileSync(path.join(root, (CONSUMER_MISSING_SOURCES[relative] || relative).split('/').join(path.sep))); }
+
+function linkParent(root, relative) {
+  const parent = path.posix.dirname(relative);
+  if (parent === '.') return;
+  let current = root;
+  for (const part of parent.split('/')) {
+    current = path.join(current, part);
+    if (!fs.existsSync(current)) continue;
+    const stat = fs.lstatSync(current);
+    if (stat.isSymbolicLink()) fail(`Claude skill link ${relative} uses symlink ${posix(path.relative(root, current))}`);
+    if (!stat.isDirectory()) fail(`Claude skill link ${relative} parent ${posix(path.relative(root, current))} must be a directory`);
+  }
+}
+
+function claudeSkillLink(root, skill) {
+  const relative = `.claude/skills/${skill}`;
+  const target = `../../.agents/skills/${skill}`;
+  linkParent(root, relative);
+  const destination = path.join(root, ...relative.split('/'));
+  const current = fs.lstatSync(destination, { throwIfNoEntry: false });
+  if (!current) return { relative, target, kind: 'add' };
+  if (!current.isSymbolicLink() || fs.readlinkSync(destination) !== target) fail(`Claude skill link ${relative} is an unsafe collision`);
+  const resolved = path.resolve(path.dirname(destination), target);
+  const targetRoot = path.resolve(root, `.agents/skills/${skill}`);
+  if (resolved !== targetRoot || !resolved.startsWith(`${path.resolve(root)}${path.sep}`)) fail(`Claude skill link ${relative} escapes target`);
+  return { relative, target, kind: 'no-change' };
+}
+
+export function buildPlan({ sourceRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '../..'), targetRoot = process.cwd(), selectedModules, modules } = {}) {
+  const source = asRoot(sourceRoot), target = asRoot(targetRoot); const requested = selectedModules || modules; const requestedResolved = requestedModules(requested); const installedManifest = loadManifest(target); const installed = installedManifest.layers || []; const effective = resolveModules(requestedResolved); const manifestLayers = resolveModules([...requestedResolved, ...installed]);
+  const entries = catalog(source, effective); const actions = [], conflicts = [], retired = []; const records = Object.fromEntries(Object.entries(installedManifest.files || {}).filter(([, record]) => !effective.includes(record.layer)));
+  const missing = new Set(effective.flatMap((module) => LAYER_MISSING_PATHS[module].flatMap((item) => sourceFiles(source, item)))); if (effective.includes('core')) Object.keys(CONSUMER_MISSING_SOURCES).forEach((item) => missing.add(item));
+  for (const [relative, owners] of [...entries.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+    const module = owners[0];
+    const packageBytes = sourceBytes(source, relative), installedBytes = adoptedBytes(relative, packageBytes), destination = safePath(target, relative, 'managed destination'); const previous = installedManifest.files[relative]; const exists = fs.existsSync(destination);
+    if (missing.has(relative)) { actions.push({ path: relative, kind: exists ? 'preserve' : 'add', modules: owners, reason: exists ? 'consumer-owned file unchanged' : 'new neutral scaffolding' }); records[relative] = record(module, 'consumer', packageBytes, null); continue; }
+    if (previous?.ownership === 'consumer' && !isProvider(relative)) { actions.push({ path: relative, kind: 'preserve', modules: owners, reason: 'consumer-owned file unchanged' }); records[relative] = previous; continue; }
+    const current = exists ? fs.readFileSync(destination) : null; let kind;
+    if (previous) { if (!current) { kind = 'conflict'; conflicts.push(relative); } else if (sha256(current) !== previous.installed_sha256) { kind = 'modified'; conflicts.push(relative); } else kind = current.compare(installedBytes) === 0 ? 'no-change' : 'update'; }
+    else if (!exists) kind = 'add'; else if (current.compare(installedBytes) === 0) kind = 'claim'; else { kind = 'conflict'; conflicts.push(relative); }
+    actions.push({ path: relative, kind, modules: owners, sourceSha256: sha256(packageBytes), installedSha256: exists ? sha256(installedBytes) : undefined, reason: ['conflict', 'modified'].includes(kind) ? 'consumer content requires a decision' : kind === 'claim' ? 'file unchanged; ownership record added' : undefined }); records[relative] = record(module, 'managed', packageBytes, installedBytes);
+  }
+  for (const [relative, previous] of Object.entries(installedManifest.files || {}).sort(([a], [b]) => a.localeCompare(b))) {
+    if (records[relative] || previous.ownership === 'consumer' || relative.startsWith('knowledge/wiki/')) continue;
+    const destination = safePath(target, relative, 'retired destination'); if (!isRetirable(relative)) continue;
+    if (!fs.existsSync(destination)) { retired.push(relative); actions.push({ path: relative, kind: 'remove', modules: [previous.layer], reason: 'retired workflow path' }); continue; }
+    const expected = previous.ownership === 'consumer' ? previous.source_sha256 : previous.installed_sha256; if (sha256(fs.readFileSync(destination)) !== expected) { conflicts.push(relative); actions.push({ path: relative, kind: 'conflict', modules: [previous.layer], reason: 'retired file was modified' }); } else { retired.push(relative); actions.push({ path: relative, kind: 'remove', modules: [previous.layer], reason: 'retired workflow path' }); }
+  }
+  const blocks = composeBlocks(source, target, effective, installedManifest); conflicts.push(...blocks.conflicts); for (const conflict of blocks.conflicts) { const [filename, owner] = conflict.split(':'); actions.push({ path: conflict, kind: 'conflict', modules: [owner], reason: 'consumer content requires a decision' }); }
+  const gitignore = safePath(target, '.gitignore', 'ignore file'); const searchignore = safePath(target, '.ignore', 'ignore file'); const ignorePlans = [[gitignore, '.gitignore', mergeIgnore(fs.existsSync(gitignore) ? fs.readFileSync(gitignore) : null, WORKFLOW_GITIGNORE_ENTRIES, LEGACY_WORKFLOW_GITIGNORE_ENTRIES)], [searchignore, '.ignore', mergeIgnore(fs.existsSync(searchignore) ? fs.readFileSync(searchignore) : null, WORKFLOW_SEARCHIGNORE_ENTRIES)]]; for (const [file, relative, bytes] of ignorePlans) { const exists = fs.existsSync(file); const kind = !exists ? 'add' : Buffer.compare(fs.readFileSync(file), bytes) === 0 ? 'no-change' : 'update'; actions.push({ path: relative, kind, modules: [...effective], reason: 'workflow ignore rules' }); }
+  const links = {};
+  const linkedSkills = new Set(effective.flatMap((module) => CLAUDE_SKILL_LINKS[module]));
+  for (const skill of linkedSkills) {
+    const link = claudeSkillLink(target, skill);
+    actions.push({ path: link.relative, kind: link.kind, modules: effective.filter((module) => CLAUDE_SKILL_LINKS[module].includes(skill)), reason: 'Claude public skill alias' });
+    if (link.kind === 'add') links[link.relative] = link.target;
+  }
+  const staged = { '.gitignore': ignorePlans[0][2], '.ignore': ignorePlans[1][2], ...blocks.outputs };
+  for (const action of actions) if (['add', 'update', 'claim'].includes(action.kind) && !['.gitignore', '.ignore'].includes(action.path) && !links[action.path]) staged[action.path] = adoptedBytes(action.path, sourceBytes(source, action.path));
+  const newManifest = { schema: 1, workflow_version: WORKFLOW_VERSION, layers: manifestLayers, files: records, blocks: blocks.blocks }; staged['.my-workflow/adoption.json'] = Buffer.from(`${JSON.stringify(newManifest, null, 2)}\n`);
+  const selectedSet = new Set(effective); const assessments = effective.map((id) => { const own = actions.filter((action) => action.modules.includes(id)); const kinds = new Set(own.map((action) => action.kind)); const status = kinds.has('conflict') ? 'conflict' : kinds.has('modified') ? 'modified' : kinds.has('update') ? 'outdated' : kinds.has('add') || kinds.has('claim') ? 'not installed' : 'up to date'; return { id, status, requiredBy: LAYERS.filter((candidate) => candidate !== id && DEPENDENCIES[candidate].includes(id) && selectedSet.has(candidate)), actions: own }; });
+  const noChange = actions.length > 0 && actions.every((action) => ['preserve', 'no-change'].includes(action.kind)) && !conflicts.length;
+  const finalActions = noChange ? [] : actions.map((action) => ({ ...action, modules: [...new Set(action.modules)] })).sort((a, b) => a.path.localeCompare(b.path));
+  return { plan: { target, packageVersion: WORKFLOW_VERSION, selectedModules: effective, assessments, actions: finalActions, unresolved: [...new Set(conflicts)].sort(), retired, status: conflicts.length ? 'conflict' : noChange ? 'no-change' : 'ready', message: noChange ? 'Selected modules are up to date. No files will change.' : undefined }, staged, links, manifest: newManifest };
+}
+
+export function gitProof(root, runner = execFileSync) {
+  const target = asRoot(root);
+  try {
+    const run = (args) => String(runner('git', args, { cwd: target, shell: false, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })).trim();
+    if (run(['rev-parse', '--is-inside-work-tree']) !== 'true') fail('Git work tree required');
+    if (path.resolve(run(['rev-parse', '--show-toplevel'])) !== target) fail('target must be the root of its Git work tree');
+    if (!run(['rev-parse', '--verify', 'HEAD'])) fail('Git repository requires HEAD');
+    if (run(['status', '--porcelain', '--untracked-files=all'])) fail('Git target must be clean');
+    return true;
+  } catch (error) { if (error instanceof InstallerError) throw error; fail(`Git proof failed: ${error.message}`); }
+}
+
+export function assessModules(input) { return buildPlan(input).plan.assessments; }
+export function recalculatePlan(planInput, decisions = {}) { const result = buildPlan({ ...planInput, selectedModules: decisions.selectedModules || planInput.selectedModules }); if (decisions.replacements) for (const action of result.plan.actions) if (action.kind === 'conflict' && decisions.replacements.includes(action.path)) { action.kind = 'replace'; result.plan.unresolved = result.plan.unresolved.filter((item) => item !== action.path); } return result; }
+
+export default { buildPlan, assessModules, recalculatePlan, resolveModules, requestedModules, loadManifest, validateRelative, safePath, sha256, gitProof, LAYERS };

package/scripts/installer/knowledge.js

@@ -0,0 +1,28 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { KNOWLEDGE_DESTINATIONS } from './engine.js';
+
+export function knowledgeTransfers(plan, backup) {
+  const backupRoot = typeof backup === 'string' ? backup : backup?.backup;
+  if (!backupRoot) return [];
+  return (plan?.actions || []).filter((action) => ['replace', 'remove'].includes(action.kind || action.action) && KNOWLEDGE_DESTINATIONS[action.path?.split(':')[0]]).map((action) => {
+    const source = path.posix.join(backupRoot.split(path.sep).join('/'), 'files', action.path.split(':')[0]);
+    const destination = KNOWLEDGE_DESTINATIONS[action.path.split(':')[0]];
+    return { source, destination: destination.destination, reason: destination.reason, status: 'Pending human transfer' };
+  });
+}
+
+export function writeKnowledgeChecklist(backupRoot, items) {
+  if (!items?.length) return null;
+  const target = path.join(backupRoot, 'knowledge-transfer.md');
+  const lines = ['# Knowledge transfer', '', 'The installer preserved these consumer-owned sources. Review and transfer content manually.', ''];
+  for (const item of items) lines.push(`- Source: ${item.source}`, `  Destination: ${item.destination}`, `  Reason: ${item.reason}`, `  Status: ${item.status}`, '');
+  fs.writeFileSync(target, `${lines.join('\n')}\n`);
+  return target;
+}
+
+export function prepareKnowledge(plan, prepared) {
+  const items = knowledgeTransfers(plan, prepared); if (items.length && prepared?.backup) writeKnowledgeChecklist(path.resolve(prepared.targetRoot, prepared.backup), items); return items;
+}
+
+export default { knowledgeTransfers, writeKnowledgeChecklist, prepareKnowledge };

package/scripts/installer/packets.js

@@ -0,0 +1,77 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { parse } from 'smol-toml';
+import { safePath } from './engine.js';
+
+export const PROVIDERS = ['claude', 'codex', 'cursor'];
+export const ROLES = ['planner', 'implementer', 'verifier', 'explorer', 'deep_reviewer', 'designer'];
+export const AGENT_NAMES = { deep_reviewer: 'deep-reviewer' };
+const EFFORTS = ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'];
+const modelRe = /^[^\\\s[\]"\x00-\x1f\x7f]+$/;
+const runtimePath = (provider, role) => `.${provider}/agents/${AGENT_NAMES[role] || role}.${provider === 'codex' ? 'toml' : 'md'}`;
+const templatePath = (root, provider, role) => path.join(root, '.agents', 'skills', 'wtk-config', 'assets', 'agents', provider, `${AGENT_NAMES[role] || role}.${provider === 'codex' ? 'toml' : 'md'}`);
+const error = (message) => { throw new Error(`wtk-config: ${message}`); };
+
+export function validateWorkflowConfig(config) {
+  if (!config || typeof config !== 'object' || Array.isArray(config)) error('configuration must contain a table');
+  if (config.version !== 3) error('version must be integer 3; refresh the project configuration');
+  const allowed = new Set(['version', 'deep_review', 'parallelization', 'profiles', 'models', 'remediation']);
+  const unknown = Object.keys(config).find((key) => !allowed.has(key)); if (unknown) error(`contains unknown top-level key '${unknown}'`);
+  if (!config.models || typeof config.models !== 'object') error('models must be a table containing every provider');
+  for (const provider of PROVIDERS) {
+    const values = config.models[provider]; if (!values || typeof values !== 'object') error(`models.${provider} must be a table`);
+    for (const role of ROLES) {
+      const setting = values[role]; const name = `models.${provider}.${role}`;
+      if (!setting || typeof setting !== 'object') error(`${name} must be a table`);
+      if (typeof setting.model !== 'string' || !setting.model.trim() || !modelRe.test(setting.model)) error(`${name}.model must be a valid native model identifier`);
+      if (typeof setting.effort !== 'string' || !EFFORTS.includes(setting.effort)) error(`${name}.effort must be one of: ${EFFORTS.join(', ')}`);
+      if (provider === 'claude' && setting.effort === 'ultra') error(`${name}.effort 'ultra' is not supported by claude`);
+    }
+  }
+  return config;
+}
+
+export function readWorkflowConfig(root) {
+  const local = safePath(root, '.wtk.toml', 'workflow config'); const example = safePath(root, '.wtk.toml.example', 'workflow config'); const configPath = fs.existsSync(local) ? local : example;
+  if (!fs.existsSync(configPath)) error('.wtk.toml is missing');
+  let config; try { config = parse(fs.readFileSync(configPath, 'utf8')); } catch (cause) { error(`invalid .wtk.toml: ${cause.message}`); }
+  return validateWorkflowConfig(config);
+}
+
+function one(regex, content, label) { const matches = [...content.matchAll(regex)]; if (matches.length !== 1) error(`packet must contain exactly one ${label} metadata field`); return matches[0]; }
+export function packetSetting(provider, content) {
+  const text = Buffer.isBuffer(content) ? content.toString('utf8') : content;
+  let model, effort;
+  if (provider === 'claude') { const header = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1]; if (header === undefined) error('packet must contain a native YAML frontmatter header'); model = one(/^model:\s*([^\r\n]+)$/gm, header, 'model')[1].trim(); effort = one(/^effort:\s*([^\r\n]+)$/gm, header, 'effort')[1].trim(); }
+  else if (provider === 'cursor') { const header = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(text)?.[1]; if (header === undefined) error('packet must contain a native YAML frontmatter header'); const match = one(/^model:\s*([^\[\r\n]+)\[effort=([^\]\r\n]+)\]$/gm, header, 'model/effort'); model = match[1].trim(); effort = match[2].trim(); }
+  else { const modelMatch = one(/^model\s*=\s*"((?:\\.|[^"\\])*)"/gm, text, 'model'); const effortMatch = one(/^model_reasoning_effort\s*=\s*"((?:\\.|[^"\\])*)"/gm, text, 'model_reasoning_effort'); model = JSON.parse(`"${modelMatch[1]}"`); effort = JSON.parse(`"${effortMatch[1]}"`); }
+  if (!modelRe.test(model)) error('packet contains an invalid model identifier'); return { model, effort };
+}
+
+export function renderAgentPacket(provider, content, setting) {
+  const text = Buffer.isBuffer(content) ? content.toString('utf8') : content; let rendered;
+  if (provider === 'claude') {
+    rendered = text.replace(/^(model:)\s*[^\r\n]+$/m, `$1 ${setting.model}`).replace(/^(effort:)\s*[^\r\n]+$/m, `$1 ${setting.effort}`);
+  } else if (provider === 'cursor') {
+    rendered = text.replace(/^(model:)\s*[^\[\r\n]+\[effort=[^\]\r\n]+\]/m, `$1 ${setting.model}[effort=${setting.effort}]`);
+  } else {
+    const quote = JSON.stringify(setting.model).slice(1, -1); const effort = JSON.stringify(setting.effort).slice(1, -1);
+    rendered = text.replace(/^(model\s*=\s*")[^"\\]*(?:\\.[^"\\]*)*(")/m, `$1${quote}$2`).replace(/^(model_reasoning_effort\s*=\s*")[^"\\]*(?:\\.[^"\\]*)*(")/m, `$1${effort}$2`);
+  }
+  packetSetting(provider, rendered); return Buffer.isBuffer(content) ? Buffer.from(rendered) : rendered;
+}
+
+export function stageAgentPackets(stageRoot, targetRoot = stageRoot) {
+  const root = path.resolve(stageRoot); const target = path.resolve(targetRoot); let config;
+  if (fs.existsSync(path.join(target, '.wtk.toml')) || fs.existsSync(path.join(target, '.wtk.toml.example'))) config = readWorkflowConfig(target);
+  else config = validateWorkflowConfig(parse(fs.readFileSync(path.join(root, '.wtk.toml.example'), 'utf8')));
+  const generated = {};
+  for (const provider of PROVIDERS) for (const role of ROLES) {
+    const template = templatePath(root, provider, role); if (!fs.existsSync(template) || !fs.lstatSync(template).isFile()) error(`missing agent template ${path.relative(root, template)}`);
+    const content = fs.readFileSync(template); packetSetting(provider, content); generated[runtimePath(provider, role)] = renderAgentPacket(provider, content, config.models[provider][role]);
+  }
+  if (!fs.existsSync(path.join(target, '.wtk.toml')) && fs.existsSync(path.join(root, '.wtk.toml.example'))) generated['.wtk.toml'] = fs.readFileSync(path.join(root, '.wtk.toml.example'));
+  return generated;
+}
+
+export default { stageAgentPackets, readWorkflowConfig, validateWorkflowConfig, packetSetting, renderAgentPacket, PROVIDERS, ROLES };

package/scripts/installer/terminal.js

@@ -0,0 +1,98 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { buildPlan, composeBlocks, gitProof, LAYERS, loadManifest, resolveModules, safePath } from './engine.js';
+import { applyTransaction, hasInterruptedTransaction, restoreInterrupted } from './transaction.js';
+import { knowledgeTransfers } from './knowledge.js';
+import { stageAgentPackets } from './packets.js';
+
+const descriptions = {
+  compact: { core: 'Workflow Toolkit, Lean workflow, and shared tooling', quality: 'Deep review and QA skills', extras: 'Optional Ponytail utilities and prompt-review' },
+  wide: { core: 'Workflow Toolkit, Lean workflow, configuration, and shared tooling', quality: 'Deep review, verification, and QA skills', extras: 'Optional Ponytail utilities and prompt-review' },
+};
+const statusBox = (value, width = 15) => { const label = statusLabel(value); return `[${label}]${' '.repeat(Math.max(1, width - label.length - 2))}`; };
+const labels = { add: 'ADD', update: 'UPDATE', claim: 'ADOPT', replace: 'REPLACE', remove: 'REMOVE', preserve: 'PRESERVE', 'no-change': 'NO CHANGE', conflict: 'CONFLICT', modified: 'MODIFIED' };
+const statusLabel = (value) => value.toUpperCase();
+const line = (value, width) => { if (value.length <= width) return [value]; const result = []; for (let start = 0; start < value.length; start += width) result.push(value.slice(start, start + width)); return result; };
+
+export function parseModuleSelection(input) {
+  if (typeof input !== 'string' || !input.trim()) return null;
+  const values = input.split(',').map((item) => item.trim()); if (!values.every((item) => /^[1-3]$/.test(item))) return null;
+  const indexes = [...new Set(values.map(Number))]; return LAYERS.filter((_, index) => indexes.includes(index + 1));
+}
+
+export function renderPlan(plan, width = 80) {
+  const lines = [`Plan for ${plan.target}`, ''];
+  if (width >= 100) lines.push('  ACTION     MODULE      PATH');
+  for (const action of plan.actions || []) {
+    const modules = (action.modules || []).join(', ');
+    const label = labels[action.kind] || action.kind;
+    if (width >= 100) {
+      lines.push(...line(`  ${label.padEnd(10)} ${modules.padEnd(10)} ${action.path}${action.reason ? ` (${action.reason})` : ''}`, width));
+    } else {
+      lines.push(...line(`  ${label.padEnd(9)} ${action.path}`, width));
+      lines.push(...line(`            ${action.reason ? `module: ${modules}; ${action.reason}` : `module: ${modules}`}`, width));
+    }
+  }
+  if (plan.unresolved?.length) lines.push('', `Unresolved conflicts: ${plan.unresolved.length}`, 'Resolve every conflict before final confirmation.');
+  return lines.join('\n');
+}
+
+const outputOf = (write) => (value) => { if (write) write(value); };
+async function ask(input, write, prompt) { outputOf(write)(prompt); const answer = await input(prompt); return answer == null ? null : String(answer); }
+const yes = (answer) => answer !== null && /^y(?:es)?$/i.test(answer.trim());
+const shellQuote = (value) => `'${String(value).replaceAll("'", "'\"'\"'")}'`;
+export const securityInstallCommand = (packageRoot, targetRoot) => `python3 ${shellQuote(path.join(packageRoot, 'scripts/install_security_skills.py'))} ${shellQuote(targetRoot)} --yes`;
+export const repositoryIntelligenceInstallCommands = [
+  'npm install --save-dev --save-exact @nanonets/graft@0.10.1',
+  'uv tool install graphifyy==0.9.14',
+];
+const printRepositoryIntelligenceSetup = (print) => {
+  print('\nRepository intelligence setup (manual; not executed):');
+  repositoryIntelligenceInstallCommands.forEach((command) => print(`  ${command}`));
+};
+function addPacketActions(built, packageRoot, targetRoot) { const packets = stageAgentPackets(packageRoot, targetRoot); Object.assign(built.staged, packets); for (const [relative, bytes] of Object.entries(packets)) { const target = safePath(targetRoot, relative, 'runtime packet'); const exists = fs.existsSync(target); const kind = !exists ? 'add' : fs.readFileSync(target).compare(bytes) === 0 ? 'no-change' : 'update'; if (!built.plan.actions.some((action) => action.path === relative)) built.plan.actions.push({ path: relative, kind, modules: [...built.plan.selectedModules], reason: 'generated provider packet' }); } built.plan.actions.sort((a, b) => a.path.localeCompare(b.path)); if (built.plan.message && built.plan.actions.some((action) => !['preserve', 'no-change'].includes(action.kind))) { built.plan.message = undefined; built.plan.status = 'ready'; } else if (built.plan.message) built.plan.actions = []; return built; }
+
+export async function runInstallWizard({ targetRoot = process.cwd(), sourceRoot, input = async () => null, write = console.log, width = Number(process.stdout.columns) || 80, color = !process.env.NO_COLOR, planner = buildPlan, transaction = applyTransaction, requireGit = false } = {}) {
+  const root = path.resolve(targetRoot); const print = outputOf(write);
+  const packageRoot = sourceRoot ? path.resolve(sourceRoot) : path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+  if (requireGit) { try { gitProof(root); } catch (error) { print(`[ERROR] ${error.message}\nNo files changed.`); return { code: 1, error }; } }
+  if (hasInterruptedTransaction(root)) {
+    const answer = await ask(input, write, 'A previous installation was interrupted. Restore its recorded backup before continuing. Restore now? (y/N): ');
+    if (!yes(answer)) { print('Installation cancelled. No files changed.'); return { cancelled: true, code: 0 }; }
+    try { restoreInterrupted({ targetRoot: root }); } catch (error) { print(`[ERROR] ${error.message}\nNo files changed.`); return { code: 1, error }; }
+  }
+  print('\nWorkflow Toolkit Installer'); print(`Target: ${root}\n`); print('Select modules to install or update:');
+  const wide = width >= 100;
+  const assessment = planner({ sourceRoot, targetRoot: root, selectedModules: LAYERS }).plan.assessments;
+  assessment.forEach((module, index) => print(`  ${index + 1}. [ ] ${module.id.padEnd(9)} ${statusBox(module.status, wide ? 17 : 16)}${descriptions[wide ? 'wide' : 'compact'][module.id]}`));
+  let selected; while (!selected) { const answer = await ask(input, write, '\nModules [1-3, comma-separated]: '); if (answer === null) { print('Installation cancelled. No files changed.'); return { cancelled: true, code: 0 }; } selected = parseModuleSelection(answer); if (!selected) print('Choose one or more modules using numbers 1-3.'); }
+  const plannedModules = resolveModules(selected); print('\nSelected modules:'); for (const module of plannedModules) { const source = assessment.find((item) => item.id === module); const required = plannedModules.filter((item) => item !== module && (module === 'core' && ['quality', 'extras'].includes(item))).join(', '); print(`  [x] ${module.padEnd(9)} ${statusBox(source?.status || 'not installed', wide ? 17 : 16)}${required ? `required by ${required}` : ''}`); }
+  const preview = await ask(input, write, '\nContinue to preview? (y/N): '); if (!yes(preview)) { print('Installation cancelled. No files changed.'); return { cancelled: true, code: 0 }; }
+  let built = addPacketActions(planner({ sourceRoot, targetRoot: root, selectedModules: selected }), packageRoot, root); if (built.plan.message) { print(built.plan.message); print('No backup required.'); printRepositoryIntelligenceSetup(print); print('\nExternal security skills remain separately authorized.'); print('\nIf external security skills are not installed, the security gate remains uncovered.'); print(securityInstallCommand(packageRoot, root)); return { plan: built.plan, code: 0 }; }
+  print(`\n${renderPlan(built.plan, width)}`);
+  const replacements = []; const excluded = new Set();
+  while (built.plan.unresolved?.length) {
+    const conflict = built.plan.unresolved[0]; const action = built.plan.actions.find((item) => item.path === conflict); const dependents = (action?.modules || []).flatMap((module) => plannedModules.filter((candidate) => candidate !== module && DEPENDENCIES[candidate]?.includes(module))).filter((item, index, list) => list.indexOf(item) === index);
+    print(`\nConflict 1 of ${built.plan.unresolved.length}`); print(`This file contains content not owned by the installer: ${conflict}`); print(`Module: ${(action?.modules || []).join(', ')}`);
+    if (wide) print(`\nChoose an action:\n  1. Back up and replace  Adds a pending transfer from the backup to docs/product/AGENT-CONTEXT.md.\n  2. Exclude module       ${dependents.length ? `Excluding ${(action?.modules || []).join(', ')} also excludes: ${dependents.join(', ')}.` : 'Exclude the affected module.'}`);
+    else { print('\nChoose an action:\n  1. Back up and replace\n     Adds a pending transfer from the backup to\n     docs/product/AGENT-CONTEXT.md.\n  2. Exclude module'); if (dependents.length) print(`     Excluding ${(action?.modules || []).join(', ')} also excludes: ${dependents.join(', ')}.`); }
+    print('  3. Cancel installation');
+    const choice = await ask(input, write, '\nDecision [1-3]: ');
+    if (choice === null || choice.trim() === '3' || !['1', '2'].includes(choice.trim())) { print('Installation cancelled. No files changed.'); return { cancelled: true, code: 0 }; }
+    if (choice.trim() === '1') { replacements.push(conflict); print(wide ? 'AGENTS.md will be backed up and replaced. Pending knowledge transfers: 1' : 'AGENTS.md will be backed up and replaced.'); if (knowledgeDestination(conflict) && !wide) print('Pending knowledge transfers: 1'); }
+    else { for (const module of action?.modules || []) excluded.add(module); if (excluded.has('core')) ['quality', 'extras'].forEach((module) => excluded.add(module)); const cascade = [...excluded].filter((module) => module !== (action?.modules || [])[0]); print(`Excluding ${[...excluded].join(', ')}${cascade.length ? `; also excludes: ${cascade.join(', ')}` : ''}; recalculating plan.`); }
+    const modulesAfter = plannedModules.filter((module) => !excluded.has(module)); if (!modulesAfter.length) { print('Installation cancelled. No files changed.'); return { cancelled: true, code: 0 }; }
+    built = addPacketActions(planner({ sourceRoot, targetRoot: root, selectedModules: modulesAfter }), packageRoot, root); for (const item of built.plan.actions) if (replacements.includes(item.path)) item.kind = 'replace'; for (const replacement of replacements.filter((item) => item.includes(':'))) { const [filename, module] = replacement.split(':'); const manifest = loadManifest(root); delete manifest.blocks[replacement]; const composed = composeBlocks(packageRoot, root, built.plan.selectedModules, manifest); if (composed.outputs[filename]) built.staged[filename] = composed.outputs[filename]; built.manifest.blocks = { ...built.manifest.blocks, ...composed.blocks }; built.staged['.my-workflow/adoption.json'] = fs.readFileSync(path.join(root, '.my-workflow/adoption.json')); built.staged['.my-workflow/adoption.json'] = Buffer.from(`${JSON.stringify(built.manifest, null, 2)}\n`); } built.plan.unresolved = built.plan.unresolved.filter((item) => !replacements.includes(item));
+  }
+  const actions = built.plan.actions.filter((item) => !['preserve', 'no-change'].includes(item.kind)); const counts = Object.fromEntries(Object.keys(labels).map((key) => [key, built.plan.actions.filter((item) => item.kind === key).length])); const summary = Object.entries(counts).filter(([, count]) => count).map(([key, count]) => `${count} ${labels[key].toLowerCase()}`).join(', ') || 'none'; const knowledgeCount = built.plan.actions.filter((item) => ['replace', 'remove'].includes(item.kind) && knowledgeDestination(item.path)).length; const backupPreview = actions.some((item) => ['replace', 'remove', 'update'].includes(item.kind)) ? '.my-workflow/backups/<UTC timestamp>/' : 'No backup required.'; print('\nReady to install'); print(`Selected modules: ${built.plan.selectedModules.join(', ')}`); print(`Actions: ${summary}`); print(`Backup: ${backupPreview}`); print(`Knowledge transfers: ${knowledgeCount} pending`);
+  const confirmation = await ask(input, write, '\nApply this plan? (y/N): '); if (!yes(confirmation)) { print('Installation cancelled. No files changed.'); return { cancelled: true, code: 0 }; }
+  const knowledgeActions = built.plan.actions.filter((item) => ['replace', 'remove'].includes(item.kind) && item.path.split(':')[0] in { 'AGENTS.md': 1, 'CLAUDE.md': 1, 'knowledge/AGENTS.md': 1, 'knowledge/raw/README.md': 1 });
+  const prepared = { targetRoot: root, plan: built.plan, staged: built.staged, links: built.links, knowledgeActions }; for (const action of built.plan.actions.filter((item) => item.kind === 'replace')) { const relative = action.path.split(':')[0]; if (!prepared.staged[relative]) prepared.staged[relative] = fs.readFileSync(path.join(packageRoot, relative)); }
+  if (!wide) print('\nApplying... files'); let result; try { result = transaction(prepared); } catch (error) { const publication = /publication failed; previous repository state was restored/.test(error.message); if (publication) print('[ERROR] Installation failed. The previous repository state was restored.'); else if (/backup failed:/.test(error.message)) print(`[ERROR] Backup failed: ${error.message.slice(error.message.indexOf(':') + 1).trim()}`); else print(`[ERROR] ${error.message}`); if (!publication) print('No target files or adoption state changed.'); return { code: 1, error }; } if (!wide) print('Applying... adoption state'); const items = knowledgeTransfers(built.plan, result); print('\nInstallation complete.'); print(`Modules: ${built.plan.selectedModules.join(', ')}`); print(`Actions: ${summary}`); const backup = result.backup ? `${result.backup}/` : 'No backup required.'; print(`Backup: ${backup}`); if (items.length) { print('\nKnowledge transfer required:'); items.forEach((item) => { if (wide) print(`  Source:      ${item.source}\n  Destination: ${item.destination}\n  Reason:      ${item.reason}\n  Status:      ${item.status}`); else print(`  Source:\n    ${item.source}\n  Destination: ${item.destination}\n  Reason: ${item.reason}\n  Status: ${item.status}`); }); if (wide) print(`Checklist: ${result.backup}/knowledge-transfer.md`); else print(`Checklist:\n  ${result.backup}/\n  knowledge-transfer.md`); } printRepositoryIntelligenceSetup(print); print('\nExternal security skills remain separately authorized.'); print('\nIf external security skills are not installed, the security gate remains uncovered.'); print(securityInstallCommand(packageRoot, root)); return { plan: built.plan, result, knowledge: items, code: 0 };
+}
+
+const DEPENDENCIES = { core: [], quality: ['core'], extras: ['core'] };
+const knowledgeDestination = (relative) => ['AGENTS.md', 'CLAUDE.md', 'knowledge/AGENTS.md', 'knowledge/raw/README.md'].includes(relative?.split(':')[0]);
+
+export default { runInstallWizard, renderPlan, parseModuleSelection };

package/scripts/installer/transaction.js

@@ -0,0 +1,75 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { KNOWLEDGE_DESTINATIONS, safePath, sha256, validateRelative, InstallerError } from './engine.js';
+
+const fail = (message) => { throw new InstallerError(message); };
+const atomicWrite = (file, content) => { fs.mkdirSync(path.dirname(file), { recursive: true }); const temporary = path.join(path.dirname(file), `.${path.basename(file)}.${process.pid}.${crypto.randomUUID()}.tmp`); try { const fd = fs.openSync(temporary, 'w', 0o600); fs.writeFileSync(fd, content); fs.fsyncSync(fd); fs.closeSync(fd); fs.renameSync(temporary, file); } finally { if (fs.existsSync(temporary)) fs.unlinkSync(temporary); } };
+const targetOf = (input) => path.resolve(input?.targetRoot || input?.target || process.cwd());
+const timestamp = (clock) => new Date(typeof clock === 'function' ? clock() : clock || Date.now()).toISOString().replace(/:/g, '-');
+const journalPath = (root) => path.join(root, '.my-workflow', 'transaction.json');
+function ensureDirectory(root, relative) { let current = root; for (const part of relative.split('/')) { current = path.join(current, part); if (fs.existsSync(current) && (!fs.lstatSync(current).isDirectory() || fs.lstatSync(current).isSymbolicLink())) fail(`backup parent ${relative} uses symlink or non-directory: ${part}`); } }
+
+function actionPath(action) { return action.path.includes(':') && !action.path.startsWith('.my-workflow/') ? action.path.split(':')[0] : action.path; }
+function destructive(action) { return ['update', 'replace', 'remove'].includes(action.kind || action.action); }
+function linkDestination(root, relative, target) {
+  validateRelative(relative);
+  if (typeof target !== 'string' || !target || path.posix.isAbsolute(target) || path.posix.normalize(target) !== target) fail(`Claude skill link target is unsafe: ${relative}`);
+  ensureDirectory(root, path.posix.dirname(relative));
+  const destination = path.join(root, ...relative.split('/'));
+  const resolved = path.resolve(path.dirname(destination), target);
+  const base = path.resolve(root);
+  if (resolved !== path.resolve(root, `.agents/skills/${relative.split('/').at(-1)}`) || !resolved.startsWith(`${base}${path.sep}`)) fail(`Claude skill link target escapes target: ${relative}`);
+  const current = fs.lstatSync(destination, { throwIfNoEntry: false });
+  if (current && (!current.isSymbolicLink() || fs.readlinkSync(destination) !== target)) fail(`Claude skill link ${relative} is an unsafe collision`);
+  return destination;
+}
+
+function publishLink(root, relative, target) {
+  const destination = linkDestination(root, relative, target);
+  if (fs.existsSync(destination) || fs.lstatSync(destination, { throwIfNoEntry: false })) return;
+  fs.mkdirSync(path.dirname(destination), { recursive: true });
+  linkDestination(root, relative, target);
+  fs.symlinkSync(target, destination);
+}
+
+function removeLink(root, relative) {
+  validateRelative(relative);
+  ensureDirectory(root, path.posix.dirname(relative));
+  const destination = path.join(root, ...relative.split('/'));
+  const current = fs.lstatSync(destination, { throwIfNoEntry: false });
+  if (!current) return;
+  if (!current.isSymbolicLink()) fail(`restore cleanup ${relative} is not a symlink`);
+  fs.unlinkSync(destination);
+}
+function entry(root, action, backupRoot) {
+  const relative = actionPath(action); const file = safePath(root, relative, 'backup source'); if (!fs.existsSync(file)) return null; const stat = fs.lstatSync(file); if (!stat.isFile() || stat.isSymbolicLink()) fail(`backup failed: ${relative} is not a regular file`); const bytes = fs.readFileSync(file); const backup = path.join(backupRoot, 'files', ...relative.split('/')); fs.mkdirSync(path.dirname(backup), { recursive: true }); fs.writeFileSync(backup, bytes, { mode: stat.mode & 0o7777 }); const copied = fs.readFileSync(backup); if (sha256(bytes) !== sha256(copied) || (fs.statSync(backup).mode & 0o7777) !== (stat.mode & 0o7777)) fail(`backup failed: ${relative} could not be verified`); return { path: relative, action: action.kind || action.action, sha256: sha256(bytes), mode: stat.mode & 0o7777, backup: posix(path.relative(backupRoot, backup)) }; }
+const posix = (value) => value.split(path.sep).join('/');
+
+export function prepareBackup(input, maybeTarget) {
+  const value = input?.plan ? input : { plan: input, targetRoot: maybeTarget }; const root = targetOf(value); const plan = value.plan || {}; const staged = value.staged || {}; const links = value.links || {}; const actions = (plan.actions || []).filter(destructive); for (const [relative, target] of Object.entries(links)) linkDestination(root, relative, target); if (!actions.length && !Object.keys(staged).length && !Object.keys(links).length) return { targetRoot: root, plan, staged, links, backup: null, journal: null, entries: [] };
+  const removeLinks = Object.keys(links).filter((relative) => !fs.lstatSync(path.join(root, ...relative.split('/')), { throwIfNoEntry: false }));
+  if (!actions.length) { ensureDirectory(root, '.my-workflow'); const adoption = path.join(root, '.my-workflow', 'adoption.json'); const journal = { schema: 1, state: 'prepared', backup: null, restore: [], removeOnRestore: Object.keys(staged).filter((relative) => !fs.existsSync(path.join(root, relative))), removeLinksOnRestore: removeLinks, previousAdoptionState: fs.existsSync(adoption) ? fs.readFileSync(adoption, 'utf8') : null }; atomicWrite(journalPath(root), Buffer.from(`${JSON.stringify(journal, null, 2)}\n`)); return { targetRoot: root, plan, staged, links, backup: null, journal, entries: [] }; }
+  const backupRelative = `.my-workflow/backups/${timestamp(value.clock)}`; ensureDirectory(root, '.my-workflow'); ensureDirectory(root, '.my-workflow/backups'); const backupRoot = path.join(root, ...backupRelative.split('/')); if (fs.existsSync(backupRoot)) fail(`backup already exists: ${backupRelative}`); fs.mkdirSync(path.join(backupRoot, 'files'), { recursive: true });
+  const entries = []; const seen = new Set(); try { for (const action of actions) { const relative = actionPath(action); if (seen.has(relative)) continue; seen.add(relative); if (value.failBackup === relative) fail(`backup failed: ${relative} could not be verified`); const backupEntry = entry(root, action, backupRoot); if (backupEntry) entries.push(backupEntry); } const manifest = { created_at: new Date(typeof value.clock === 'function' ? value.clock() : value.clock || Date.now()).toISOString(), package: 'workflow-toolkit', version: plan.packageVersion || '1.0.1', target: '.', files: entries }; atomicWrite(path.join(backupRoot, 'manifest.json'), Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`)); const knowledge = (value.knowledgeActions || []).filter((action) => KNOWLEDGE_DESTINATIONS[actionPath(action)]).map((action) => { const relative = actionPath(action); const destination = KNOWLEDGE_DESTINATIONS[relative]; return { source: `${backupRelative}/files/${relative}`, destination: destination.destination, reason: destination.reason, status: 'Pending human transfer' }; }); if (knowledge.length) { if (value.failChecklist) fail('checklist write failed'); const lines = ['# Knowledge transfer', '', 'Review these consumer-owned sources and transfer content manually.', '']; for (const item of knowledge) lines.push(`- Source: ${item.source}`, `  Destination: ${item.destination}`, `  Reason: ${item.reason}`, `  Status: ${item.status}`, ''); atomicWrite(path.join(backupRoot, 'knowledge-transfer.md'), Buffer.from(`${lines.join('\n')}\n`)); } const adoption = safePath(root, '.my-workflow/adoption.json', 'adoption state'); const journal = { schema: 1, state: 'prepared', backup: backupRelative, restore: entries, removeOnRestore: Object.keys(staged).filter((relative) => !fs.existsSync(path.join(root, relative))), removeLinksOnRestore: removeLinks, previousAdoptionState: fs.existsSync(adoption) ? fs.readFileSync(adoption, 'utf8') : null }; atomicWrite(journalPath(root), Buffer.from(`${JSON.stringify(journal, null, 2)}\n`)); return { targetRoot: root, plan, staged, links, backup: backupRelative, journal, entries }; } catch (error) { removePath(backupRoot); const parent = path.dirname(backupRoot); if (fs.existsSync(parent) && fs.readdirSync(parent).length === 0) fs.rmdirSync(parent); throw error; } }
+
+function removePath(target) { if (!fs.existsSync(target) && !fs.lstatSync(target, { throwIfNoEntry: false })) return; const stat = fs.lstatSync(target); if (stat.isDirectory() && !stat.isSymbolicLink()) for (const child of fs.readdirSync(target)) removePath(path.join(target, child)); fs.rmSync(target, { recursive: true, force: true }); }
+function publishBytes(root, relative, bytes) { const destination = safePath(root, relative, 'publication destination'); atomicWrite(destination, bytes); }
+
+export function publish(prepared, options = {}) {
+  const root = targetOf(prepared); const plan = prepared.plan || {}; const staged = prepared.staged || {}; const links = prepared.links || {}; const entries = prepared.entries || []; const journal = prepared.journal || null; const order = (relative) => relative === '.my-workflow/adoption.json' ? 2 : relative === '.wtk.toml' || relative.startsWith('.claude/agents/') || relative.startsWith('.codex/agents/') || relative.startsWith('.cursor/agents/') ? 1 : 0;
+  try { for (const [relative, bytes] of Object.entries(staged).sort(([a], [b]) => order(a) - order(b) || a.localeCompare(b))) { if (relative === '.my-workflow/adoption.json') continue; if (options.failAfter && options.failAfter === relative) fail(`injected publication failure: ${relative}`); publishBytes(root, relative, bytes); options.onPublish?.(relative); } for (const [relative, target] of Object.entries(links).sort(([a], [b]) => a.localeCompare(b))) { if (options.failAfter && options.failAfter === relative) fail(`injected publication failure: ${relative}`); publishLink(root, relative, target); options.onPublish?.(relative); } for (const action of plan.actions || []) if ((action.kind || action.action) === 'remove') { const relative = actionPath(action); const destination = safePath(root, relative, 'retired destination'); if (fs.existsSync(destination)) { if (!fs.lstatSync(destination).isFile()) fail(`retired destination is no longer a file: ${relative}`); fs.unlinkSync(destination); options.onPublish?.(relative); } } if (staged['.my-workflow/adoption.json']) { publishBytes(root, '.my-workflow/adoption.json', staged['.my-workflow/adoption.json']); options.onPublish?.('.my-workflow/adoption.json'); } if (journal && fs.existsSync(journalPath(root))) fs.unlinkSync(journalPath(root)); return { ok: true, backup: prepared.backup }; } catch (error) { if (journal) { try { restoreInterrupted({ targetRoot: root, journal }); } catch (restoreError) { fail(`publication failed and rollback failed: ${restoreError.message}`); } } throw new InstallerError(`publication failed; previous repository state was restored: ${error.message}`); }
+}
+
+export function applyTransaction(input, options = {}) { const prepared = prepareBackup(input); return publish(prepared, options); }
+
+export function restoreInterrupted(input) {
+  const root = targetOf(input); const journal = input?.journal || (() => { const file = journalPath(root); if (!fs.existsSync(file)) return null; safePath(root, '.my-workflow/transaction.json', 'transaction journal'); try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch (error) { fail(`invalid transaction journal: ${error.message}`); } })(); if (!journal) return { restored: false, reason: 'none' }; if (journal.schema !== 1 || journal.state !== 'prepared' || (journal.backup !== null && typeof journal.backup !== 'string')) fail('invalid transaction journal'); if (journal.backup !== null) { validateRelative(journal.backup); if (!journal.backup.startsWith('.my-workflow/backups/')) fail('transaction backup must stay inside .my-workflow/backups'); const backupRoot = path.resolve(root, ...journal.backup.split('/')); if (backupRoot !== root && !backupRoot.startsWith(`${root}${path.sep}`)) fail('transaction backup must stay inside target'); ensureDirectory(root, '.my-workflow'); ensureDirectory(root, '.my-workflow/backups'); ensureDirectory(root, journal.backup); }
+  for (const record of journal.restore || []) { const target = safePath(root, record.path, 'restore target'); const backup = safePath(path.join(root, ...journal.backup.split('/')), record.backup, 'restore backup'); if (!fs.existsSync(backup) || sha256(fs.readFileSync(backup)) !== record.sha256) fail(`backup verification failed: ${record.path}`); publishBytes(root, record.path, fs.readFileSync(backup)); fs.chmodSync(target, record.mode); }
+  for (const relative of journal.removeOnRestore || []) { const target = safePath(root, relative, 'restore cleanup'); if (fs.existsSync(target)) removePath(target); }
+  for (const relative of journal.removeLinksOnRestore || []) removeLink(root, relative);
+  ensureDirectory(root, '.my-workflow'); const adoption = safePath(root, '.my-workflow/adoption.json', 'adoption state'); if (journal.previousAdoptionState === null) { if (fs.existsSync(adoption)) fs.unlinkSync(adoption); } else atomicWrite(adoption, Buffer.from(journal.previousAdoptionState)); if (fs.existsSync(journalPath(root))) fs.unlinkSync(journalPath(root)); return { restored: true, backup: journal.backup };
+}
+
+export function hasInterruptedTransaction(root = process.cwd()) { const target = path.resolve(root); const file = journalPath(target); if (!fs.existsSync(file)) return false; safePath(target, '.my-workflow/transaction.json', 'transaction journal'); return true; }
+export default { prepareBackup, publish, applyTransaction, restoreInterrupted, hasInterruptedTransaction };