@damiangilgonzalez/harness 1.3.7

package/scripts/lib/onboarding.js

@@ -0,0 +1,329 @@
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readdirSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, join, relative, resolve, sep } from 'node:path';
+import { TARGET_IDS } from '../../targets/index.js';
+import { resolveAgentNames } from '../../targets/agents.js';
+import { loadManifest, skillsForProfile } from './manifest.js';
+import { managedPathsForInstall } from '../install-apply.js';
+
+export const ONBOARDING_SCHEMA_VERSION = 1;
+export const ONBOARDING_VALUES = Object.freeze({
+  technicalLevel: ['non-technical', 'mixed', 'technical'],
+  accompaniment: ['L0', 'L1', 'L2', 'L3'],
+  projectKind: ['software', 'operations', 'research', 'content', 'mixed'],
+  softwareScope: ['small', 'growing', 'complex'],
+});
+
+const ignored = new Set([
+  '.git', '.rsc', 'node_modules', '.venv', '.next', 'dist', 'build', 'coverage', '__pycache__', '.dart_tool',
+  '.claude', '.codex', '.cursor', '.opencode', '.amp', '.jules', '.zed', '.gemini', '.antigravity',
+  '.windsurf', '.clinerules', '.roo', '.continue', '.junie', '.kiro', '.aider',
+]);
+const manifests = new Set(['package.json', 'pyproject.toml', 'go.mod', 'Cargo.toml', 'pubspec.yaml', 'requirements.txt']);
+const sourceExt = new Set(['.js', '.jsx', '.ts', '.tsx', '.py', '.go', '.rs', '.dart', '.java', '.kt', '.swift', '.php', '.rb']);
+
+const clean = (value) => String(value ?? '').trim();
+const oneOf = (field, value, values) => {
+  if (!values.includes(value)) throw new Error(`invalid ${field}: expected ${values.join('|')}`);
+  return value;
+};
+
+export function normalizeOnboarding(raw = {}) {
+  const schemaVersion = Number(raw.schemaVersion ?? ONBOARDING_SCHEMA_VERSION);
+  if (schemaVersion !== ONBOARDING_SCHEMA_VERSION) throw new Error(`invalid schemaVersion: expected ${ONBOARDING_SCHEMA_VERSION}`);
+  const technicalLevel = oneOf('technical-level', clean(raw.technicalLevel).toLowerCase(), ONBOARDING_VALUES.technicalLevel);
+  const accompaniment = oneOf('accompaniment', clean(raw.accompaniment).toUpperCase(), ONBOARDING_VALUES.accompaniment);
+  const projectKind = oneOf('project-kind', clean(raw.projectKind).toLowerCase(), ONBOARDING_VALUES.projectKind);
+  const goal = clean(raw.goal).replace(/\s+/g, ' ');
+  if (!goal) throw new Error('invalid goal: a concrete goal is required');
+  const targets = [...new Set((Array.isArray(raw.targets) ? raw.targets : clean(raw.targets).split(','))
+    .map((target) => clean(target).toLowerCase()).filter(Boolean))].sort();
+  if (!targets.length || targets.some((target) => !TARGET_IDS.includes(target))) {
+    throw new Error(`invalid target: expected one or more of ${TARGET_IDS.join(',')}`);
+  }
+  const needsScope = projectKind === 'software' || projectKind === 'mixed';
+  const softwareScope = clean(raw.softwareScope).toLowerCase();
+  if (needsScope) oneOf('software-scope', softwareScope, ONBOARDING_VALUES.softwareScope);
+  return {
+    schemaVersion,
+    technicalLevel,
+    accompaniment,
+    projectKind,
+    goal,
+    ...(needsScope ? { softwareScope } : {}),
+    targets,
+  };
+}
+
+function extension(file) {
+  const dot = file.lastIndexOf('.');
+  return dot < 0 ? '' : file.slice(dot);
+}
+
+export function scanProject(root = process.cwd()) {
+  const absolute = realpathSync(resolve(root));
+  const signals = [];
+  const stacks = new Set();
+  const complexitySignals = new Set();
+  let markdownCount = 0;
+  let sourceFileCount = 0;
+  const visit = (dir) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      if (ignored.has(entry.name) || entry.isSymbolicLink()) continue;
+      const path = join(dir, entry.name);
+      const rel = relative(absolute, path).split(sep).join('/');
+      if (rel.startsWith('../') || rel === '..') throw new Error('project scan escaped the selected root');
+      if (rel === 'docs/wiki/harness' || rel.startsWith('docs/wiki/harness/')) continue;
+      // Mismo motivo que la línea de arriba, y descubierto igual de tarde: el instalador escribe
+      // `01-TOOLS/_TEMPLATE/` y sus dos `.md` entraban como evidencia de proyecto, moviendo la
+      // identidad del plan. El segundo `onboard --accept-plan <id>` moría con RSC_PLAN_CHANGED, y
+      // con él el reintento que la documentación pide tras reparar el suelo. Los proveedores reales
+      // que el usuario añada bajo `01-TOOLS/` sí siguen contando: son suyos, no nuestros.
+      if (rel === '01-TOOLS/_TEMPLATE' || rel.startsWith('01-TOOLS/_TEMPLATE/')) continue;
+      if (entry.isDirectory()) { visit(path); continue; }
+      if (!entry.isFile()) continue;
+      let isSignal = manifests.has(entry.name) || entry.name.endsWith('.md');
+      // Codex stores the always-on layer in AGENTS.md. Ignore a file that contains
+      // only our managed block, while retaining a user's surrounding instructions
+      // as real project evidence across repair/re-onboarding.
+      if (entry.name === 'AGENTS.md') {
+        const human = readFileSync(path, 'utf8')
+          .replace(/\n*<!-- rsc-suggest:start -->[\s\S]*?<!-- rsc-suggest:end -->\n*/g, '')
+          .trim();
+        isSignal = Boolean(human);
+      }
+      if (isSignal && manifests.has(entry.name)) signals.push(`manifest:${entry.name}`);
+      else if (isSignal) markdownCount++;
+      if (sourceExt.has(extension(entry.name))) sourceFileCount++;
+      const lowerRel = rel.toLowerCase();
+      if (/(^|[/_.-])(auth|login|oauth|session)([/_.-]|$)/.test(lowerRel)) complexitySignals.add('authentication');
+      if (/(^|[/_.-])(payment|billing|checkout)([/_.-]|$)/.test(lowerRel)) complexitySignals.add('payments');
+      if (/(^|[/_.-])(database|persistence|migration|schema)([/_.-]|$)/.test(lowerRel)) complexitySignals.add('persistence');
+      if (/(^|[/_.-])(integration|webhook|connector)([/_.-]|$)/.test(lowerRel)) complexitySignals.add('external-integrations');
+      if (entry.name === 'package.json') {
+        try {
+          const pkg = JSON.parse(readFileSync(path, 'utf8'));
+          const deps = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+          for (const [name, stack] of [['next', 'nextjs'], ['react', 'react'], ['vue', 'vue'], ['svelte', 'svelte'], ['@angular/core', 'angular']]) if (deps[name]) stacks.add(stack);
+          stacks.add('node');
+          const names = Object.keys(deps).join(' ').toLowerCase();
+          if (/(passport|auth0|clerk|next-auth|better-auth)/.test(names)) complexitySignals.add('authentication');
+          if (/(stripe|paypal|adyen|braintree)/.test(names)) complexitySignals.add('payments');
+          if (/(prisma|typeorm|sequelize|mongoose|postgres|mysql|sqlite|supabase|firebase)/.test(names)) complexitySignals.add('persistence');
+          if (/(webhook|octokit|twilio|sendgrid|slack)/.test(names)) complexitySignals.add('external-integrations');
+        } catch { stacks.add('node'); }
+      }
+      if (entry.name === 'pyproject.toml' || entry.name === 'requirements.txt') stacks.add('python');
+      if (entry.name === 'go.mod') stacks.add('go');
+      if (entry.name === 'Cargo.toml') stacks.add('rust');
+      if (entry.name === 'pubspec.yaml') stacks.add('flutter');
+    }
+  };
+  visit(absolute);
+  if (markdownCount) signals.push(`markdown:${markdownCount}`);
+  let parentHarness = null;
+  let cursor = dirname(absolute);
+  while (cursor !== dirname(cursor)) {
+    if (existsSync(join(cursor, '.rsc.json'))) {
+      parentHarness = relative(absolute, cursor).split(sep).join('/') || '..';
+      break;
+    }
+    cursor = dirname(cursor);
+  }
+  const evidence = {
+    schemaVersion: 1,
+    signals: [...new Set(signals)].sort(),
+    stacks: [...stacks].sort(),
+    complexitySignals: [...complexitySignals].sort(),
+    sourceFileCount,
+    parentHarness,
+  };
+  Object.defineProperty(evidence, 'root', { value: absolute, enumerable: false });
+  return evidence;
+}
+
+function selected(id, kind, reason, provenance = 'declared-intent') {
+  return { kind, id, state: 'selected', reason, provenance, reevaluateWhen: [] };
+}
+function deferred(id, kind, reason, reevaluateWhen, triggerRules = [], provenance = 'proportionality-policy') {
+  return { kind, id, state: 'deferred', reason, provenance, reevaluateWhen, triggerRules };
+}
+function excluded(id, kind, reason, provenance = 'separate-consent-boundary') {
+  return { kind, id, state: 'excluded', reason, provenance, reevaluateWhen: [], triggerRules: [] };
+}
+
+export function buildOnboardingPlan(record, evidence) {
+  const normalized = normalizeOnboarding(record);
+  const isSoftware = normalized.projectKind === 'software' || normalized.projectKind === 'mixed';
+  const goalSignals = [];
+  const goal = normalized.goal.toLowerCase();
+  if (/auth|login|oauth|sesión|session/.test(goal)) goalSignals.push('authentication');
+  if (/payment|billing|checkout|pago|cobro/.test(goal)) goalSignals.push('payments');
+  if (/database|persistence|persistencia|base de datos/.test(goal)) goalSignals.push('persistence');
+  if (/integration|integración|webhook|third-party|tercero/.test(goal)) goalSignals.push('external-integrations');
+  const complexitySignals = [...new Set([...(evidence.complexitySignals || []), ...goalSignals])].sort();
+  const UI_STACKS = new Set(['nextjs', 'react', 'vue', 'svelte', 'angular']);
+  const needsWorkflow = isSoftware && (normalized.softwareScope !== 'small' || complexitySignals.length > 0);
+  const hasInterface = needsWorkflow && (evidence.stacks || []).some((stack) => UI_STACKS.has(stack));
+  const profile = !needsWorkflow ? 'minimal' : (hasInterface ? 'ui' : 'core');
+  const catalog = loadManifest();
+  const catalogIds = new Set(catalog.skills.map((skill) => skill.id));
+  const detectedSkills = (evidence.stacks || []).filter((stack) => catalogIds.has(stack));
+  const skills = [...new Set([...skillsForProfile(catalog, profile), ...detectedSkills])].sort();
+  const baseAgents = needsWorkflow;
+  const hooks = needsWorkflow;
+  const agents = baseAgents ? resolveAgentNames(skills, []).sort() : [];
+  const gitmojiGuard = hooks && normalized.targets.includes('claude');
+  const decisions = skills.map((id) => detectedSkills.includes(id)
+    ? selected(id, 'skill', `Detected ${id} evidence inside the selected project root.`, 'workspace-evidence')
+    : selected(id, 'skill', needsWorkflow
+      ? (id === 'sdd' && complexitySignals.length
+        ? `Included because the accepted work has ${complexitySignals.join(', ')} complexity.`
+        : `Included in the development workflow for ${normalized.softwareScope} software.`)
+      : `Included in the lightweight foundation for this ${normalized.projectKind} project.`));
+  const sddTriggers = ['multiple related features', 'authentication or persistence', 'external integrations', 'cross-cutting changes'];
+  const softwareTriggers = [
+    { type: 'source-growth', atLeast: 5 },
+    { type: 'complexity-added', atLeast: 1 },
+    { type: 'manifest-with-implementation' },
+  ];
+  if (!needsWorkflow) {
+    decisions.push(deferred('sdd', 'workflow', isSoftware
+      ? 'The software scope is small, so specification overhead is not justified yet.'
+      : 'SDD applies to substantial software work, which is not the declared project purpose.', sddTriggers, softwareTriggers));
+  } else {
+    decisions.push(selected('sdd', 'workflow', complexitySignals.length
+      ? `Included because the accepted work has ${complexitySignals.join(', ')} complexity.`
+      : `Included in the development workflow for ${normalized.softwareScope} software.`));
+  }
+  if (baseAgents) {
+    for (const id of agents) decisions.push(selected(id, 'agent', 'The accepted substantial software workflow requires this implementation or review role.'));
+  } else {
+    decisions.push(deferred('base-agents', 'agent', 'No substantial software implementation is planned.', ['substantial software implementation is introduced'], softwareTriggers));
+  }
+  decisions.push(hooks
+    ? selected('code-hooks', 'hook', 'The accepted software workflow needs its deterministic code gates.')
+    : deferred('code-hooks', 'hook', 'Code-only gates would add unrelated behavior to this project.', ['a substantial software workflow is accepted'], softwareTriggers));
+  decisions.push(gitmojiGuard
+    ? selected('gitmoji-guard', 'guard', 'Claude Code supports the commit guard and the accepted code policy includes it.')
+    : deferred('gitmoji-guard', 'guard', 'No selected target and project policy justify this Claude-only commit guard.', ['Claude Code is selected and a governed software workflow adopts the convention'], [{ type: 'software-trigger-and-claude' }]));
+  decisions.push(selected('memory', 'capability', 'Local bounded project memory supports continuity without an external account.'));
+  decisions.push(selected('harness-documents', 'route', 'The accepted profile and plan are persisted under docs/wiki/harness/.'));
+  decisions.push(excluded('context7', 'integration', 'External MCP connections require a separate, provider-specific consent flow and are outside this local harness plan.'));
+  if (needsWorkflow) {
+    decisions.push(selected('superpowers', 'plugin',
+      'The planning and execution chain lives in the superpowers plugin, kept current by Claude Code.'));
+  }
+  decisions.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+  const policy = {
+    skills,
+    targets: normalized.targets,
+    baseAgents,
+    agents,
+    alwaysOn: true,
+    codeHooks: needsWorkflow,
+    gitmojiGuard,
+    memory: true,
+    context7: false,
+    plugins: needsWorkflow ? ['superpowers@claude-plugins-official'] : [],
+  };
+  const root = evidence.root;
+  const governedPaths = root ? [...new Set([
+    '.rsc.json', '.rsc/backups/',
+    ...(existsSync(join(root, '.git')) ? ['.gitignore'] : []),
+    'docs/wiki/harness/user-profile.md',
+    'docs/wiki/harness/decisions.md',
+    'docs/wiki/harness/installation-plan.md',
+    '.rsc/.no-context7',
+    ...normalized.targets.flatMap((target) => managedPathsForInstall({ skillIds: skills, target, cwd: root, policy })
+      .map((path) => relative(root, path).split(sep).join('/'))),
+  ])].sort() : ['.rsc.json', '.rsc/', 'docs/wiki/harness/'];
+  // El suelo viaja dentro del plan a propósito: así un recibo aceptado por una versión anterior no
+  // lo trae y queda exento sin que exista ninguna lista de exentos (P3, el contenido es el ledger).
+  // Este fork no incluye constitución en el suelo: su flujo (grill-with-docs → to-spec → write-adr)
+  // no la escribe, así que exigirla dejaría todo proyecto de software en INCOMPLETE para siempre.
+  const floorPaths = [
+    '01-TOOLS/_TEMPLATE/',
+    'docs/wiki/harness/',
+  ].sort();
+  return {
+    schemaVersion: 1,
+    record: normalized,
+    evidence: {
+      schemaVersion: evidence.schemaVersion,
+      signals: [...evidence.signals], stacks: [...evidence.stacks],
+      complexitySignals: [...(evidence.complexitySignals || [])],
+      sourceFileCount: evidence.sourceFileCount, parentHarness: evidence.parentHarness,
+    },
+    decisions,
+    policy,
+    governedPaths,
+    floorPaths,
+  };
+}
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  }
+  return value;
+}
+
+export const canonicalJson = (value) => JSON.stringify(canonical(value));
+export const identifyPlan = (plan) => createHash('sha256').update(canonicalJson(plan)).digest('hex');
+export const shellQuote = (value) => `'${String(value).replaceAll("'", `'"'"'`)}'`;
+export const encodeGoal = (value) => Buffer.from(String(value), 'utf8').toString('base64url');
+export const decodeGoal = (value) => {
+  try {
+    const decoded = Buffer.from(String(value), 'base64url').toString('utf8');
+    return encodeGoal(decoded) === String(value).replace(/=+$/, '') ? decoded : undefined;
+  } catch { return undefined; }
+};
+
+export function recommendDeferredComponents(acceptedPlan, currentEvidence) {
+  const baseline = acceptedPlan?.evidence || {};
+  const grewBy = (currentEvidence?.sourceFileCount || 0) - (baseline.sourceFileCount || 0);
+  const addedManifests = (currentEvidence?.signals || []).filter((signal) => signal.startsWith('manifest:') && !(baseline.signals || []).includes(signal));
+  const addedComplexity = (currentEvidence?.complexitySignals || []).filter((signal) => !(baseline.complexitySignals || []).includes(signal));
+  const manifestWithImplementation = addedManifests.length && grewBy > 0;
+  const facts = { grewBy, manifestWithImplementation: Boolean(manifestWithImplementation), addedComplexity: addedComplexity.length };
+  const evidence = addedComplexity.length
+    ? `The project added ${addedComplexity.join(', ')} evidence.`
+    : grewBy >= 5
+    ? `The project grew by ${grewBy} source files since the accepted plan.`
+    : `The project added software manifest evidence: ${addedManifests.join(', ')}.`;
+  const suggestedRecord = {
+    ...acceptedPlan.record,
+    projectKind: ['software', 'mixed'].includes(acceptedPlan.record.projectKind) ? acceptedPlan.record.projectKind : 'mixed',
+    softwareScope: 'growing',
+  };
+  const matches = (rule) => {
+    if (rule.type === 'source-growth') return facts.grewBy >= rule.atLeast;
+    if (rule.type === 'complexity-added') return facts.addedComplexity >= rule.atLeast;
+    if (rule.type === 'manifest-with-implementation') return facts.manifestWithImplementation;
+    if (rule.type === 'software-trigger-and-claude') return acceptedPlan.record.targets.includes('claude') && (facts.grewBy >= 5 || facts.addedComplexity > 0 || facts.manifestWithImplementation);
+    return false;
+  };
+  return (acceptedPlan.decisions || [])
+    .filter((decision) => decision.state === 'deferred' && (decision.triggerRules || []).some(matches))
+    .map((decision) => ({
+      kind: decision.kind,
+      id: decision.id,
+      explanation: `${evidence} This matches: ${decision.reevaluateWhen.join('; ')}.`,
+      requiresNewPlan: true,
+      suggestedRecord,
+    }));
+}
+
+export function missingOnboardingFields(raw = {}) {
+  const missing = [];
+  if (!clean(raw.technicalLevel)) missing.push('technical-level');
+  if (!clean(raw.accompaniment)) missing.push('accompaniment');
+  if (!clean(raw.projectKind)) missing.push('project-kind');
+  if (!clean(raw.goal)) missing.push('goal');
+  const kind = clean(raw.projectKind).toLowerCase();
+  if ((kind === 'software' || kind === 'mixed') && !clean(raw.softwareScope)) missing.push('software-scope');
+  if (!(Array.isArray(raw.targets) ? raw.targets.length : clean(raw.targets))) missing.push('target');
+  return missing;
+}

