kodelyth-ecc 1.5.10 → 1.7.0

package/scripts/replay/bundle.js

@@ -0,0 +1,191 @@
+// =============================================================================
+// Kodelyth ECC — Session Bundle (Phase 2.8)
+//
+// Pure read/write of portable session bundles. A bundle is a single JSON file
+// that captures everything in a coordination directory:
+//
+//   .orchestration/<session>/                  ← input
+//     <worker-slug>/
+//       task.md
+//       handoff.md
+//       status.md
+//
+// Bundle format (v1):
+// {
+//   "schema":  "kodelyth.session-bundle/v1",
+//   "session": "swarm-2026-05-10-4a",
+//   "exported_at": "2026-05-10T17:30:00Z",
+//   "exported_by": "kodelyth-ecc@1.7.0",
+//   "meta": {                                  ← optional, for replay variations
+//     "task":          "audit oauth flow",
+//     "agents":        ["security-reviewer", "code-reviewer", ...],
+//     "harness":       "claude",
+//     "base_ref":      "HEAD",
+//     "repo_root":     "/path/to/repo"
+//   },
+//   "workers": [
+//     { "slug": "security-reviewer", "task": "...", "handoff": "...", "status": "..." }
+//   ]
+// }
+//
+// Pure functions, zero deps. Tested without spawning anything.
+// =============================================================================
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const BUNDLE_SCHEMA = 'kodelyth.session-bundle/v1';
+const BUNDLE_VERSION = '1.7.0';
+
+// ── Read a coordination dir into a bundle ────────────────────────────────────
+function exportBundle({ sessionDir, sessionName, meta = {} }) {
+  if (!sessionDir || typeof sessionDir !== 'string') {
+    throw new Error('exportBundle: sessionDir is required');
+  }
+  if (!fs.existsSync(sessionDir)) {
+    throw new Error(`exportBundle: session directory not found: ${sessionDir}`);
+  }
+  const session = sessionName || path.basename(sessionDir);
+
+  const entries = fs.readdirSync(sessionDir, { withFileTypes: true });
+  const workers = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const slug = entry.name;
+    const dir  = path.join(sessionDir, slug);
+    workers.push({
+      slug,
+      task:    safeRead(path.join(dir, 'task.md')),
+      handoff: safeRead(path.join(dir, 'handoff.md')),
+      status:  safeRead(path.join(dir, 'status.md')),
+    });
+  }
+
+  workers.sort((a, b) => a.slug.localeCompare(b.slug));
+
+  return {
+    schema:      BUNDLE_SCHEMA,
+    session,
+    exported_at: new Date().toISOString(),
+    exported_by: `kodelyth-ecc@${BUNDLE_VERSION}`,
+    meta:        { ...meta },
+    workers,
+  };
+}
+
+// ── Write a bundle JSON to disk ──────────────────────────────────────────────
+function writeBundle(bundle, outPath) {
+  if (!bundle || bundle.schema !== BUNDLE_SCHEMA) {
+    throw new Error(`writeBundle: invalid schema (${bundle && bundle.schema})`);
+  }
+  fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+  fs.writeFileSync(outPath, JSON.stringify(bundle, null, 2) + '\n', 'utf8');
+  return outPath;
+}
+
+// ── Read + validate a bundle file ────────────────────────────────────────────
+function readBundle(bundlePath) {
+  if (!fs.existsSync(bundlePath)) {
+    throw new Error(`readBundle: file not found: ${bundlePath}`);
+  }
+  const raw = JSON.parse(fs.readFileSync(bundlePath, 'utf8'));
+  return validateBundle(raw);
+}
+
+function validateBundle(raw) {
+  if (!raw || typeof raw !== 'object') throw new Error('bundle: not an object');
+  if (raw.schema !== BUNDLE_SCHEMA) {
+    throw new Error(`bundle: unsupported schema "${raw.schema}" (expected "${BUNDLE_SCHEMA}")`);
+  }
+  if (typeof raw.session !== 'string' || !raw.session) {
+    throw new Error('bundle: missing "session"');
+  }
+  if (!Array.isArray(raw.workers) || raw.workers.length === 0) {
+    throw new Error('bundle: "workers" must be a non-empty array');
+  }
+  for (const w of raw.workers) {
+    if (!w || typeof w.slug !== 'string') throw new Error('bundle: each worker needs a string "slug"');
+  }
+  return raw;
+}
+
+// ── Restore a bundle into a coordination dir ─────────────────────────────────
+function importBundle(bundle, { targetDir, overwrite = false } = {}) {
+  validateBundle(bundle);
+  if (!targetDir) throw new Error('importBundle: targetDir is required');
+  const dir = path.resolve(targetDir);
+  if (fs.existsSync(dir)) {
+    if (!overwrite) throw new Error(`importBundle: targetDir already exists: ${dir} (pass overwrite=true to replace)`);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+  fs.mkdirSync(dir, { recursive: true });
+  for (const w of bundle.workers) {
+    const wdir = path.join(dir, w.slug);
+    fs.mkdirSync(wdir, { recursive: true });
+    if (typeof w.task    === 'string') fs.writeFileSync(path.join(wdir, 'task.md'),    w.task,    'utf8');
+    if (typeof w.handoff === 'string') fs.writeFileSync(path.join(wdir, 'handoff.md'), w.handoff, 'utf8');
+    if (typeof w.status  === 'string') fs.writeFileSync(path.join(wdir, 'status.md'),  w.status,  'utf8');
+  }
+  return { targetDir: dir, workers: bundle.workers.map(w => w.slug) };
+}
+
+// ── Diff: compare two bundles' handoffs (for A/B replay analysis) ────────────
+function diffBundles(a, b) {
+  validateBundle(a);
+  validateBundle(b);
+
+  const aBySlug = new Map(a.workers.map(w => [w.slug, w]));
+  const bBySlug = new Map(b.workers.map(w => [w.slug, w]));
+  const allSlugs = new Set([...aBySlug.keys(), ...bBySlug.keys()]);
+
+  const out = [];
+  for (const slug of [...allSlugs].sort()) {
+    const A = aBySlug.get(slug);
+    const B = bBySlug.get(slug);
+    out.push({
+      slug,
+      in_a: !!A,
+      in_b: !!B,
+      task_changed:    !!A && !!B && (A.task    || '') !== (B.task    || ''),
+      handoff_changed: !!A && !!B && (A.handoff || '') !== (B.handoff || ''),
+      status_changed:  !!A && !!B && (A.status  || '') !== (B.status  || ''),
+      a_handoff_len: A ? (A.handoff || '').length : 0,
+      b_handoff_len: B ? (B.handoff || '').length : 0,
+    });
+  }
+  return out;
+}
+
+// ── Helper ───────────────────────────────────────────────────────────────────
+function safeRead(p) {
+  try { return fs.readFileSync(p, 'utf8'); }
+  catch { return ''; }
+}
+
+// ── Compute the next replay session name ─────────────────────────────────────
+function nextReplayName(originalSession, takenSet = new Set()) {
+  if (typeof originalSession !== 'string' || !originalSession) {
+    throw new Error('nextReplayName: originalSession is required');
+  }
+  // Strip any existing -replay-N suffix to get the canonical base.
+  const base = originalSession.replace(/-replay-\d+$/, '');
+  for (let n = 1; n < 1000; n++) {
+    const candidate = `${base}-replay-${n}`;
+    if (!takenSet.has(candidate)) return candidate;
+  }
+  throw new Error('nextReplayName: exhausted replay numbers');
+}
+
+module.exports = {
+  BUNDLE_SCHEMA,
+  BUNDLE_VERSION,
+  exportBundle,
+  writeBundle,
+  readBundle,
+  validateBundle,
+  importBundle,
+  diffBundles,
+  nextReplayName,
+};

package/scripts/replay/replay.js

@@ -0,0 +1,107 @@
+// =============================================================================
+// Kodelyth ECC — Session Replay Engine (Phase 2.8)
+//
+// Takes a bundle (or a live coordination dir) and reconstructs a swarm plan-
+// config that re-runs the same task. Supports replay variations:
+//
+//   - Different harness  (--harness codex)         — model A/B test
+//   - Different agents   (--agents new1,new2)      — agent A/B test
+//   - Different baseRef  (--base-ref main)         — re-test against new code
+//   - Different model via cost router env vars     — model A/B test
+//
+// Pure planning. The actual execution is delegated to the existing
+// orchestrator (scripts/lib/tmux-worktree-orchestrator.js).
+// =============================================================================
+
+'use strict';
+
+const path = require('path');
+
+const { buildSwarmPlan } = require('../swarm/build-plan.js');
+const { nextReplayName } = require('./bundle.js');
+
+// ── Extract a replay-able task from a bundle ─────────────────────────────────
+function extractTaskFromBundle(bundle) {
+  // Prefer explicit meta.task (set when exporting from a swarm).
+  if (bundle.meta && typeof bundle.meta.task === 'string' && bundle.meta.task.trim()) {
+    return bundle.meta.task.trim();
+  }
+  // Fallback: read the FIRST worker's task.md and strip the agent-shaped header
+  // we added in scripts/swarm/build-plan.js (shapeTaskForAgent).
+  const first = bundle.workers && bundle.workers[0];
+  if (first && typeof first.task === 'string') {
+    return extractSharedTaskFromShapedPrompt(first.task);
+  }
+  throw new Error('replay: cannot extract task — bundle has no meta.task and no worker tasks');
+}
+
+function extractSharedTaskFromShapedPrompt(prompt) {
+  // The shaped format is:
+  //   # <agent> — swarm task
+  //   ...
+  //   ## Shared Task
+  //
+  //   <THE TASK>
+  //
+  //   ## Required handoff sections
+  //   ...
+  const m = prompt.match(/##\s*Shared Task\s*\n([\s\S]*?)\n##\s*Required handoff sections/);
+  if (m) return m[1].trim();
+  // Tmux orchestrator's own task.md has "## Objective\n<task>\n## Completion".
+  const m2 = prompt.match(/##\s*Objective\s*\n([\s\S]*?)\n##\s*Completion/);
+  if (m2) return m2[1].trim();
+  // Last-resort: return the whole prompt.
+  return prompt.trim();
+}
+
+// ── Build a replay plan-config ───────────────────────────────────────────────
+function buildReplayPlanConfig(bundle, opts = {}) {
+  const {
+    repoRoot         = process.cwd(),
+    coordinationRoot,
+    worktreeRoot,
+    baseRef,
+    harness,
+    agents,                 // array | null — overrides bundle's agent list
+    sessionName,            // explicit override; otherwise auto next-replay-N
+    takenSessions = new Set(),
+    replaceExisting = false,
+    seedPaths = [],
+    launcherCmd,
+  } = opts;
+
+  const task = extractTaskFromBundle(bundle);
+
+  // Resolve which agents to run.
+  let agentList;
+  if (Array.isArray(agents) && agents.length > 0) {
+    agentList = agents.slice();
+  } else if (bundle.meta && Array.isArray(bundle.meta.agents) && bundle.meta.agents.length > 0) {
+    agentList = bundle.meta.agents.slice();
+  } else {
+    agentList = bundle.workers.map(w => w.slug);
+  }
+
+  // Resolve session name.
+  const session = sessionName || nextReplayName(bundle.session, takenSessions);
+
+  return buildSwarmPlan({
+    task,
+    agents:           agentList,
+    harness:          harness          || (bundle.meta && bundle.meta.harness)  || 'claude',
+    launcherCmd,
+    sessionName:      session,
+    repoRoot,
+    worktreeRoot,
+    coordinationRoot,
+    baseRef:          baseRef          || (bundle.meta && bundle.meta.base_ref) || 'HEAD',
+    seedPaths,
+    replaceExisting,
+  });
+}
+
+module.exports = {
+  extractTaskFromBundle,
+  extractSharedTaskFromShapedPrompt,
+  buildReplayPlanConfig,
+};

package/scripts/router/classify.js

@@ -0,0 +1,232 @@
+// =============================================================================
+// Kodelyth ECC — Cost-Aware Model Router (Classifier + Config Loader)
+//
+// Pure-function task classifier. Given a task description and optional
+// signals (file count, agent in scope, security flags, etc.), returns a
+// recommended tier ("trivial" | "standard" | "hard") plus the top reasons.
+//
+// Used by:
+//   - npx kodelyth-ecc route <task...>      ad-hoc CLI
+//   - skills/cost-aware-model-routing       explicit invocation
+//   - any future hook that wants a hint
+//
+// Pure JS, zero deps, deterministic.
+// =============================================================================
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+// ── Defaults (provider-agnostic) ─────────────────────────────────────────────
+const DEFAULT_MODELS = {
+  trivial:  'claude-haiku-4-5-20251001',
+  standard: 'claude-sonnet-4-6',
+  hard:     'claude-opus-4-1',
+  default:  'standard',
+};
+
+// Agents that should NEVER downgrade — security / incident / adversarial work.
+const HARD_TIER_AGENTS = new Set([
+  'security-reviewer', 'incident-commander', 'debug-detective',
+  'prompt-injection-hunter', 'supply-chain-auditor', 'secret-hunter',
+  'backdoor-hunter', 'chaos-engineer', 'jailbreak-tester',
+  'code-stealer-detector', 'license-violation-finder',
+  'code-architect', 'architect',
+]);
+
+// ── Signal catalogues ────────────────────────────────────────────────────────
+const TRIVIAL_SIGNALS = [
+  { id: 'rename',      regex: /\b(rename|renaming)\b/i },
+  { id: 'format',      regex: /\b(format|formatting|prettier|biome|reformat)\b/i },
+  { id: 'typo',        regex: /\b(typo|misspell|spelling)\b/i },
+  { id: 'doc-comment', regex: /\b(jsdoc|tsdoc|docstring|add comments?|add docs?)\b/i },
+  { id: 'capitalize',  regex: /\b(capitali[sz]e|lowercase|uppercase|kebab-case|snake_case|camelCase)\b/i },
+  { id: 'list-files',  regex: /\b(list|count|enumerate)\s+(files?|imports?|exports?|functions?)\b/i },
+  { id: 'summarize',   regex: /\b(summari[sz]e|tl;?dr|short summary)\b/i },
+  { id: 'version-bump',regex: /\b(version\s+bump|bump\s+(version|deps?))\b/i },
+  { id: 'simple-regex',regex: /\b(simple\s+regex|one[\s-]liner|small\s+regex)\b/i },
+];
+
+const HARD_SIGNALS = [
+  { id: 'production',  regex: /\b(production|prod|live|outage|incident|down|leaking|on[\s-]?call|p[01]|sev[12])\b/i, weight: 3 },
+  { id: 'security',    regex: /\b(security|vuln(?:erability)?|cve|exploit|injection|auth(?:n|z)?\s+(?:bypass|flaw)|secrets?\s+(?:leak|exposure))\b/i, weight: 3 },
+  { id: 'architecture',regex: /\b(architect(?:ure|ural)?\s+(?:decision|design|review|trade[\s-]?off)|design\s+review|adr|RFC)\b/i, weight: 2 },
+  { id: 'multi-file',  regex: /\b(across\s+(?:the\s+)?(?:codebase|repo|project)|every(?:where)?|all\s+(?:files|modules|services))\b/i, weight: 2 },
+  { id: 'concurrency', regex: /\b(race\s+condition|deadlock|concurrency|thread[\s-]safe|atomic|mutex|lock)\b/i, weight: 2 },
+  { id: 'urgent',      regex: /\b(urgent|asap|right\s+now|emergency|critical(?:al)?ly|fire|burning)\b/i, weight: 2 },
+  { id: 'devil-mode',  regex: /\b(\/devil-mode|devil[\s-]?mode|red[\s-]?team|adversarial)\b/i, weight: 3 },
+  { id: 'incident',    regex: /\bincident[\s-]?(commander|response|triage|postmortem|post[\s-]?mortem)\b/i, weight: 3 },
+];
+
+const STANDARD_SIGNALS = [
+  { id: 'review-pr',   regex: /\b(review\s+(?:this\s+)?pr|code\s+review|pr\s+review)\b/i },
+  { id: 'write-test',  regex: /\b(write\s+(?:a\s+)?(?:unit\s+)?tests?|add\s+tests?)\b/i },
+  { id: 'fix-bug',     regex: /\b(fix\s+(?:this\s+)?bug|debug\s+this|why\s+is\s+this\s+failing)\b/i },
+  { id: 'refactor',    regex: /\brefactor(?:ing)?\b/i },
+  { id: 'optimize',    regex: /\b(optimi[sz]e|speed\s+up|improve\s+performance)\b/i },
+  { id: 'doc-section', regex: /\b(write\s+docs?|document(?:ation)?\s+for)\b/i },
+];
+
+// ── Token utilities ──────────────────────────────────────────────────────────
+function chars(s) { return typeof s === 'string' ? s.length : 0; }
+
+// ── Main classifier ──────────────────────────────────────────────────────────
+function classify(task, opts = {}) {
+  if (!task || typeof task !== 'string') {
+    return { tier: 'standard', reasons: ['no task text — defaulting to standard'], score: { trivial: 0, standard: 0, hard: 0 } };
+  }
+  const t = task.trim();
+  const len = chars(t);
+
+  const fileCount = Number(opts.file_count) || 0;
+  const activeAgent = String(opts.active_agent || '').trim();
+  const sessionTokens = Number(opts.session_tokens) || 0;
+  const budgetTokens = Number(opts.budget_tokens) || 0;
+  const explicitTier = opts.explicit_tier; // if user set --model X, we respect it.
+
+  const score = { trivial: 0, standard: 0, hard: 0 };
+  const reasons = [];
+
+  // ── HARD: agent in scope ────────────────────────────────────────────────────
+  if (activeAgent && HARD_TIER_AGENTS.has(activeAgent)) {
+    score.hard += 4;
+    reasons.push(`active agent "${activeAgent}" never downgrades`);
+  }
+
+  // ── HARD signals ────────────────────────────────────────────────────────────
+  for (const s of HARD_SIGNALS) {
+    if (s.regex.test(t)) {
+      score.hard += s.weight;
+      reasons.push(`hard:${s.id}`);
+    }
+  }
+
+  // ── STANDARD signals ────────────────────────────────────────────────────────
+  for (const s of STANDARD_SIGNALS) {
+    if (s.regex.test(t)) {
+      score.standard += 1;
+      reasons.push(`standard:${s.id}`);
+    }
+  }
+
+  // ── TRIVIAL signals ─────────────────────────────────────────────────────────
+  for (const s of TRIVIAL_SIGNALS) {
+    if (s.regex.test(t)) {
+      score.trivial += 1;
+      reasons.push(`trivial:${s.id}`);
+    }
+  }
+
+  // ── File-count signals ──────────────────────────────────────────────────────
+  if (fileCount >= 4) {
+    score.hard += 2;
+    reasons.push(`file_count=${fileCount} ≥ 4 (multi-file refactor)`);
+  } else if (fileCount === 0 && len < 80 && score.hard === 0) {
+    score.trivial += 1;
+    reasons.push(`short task (${len} chars), no files in scope`);
+  } else if (fileCount >= 1 && fileCount <= 3) {
+    score.standard += 1;
+    reasons.push(`file_count=${fileCount} (focused scope)`);
+  }
+
+  // ── Length signals ──────────────────────────────────────────────────────────
+  if (len > 800 && score.trivial === 0) {
+    score.standard += 1;
+    reasons.push(`long task description (${len} chars)`);
+  }
+
+  // ── Budget pressure: bias one tier downward when ambiguous ──────────────────
+  if (budgetTokens > 0 && sessionTokens / budgetTokens > 0.7 && score.hard === 0) {
+    if (score.standard > 0) {
+      score.trivial += 1;
+      reasons.push('budget > 70% — biasing downward when standard/trivial tied');
+    }
+  }
+
+  // ── Tier resolution ─────────────────────────────────────────────────────────
+  // Hard rules first.
+  if (score.hard >= 2) {
+    return { tier: 'hard', reasons, score, explicit_tier: explicitTier || null };
+  }
+
+  // Trivial wins ONLY if it dominates and no hard signal at all.
+  if (score.hard === 0 && score.trivial > 0 && score.trivial >= score.standard) {
+    return { tier: 'trivial', reasons, score, explicit_tier: explicitTier || null };
+  }
+
+  // Anything with a hard signal but not enough weight → standard (defensive).
+  if (score.hard > 0) {
+    return { tier: 'standard', reasons: [...reasons, 'hard signal present but weight < 2 → defensive standard'], score, explicit_tier: explicitTier || null };
+  }
+
+  return { tier: 'standard', reasons, score, explicit_tier: explicitTier || null };
+}
+
+// ── Config loader (env vars + .kodelyth/router.json) ─────────────────────────
+function loadConfig({ projectRoot = process.cwd() } = {}) {
+  const cfg = { ...DEFAULT_MODELS, notes: '' };
+
+  // 1. Project-level override.
+  try {
+    const file = path.join(projectRoot, '.kodelyth', 'router.json');
+    if (fs.existsSync(file)) {
+      const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+      for (const k of ['trivial', 'standard', 'hard', 'default', 'notes']) {
+        if (typeof raw[k] === 'string') cfg[k] = raw[k];
+      }
+    }
+  } catch { /* ignore — fall back to defaults */ }
+
+  // 2. Env-var override (highest precedence).
+  if (process.env.KODELYTH_ROUTER_TRIVIAL)  cfg.trivial  = process.env.KODELYTH_ROUTER_TRIVIAL;
+  if (process.env.KODELYTH_ROUTER_STANDARD) cfg.standard = process.env.KODELYTH_ROUTER_STANDARD;
+  if (process.env.KODELYTH_ROUTER_HARD)     cfg.hard     = process.env.KODELYTH_ROUTER_HARD;
+  if (process.env.KODELYTH_ROUTER_DEFAULT)  cfg.default  = process.env.KODELYTH_ROUTER_DEFAULT;
+
+  cfg.disabled = String(process.env.KODELYTH_ROUTER || '').toLowerCase() === 'off';
+  return cfg;
+}
+
+// ── Recommend (combines classify + config) ───────────────────────────────────
+function recommend(task, opts = {}) {
+  const cfg = loadConfig({ projectRoot: opts.project_root });
+  if (cfg.disabled) {
+    return {
+      disabled: true,
+      tier: 'unknown',
+      model: opts.current_model || null,
+      reasons: ['KODELYTH_ROUTER=off — router disabled'],
+      config: cfg,
+    };
+  }
+  const cls = classify(task, opts);
+  const tier = cls.tier;
+  const recommendedModel = cfg[tier] || cfg.standard;
+  const currentModel = opts.current_model || null;
+  const mismatched = !!currentModel && currentModel !== recommendedModel;
+
+  return {
+    disabled: false,
+    tier,
+    recommended_model: recommendedModel,
+    current_model: currentModel,
+    mismatched,
+    reasons: cls.reasons,
+    score: cls.score,
+    notes: cfg.notes || '',
+    config: cfg,
+  };
+}
+
+module.exports = {
+  DEFAULT_MODELS,
+  HARD_TIER_AGENTS,
+  TRIVIAL_SIGNALS,
+  STANDARD_SIGNALS,
+  HARD_SIGNALS,
+  classify,
+  loadConfig,
+  recommend,
+};

package/scripts/supply-chain/manifest.js

@@ -0,0 +1,154 @@
+// scripts/supply-chain/manifest.js
+//
+// Content manifest generator for kodelyth-ecc.
+//
+// Walks every shipped asset directory, computes sha256 of each file, and
+// produces a stable, deterministic JSON manifest.
+//
+// The manifest is the "ground truth" for `kodelyth-ecc verify`: an installed
+// copy is compared file-by-file against this manifest.
+//
+// Pure functions — no network, no external deps.
+//
+// Exports:
+//   - MANIFEST_SCHEMA
+//   - SHIPPED_DIRS                 (default list of asset directories)
+//   - generateManifest({ rootDir, dirs?, timestamp? })
+//   - hashFile(absPath)
+//   - walkFiles(rootDir, dirs)     (iterator-friendly array, sorted)
+//
+'use strict';
+
+const fs     = require('fs');
+const path   = require('path');
+const crypto = require('crypto');
+
+const MANIFEST_SCHEMA  = 'kodelyth.content-manifest/v1';
+const MANIFEST_VERSION = 1;
+
+// Directories whose contents are considered part of the shipped artifact.
+// Order doesn't matter — output is sorted by relative path.
+const SHIPPED_DIRS = [
+  'agents',
+  'skills',
+  'commands',
+  'rules',
+  'hooks',
+  'scripts',
+  'bin',
+  'parallel-commands',
+  'bundles',
+];
+
+// Files that should be included individually from the repo root.
+const SHIPPED_ROOT_FILES = [
+  'package.json',
+  'README.md',
+  'CHANGELOG.md',
+  'VERSION',
+  'install.sh',
+  'install.ps1',
+];
+
+// Patterns to skip even within shipped dirs.
+const SKIP_PATTERNS = [
+  /\/\.DS_Store$/,
+  /\/node_modules\//,
+  /\/\.git\//,
+  /\/__pycache__\//,
+  /\.pyc$/,
+];
+
+function isSkipped(absPath) {
+  return SKIP_PATTERNS.some(p => p.test(absPath));
+}
+
+function hashFile(absPath) {
+  const buf = fs.readFileSync(absPath);
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function* walkRecursive(absDir) {
+  let entries;
+  try { entries = fs.readdirSync(absDir, { withFileTypes: true }); }
+  catch { return; }
+  // Sort for stability.
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const e of entries) {
+    const abs = path.join(absDir, e.name);
+    if (isSkipped(abs)) continue;
+    if (e.isDirectory()) yield* walkRecursive(abs);
+    else if (e.isFile()) yield abs;
+  }
+}
+
+function walkFiles(rootDir, dirs = SHIPPED_DIRS, rootFiles = SHIPPED_ROOT_FILES) {
+  if (!rootDir) throw new Error('walkFiles: rootDir is required');
+  const out = [];
+
+  for (const file of rootFiles) {
+    const abs = path.join(rootDir, file);
+    if (fs.existsSync(abs) && fs.statSync(abs).isFile() && !isSkipped(abs)) {
+      out.push(abs);
+    }
+  }
+
+  for (const dir of dirs) {
+    const abs = path.join(rootDir, dir);
+    if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory()) continue;
+    for (const f of walkRecursive(abs)) out.push(f);
+  }
+
+  // Final sort by relative path so manifest output is deterministic.
+  return out.sort((a, b) => a.localeCompare(b));
+}
+
+function generateManifest({ rootDir, dirs, rootFiles, timestamp } = {}) {
+  if (!rootDir) throw new Error('generateManifest: rootDir is required');
+  const files = walkFiles(rootDir, dirs, rootFiles);
+
+  const pkgPath = path.join(rootDir, 'package.json');
+  let pkgName = 'kodelyth-ecc';
+  let pkgVersion = '0.0.0';
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    pkgName = pkg.name || pkgName;
+    pkgVersion = pkg.version || pkgVersion;
+  } catch { /* leave defaults */ }
+
+  const entries = files.map(abs => {
+    const rel = path.relative(rootDir, abs).split(path.sep).join('/');
+    const stat = fs.statSync(abs);
+    return {
+      path:   rel,
+      size:   stat.size,
+      sha256: hashFile(abs),
+    };
+  });
+
+  // Compute a manifest-level digest = sha256 over the deterministic JSON of entries.
+  const entriesJson = JSON.stringify(entries);
+  const manifestDigest = crypto.createHash('sha256').update(entriesJson).digest('hex');
+
+  return {
+    schema:    MANIFEST_SCHEMA,
+    version:   MANIFEST_VERSION,
+    package:   pkgName,
+    pkg_version: pkgVersion,
+    generated_at: timestamp || new Date().toISOString(),
+    file_count:   entries.length,
+    digest:       manifestDigest,
+    files:        entries,
+  };
+}
+
+module.exports = {
+  MANIFEST_SCHEMA,
+  MANIFEST_VERSION,
+  SHIPPED_DIRS,
+  SHIPPED_ROOT_FILES,
+  SKIP_PATTERNS,
+  generateManifest,
+  hashFile,
+  walkFiles,
+};