just-vibe 0.7.0

package/plugins/just-vibe/scripts/lib/project.mjs

@@ -0,0 +1,60 @@
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { join, resolve, relative } from 'node:path';
+import { spawnSync } from 'node:child_process';
+export { findExecutable } from './command.mjs';
+
+const ignored = new Set(['.git', 'node_modules', '.venv', 'venv', 'dist', 'build', 'coverage', '.next', '.tmp', '.cache', '.codex', '.claude']);
+const secretName = /(?:^\.env(?:\.|$)|\.(?:pem|key|p12|pfx)$|credentials|secrets?\.)/i;
+const interesting = /^(?:AGENTS\.md|CLAUDE\.md|README(?:\.md)?|package\.json|pyproject\.toml|requirements[^/]*\.txt|Cargo\.toml|go\.mod|Dockerfile[^/]*|compose\.ya?ml|(?:vite|next|vitest|jest|playwright)\.config\.[a-z]+|vercel\.json|prisma\.schema|schema\.prisma|Gemfile|pom\.xml|Makefile)$/;
+
+export function gitRead(root, args) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.startsWith('GIT_')));
+  const result = spawnSync('git', ['--no-optional-locks', '--no-pager', '--no-replace-objects', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
+    encoding: 'utf8', timeout: 5000, maxBuffer: 512 * 1024, shell: false, stdio: ['ignore', 'pipe', 'pipe'],
+    env: { ...env, GIT_TERMINAL_PROMPT: '0' },
+  });
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+export function inspectProject(path = process.cwd(), { maxEntries = 3000, maxDepth = 5, git = gitRead } = {}) {
+  if (!Number.isInteger(maxEntries) || maxEntries < 1 || maxEntries > 10000) throw new Error('Invalid inspection entry budget.');
+  if (!Number.isInteger(maxDepth) || maxDepth < 0 || maxDepth > 10) throw new Error('Invalid inspection depth.');
+  const root = realpathSync(resolve(path));
+  if (!statSync(root).isDirectory()) throw new Error('Project root must be a directory.');
+  const manifests = [], packages = [], instructions = [], errors = [];
+  let scanned = 0, truncated = false;
+  const queue = [{ path: root, depth: 0 }];
+  while (queue.length && scanned < maxEntries) {
+    const current = queue.shift();
+    let entries;
+    try { entries = readdirSync(current.path, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name)); }
+    catch { errors.push(`Cannot read directory: ${relative(root, current.path) || '.'}`); continue; }
+    for (const entry of entries) {
+      if (++scanned > maxEntries) { truncated = true; break; }
+      if (entry.isSymbolicLink() || ignored.has(entry.name) || secretName.test(entry.name)) continue;
+      const file = join(current.path, entry.name);
+      if (entry.isDirectory()) {
+        if (current.depth < maxDepth) queue.push({ path: file, depth: current.depth + 1 });
+        else truncated = true;
+        continue;
+      }
+      if (!entry.isFile() || !interesting.test(entry.name)) continue;
+      const rel = relative(root, file);
+      manifests.push(rel);
+      if (['AGENTS.md', 'CLAUDE.md'].includes(entry.name)) instructions.push(rel);
+      if (entry.name === 'package.json') {
+        try {
+          if (statSync(file).size > 256 * 1024) throw new Error('size');
+          const pkg = JSON.parse(readFileSync(file, 'utf8'));
+          packages.push({ path: rel, scripts: Object.keys(pkg.scripts || {}),
+            dependencies: Object.keys({ ...pkg.dependencies, ...pkg.devDependencies }).sort() });
+        } catch { errors.push(`Cannot parse bounded manifest: ${rel}`); }
+      }
+    }
+  }
+  if (queue.length) truncated = true;
+  const gitRoot = git(root, ['rev-parse', '--show-toplevel']);
+  return { root, manifests, packages, instructions, errors, truncated, scanned: Math.min(scanned, maxEntries),
+    git: gitRoot ? { root: gitRoot, head: git(root, ['rev-parse', '--verify', 'HEAD']), branch: git(root, ['symbolic-ref', '--quiet', '--short', 'HEAD']) } : null,
+    note: 'Read-only inventory. Script names are discovered, not executed. No environment values, config code, hooks, or package scripts are evaluated. Ancestor instructions must also be read by the host.' };
+}

package/plugins/just-vibe/scripts/lib/routing.mjs