package/scripts/lib/recommend.js

@@ -0,0 +1,56 @@
+import { skillById } from './manifest.js';
+
+const OUTCOMES = {
+  bro: 'Writing that sounds natural and human',
+  suggest: 'An assistant that proposes what you need as you go',
+  harness: 'A tidy workspace: connect and document your company',
+  init: 'Guided project bootstrap',
+  nextjs: 'Your website (fast, ready for Google)',
+  flutter: 'Your mobile app',
+  fastapi: 'Your API / Python backend',
+  go: 'Your Go backend service',
+  postgresdb: 'Store your data reliably',
+  design: 'Make it look good and convert',
+  'design-loop': 'Make it as good as the site you admire',
+  'design-dna': 'Keep every page looking like yours',
+  marketing: 'Copy that sells',
+  presentations: 'On-brand presentations',
+  'course-storytelling': 'Teach so it actually lands',
+  'building-agents': 'Your own AI agent',
+  'secure-coding': 'Make it secure',
+  deployment: 'Put it online',
+  godot: 'Your game (Godot)',
+  unity: 'Your game (Unity)',
+  unreal: 'Your game (Unreal)',
+  'game-design': "Design a game that's fun",
+  'fable-operator': 'Reason it through, reliably',
+  finetuning: 'Fine-tune an open model',
+  'machine-learning': 'Build a classic ML model',
+  'deep-learning': 'Train a neural network',
+  nlp: 'Do NLP the right way',
+  'open-weights': 'Pick an open-weight model',
+  vllm: 'Serve open models at scale',
+  'automation-strategy': 'Decide what to automate',
+  n8n: 'Automate with n8n (API/MCP)',
+  make: 'Automate with Make (API/MCP)',
+  zapier: 'Automate with Zapier (MCP)',
+  'power-automate': 'Automate with Power Automate',
+};
+
+export function hasOutcome(id) {
+  return Object.prototype.hasOwnProperty.call(OUTCOMES, id);
+}
+
+export function expandRecommends(manifest, chosen) {
+  const set = new Set();
+  for (const id of chosen) {
+    set.add(id);
+    const s = skillById(manifest, id);
+    for (const r of s?.recommends || []) set.add(r);
+  }
+  return [...set];
+}
+
+export function toOutcomes(ids) {
+  return ids.map((id) => ({ id, label: OUTCOMES[id] || id }));
+}

