@ericrisco/rsc 1.2.3 → 1.3.0

package/scripts/lib/onboarding-apply.js

@@ -0,0 +1,206 @@
+import { createHash } from 'node:crypto';
+import { appendFileSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, readlinkSync, realpathSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { applyInstall, pruneSharedBases, removeTargetInstall } from '../install-apply.js';
+import { targetPaths } from '../../targets/index.js';
+import { readState } from './state.js';
+import { readManifest, writeManifest } from './manifest-file.js';
+import { encodeGoal, identifyPlan } from './onboarding.js';
+import { createBackup, restoreBackup } from './backups.js';
+
+const sameSet = (a = [], b = []) => JSON.stringify([...a].sort()) === JSON.stringify([...b].sort());
+
+function inside(root, path) {
+  return path === root || path.startsWith(`${root}${sep}`);
+}
+
+export function assertManagedPathsStayInsideRoot(cwd, paths) {
+  const root = realpathSync(resolve(cwd));
+  for (const rel of paths || []) {
+    const clean = rel.replace(/\/$/, '');
+    const absolute = resolve(root, clean);
+    if (!inside(root, absolute)) throw new Error(`RSC_ROOT_AMBIGUOUS: managed path escapes project root: ${rel}`);
+    const segments = relative(root, absolute).split(sep).filter(Boolean);
+    let cursor = root;
+    for (const segment of segments) {
+      cursor = join(cursor, segment);
+      if (!existsSync(cursor)) break;
+      if (lstatSync(cursor).isSymbolicLink()) {
+        const destination = realpathSync(cursor);
+        if (!inside(root, destination)) throw new Error(`RSC_ROOT_AMBIGUOUS: managed path follows a symlink outside project root: ${rel}`);
+      }
+    }
+  }
+}
+
+function digestPath(path) {
+  if (!existsSync(path)) return 'missing';
+  const stat = lstatSync(path);
+  if (stat.isSymbolicLink()) return createHash('sha256').update(`link:${readlinkSync(path)}`).digest('hex');
+  if (stat.isDirectory()) {
+    const rows = readdirSync(path).sort().map((name) => `${name}:${digestPath(join(path, name))}`);
+    return createHash('sha256').update(`dir:${rows.join('|')}`).digest('hex');
+  }
+  return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+
+function digestGovernedPaths(cwd, paths) {
+  return Object.fromEntries((paths || [])
+    .filter((path) => path !== '.rsc.json' && path !== '.rsc/backups/')
+    .map((path) => [path, digestPath(join(cwd, path.replace(/\/$/, '')))]));
+}
+
+function recoveryCommand(plan, planId) {
+  const record = plan.record;
+  return [
+    'npx @ericrisco/rsc@latest onboard',
+    `--technical-level ${record.technicalLevel}`,
+    `--accompaniment ${record.accompaniment}`,
+    `--project-kind ${record.projectKind}`,
+    `--goal-base64 ${encodeGoal(record.goal)}`,
+    ...(record.softwareScope ? [`--software-scope ${record.softwareScope}`] : []),
+    `--target ${record.targets.join(',')}`,
+    `--accept-plan ${planId}`,
+  ].join(' ');
+}
+
+export function renderOnboardingDocuments(plan, planId) {
+  const profile = `---\ntechnical_level: ${plan.record.technicalLevel}\naccompaniment: ${plan.record.accompaniment}\nproject_kind: ${plan.record.projectKind}\n---\n\n# User profile\n\nGoal: ${plan.record.goal}\n`;
+  const rows = plan.decisions.map((d) => `| ${d.kind} | ${d.id} | ${d.state} | ${d.reason} | ${d.reevaluateWhen.join('; ') || '—'} |`).join('\n');
+  const installation = `# Accepted harness plan\n\nPlan id: \`${planId}\`\n\n| Kind | Component | Decision | Reason | Reevaluate when |\n| --- | --- | --- | --- | --- |\n${rows}\n`;
+  const decisions = `# Harness decisions\n\n- Accepted plan \`${planId}\`.\n- Project kind: ${plan.record.projectKind}.\n- SDD: ${plan.decisions.find((d) => d.id === 'sdd')?.state || 'selected through profile'}.\n`;
+  return { profile, installation, decisions };
+}
+
+export function writeOnboardingDocuments(cwd, plan, planId) {
+  const dir = join(cwd, '02-DOCS', 'wiki', 'harness');
+  mkdirSync(dir, { recursive: true });
+  const docs = renderOnboardingDocuments(plan, planId);
+  writeFileSync(join(dir, 'user-profile.md'), docs.profile);
+  writeFileSync(join(dir, 'installation-plan.md'), docs.installation);
+  const decisionsPath = join(dir, 'decisions.md');
+  if (!existsSync(decisionsPath)) writeFileSync(decisionsPath, docs.decisions);
+  else if (!readFileSync(decisionsPath, 'utf8').includes(`Accepted plan \`${planId}\``)) {
+    appendFileSync(decisionsPath, `${readFileSync(decisionsPath, 'utf8').endsWith('\n') ? '' : '\n'}\n${docs.decisions.replace(/^# Harness decisions\n+/, '')}`);
+  }
+}
+
+export function verifyOnboarding(cwd, plan, planId) {
+  const differences = [];
+  if (identifyPlan(plan) !== planId) differences.push('persisted plan identity differs from its canonical content');
+  for (const target of plan.policy.targets) {
+    const state = readState(targetPaths(target, undefined, cwd).stateFile);
+    if (!sameSet(Object.keys(state.skills || {}), plan.policy.skills)) differences.push(`${target}: installed skills differ from accepted policy`);
+    if (!sameSet(state.agents || [], plan.policy.agents || [])) differences.push(`${target}: installed agents differ from accepted policy`);
+    if (state.policy?.alwaysOn !== plan.policy.alwaysOn) differences.push(`${target}: always-on policy differs`);
+    if (state.policy?.codeHooks !== plan.policy.codeHooks) differences.push(`${target}: code-hook policy differs`);
+    if (state.policy?.memory !== plan.policy.memory) differences.push(`${target}: memory policy differs`);
+    if (state.policy?.context7 !== plan.policy.context7) differences.push(`${target}: context7 policy differs`);
+  }
+  for (const name of ['user-profile.md', 'installation-plan.md', 'decisions.md']) {
+    if (!existsSync(join(cwd, '02-DOCS', 'wiki', 'harness', name))) differences.push(`missing ${name}`);
+  }
+  for (const path of plan.governedPaths || []) {
+    if (!existsSync(join(cwd, path.replace(/\/$/, '')))) differences.push(`missing governed path ${path}`);
+  }
+  const manifest = readManifest(cwd);
+  if (manifest?.onboarding?.acceptedPlanId !== planId) differences.push('manifest receipt differs from accepted plan');
+  const expectedDigests = manifest?.onboarding?.artifactDigests;
+  if (!expectedDigests) differences.push('manifest receipt has no governed artifact digests');
+  else {
+    const expectedPaths = (plan.governedPaths || []).filter((path) => path !== '.rsc.json' && path !== '.rsc/backups/');
+    if (!sameSet(Object.keys(expectedDigests), expectedPaths)) differences.push('governed artifact digest inventory differs from accepted plan');
+    for (const path of expectedPaths) {
+      if (digestPath(join(cwd, path.replace(/\/$/, ''))) !== expectedDigests[path]) differences.push(`governed content differs at ${path}`);
+    }
+  }
+  const docsDir = join(cwd, '02-DOCS', 'wiki', 'harness');
+  const profile = existsSync(join(docsDir, 'user-profile.md')) ? readFileSync(join(docsDir, 'user-profile.md'), 'utf8') : '';
+  for (const line of [
+    `technical_level: ${plan.record.technicalLevel}`,
+    `accompaniment: ${plan.record.accompaniment}`,
+    `project_kind: ${plan.record.projectKind}`,
+    `Goal: ${plan.record.goal}`,
+  ]) if (!profile.split('\n').includes(line)) differences.push(`profile content differs: ${line.split(':')[0]}`);
+  const installation = existsSync(join(docsDir, 'installation-plan.md')) ? readFileSync(join(docsDir, 'installation-plan.md'), 'utf8') : '';
+  if (!installation.includes(`Plan id: \`${planId}\``)) differences.push('installation plan identity differs');
+  for (const decision of plan.decisions || []) {
+    const row = `| ${decision.kind} | ${decision.id} | ${decision.state} | ${decision.reason} | ${decision.reevaluateWhen.join('; ') || '—'} |`;
+    if (!installation.split('\n').includes(row)) differences.push(`installation plan content differs for ${decision.kind}/${decision.id}`);
+  }
+  const decisions = existsSync(join(docsDir, 'decisions.md')) ? readFileSync(join(docsDir, 'decisions.md'), 'utf8') : '';
+  if (!decisions.includes(`Accepted plan \`${planId}\``)) differences.push('decision ledger omits accepted plan');
+  if (!sameSet(manifest?.targets || [], plan.policy.targets)) differences.push('manifest targets differ from accepted policy');
+  if (!sameSet(manifest?.skills || [], plan.policy.skills)) differences.push('manifest skills differ from accepted policy');
+  if (!sameSet(manifest?.agents || [], plan.policy.agents || [])) differences.push('manifest agents differ from accepted policy');
+  return differences;
+}
+
+export async function applyAcceptedOnboarding({ cwd = process.cwd(), plan, planId, now = new Date(), apply = applyInstall }) {
+  if (identifyPlan(plan) !== planId) throw new Error('RSC_PLAN_CHANGED: regenerate the plan and ask the user to accept the new id');
+  const previousManifest = readManifest(cwd);
+  const previousReceipt = previousManifest?.onboarding;
+  const previousPlan = previousReceipt?.plan;
+  const transactionPaths = [...new Set([
+    ...(plan.governedPaths || []),
+    ...(previousPlan?.governedPaths || []),
+    '.rsc.json',
+  ])];
+  assertManagedPathsStayInsideRoot(cwd, transactionPaths);
+  const snapshotPaths = transactionPaths.filter((path) => path !== '.rsc/backups/');
+  const transaction = createBackup({
+    cwd, operation: 'onboarding-transaction', target: plan.policy.targets.join('-'),
+    paths: snapshotPaths.map((path) => join(cwd, path.replace(/\/$/, ''))), cliVersion: 'onboarding', now,
+  });
+  const existed = Object.fromEntries((plan.governedPaths || []).map((path) => [path, existsSync(join(cwd, path.replace(/\/$/, '')))]));
+  const receipt = {
+    schemaVersion: 1,
+    acceptedPlanId: planId,
+    acceptedAt: now.toISOString(),
+    plan,
+    provenance: {
+      skills: Object.fromEntries(plan.policy.skills.map((id) => [id,
+        previousReceipt?.plan?.policy?.skills?.includes(id) ? 'conserved' : previousManifest?.skills?.includes(id) ? 'preexisting' : 'installed',
+      ])),
+      targets: Object.fromEntries(plan.policy.targets.map((id) => [id,
+        previousReceipt?.plan?.policy?.targets?.includes(id) ? 'conserved' : previousManifest?.targets?.includes(id) ? 'preexisting' : 'installed',
+      ])),
+      paths: {},
+    },
+  };
+  try {
+    for (const target of previousPlan?.policy?.targets || []) {
+      if (!plan.policy.targets.includes(target)) removeTargetInstall({ cwd, target });
+    }
+    for (const target of plan.policy.targets) {
+      await apply({
+        cwd,
+        target,
+        skillIds: plan.policy.skills,
+        policy: plan.policy,
+        operation: 'onboard',
+      });
+    }
+    pruneSharedBases({ cwd, skillIds: plan.policy.skills });
+    writeOnboardingDocuments(cwd, plan, planId);
+    receipt.provenance.paths = Object.fromEntries((plan.governedPaths || []).map((path) => [
+      path,
+      existed[path] ? (previousReceipt ? 'conserved' : 'preexisting') : 'installed',
+    ]));
+    receipt.artifactDigests = digestGovernedPaths(cwd, plan.governedPaths);
+    const manifest = readManifest(cwd);
+    writeManifest(cwd, {
+      ...manifest,
+      targets: [...plan.policy.targets],
+      skills: [...plan.policy.skills],
+      agents: [...(plan.policy.agents || [])],
+      onboarding: receipt,
+    });
+    const differences = verifyOnboarding(cwd, plan, planId);
+    if (differences.length) throw new Error(differences.join('; '));
+    return receipt;
+  } catch (error) {
+    restoreBackup({ cwd, id: transaction.id });
+    throw new Error(`RSC_ONBOARDING_INCOMPLETE: ${error.message}. Recover with: ${recoveryCommand(plan, planId)}`);
+  }
+}

package/scripts/lib/onboarding.js

@@ -0,0 +1,301 @@
+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 === '02-DOCS/wiki/harness' || rel.startsWith('02-DOCS/wiki/harness/')) 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']]) 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 needsSdd = isSoftware && (normalized.softwareScope !== 'small' || complexitySignals.length > 0);
+  const profile = needsSdd ? 'core' : 'minimal';
+  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 = needsSdd;
+  const hooks = needsSdd;
+  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', needsSdd
+      ? (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 (!needsSdd) 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));
+  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 02-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.'));
+  decisions.sort((a, b) => `${a.kind}:${a.id}`.localeCompare(`${b.kind}:${b.id}`));
+  const policy = {
+    skills,
+    targets: normalized.targets,
+    baseAgents,
+    agents,
+    alwaysOn: true,
+    codeHooks: needsSdd,
+    gitmojiGuard,
+    memory: true,
+    context7: false,
+  };
+  const root = evidence.root;
+  const governedPaths = root ? [...new Set([
+    '.rsc.json', '.rsc/backups/',
+    ...(existsSync(join(root, '.git')) ? ['.gitignore'] : []),
+    '02-DOCS/wiki/harness/user-profile.md',
+    '02-DOCS/wiki/harness/decisions.md',
+    '02-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/', '02-DOCS/wiki/harness/'];
+  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,
+  };
+}
+
+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;
+}