@@ -0,0 +1,82 @@
+import { inspectProject } from './project.mjs';
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { readPreferences } from './continuity.mjs';
+
+const starter = ['auto', 'fix', 'explain', 'plan', 'review', 'test', 'teach', 'tools', 'profile', 'checkpoint', 'resume', 'help'];
+const intents = [
+  { test: /\b(?:claude|agents)\.md\b|\b(?:save|remember|persist|preserve)\b.*\b(?:conversation|project instructions|context|decisions|corrections)\b/i, ids: ['remember'], reason: 'Durable project instructions from conversation context' },
+  { test: /\b(?:ci|checks?|actions|pipeline)\b.*\b(?:fail|broken|red)|\b(?:fail|broken|red)\w*\b.*\b(?:ci|checks?|actions|pipeline)\b/i, ids: ['github-fix-ci', 'github-actions'], reason: 'Failing CI/checks' },
+  { test: /\b(?:refresh|oauth|login|logout|session|password reset|authentication)\b/i, ids: ['backend-auth'], reason: 'Identity or session lifecycle' },
+  { test: /\b(?:dialog|combobox|date picker|datepicker|component)\b/i, ids: ['react-component', 'ui-component'], reason: 'Component interaction contract' },
+  { test: /\b(?:race|stale|out.of.order)\b.*\b(?:request|response|fetch)|\b(?:request|response|fetch)\b.*\b(?:race|stale|out.of.order)\b/i, ids: ['react-async', 'backend-concurrency'], reason: 'Request ordering and ownership' },
+  { test: /\b(?:freeze|freezes|slow|rerender|re-render)\b.*\b(?:filter|grid|render|component)|\b(?:filter|grid|render|component)\b.*\b(?:freeze|freezes|slow|rerender|re-render)\b/i, ids: ['react-rerenders'], reason: 'Slow UI interaction' },
+  { test: /\b(?:offline|validation)\b.*\b(?:production|serving|live)\b/i, ids: ['ml-parity', 'ml-leakage'], reason: 'Offline versus serving mismatch' },
+  { test: /\b(?:leakage|future information|look.?ahead|point.in.time)\b/i, ids: ['ml-leakage', 'ml-features'], reason: 'Prediction-time information boundary' },
+  { test: /\b(?:train|training)\b.*\b(?:resume|checkpoint|interrupt)|\b(?:resume|checkpoint)\b.*\b(?:train|training)\b/i, ids: ['ml-train', 'ml-reproduce'], reason: 'Training continuation state' },
+  { test: /\b(?:vercel|preview|deployment)\b.*\b(?:build|fail|broken)|\bbuild\b.*\b(?:vercel|preview|deployment)\b/i, ids: ['vercel-build-fix'], reason: 'Deployment build diagnosis' },
+  { test: /\b(?:migration|migrations|schema change)\b/i, ids: ['db-migrate'], reason: 'Schema rollout and recovery' },
+  { test: /\b(?:partial|staged|unstaged|only these|selected files)\b.*\bcommit|\bcommit\b.*\b(?:partial|staged|unstaged|only these|selected files)\b/i, ids: ['git-commit', 'git-split'], reason: 'Commit scope and index preservation' },
+  { test: /\b(?:which|compare|choose|trade.?off|decide)\b/i, ids: ['decide'], reason: 'A decision rather than immediate implementation' },
+];
+const stackPacks = { react: ['react', 'ui'], vite: ['vite'], next: ['react', 'ui', 'vercel'], prisma: ['database'], torch: ['ml-experiments', 'ml-data'], 'scikit-learn': ['ml-experiments', 'ml-data'], django: ['backend'], fastapi: ['backend'], postgres: ['database'] };
+
+export function routeContext(root) {
+  const project = inspectProject(root);
+  const dependencies = new Set(project.packages.flatMap(p => p.dependencies));
+  for (const manifest of project.manifests.filter(p => /(?:pyproject\.toml|requirements[^/]*\.txt)$/.test(p))) {
+    const path = join(project.root, manifest);
+    if (statSync(path).size <= 256 * 1024) {
+      const source = readFileSync(path, 'utf8');
+      for (const dependency of ['torch', 'scikit-learn', 'django', 'fastapi']) if (new RegExp(`(?:^|[\\s"'\\[,])${dependency}(?=[\\s"'\\]<>=!~;]|$)`, 'mi').test(source)) dependencies.add(dependency);
+    }
+  }
+  // Parse bounded manifest text only; never import framework configuration.
+  const frameworks = Object.keys(stackPacks).filter(key => dependencies.has(key) || (key === 'prisma' && dependencies.has('@prisma/client')));
+  let preferences = null, preferenceError = null;
+  try { preferences = readPreferences(root)?.preferences || null; } catch (error) { preferenceError = error.message; }
+  return { frameworks, packs: [...new Set(frameworks.flatMap(f => stackPacks[f]))], manifests: project.manifests, packages: project.packages.map(p => p.path), truncated: project.truncated,
+    preferences, preferenceError, preferencePolicy: 'Saved context only. The host must resolve conflicts with the current request; a saved profile is not an active pin or permission.' };
+}
+
+export function intentSignals(brief) {
+  // Ignore ordinary negative clauses for ranking only. The full brief is returned unchanged.
+  const excluded = [...brief.matchAll(/\b(?:do not|don't|never|without)\s+([^.;\n]+)/gi)].map(m => m[0]);
+  const positive = brief.replace(/\b(?:do not|don't|never|without)\s+[^.;\n]+/gi, ' ');
+  return { positive, excluded, matches: intents.filter(rule => rule.test.test(positive)) };
+}
+
+export function rankCandidates(candidates, brief, context) {
+  const { positive, excluded, matches } = intentSignals(brief);
+  const named = new Set((positive.match(/\b[a-z][a-z0-9]*(?:-[a-z0-9]+)+\b/g) || []));
+  return candidates.map(c => {
+    const reasons = [];
+    let score = c.score;
+    if (named.has(c.id) || c.matchedNames.some(id => named.has(id))) { score += 1000; reasons.push('Workflow named explicitly'); }
+    for (const rule of matches) if (rule.ids.includes(c.id)) { score += 45 - rule.ids.indexOf(c.id) * 8; reasons.push(rule.reason); }
+    if (context.packs.includes(c.pack)) { score += 10; reasons.push(`Fits detected ${context.frameworks.join(', ')} project`); }
+    if (c.status === 'available') { score += 3; reasons.push('Declared prerequisites observed'); }
+    else reasons.push(`Prerequisites ${c.status}; inspect before execution`);
+    if (!reasons.length) reasons.push('Request terms match this workflow');
+    return { ...c, score, selectionReasons: reasons, excludedClauses: excluded };
+  }).sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+}
+
+export function executionStrategy(brief, candidates = []) {
+  const { positive } = intentSignals(brief);
+  const reasons = [];
+  if (/\b(?:deploy|publish|push|merge|provision|production migration|paid|purchase)\b/i.test(positive)) reasons.push('External or consequential effects need explicit tracking');
+  if (/\b(?:resume|interrupted|handoff|checkpoint|record every|track every)\b/i.test(positive)) reasons.push('Continuation or recorded history requested');
+  if ((positive.match(/\b(?:then|after that|next|finally)\b|\n\s*\d+[.)]/gi) || []).length >= 2) reasons.push('Several dependent stages');
+  if (candidates.slice(0, 3).filter(c => c.status !== 'available').length === 3) reasons.push('Selected route needs unresolved capabilities');
+  return { suggested: reasons.length ? 'tracked' : 'quick', reasons: reasons.length ? reasons : ['Start with a bounded local workflow; escalate if dependencies, retries or effects make tracking useful'], instruction: 'A suggestion, not a permission decision. The host resolves actual scope and effects. Quick work still preserves constraints, verifies results and reports limitations; switching to tracked work retains prior evidence and consumed budgets.' };
+}
+
+export function starterIds(context) {
+  const additions = [];
+  if (context.frameworks.includes('react') || context.frameworks.includes('next')) additions.push('react-component', 'react-async');
+  if (context.frameworks.includes('vite')) additions.push('vite-bundle');
+  if (context.frameworks.includes('prisma')) additions.push('db-migrate');
+  if (context.frameworks.includes('torch') || context.frameworks.includes('scikit-learn')) additions.push('ml-train', 'ml-evaluate');
+  return [...new Set([...starter, ...additions])];
+}

package/plugins/just-vibe/scripts/lib/run.mjs

@@ -0,0 +1,248 @@
+import { randomUUID } from 'node:crypto';
+import { realpathSync, lstatSync, statSync } from 'node:fs';
+import { resolve, dirname, relative, isAbsolute } from 'node:path';
+import { getCommand, availability, MODES } from './catalog.mjs';
+import { loadProfiles, selectProfiles, validateProfileSelection } from './profiles.mjs';
+
+const terminal = new Set(['completed', 'partial', 'blocked', 'failed', 'cancelled']);
+const effects = new Set(['read', 'plan-artifact', 'local-write', 'external-write', 'destructive', 'paid']);
+const clone = value => structuredClone(value);
+const required = (value, name) => {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${name} is required.`);
+  return value;
+};
+function positive(value, name, max) {
+  if (!Number.isInteger(value) || value < 1 || value > max) throw new Error(`${name} must be an integer from 1 to ${max}.`);
+  return value;
+}
+
+export function insideProject(root, path) {
+  const base = realpathSync(resolve(root));
+  const target = resolve(base, path);
+  // Resolve the closest existing ancestor so a missing leaf cannot hide a symlink escape.
+  let ancestor = target;
+  while (true) {
+    try { lstatSync(ancestor); break; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    const next = dirname(ancestor);
+    if (next === ancestor) throw new Error('Cannot resolve target path.');
+    ancestor = next;
+  }
+  const actual = resolve(realpathSync(ancestor), relative(ancestor, target));
+  const rel = relative(base, actual);
+  if (rel === '..' || rel.startsWith('../') || rel.startsWith('..\\') || isAbsolute(rel)) throw new Error('Target escapes the selected project.');
+  if (rel.split(/[\\/]/).includes('.git')) throw new Error('Do not modify Git internals through a workflow target.');
+  return actual;
+}
+
+export function createRun(catalog, invokedAs, options, now = Date.now()) {
+  const command = getCommand(catalog, invokedAs, { canonical: true });
+  const brief = required(options.brief, 'Original brief');
+  const root = realpathSync(resolve(options.root || process.cwd()));
+  if (!statSync(root).isDirectory()) throw new Error('Run root must be a directory.');
+  const mode = options.mode || command.defaultMode;
+  if (!MODES.includes(mode)) throw new Error('Invalid mode.');
+  const context = options.context || {};
+  if (context.profile !== undefined && context.profile !== null) validateProfileSelection(loadProfiles(), context.profile);
+  if (options.profile && context.profile) throw new Error('Use --profile or context.profile, not both.');
+  const profile = options.profile ? selectProfiles(loadProfiles(), { primary: options.profile, selectedBy: 'user', reason: 'Explicit workflow profile option.' }) : context.profile;
+  for (const key of ['constraints', 'references', 'successCriteria', 'assumptions', 'authorization']) {
+    if (context[key] !== undefined && !Array.isArray(context[key])) throw new Error(`context.${key} must be an array.`);
+  }
+  const scope = options.scope ? insideProject(root, options.scope) : root;
+  const budget = {
+    maxStages: positive(options.budget?.maxStages ?? 8, 'maxStages', 100),
+    maxAttempts: positive(options.budget?.maxAttempts ?? 3, 'maxAttempts', 20),
+    maxMinutes: positive(options.budget?.maxMinutes ?? 60, 'maxMinutes', 1440),
+  };
+  return { schemaVersion: 1, id: randomUUID(), invokedAs, command: command.id, root, scope, mode,
+    brief, context: { objective: brief, constraints: [], references: [], successCriteria: [], assumptions: [], authorization: [], ...clone(context), ...(profile ? { profile: clone(profile) } : {}) },
+    budget, createdAt: new Date(now).toISOString(), status: 'ready', stages: [],
+    note: 'This record validates workflow state. It does not sandbox the host or independently prove evidence/authorization. Host tool permissions still apply.' };
+}
+
+export function validateRun(run) {
+  if (run?.schemaVersion !== 1 || !Array.isArray(run.stages) || !MODES.includes(run.mode)
+      || !['ready', 'running', ...terminal].includes(run.status)) throw new Error('Invalid run record.');
+  required(run.id, 'Run id'); required(run.brief, 'Original brief');
+  required(run.root, 'Root'); required(run.scope, 'Scope');
+  if (!run.context || !Array.isArray(run.context.authorization) || !Array.isArray(run.context.successCriteria)) throw new Error('Invalid run context.');
+  if (run.context.profile !== undefined && run.context.profile !== null) validateProfileSelection(loadProfiles(), run.context.profile);
+  for (const [name, max] of [['maxStages', 100], ['maxAttempts', 20], ['maxMinutes', 1440]]) positive(run.budget?.[name], name, max);
+  if (!Number.isFinite(Date.parse(run.createdAt))) throw new Error('Invalid run timestamp.');
+  return run;
+}
+
+export function setRunProfiles(run, request, now = Date.now()) {
+  active(run, now);
+  const selection = selectProfiles(loadProfiles(), request, run.context.profile);
+  const result = clone(run);
+  result.context.profile = selection;
+  result.profileHistory ??= [];
+  result.profileHistory.push({ previous: clone(run.context.profile ?? null), next: clone(selection), selectedBy: request.selectedBy,
+    reason: request.reason, changedAt: new Date(now).toISOString() });
+  return result;
+}
+
+function active(run, now) {
+  validateRun(run);
+  if (terminal.has(run.status)) throw new Error(`Run is ${run.status}; resume explicitly before continuing.`);
+  if (now - Date.parse(run.createdAt) >= run.budget.maxMinutes * 60000) throw new Error('Run time budget exhausted.');
+}
+
+export function authorizeEffect(run, { effect, target, action }) {
+  if (!effects.has(effect)) throw new Error('Unknown effect class.');
+  required(target, 'Action target'); required(action, 'Action description');
+  if (run.mode === 'inspect' && effect !== 'read') throw new Error('Inspect mode permits read-only stages.');
+  if (run.mode === 'plan' && !['read', 'plan-artifact'].includes(effect)) throw new Error('Plan mode cannot execute changes.');
+  if (['local-write', 'plan-artifact'].includes(effect)) {
+    const path = insideProject(run.root, target);
+    const scope = insideProject(run.root, run.scope);
+    const rel = relative(scope, path);
+    if (rel === '..' || rel.startsWith('../') || rel.startsWith('..\\') || isAbsolute(rel)) throw new Error('Write target escapes requested scope.');
+  }
+  if (['plan-artifact', 'external-write', 'destructive', 'paid'].includes(effect)) {
+    const grant = run.context.authorization.find(a => {
+      if (a?.effect !== effect || a.action !== action || typeof a.basis !== 'string' || !a.basis.trim()) return false;
+      if (effect !== 'plan-artifact') return a.target === target;
+      try { return insideProject(run.root, a.target) === insideProject(run.root, target); } catch { return false; }
+    });
+    if (!grant) throw new Error('Missing exact action/target authorization from the user session.');
+  }
+}
+
+export function startStage(catalog, run, request, capabilities, host = 'claude', now = Date.now()) {
+  active(run, now);
+  if (run.stages.some(s => s.status === 'running')) throw new Error('Finish the running stage before starting another.');
+  const command = getCommand(catalog, request.command, { canonical: true });
+  if (command.id === 'auto') throw new Error('Recursive auto/do routing is not allowed.');
+  if (availability(catalog, command, capabilities, host).status !== 'available') throw new Error(`Workflow prerequisites are not verified: ${command.id}`);
+  const id = request.id || randomUUID();
+  let stage = run.stages.find(s => s.id === id);
+  if (stage) {
+    if (!['failed', 'blocked'].includes(stage.status) || stage.command !== command.id) throw new Error('Only the same failed or blocked stage may be retried.');
+    if (stage.attempts.length >= run.budget.maxAttempts) throw new Error('Stage retry budget exhausted.');
+    required(request.newEvidence, 'New evidence supporting retry');
+  } else if (run.stages.length >= run.budget.maxStages) throw new Error('Workflow stage budget exhausted.');
+  const effect = request.effect || 'read';
+  const target = request.target || run.scope;
+  const action = required(request.action, 'Stage action');
+  authorizeEffect(run, { effect, target, action });
+  const result = clone(run);
+  stage = result.stages.find(s => s.id === id);
+  if (!stage) { stage = { id, command: command.id, attempts: [] }; result.stages.push(stage); }
+  stage.status = 'running';
+  stage.attempts.push({ effect, target, action, startedAt: new Date(now).toISOString(), newEvidence: request.newEvidence || null });
+  result.status = 'running';
+  return result;
+}
+
+function checkEvidence(evidence, criteria, completed) {
+  if (!Array.isArray(evidence) || !Array.isArray(criteria)) throw new Error('Evidence and criteria arrays are required.');
+  for (const e of evidence) {
+    if (!e || !['pass', 'fail', 'unverified'].includes(e.result)) throw new Error('Invalid evidence result.');
+    required(e.reference, 'Evidence reference'); required(e.detail, 'Evidence detail');
+  }
+  for (const c of criteria) {
+    required(c.criterion, 'Criterion');
+    if (!['pass', 'fail', 'unverified'].includes(c.result) || !Array.isArray(c.evidence)
+        || c.evidence.some(i => !Number.isInteger(i) || !evidence[i])) throw new Error('Invalid criterion evidence linkage.');
+    if (c.result === 'pass' && (!c.evidence.length || c.evidence.some(i => evidence[i].result !== 'pass'))) throw new Error('Passing criteria need passing evidence.');
+  }
+  if (completed && (!criteria.length || criteria.some(c => c.result !== 'pass') || evidence.some(e => e.result !== 'pass'))) throw new Error('Completion requires verified criteria; failed/unverified evidence cannot become a pass.');
+}
+
+export function recordStage(run, outcome, now = Date.now()) {
+  validateRun(run);
+  if (terminal.has(run.status)) throw new Error('Run is already terminal.');
+  const result = clone(run);
+  const stage = result.stages.find(s => s.id === outcome.id && s.status === 'running');
+  if (!stage) throw new Error('No matching running stage.');
+  if (!['completed', 'blocked', 'failed', 'cancelled'].includes(outcome.status)) throw new Error('Invalid stage outcome.');
+  required(outcome.summary, 'Outcome summary');
+  checkEvidence(outcome.evidence || [], outcome.criteria || [], outcome.status === 'completed');
+  Object.assign(stage.attempts.at(-1), { finishedAt: new Date(now).toISOString(),
+    status: outcome.status, summary: outcome.summary,
+    evidence: clone(outcome.evidence || []), criteria: clone(outcome.criteria || []) });
+  stage.status = outcome.status;
+  result.status = 'ready';
+  return result;
+}
+
+// Add an action to a running attempt without restarting it or losing its history.
+// Multiple effects belong to the same action (e.g. external-write AND paid).
+export function amendStage(run, request, now = Date.now()) {
+  active(run, now);
+  const stage = run.stages.find(s => s.id === request.id && s.status === 'running');
+  if (!stage) throw new Error('No matching running stage.');
+  if (!Array.isArray(request.effects) || !request.effects.length
+      || new Set(request.effects).size !== request.effects.length) throw new Error('Distinct action effects are required.');
+  for (const effect of request.effects) authorizeEffect(run, { ...request, effect });
+  const result = clone(run);
+  const attempt = result.stages.find(s => s.id === request.id).attempts.at(-1);
+  attempt.actions ??= [];
+  attempt.actions.push({ action: request.action, target: request.target, effects: [...request.effects], checkedAt: new Date(now).toISOString() });
+  return result;
+}
+
+export function supersedeStage(run, resolution, now = Date.now()) {
+  active(run, now);
+  const source = run.stages.find(s => s.id === resolution.id);
+  if (!source || !['failed', 'blocked'].includes(source.status)) throw new Error('Only a failed or blocked stage can be superseded.');
+  required(resolution.reason, 'Supersession reason');
+  const ids = resolution.replacements;
+  if (!Array.isArray(ids) || !ids.length || new Set(ids).size !== ids.length || ids.includes(source.id)) throw new Error('Distinct replacement stages are required.');
+  const replacements = ids.map(id => run.stages.find(s => s.id === id));
+  if (replacements.some(s => !s || s.status !== 'completed')) throw new Error('Replacement stages must already be completed.');
+  checkEvidence(resolution.evidence, resolution.criteria, true);
+  const uncertainEffects = source.attempts.some(a => ['external-write', 'destructive', 'paid'].includes(a.effect)
+    || a.actions?.some(action => action.effects.some(effect => ['external-write', 'destructive', 'paid'].includes(effect))));
+  if (uncertainEffects) {
+    const evidence = resolution.effectReconciliation;
+    if (!evidence || evidence.result !== 'pass') throw new Error('External effects need successful reconciliation evidence before supersession.');
+    checkEvidence([evidence], [{ criterion: 'Prior effects reconciled', result: 'pass', evidence: [0] }], true);
+  }
+  const covered = new Set(replacements.flatMap(s => s.attempts.at(-1).criteria.filter(c => c.result === 'pass').map(c => c.criterion)));
+  const obligations = new Set([...(source.attempts.at(-1).criteria || []).map(c => c.criterion), ...resolution.criteria.map(c => c.criterion)]);
+  if ([...obligations].some(c => !covered.has(c))) throw new Error('Replacement evidence does not cover the superseded criteria.');
+  const result = clone(run);
+  const stage = result.stages.find(s => s.id === source.id);
+  stage.status = 'superseded';
+  stage.resolution = { reason: resolution.reason, replacements: [...ids], evidence: clone(resolution.evidence), criteria: clone(resolution.criteria),
+    ...(resolution.effectReconciliation ? { effectReconciliation: clone(resolution.effectReconciliation) } : {}), resolvedAt: new Date(now).toISOString() };
+  return result;
+}
+
+export function finishRun(run, outcome, now = Date.now()) {
+  validateRun(run);
+  if (terminal.has(run.status)) throw new Error('Run is already terminal.');
+  if (!terminal.has(outcome.status)) throw new Error('Invalid terminal status.');
+  if (run.stages.some(s => s.status === 'running')) throw new Error('Record running stage results before finishing.');
+  required(outcome.summary, 'Run summary');
+  checkEvidence(outcome.evidence || [], outcome.criteria || [], outcome.status === 'completed');
+  if (outcome.status === 'completed') {
+    if (!run.stages.length || run.stages.some(s => !['completed', 'superseded'].includes(s.status))) throw new Error('Unfinished stages prevent completion.');
+    for (const stage of run.stages.filter(s => s.status === 'superseded')) {
+      if (!stage.resolution?.replacements?.length || stage.resolution.replacements.some(id => id === stage.id || !run.stages.some(s => s.id === id && s.status === 'completed'))) throw new Error('Superseded stages require completed replacements.');
+      checkEvidence(stage.resolution.evidence, stage.resolution.criteria, true);
+    }
+    const covered = new Set((outcome.criteria || []).filter(c => c.result === 'pass').map(c => c.criterion));
+    if (run.context.successCriteria.some(c => !covered.has(c))) throw new Error('Original success criteria have not all been verified.');
+  }
+  return { ...clone(run), status: outcome.status, finishedAt: new Date(now).toISOString(), outcome: clone(outcome) };
+}
+
+export function resumeRun(run, observation, now = Date.now()) {
+  validateRun(run);
+  if (['completed', 'cancelled'].includes(run.status)) throw new Error('Start a new run for completed or cancelled work.');
+  if (realpathSync(resolve(observation.root)) !== realpathSync(run.root)) throw new Error('Resume target differs from the original project.');
+  required(observation.summary, 'Current-state revalidation');
+  if (!Array.isArray(observation.evidence) || !observation.evidence.length) throw new Error('Resume requires current evidence.');
+  if (run.stages.some(s => s.status === 'running')) throw new Error('Reconcile the interrupted stage before resuming; do not replay uncertain effects.');
+  // Preserve consumed stages/attempts/time. A new budget requires an explicit new run.
+  if (now - Date.parse(run.createdAt) >= run.budget.maxMinutes * 60000) throw new Error('Budget expired; create a new run with explicit budget and prior evidence.');
+  const result = { ...clone(run), status: 'ready', resumeObservations: [...(run.resumeObservations || []), clone(observation)] };
+  if (result.outcome) result.previousOutcomes = [...(result.previousOutcomes || []), { ...result.outcome, finishedAt: result.finishedAt }];
+  delete result.outcome;
+  delete result.finishedAt;
+  return result;
+}

package/plugins/just-vibe/scripts/lib/storage.mjs

@@ -0,0 +1,84 @@
+import { existsSync, lstatSync, realpathSync, readFileSync, mkdirSync, openSync, closeSync, writeFileSync, renameSync, unlinkSync, readdirSync } from 'node:fs';
+import { resolve, join, relative, sep, dirname, isAbsolute } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { gitRead } from './project.mjs';
+
+export const digest = value => createHash('sha256').update(value).digest('hex');
+export const projectRoot = root => realpathSync(resolve(root));
+export const privateName = name => /(?:^\.env(?:\.|$)|\.(?:pem|key|p12|pfx)$|credentials|secrets?\.)/i.test(name);
+
+export function within(root, path) {
+  const base = projectRoot(root), full = resolve(base, path), rel = relative(base, full);
+  if (isAbsolute(rel) || rel === '..' || rel.startsWith(`..${sep}`)) throw Error('Path escapes the selected project.');
+  let cursor = base;
+  for (const part of rel.split(sep).filter(Boolean)) {
+    cursor = join(cursor, part);
+    if (existsSync(cursor) || (() => { try { return lstatSync(cursor).isSymbolicLink(); } catch { return false; } })()) {
+      if (lstatSync(cursor).isSymbolicLink()) throw Error('Symlink paths are not supported for managed state or evidence.');
+    }
+  }
+  return full;
+}
+
+export function readJson(path, limit = 512 * 1024) {
+  const stat = lstatSync(path);
+  if (!stat.isFile() || stat.isSymbolicLink() || stat.size > limit) throw Error('Expected a bounded regular JSON file.');
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function atomicJson(root, relativePath, value, expectedRevision) {
+  const path = within(root, relativePath);
+  within(root, dirname(path));
+  mkdirSync(dirname(path), { recursive: true });
+  const lock = `${path}.lock`;
+  let handle;
+  try { handle = openSync(lock, 'wx', 0o600); } catch { throw Error('State is being updated; retry after the current writer finishes.'); }
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    const previous = existsSync(path) ? readJson(path) : null;
+    if ((previous?.revision ?? 0) !== expectedRevision) throw Error('State revision changed. Read it again before updating.');
+    const record = { ...value, revision: expectedRevision + 1 };
+    const text = JSON.stringify(record, null, 2) + '\n';
+    if (Buffer.byteLength(text) > 512 * 1024) throw Error('State exceeds 512 KiB.');
+    writeFileSync(temporary, text, { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, path);
+    return record;
+  } finally {
+    closeSync(handle);
+    if (existsSync(temporary)) unlinkSync(temporary);
+    unlinkSync(lock);
+  }
+}
+
+export function fingerprint(root) {
+  const base = projectRoot(root);
+  const head = gitRead(base, ['rev-parse', '--verify', 'HEAD']);
+  const branch = gitRead(base, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+  const repo = gitRead(base, ['rev-parse', '--show-toplevel']);
+  const entries = []; let bytes = 0, visited = 0, partial = false;
+  function collect(directory) {
+    for (const entry of readdirSync(directory, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (++visited > 10000) { partial = true; return; }
+      if (['.git', '.just-vibe', 'node_modules', '.venv', 'venv', 'dist', 'build', 'coverage', '.next', '.tmp', '.cache', 'PLAN.md', 'NAMING.md'].includes(entry.name) || privateName(entry.name)) continue;
+      const file = join(directory, entry.name);
+      if (entry.isSymbolicLink()) { entries.push([relative(base, file), 'symlink']); continue; }
+      if (entry.isDirectory()) collect(file);
+      else if (entry.isFile()) {
+        const stat = lstatSync(file);
+        if (stat.size > 8 * 1024 * 1024 || bytes + stat.size > 32 * 1024 * 1024) { partial = true; entries.push([relative(base, file), stat.mode, stat.size, stat.mtimeMs, 'metadata-only']); }
+        else { bytes += stat.size; entries.push([relative(base, file), stat.mode, digest(readFileSync(file))]); }
+      }
+    }
+  }
+  collect(base);
+  // Save hashes, never the patch or file contents. Index changes matter even when worktree bytes do not change.
+  const index = repo ? gitRead(base, ['diff', '--cached', '--no-ext-diff', '--no-textconv', '--binary', '--', '.', ':(exclude).just-vibe']) : '';
+  if (repo && index === null) partial = true;
+  return { root: base, repository: repo, head, branch, files: entries.length, content: digest(JSON.stringify(entries)), index: digest(index || ''), partial };
+}
+
+export function compareSnapshot(saved, current) {
+  const differences = ['root', 'repository', 'head', 'branch', 'content', 'index'].filter(key => saved?.[key] !== current[key]);
+  if (saved?.partial || current.partial) differences.push('incomplete-snapshot-coverage');
+  return { stale: differences.length > 0, differences, current };
+}

package/plugins/just-vibe/scripts/lib/teaching.mjs

@@ -0,0 +1,118 @@
+import { randomUUID, randomInt } from 'node:crypto';
+
+const dialogs = new Set(['codex-async', 'codex', 'claude']);
+function nonempty(value, field) {
+  if (typeof value !== 'string' || !value.trim()) throw new Error(`${field} is required.`);
+  return value;
+}
+function checkQuiz(quiz) {
+  if (quiz?.schemaVersion !== 1 || quiz.kind !== 'teach-test' || !Array.isArray(quiz.answers)
+      || !['ready', 'awaiting-answer', 'awaiting-review', 'completed', 'cancelled'].includes(quiz.status)) throw new Error('Invalid quiz state.');
+  return quiz;
+}
+export function createQuiz({ topic, maxQuestions = 5, difficulty = 1, mode = 'practice' }) {
+  nonempty(topic, 'Topic or target workflow');
+  if (!Number.isInteger(maxQuestions) || maxQuestions < 1 || maxQuestions > 20) throw new Error('Choose 1–20 questions.');
+  if (!Number.isInteger(difficulty) || difficulty < 1 || difficulty > 3) throw new Error('Difficulty must be 1, 2 or 3.');
+  if (!['practice', 'test'].includes(mode)) throw new Error('Quiz mode must be practice or test.');
+  return { schemaVersion: 1, kind: 'teach-test', id: randomUUID(), topic, maxQuestions, difficulty, mode,
+    status: 'ready', answers: [], pending: null };
+}
+
+function validateQuestion(question) {
+  for (const field of ['prompt', 'concept', 'explanation']) nonempty(question[field], field);
+  if (!Array.isArray(question.options) || question.options.length !== 3) throw new Error('Use exactly three choices for cross-host compatibility.');
+  const ids = new Set(), labels = new Set();
+  for (const o of question.options) {
+    if (!/^[a-z0-9_-]+$/.test(o.id)) throw new Error('Choice IDs must be stable identifiers.');
+    nonempty(o.label, 'Choice label'); nonempty(o.description, 'Choice description');
+    if (o.label.trim().split(/\s+/).length > 5 || o.label.length > 80) throw new Error('Choice labels must be short (1–5 words).');
+    if (ids.has(o.id) || labels.has(o.label.toLowerCase())) throw new Error('Duplicate choice.');
+    if (/\b(?:recommended|correct answer)\b/i.test(o.label + ' ' + o.description)) throw new Error('Do not disclose an answer through option hints.');
+    ids.add(o.id); labels.add(o.label.toLowerCase());
+  }
+  if (!ids.has(question.correctOptionId)) throw new Error('Answer key must identify one of the choices.');
+}
+
+export function nativeQuestionPayload(question, dialog) {
+  if (!dialogs.has(dialog)) throw new Error('A supported native question dialog is required; do not fall back to inline quiz questions.');
+  const options = question.options.map(o => ({ label: o.label, description: o.description }));
+  if (dialog === 'codex-async') return { tool: 'request_user_input_async', arguments: {
+    questions: [{ title: question.prompt, options: options.map(o => `${o.label} — ${o.description}`) }],
+  } };
+  if (dialog === 'codex') return { tool: 'request_user_input', arguments: {
+    questions: [{ id: question.id, header: 'Knowledge', question: question.prompt, options }],
+  } };
+  return { tool: 'AskUserQuestion', arguments: {
+    questions: [{ header: 'Knowledge', question: question.prompt, options, multiSelect: false }],
+  } };
+}
+
+export function presentQuestion(quiz, question, dialog) {
+  checkQuiz(quiz);
+  if (quiz.status !== 'ready' || quiz.pending) throw new Error('Wait for and review the current answer before asking another question.');
+  if (quiz.answers.length >= quiz.maxQuestions) throw new Error('Question budget exhausted.');
+  validateQuestion(question);
+  const options = structuredClone(question.options);
+  for (let i = options.length - 1; i > 0; i--) { const j = randomInt(i + 1); [options[i], options[j]] = [options[j], options[i]]; }
+  const pending = { ...structuredClone(question), id: `q_${quiz.id.replaceAll('-', '_')}_${quiz.answers.length + 1}`, options, dialog };
+  const presentation = nativeQuestionPayload(pending, dialog);
+  return { quiz: { ...structuredClone(quiz), pending, status: 'awaiting-answer' }, presentation };
+}
+
+function assessed(quiz, response, result, explanation) {
+  const next = structuredClone(quiz);
+  const q = next.pending;
+  const answer = { questionId: q.id, prompt: q.prompt, concept: q.concept, response, result,
+    correctLabel: q.options.find(o => o.id === q.correctOptionId).label, explanation };
+  next.answers.push(answer);
+  next.pending = null;
+  if (next.mode === 'practice' && result !== 'skipped') next.difficulty = Math.max(1, Math.min(3, next.difficulty + (result === 'correct' ? 1 : -1)));
+  next.status = next.answers.length >= next.maxQuestions ? 'completed' : 'ready';
+  const feedback = next.mode === 'practice' ? answer : { questionId: answer.questionId, recorded: true };
+  return { quiz: next, feedback, ...(next.mode === 'practice' ? {
+    nextFocus: result === 'correct' ? 'Apply or extend the concept.' : `Revisit ${q.concept} with a simpler or differently framed example.`,
+  } : {}) };
+}
+
+export function answerQuestion(quiz, response) {
+  checkQuiz(quiz);
+  if (!quiz.pending || quiz.status !== 'awaiting-answer') throw new Error('No unanswered native question is pending.');
+  // Async tool calls returning immediately, empty submissions and timeouts are not answers.
+  if (!response || response.submitted !== true) return { quiz: structuredClone(quiz), feedback: null, waiting: true };
+  if (response.questionId !== quiz.pending.id) throw new Error('Answer belongs to a different question.');
+  if (response.cancelled) return { quiz: { ...structuredClone(quiz), status: 'cancelled' }, feedback: null };
+  if (response.skipped) return assessed(quiz, null, 'skipped', quiz.pending.explanation);
+  const selected = quiz.pending.options.find(o => o.id === response.selection || o.label === response.selection || `${o.label} — ${o.description}` === response.selection);
+  if (selected) return assessed(quiz, response.selection, selected.id === quiz.pending.correctOptionId ? 'correct' : 'incorrect', quiz.pending.explanation);
+  if (typeof response.freeText === 'string' && response.freeText.trim()) {
+    const next = structuredClone(quiz);
+    next.status = 'awaiting-review'; next.pending.freeText = response.freeText;
+    return { quiz: next, feedback: null, needsReview: true };
+  }
+  throw new Error('Unrecognized answer. Preserve the pending question; do not infer a selection.');
+}
+
+export function reviewFreeText(quiz, judgment) {
+  checkQuiz(quiz);
+  if (quiz.status !== 'awaiting-review' || !quiz.pending?.freeText) throw new Error('No free-text answer awaits review.');
+  if (!['correct', 'partial', 'incorrect'].includes(judgment.result)) throw new Error('Invalid review result.');
+  nonempty(judgment.explanation, 'Grounded explanation of the learner answer');
+  return assessed(quiz, quiz.pending.freeText, judgment.result, judgment.explanation);
+}
+
+export function quizReport(quiz) {
+  checkQuiz(quiz);
+  const correct = quiz.answers.filter(a => a.result === 'correct').length;
+  const incorrect = quiz.answers.filter(a => ['incorrect', 'partial'].includes(a.result));
+  const finished = ['completed', 'cancelled'].includes(quiz.status);
+  const report = { topic: quiz.topic, status: quiz.status, answered: quiz.answers.length,
+    graded: quiz.answers.filter(a => a.result !== 'skipped').length, skipped: quiz.answers.filter(a => a.result === 'skipped').length,
+    pending: Boolean(quiz.pending), nextDifficulty: quiz.difficulty,
+    note: 'Results describe this short sample, not proof of mastery. No learner profile is saved automatically.' };
+  if (quiz.mode === 'practice' || finished) {
+    report.correct = correct; report.revisit = [...new Set(incorrect.map(a => a.concept))];
+    report.answers = structuredClone(quiz.answers);
+  }
+  return report;
+}