package/scripts/lib/registry.js

@@ -0,0 +1,110 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import { targetPaths } from '../../targets/index.js';
+import { loadManifest } from './manifest.js';
+import { readState } from './state.js';
+
+const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+
+export function refreshRegistry({
+  cwd = process.cwd(),
+  target = 'codex',
+  home = homedir(),
+  manifest = loadManifest(),
+  catalogRoot = ROOT,
+} = {}) {
+  const dir = join(cwd, '.rsc');
+  mkdirSync(dir, { recursive: true });
+  const registry = buildRegistry({ cwd, target, home, manifest, catalogRoot });
+  writeFileSync(join(dir, 'skill-registry.json'), JSON.stringify(registry, null, 2) + '\n');
+  writeFileSync(join(dir, 'skill-registry.md'), renderRegistryMarkdown(registry));
+  return registry;
+}
+
+export function registryStatus({ cwd = process.cwd() } = {}) {
+  const path = join(cwd, '.rsc', 'skill-registry.json');
+  if (!existsSync(path)) return { exists: false, path };
+  const data = JSON.parse(readFileSync(path, 'utf8'));
+  return {
+    exists: true,
+    path,
+    version: data.version,
+    counts: data.counts || { skills: data.skills?.length || 0 },
+  };
+}
+
+export function buildRegistry({
+  cwd = process.cwd(),
+  target = 'codex',
+  home = homedir(),
+  manifest = loadManifest(),
+  catalogRoot = ROOT,
+} = {}) {
+  const installed = installedIds({ target, home, cwd });
+  const skills = manifest.skills.map((skill) => {
+    const skillPath = resolve(catalogRoot, 'skills', skill.id, 'SKILL.md');
+    const available = existsSync(skillPath);
+    return {
+      id: skill.id,
+      trigger: skill.description,
+      tags: skill.tags || [],
+      source: 'catalog',
+      path: skillPath,
+      installed: installed.has(skill.id),
+      available,
+      hash: hashSkill({ ...skill, path: skillPath, available }),
+    };
+  }).sort((a, b) => a.id.localeCompare(b.id));
+  return {
+    version: 1,
+    target,
+    root: resolve(cwd),
+    counts: {
+      skills: skills.length,
+      installed: skills.filter((s) => s.installed).length,
+      available: skills.filter((s) => s.available).length,
+    },
+    skills,
+  };
+}
+
+export function renderRegistryMarkdown(registry) {
+  const rows = [
+    '# RSC Skill Registry',
+    '',
+    `Target: ${registry.target}`,
+    `Skills: ${registry.counts.skills} (${registry.counts.installed} installed, ${registry.counts.available} available)`,
+    '',
+    '| id | installed | available | tags | path |',
+    '| --- | --- | --- | --- | --- |',
+  ];
+  for (const skill of registry.skills) {
+    rows.push(`| ${skill.id} | ${yesNo(skill.installed)} | ${yesNo(skill.available)} | ${(skill.tags || []).join(', ')} | ${skill.path} |`);
+  }
+  return rows.join('\n') + '\n';
+}
+
+function installedIds({ target, home, cwd }) {
+  const paths = targetPaths(target, home, cwd);
+  return new Set(Object.keys(readState(paths.stateFile).skills || {}));
+}
+
+function hashSkill(skill) {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      id: skill.id,
+      trigger: skill.description,
+      tags: skill.tags || [],
+      path: skill.path,
+      available: skill.available,
+    }))
+    .digest('hex')
+    .slice(0, 12);
+}
+
+function yesNo(value) {
+  return value ? 'yes' : 'no';
+}

package/scripts/lib/repair.js

@@ -0,0 +1,156 @@
+import { existsSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { targetPaths, installedTargets, detectTarget, unwireHook } from '../../targets/index.js';
+import { readState } from './state.js';
+import { readManifest } from './manifest-file.js';
+import { createBackup } from './backups.js';
+import { countHookEntries } from '../doctor.js';
+import { applyInstall, recordInManifest, managedPathsForInstall } from '../install-apply.js';
+
+// Fixing a harness that came from an earlier version.
+//
+// The other two deliveries fix the future and fix nobody: everyone who built a harness on
+// 0.1 or 1.0 wakes up the day after with exactly what they had, and does not know it. This
+// is the one command for them — no flags, no need to know what is wrong.
+//
+// EVERY finding is born with its class, and the executor only reads that field. It never
+// decides:
+//
+//   restore — put the harness back to what was ALREADY declared. Nobody decides anything,
+//             so it happens on its own, after a recoverable copy.
+//   change  — alter something a person or a team chose. Always asked, one by one.
+//
+// Putting the boundary in the data instead of the executor means it can be tested without
+// running anything, and it cannot drift apart between branches.
+
+const finding = (id, cls, summary, action) => ({ id, class: cls, summary, action });
+
+export function diagnose({ cwd = process.cwd(), target, home = homedir(), invoked = false } = {}) {
+  const paths = targetPaths(target, home, cwd);
+  const state = readState(paths.stateFile);
+  const installed = Object.keys(state.skills || {});
+  const manifest = readManifest(cwd);
+  const out = [];
+
+  // Nothing of ours here at all: say so and touch nothing. Running this in the wrong
+  // folder must be harmless.
+  if (!installed.length && !manifest && !existsSync(join(cwd, '.rsc'))) return out;
+
+  // The 0.1 layout Claude Code never discovered. writeSkill() sweeps it, but only when
+  // that skill is reinstalled — so anyone who never reinstalled still carries it.
+  if (existsSync(join(paths.root, 'rsc'))) {
+    out.push(finding('nested-layout', 'restore',
+      'A .claude/skills/rsc/ directory from the 0.1 layout is still here; no assistant ever read it.',
+      'It gets removed. Nothing that works today lives in it.'));
+  }
+
+  // Repeated wiring. On Windows the needle never matched, so every install ADDED a hook
+  // instead of replacing it: there were real machines running each hook four times.
+  const repeated = duplicatedHooks(paths.hookTarget);
+  if (repeated.length) {
+    out.push(finding('duplicate-hooks', 'restore',
+      `${repeated.join(', ')} wired more than once, so those hooks run several times per event.`,
+      'The extra copies are removed, leaving one of each.'));
+  }
+
+  // A clone: the declaration travelled, the materialised skills did not.
+  const dangling = installed.filter((id) => !existsSync(paths.skillDir(id)))
+    .concat((manifest?.skills || []).filter((id) => !existsSync(paths.skillDir(id))));
+  if (dangling.length) {
+    out.push(finding('dangling-links', 'restore',
+      `${[...new Set(dangling)].join(', ')} are declared but not on disk — what a fresh clone looks like.`,
+      'They get rebuilt from the catalog at the version the manifest pins.'));
+  }
+
+  // Writing the manifest records something already true, which sounds like a restoration.
+  // But it makes a new committable file appear in someone's root, and that surprises —
+  // and surprising people is what started all of this. So: automatic when they typed the
+  // command (they already said yes), asked when we are the ones who noticed.
+  if (!manifest && installed.length) {
+    out.push(finding('no-manifest', invoked ? 'restore' : 'change',
+      'This harness predates .rsc.json, so it cannot be shared by git yet.',
+      'A manifest is written from what is already installed here.'));
+  }
+
+  // Installed somewhere the project does not look like. This is #249: `harness` writes an
+  // AGENTS.md, detection read it as codex, and people ended up wired to an assistant they
+  // never chose. Moving is a change — it is where the harness lives.
+  const others = installedTargets(cwd).filter((t) => t !== target);
+  const looksLike = detectTarget(cwd);
+  if (!others.length && installed.length && looksLike !== target && !manifest) {
+    out.push(finding('wrong-target', 'change',
+      `The harness is installed for ${target}, but this project looks like ${looksLike}.`,
+      `It moves to ${looksLike}, and the old wiring — including the block in the root file — is removed.`),
+    );
+    out[out.length - 1].to = looksLike;
+  }
+  return out;
+}
+
+// Remove the old wiring's skills. The list comes from the target's OWN state, which by
+// construction holds only what rsc installed — so "we never touch what we did not write"
+// is a property of the input here, not a check that could be forgotten or drift.
+//
+// It was a check, once, sitting on a list that mixed state and manifest ids. A mutant that
+// deleted the check killed no test, and chasing that revealed the branch was unreachable
+// anyway. A guard that cannot be seen to fail is worse than no guard (principle 2), so it
+// became structure instead.
+function removeManagedSkills(paths) {
+  for (const id of Object.keys(readState(paths.stateFile).skills || {})) {
+    rmSync(paths.skillDir(id), { recursive: true, force: true });
+  }
+  rmSync(paths.stateFile, { force: true });
+}
+
+function duplicatedHooks(hookTarget) {
+  let settings;
+  try { settings = JSON.parse(readFileSync(hookTarget, 'utf8')); } catch { return []; }
+  const { perEvent } = countHookEntries(settings);
+  const dup = [];
+  for (const [event, ids] of Object.entries(perEvent)) {
+    for (const [id, n] of Object.entries(ids)) if (n > 1) dup.push(`${event}/${id}`);
+  }
+  return dup;
+}
+
+export async function repair({ cwd = process.cwd(), target, home = homedir(), dryRun = false, invoked = false, accept } = {}) {
+  const found = diagnose({ cwd, target, home, invoked });
+  const restores = found.filter((f) => f.class === 'restore');
+  const changes = found.filter((f) => f.class === 'change');
+
+  // Anything the person has to decide is only applied if they actually said yes. With
+  // nobody to ask, it stays pending — and the restorations still get done, because they
+  // never depended on that decision.
+  const okChanges = [];
+  for (const c of changes) if (accept && await accept(c)) okChanges.push(c);
+  const todo = [...restores, ...okChanges];
+  if (!todo.length || dryRun) {
+    return { applied: todo, pending: changes.filter((c) => !okChanges.includes(c)), backup: null };
+  }
+
+  const paths = targetPaths(target, home, cwd);
+  const ids = [...new Set([...Object.keys(readState(paths.stateFile).skills || {}), ...(readManifest(cwd)?.skills || [])])];
+  const backup = createBackup({
+    cwd, operation: 'repair', target,
+    paths: managedPathsForInstall({ skillIds: ids, target, home, cwd }),
+  });
+
+  for (const f of todo) {
+    if (f.id === 'nested-layout') rmSync(join(paths.root, 'rsc'), { recursive: true, force: true });
+    if (f.id === 'duplicate-hooks') { unwireHook(target, paths); await applyInstall({ skillIds: ids, target, home, cwd, operation: 'repair' }); }
+    if (f.id === 'dangling-links') await applyInstall({ skillIds: ids, target, home, cwd, operation: 'repair' });
+    if (f.id === 'no-manifest') recordInManifest({ cwd, target, skillIds: ids });
+    if (f.id === 'wrong-target') {
+      // Install where the project actually points, THEN take the old wiring down — in that
+      // order, so a failure halfway leaves a working harness rather than none. Taking the
+      // block out of the old file gives it back byte-identical: in #249 that file was the
+      // project's hand-written constitution, and it had already been written into once.
+      await applyInstall({ skillIds: ids, target: f.to, home, cwd, operation: 'repair' });
+      unwireHook(target, paths);
+      removeManagedSkills(paths);
+      recordInManifest({ cwd, target: f.to, skillIds: ids, dropTarget: target });
+    }
+  }
+  return { applied: todo, pending: changes.filter((c) => !okChanges.includes(c)), backup };
+}