@juangcarmona/lighthouse 0.1.0 → 0.3.0

package/src/lighthouse.mjs

@@ -1,60 +1,852 @@
 #!/usr/bin/env node
-import { readFile, writeFile } from 'node:fs/promises';
-import { resolve } from 'node:path';
+import { access, chmod, mkdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { constants, readFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import { basename, dirname, resolve } from 'node:path';
+import { execFileSync, spawnSync } from 'node:child_process';
+import { evaluateGuardrails, readGuardrailCatalog } from './guardrails.mjs';
 
 const root = process.cwd();
+const packageRequire = createRequire(import.meta.url);
+const cliPackage = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
+function installedPackageVersion(name, entry) {
+  try {
+    const entryPath = packageRequire.resolve(`${name}/${entry}`);
+    return JSON.parse(readFileSync(resolve(dirname(entryPath), 'package.json'), 'utf8')).version;
+  } catch { return null; }
+}
 const manifestPath = resolve(root, 'lighthouse.json');
 const projection = 'LIGHTHOUSE.md';
-const usage = 'Usage: lighthouse <init|verify>';
+const upgradeStateRelative = '.lighthouse/upgrade.json';
+const upgradeStatePath = resolve(root, upgradeStateRelative);
+const layout = ['src', 'docs', 'infra', 'scripts'];
+const sdlcPackage = { name: '@juangcarmona/lighthouse-sdlc', version: installedPackageVersion('@juangcarmona/lighthouse-sdlc', 'contract.json') ?? '0.1.0' };
+const managedPaths = [
+  projection,
+  'scripts/lighthouse-guard.mjs',
+  '.husky/commit-msg',
+  '.husky/pre-push',
+  '.github/workflows/lighthouse.yml',
+  '.lighthouse/sdlc.json',
+  upgradeStateRelative,
+];
+const previousManagedPaths = managedPaths.slice(0, -1);
+const legacyManagedPaths = [projection];
+const branchPattern = '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$';
+const authorityVersions = { productShape: '0.22.0', arcShape: '0.1.3' };
+const upgradeScopes = {
+  harness: [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml'],
+  sdlc: ['.lighthouse/sdlc.json'],
+};
+const upgradeSchema = './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-upgrade.schema.json';
+const usage = 'Usage: lighthouse <init|authorities|reconcile|upgrade|verify> [--name <product>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
+
+const defaultRepository = () => ({
+  layout: [...layout],
+  publicSite: { enabled: true },
+  conventions: { commits: 'conventional', branchPattern },
+});
+
+function defaultManifest(product) {
+  return {
+    $schema: './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-manifest.schema.json',
+    schemaVersion: 1,
+    baseline: '0.1.0',
+    product,
+    profiles: [],
+    integrations: { productShape: null, arcShape: null },
+    packages: { sdlc: { ...sdlcPackage } },
+    managed: [...managedPaths],
+    repository: defaultRepository(),
+  };
+}
+
+function normalizeRepository(repository) {
+  const value = repository && typeof repository === 'object' && !Array.isArray(repository) ? repository : {};
+  return {
+    layout: Array.isArray(value.layout) ? value.layout : [...layout],
+    publicSite: value.publicSite && typeof value.publicSite === 'object'
+      ? { enabled: value.publicSite.enabled !== false }
+      : { enabled: true },
+    conventions: value.conventions && typeof value.conventions === 'object'
+      ? {
+        commits: value.conventions.commits ?? 'conventional',
+        branchPattern: value.conventions.branchPattern ?? branchPattern,
+      }
+      : { commits: 'conventional', branchPattern },
+  };
+}
+
+function normalizeSdlcPackage(manifest) {
+  const value = manifest?.packages?.sdlc;
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
+  return { name: value.name, version: value.version };
+}
+
+function sdlcContract() {
+  try {
+    const path = packageRequire.resolve('@juangcarmona/lighthouse-sdlc/contract.json');
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return {
+      routes: ['supervised', 'plan-only', 'unattended', 'hotfix', 'stacked'],
+      gates: ['triaged', 'ready', 'planned', 'done'],
+    };
+  }
+}
+
+function sdlcControlPlane(manifest) {
+  const selected = normalizeSdlcPackage(manifest);
+  if (!selected) return null;
+  const contract = sdlcContract();
+  return `${JSON.stringify({
+    $schema: './node_modules/@juangcarmona/lighthouse-sdlc/schemas/control-plane.schema.json',
+    schemaVersion: 1,
+    package: selected,
+    routes: contract.routes,
+    gates: contract.gates,
+    state: { provider: 'agent-host' },
+    memory: { provider: 'agent-host', scopes: ['run', 'project'] },
+    roles: {},
+    adapters: {},
+  }, null, 2)}\n`;
+}
 
 function render(manifest) {
-  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Agentic SDLC: ${manifest.integrations.agenticSdlc ?? 'not adopted'}\n\n## How delivery works\n\nUse ProductShape for product intent and Product Changes, and use ArcShape for applicable architecture decisions; they can advance independently. Lighthouse carries the selected authority context through the delivery stages.\n\nA greenfield project initializes both authorities through their supported provider routes. An existing project can adopt them incrementally after its ownership and managed paths are assessed. The adoption contract includes a check of the external CodeGraph MCP service, its current git-root binding and the canonical repository and active worktrees; its index and credentials stay outside the checkout.\n\n1. \`triage\` classifies the work item, estimates complexity and blast radius, records urgency, impact, dependencies and risk, and sets configured workflow labels.\n2. \`refine\` defines the problem and stops at Ready.\n3. \`propose\` creates the solution and stops at Planned.\n4. \`implement\` applies the accepted plan and stops at Done.\n5. \`integrate\` updates the tracker, maintains the PR stack and closes the repository loop.\n6. \`review\` records learning after completion.\n\nThese are lifecycle capabilities. The baseline CLI currently provides \`init\` and \`verify\`; a configured OpenSpec, tracker or agent-host integration supplies the stage commands.\n\nChoose supervised work when a person steers each stage, plan-only work when only the proposal is needed, \`ff\` for a bounded unattended route, \`hotfix\` for a confirmed defect or \`decompose\` for a large item that needs ordered child issues and stacked PRs.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
+  const repository = normalizeRepository(manifest.repository);
+  const publicSite = repository.publicSite.enabled ? 'enabled' : 'disabled';
+  const selectedSdlc = normalizeSdlcPackage(manifest);
+  const sdlcLine = selectedSdlc ? `- SDLC package: \`${selectedSdlc.name}@${selectedSdlc.version}\`\n` : '';
+  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n${sdlcLine}- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Public site: \`${publicSite}\`\n- Repository roots: ${repository.layout.map((x) => `\`${x}/\``).join(', ')}\n- Commit convention: \`${repository.conventions.commits}\`\n\n## Delivery contract\n\nProductShape remains the source of product intent and Product Changes. ArcShape remains the source of architecture documentation and decisions. Lighthouse installs the repository baseline and verifies the selected integrations without replacing either authority.\n\nThe repository keeps source code in \`src/\`, documentation in \`docs/\`, infrastructure in \`infra/\` and repository automation in \`scripts/\`. A project may record a narrow, owned exception, but an initializer never overwrites an existing project file.\n\nThe selected SDLC package owns lifecycle skills, commands, meta-commands, routes and gates. The \`.lighthouse/\` control plane records the selected package and host adapters without storing agent runtime data.\n\nWhen the public site is enabled, its publication is allowed only after ProductShape and ArcShape validate successfully. A missing or invalid authority stops the build before deployment and reports the command that can repair the missing input.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
+}
+
+function guardrailScript(manifest) {
+  const pattern = JSON.stringify(normalizeRepository(manifest.repository).conventions.branchPattern);
+  return `#!/usr/bin/env node
+import { readFileSync } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+
+const mode = process.argv[2];
+const branchPattern = new RegExp(${pattern}, 'u');
+function fail(message) { console.error(message); process.exit(1); }
+function branch() {
+  try { return execFileSync('git', ['branch', '--show-current'], { encoding: 'utf8' }).trim(); }
+  catch { return ''; }
+}
+if (mode === 'commit-msg') {
+  const file = process.argv[3];
+  if (!file) fail('Usage: lighthouse-guard commit-msg <message-file>');
+  const message = readFileSync(file, 'utf8').split('\\n').find((line) => line.trim() && !line.startsWith('#'))?.trim() ?? '';
+  if (!/^(?:feat|fix|docs|refactor|test|chore|build|ci|perf|revert)(?:\\([^)]+\\))?!?: .+/u.test(message)) fail('Commit message must follow Conventional Commits.');
+} else if (mode === 'branch' || mode === 'verify') {
+  const current = branch();
+  if (current && !['main', 'master'].includes(current) && !branchPattern.test(current)) fail('Branch ' + current + ' does not match ' + branchPattern.source + '.');
+} else fail('Usage: lighthouse-guard <commit-msg|branch|verify>');
+`;
+}
+
+function commitHook() {
+  return '#!/usr/bin/env sh\nset -eu\nnode scripts/lighthouse-guard.mjs commit-msg "$1"\n';
+}
+
+function prePushHook() {
+  return '#!/usr/bin/env sh\nset -eu\nnode scripts/lighthouse-guard.mjs branch\n';
+}
+
+function workflow() {
+  return `name: Lighthouse repository guardrails
+
+on:
+  pull_request:
+    paths:
+      - "lighthouse.json"
+      - "LIGHTHOUSE.md"
+      - "src/**"
+      - "docs/**"
+      - "infra/**"
+      - "scripts/**"
+      - ".husky/**"
+      - ".github/workflows/lighthouse.yml"
+  push:
+    branches: [main]
+    paths:
+      - "lighthouse.json"
+      - "LIGHTHOUSE.md"
+      - "src/**"
+      - "docs/**"
+      - "infra/**"
+      - "scripts/**"
+      - ".husky/**"
+      - ".github/workflows/lighthouse.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify Lighthouse foundation
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+      - run: npm ci --ignore-scripts
+      - run: |
+          if [ -f scripts/lighthouse.mjs ]; then node scripts/lighthouse.mjs verify; else npx --no-install lighthouse verify; fi
+      - run: node scripts/lighthouse-guard.mjs verify
+`;
+}
+
+function managedFiles(manifest) {
+  const files = {
+    [projection]: render(manifest),
+    'scripts/lighthouse-guard.mjs': guardrailScript(manifest),
+    '.husky/commit-msg': commitHook(),
+    '.husky/pre-push': prePushHook(),
+    '.github/workflows/lighthouse.yml': workflow(),
+  };
+  const controlPlane = sdlcControlPlane(manifest);
+  if (controlPlane) files['.lighthouse/sdlc.json'] = controlPlane;
+  return files;
+}
+
+function contentHash(content) {
+  return createHash('sha256').update(content).digest('hex');
+}
+
+function upgradeState(manifest, files = managedFiles(manifest), previous = null) {
+  const entries = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, {
+    hash: contentHash(content),
+    scope: Object.entries(upgradeScopes).find(([, paths]) => paths.includes(path))?.[0] ?? 'harness',
+  }]));
+  return {
+    $schema: upgradeSchema,
+    schemaVersion: 1,
+    package: { name: cliPackage.name, version: cliPackage.version },
+    baseline: manifest.baseline,
+    capabilities: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
+    projections: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
+    lastAppliedMigration: previous?.lastAppliedMigration ?? 'foundation-init-1',
+    files: entries,
+  };
+}
+
+async function readUpgradeState() {
+  try { return JSON.parse(await readFile(upgradeStatePath, 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`Cannot read ${upgradeStateRelative}: ${error.message}`);
+  }
 }
 
-function validate(m) {
+async function writeUpgradeState(manifest, previous = null, files = managedFiles(manifest)) {
+  const state = upgradeState(manifest, files, previous);
+  await mkdir(dirname(upgradeStatePath), { recursive: true });
+  await writeFile(upgradeStatePath, `${JSON.stringify(state, null, 2)}\n`, { flag: 'w' });
+}
+
+function stateProblems(state) {
+  if (!state || typeof state !== 'object' || Array.isArray(state)) return [`${upgradeStateRelative} is missing; run lighthouse reconcile --apply to establish ownership evidence.`];
+  const problems = [];
+  if (state.schemaVersion !== 1) problems.push(`${upgradeStateRelative} has unsupported schemaVersion ${state.schemaVersion}.`);
+  if (!state.package || state.package.name !== cliPackage.name || typeof state.package.version !== 'string') problems.push(`${upgradeStateRelative} does not identify the installed Lighthouse package.`);
+  if (!state.files || typeof state.files !== 'object' || Array.isArray(state.files)) problems.push(`${upgradeStateRelative} does not contain file ownership evidence.`);
+  return problems;
+}
+
+function scopesFromArgs(args) {
+  const selected = new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== '--scope' && !args[index].startsWith('--scope=')) continue;
+    const value = args[index] === '--scope' ? args[index + 1] : args[index].slice('--scope='.length);
+    if (args[index] === '--scope') index += 1;
+    if (!value) throw new Error('--scope requires harness, sdlc or all');
+    for (const scope of value.split(',')) {
+      if (scope === 'all') { selected.add('harness'); selected.add('sdlc'); }
+      else if (scope === 'harness' || scope === 'sdlc') selected.add(scope);
+      else throw new Error(`Unknown upgrade scope ${scope}; use harness, sdlc or all.`);
+    }
+  }
+  return selected.size ? selected : new Set(Object.keys(upgradeScopes));
+}
+
+function selectedPaths(scopes) {
+  return new Set([...scopes].flatMap((scope) => upgradeScopes[scope]));
+}
+
+function classifyUpgradeFile(path, current, expected, recordedHash) {
+  if (current === null) return { classification: 'additive', action: 'add' };
+  const currentHash = contentHash(current);
+  if (current === expected && currentHash === recordedHash) return { classification: 'unchanged', action: 'keep' };
+  if (current === expected && currentHash !== recordedHash) return { classification: 'adoptable', action: 'record' };
+  if (recordedHash && currentHash === recordedHash) return { classification: 'adoptable', action: 'update' };
+  if (recordedHash) return { classification: 'customized', action: 'preserve', reason: 'current content differs from the recorded projection' };
+  return { classification: 'conflicting', action: 'review', reason: 'ownership is not recorded for this path' };
+}
+
+async function planUpgrade(manifest, scopes) {
+  const state = await readUpgradeState();
+  const problems = stateProblems(state);
+  const files = managedFiles(manifest);
+  const paths = selectedPaths(scopes);
+  const changes = [];
+  for (const path of Object.keys(files).filter((candidate) => paths.has(candidate))) {
+    const target = resolve(root, path);
+    const current = await exists(target) ? await readFile(target, 'utf8') : null;
+    const expected = files[path];
+    const recordedHash = state?.files?.[path]?.hash;
+    const result = classifyUpgradeFile(path, current, expected, recordedHash);
+    changes.push({ path, scope: Object.entries(upgradeScopes).find(([, values]) => values.includes(path))?.[0], ...result });
+  }
+  if (state?.baseline && state.baseline !== manifest.baseline) {
+    changes.unshift({ path: 'baseline', scope: 'harness', classification: 'breaking', action: 'review', reason: `baseline ${state.baseline} is not compatible with ${manifest.baseline}` });
+  }
+  return {
+    source: {
+      package: state?.package ?? null,
+      baseline: state?.baseline ?? null,
+      capabilities: state?.capabilities ?? null,
+      projections: state?.projections ?? null,
+      lastAppliedMigration: state?.lastAppliedMigration ?? null,
+    },
+    target: {
+      package: { name: cliPackage.name, version: cliPackage.version },
+      baseline: manifest.baseline,
+      capabilities: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
+      projections: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
+    },
+    scopes: [...scopes],
+    prerequisites: problems.length ? [{ status: 'failed', message: problems.join(' ') }] : [{ status: 'passed', message: 'Ownership metadata is readable.' }],
+    changes,
+    verification: ['lighthouse verify'],
+    recovery: 'Restore the pre-update commit or rerun lighthouse upgrade after resolving the reported ownership conflict.',
+    problems,
+  };
+}
+
+function printUpgradePlan(plan) {
+  console.log('Lighthouse upgrade plan:');
+  console.log(`  package ${plan.source.package?.version ?? 'unknown'} -> ${plan.target.package.version}`);
+  console.log(`  baseline ${plan.source.baseline ?? 'unknown'} -> ${plan.target.baseline}`);
+  console.log(`  scopes ${plan.scopes.join(', ')}`);
+  for (const prerequisite of plan.prerequisites) console.log(`  prerequisite ${prerequisite.status}: ${prerequisite.message}`);
+  for (const change of plan.changes) console.log(`  ${change.classification} ${change.action} ${change.path}${change.reason ? ` (${change.reason})` : ''}`);
+  if (plan.problems.length) for (const problem of plan.problems) console.error(`  adoption gap ${problem}`);
+  console.log(`  verify ${plan.verification[0]}`);
+  console.log(`  recovery ${plan.recovery}`);
+}
+
+function validate(manifest) {
   const problems = [];
-  if (!m || typeof m !== 'object' || Array.isArray(m)) return ['manifest must be an object'];
-  const allowed = ['$schema', 'schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'managed'];
-  for (const key of Object.keys(m)) if (!allowed.includes(key)) problems.push(`unknown field ${key}`);
-  for (const key of ['schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'managed']) if (!(key in m)) problems.push(`missing ${key}`);
-  if (m.schemaVersion !== 1) problems.push('schemaVersion must be 1');
-  if (m.baseline !== '0.1.0') problems.push('this verifier supports baseline 0.1.0');
-  if ('$schema' in m && typeof m.$schema !== 'string') problems.push('$schema must be a string');
-  if (typeof m.product !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(m.product)) problems.push('product must be a readable name of 1–64 characters');
+  if (!manifest || typeof manifest !== 'object' || Array.isArray(manifest)) return ['manifest must be an object'];
+  const allowed = ['$schema', 'schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'packages', 'managed', 'repository'];
+  for (const key of Object.keys(manifest)) if (!allowed.includes(key)) problems.push(`unknown field ${key}`);
+  for (const key of ['schemaVersion', 'baseline', 'product', 'profiles', 'integrations', 'managed']) {
+    if (!(key in manifest)) problems.push(`missing ${key}`);
+  }
+  if (manifest.schemaVersion !== 1) problems.push('schemaVersion must be 1');
+  if (manifest.baseline !== '0.1.0') problems.push('this verifier supports baseline 0.1.0');
+  if ('$schema' in manifest && typeof manifest.$schema !== 'string') problems.push('$schema must be a string');
+  if (typeof manifest.product !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(manifest.product)) {
+    problems.push('product must be a readable name of 1–64 characters');
+  }
   const profiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
-  if (!Array.isArray(m.profiles) || m.profiles.some((p) => !profiles.includes(p)) || new Set(m.profiles).size !== m.profiles.length) problems.push('profiles must be unique supported profile names');
-  const integrations = m.integrations;
-  const keys = ['productShape', 'arcShape', 'agenticSdlc'];
+  if (!Array.isArray(manifest.profiles) || manifest.profiles.some((p) => !profiles.includes(p))
+      || new Set(manifest.profiles).size !== manifest.profiles.length) {
+    problems.push('profiles must be unique supported profile names');
+  }
+  const integrations = manifest.integrations;
+  const keys = ['productShape', 'arcShape'];
   const pin = /^(?:\d+\.\d+\.\d+|[a-f0-9]{40})$/;
   if (!integrations || typeof integrations !== 'object' || Array.isArray(integrations)
       || Object.keys(integrations).length !== keys.length
-      || keys.some((k) => !(k in integrations) || (integrations[k] !== null && (typeof integrations[k] !== 'string' || !pin.test(integrations[k])))))
-    problems.push('integrations must declare productShape, arcShape and agenticSdlc as exact versions, commit hashes or null');
-  if (!Array.isArray(m.managed) || m.managed.length !== 1 || m.managed[0] !== projection) problems.push(`only ${projection} is managed by this version`);
+      || keys.some((key) => !(key in integrations)
+        || (integrations[key] !== null && (typeof integrations[key] !== 'string' || !pin.test(integrations[key]))))) {
+    problems.push('integrations must declare productShape and arcShape as exact versions, commit hashes or null');
+  }
+  if ('packages' in manifest) {
+    const packages = manifest.packages;
+    const selected = packages?.sdlc;
+    if (!packages || typeof packages !== 'object' || Array.isArray(packages)
+        || Object.keys(packages).length !== 1
+        || !selected || typeof selected !== 'object' || Array.isArray(selected)
+        || Object.keys(selected).length !== 2
+        || selected.name !== sdlcPackage.name
+        || typeof selected.version !== 'string' || !pin.test(selected.version)) {
+      problems.push(`packages.sdlc must declare ${sdlcPackage.name} and an exact version or commit hash`);
+    }
+  }
+  const legacyManaged = Array.isArray(manifest.managed)
+    && manifest.managed.length === legacyManagedPaths.length
+    && manifest.managed.every((entry, index) => entry === legacyManagedPaths[index]);
+  const completeManaged = Array.isArray(manifest.managed)
+    && manifest.managed.length === managedPaths.length
+    && manifest.managed.every((entry, index) => entry === managedPaths[index]);
+  const previousCompleteManaged = Array.isArray(manifest.managed)
+    && manifest.managed.length === previousManagedPaths.length
+    && manifest.managed.every((entry, index) => entry === previousManagedPaths[index]);
+  if (!legacyManaged && !previousCompleteManaged && !completeManaged) {
+    problems.push(`managed must be ${legacyManagedPaths.join(', ')}, the previous Lighthouse guardrail set or the current complete set`);
+  }
+  if ('repository' in manifest) {
+    const repository = manifest.repository;
+    if (!repository || typeof repository !== 'object' || Array.isArray(repository)) {
+      problems.push('repository must be an object');
+    } else {
+      if (!Array.isArray(repository.layout) || repository.layout.length !== layout.length
+          || repository.layout.some((entry, index) => entry !== layout[index])) {
+        problems.push(`repository.layout must be ${layout.map((entry) => `'${entry}'`).join(', ')}`);
+      }
+      if (!repository.publicSite || typeof repository.publicSite.enabled !== 'boolean') {
+        problems.push('repository.publicSite.enabled must be a boolean');
+      }
+      if (!repository.conventions || repository.conventions.commits !== 'conventional'
+          || typeof repository.conventions.branchPattern !== 'string') {
+        problems.push('repository.conventions must declare conventional commits and a branchPattern');
+      } else {
+        try { new RegExp(repository.conventions.branchPattern, 'u'); }
+        catch { problems.push('repository.conventions.branchPattern must be a valid regular expression'); }
+      }
+    }
+  }
   return problems;
 }
 
-const command = process.argv[2];
-if (!['init', 'verify'].includes(command)) { console.error(usage); process.exit(2); }
-let manifest;
-try { manifest = JSON.parse(await readFile(manifestPath, 'utf8')); }
-catch (error) { console.error(`Cannot read lighthouse.json: ${error.message}`); process.exit(1); }
-const problems = validate(manifest);
-if (problems.length) { console.error(problems.map((p) => `Invalid lighthouse.json: ${p}`).join('\n')); process.exit(1); }
-const expected = render(manifest);
-const target = resolve(root, projection);
-if (command === 'init') {
-  try { await readFile(target); console.error(`${projection} already exists; refusing to overwrite it. Review the manifest and manage the file explicitly.`); process.exit(1); }
-  catch (error) { if (error.code !== 'ENOENT') throw error; }
-  await writeFile(target, expected, { flag: 'wx' });
-  console.log(`Created ${projection} from lighthouse.json.`);
-} else {
+async function exists(path) {
+  try { await access(path, constants.F_OK); return true; } catch { return false; }
+}
+
+async function isDirectory(path) {
+  try { return (await stat(path)).isDirectory(); } catch { return false; }
+}
+
+async function readManifest() {
+  try { return JSON.parse(await readFile(manifestPath, 'utf8')); }
+  catch (error) {
+    if (error.code === 'ENOENT') return null;
+    throw new Error(`Cannot read lighthouse.json: ${error.message}`);
+  }
+}
+
+function productNameFromArgs(args) {
+  const index = args.indexOf('--name');
+  const value = index === -1 ? args.find((arg) => arg.startsWith('--name='))?.slice('--name='.length) : args[index + 1];
+  if (index === -1 && !value) return basename(root).replace(/[^A-Za-z0-9 ._-]/gu, '').slice(0, 64) || 'adopter';
+  if (!value) throw new Error('--name requires a product name');
+  return value;
+}
+
+async function planInitialization(manifest, manifestMissing) {
+  const operations = [];
+  const conflicts = [];
+  if (manifestMissing) operations.push({ path: 'lighthouse.json', action: 'create' });
+  const files = managedFiles(manifest);
+  const directories = new Set(normalizeRepository(manifest.repository).layout);
+  for (const file of Object.keys(files)) {
+    let directory = dirname(file);
+    while (directory !== '.') {
+      directories.add(directory);
+      directory = dirname(directory);
+    }
+  }
+  for (const directory of [...directories].sort((left, right) => left.split('/').length - right.split('/').length)) {
+    const path = resolve(root, directory);
+    if (!(await exists(path))) operations.push({ path: `${directory}/`, action: 'create' });
+    else if (!(await isDirectory(path))) conflicts.push(`${directory} exists but is not a directory`);
+  }
+  for (const file of Object.keys(files)) {
+    if (await exists(resolve(root, file))) conflicts.push(`${file} already exists; refusing to overwrite it`);
+    else operations.push({ path: file, action: 'create' });
+  }
+  if (await exists(upgradeStatePath)) conflicts.push(`${upgradeStateRelative} already exists; refusing to overwrite it`);
+  else operations.push({ path: upgradeStateRelative, action: 'create' });
+  return { operations, conflicts };
+}
+
+async function planReconciliation(manifest) {
+  const operations = [];
+  const conflicts = [];
+  for (const [path, expected] of Object.entries(managedFiles(manifest))) {
+    const target = resolve(root, path);
+    if (!(await exists(target))) {
+      operations.push({ path, action: 'create', content: expected });
+      continue;
+    }
+    try {
+      const current = await readFile(target, 'utf8');
+      if (current === expected) operations.push({ path, action: 'unchanged' });
+      else conflicts.push(`${path} exists with different content; refusing to overwrite it`);
+    } catch {
+      conflicts.push(`${path} exists but is not a readable file; refusing to overwrite it`);
+    }
+  }
+  if (!(await exists(upgradeStatePath))) {
+    operations.push({ path: upgradeStateRelative, action: 'create', content: `${JSON.stringify(upgradeState(manifest), null, 2)}\n` });
+  }
+  return { operations, conflicts };
+}
+
+function printReconciliationPlan(plan) {
+  console.log('Lighthouse reconciliation plan:');
+  for (const operation of plan.operations) console.log(`  ${operation.action} ${operation.path}`);
+  for (const conflict of plan.conflicts) console.error(`  conflict ${conflict}`);
+}
+
+async function initialize(args) {
+  let manifest = await readManifest();
+  const manifestMissing = !manifest;
+  if (!manifest) manifest = defaultManifest(productNameFromArgs(args));
+  const problems = validate(manifest);
+  if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
+  const plan = await planInitialization(manifest, manifestMissing);
+  console.log('Lighthouse initialization plan:');
+  for (const operation of plan.operations) console.log(`  ${operation.action} ${operation.path}`);
+  for (const conflict of plan.conflicts) console.error(`  conflict ${conflict}`);
+  if (normalizeRepository(manifest.repository).publicSite.enabled) {
+    if (manifest.integrations.productShape === null) console.log('  adoption gap ProductShape: review lighthouse authorities --dry-run, then run lighthouse authorities --apply');
+    if (manifest.integrations.arcShape === null) console.log('  adoption gap ArcShape: review lighthouse authorities --dry-run, then run lighthouse authorities --apply');
+  }
+  if (args.includes('--dry-run')) {
+    if (plan.conflicts.length) process.exitCode = 1;
+    return;
+  }
+  if (plan.conflicts.length) throw new Error('Initialization stopped; resolve the reported conflicts and run lighthouse init again.');
+  if (manifestMissing) await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  for (const operation of plan.operations.filter((item) => item.path.endsWith('/'))) {
+    await mkdir(resolve(root, operation.path), { recursive: true });
+  }
+  const files = managedFiles(manifest);
+  for (const [file, content] of Object.entries(files)) {
+    await writeFile(resolve(root, file), content, { flag: 'wx', mode: file.startsWith('.husky/') ? 0o755 : 0o644 });
+    if (file.startsWith('.husky/')) await chmod(resolve(root, file), 0o755);
+  }
+  await writeUpgradeState(manifest, null, files);
   try {
-    const actual = await readFile(target, 'utf8');
-    if (actual !== expected) { console.error(`${projection} has drifted. Regenerate it from lighthouse.json or restore the generated content.`); process.exit(1); }
+    const configured = execFileSync('git', ['config', '--get', 'core.hooksPath'], { cwd: root, encoding: 'utf8' }).trim();
+    if (!configured) execFileSync('git', ['config', 'core.hooksPath', '.husky'], { cwd: root, stdio: 'ignore' });
+  } catch { /* A non-git target can adopt the hooks when it creates its repository. */ }
+  console.log(`Initialized ${manifest.product}. Review lighthouse.json and the managed guardrails, then run lighthouse verify.`);
+}
+
+async function reconcile(args) {
+  const manifest = await readManifest();
+  if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');
+  const problems = validate(manifest);
+  if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
+  const plan = await planReconciliation(manifest);
+  printReconciliationPlan(plan);
+  const apply = args.includes('--apply');
+  const dryRun = args.includes('--dry-run') || !apply;
+  if (args.includes('--apply') && args.includes('--dry-run')) throw new Error('--apply and --dry-run cannot be used together.');
+  if (plan.conflicts.length) {
+    if (dryRun) process.exitCode = 1;
+    else throw new Error('Reconciliation stopped; resolve the reported conflicts and run lighthouse reconcile again.');
+    return;
+  }
+  if (dryRun) {
+    console.log('Dry run: nothing was changed. Re-run with --apply to create missing managed paths.');
+    return;
+  }
+  for (const operation of plan.operations.filter((item) => item.action === 'create')) {
+    await mkdir(dirname(resolve(root, operation.path)), { recursive: true });
+    try {
+      await writeFile(resolve(root, operation.path), operation.content, { flag: 'wx', mode: operation.path.startsWith('.husky/') ? 0o755 : 0o644 });
+      if (operation.path.startsWith('.husky/')) await chmod(resolve(root, operation.path), 0o755);
+    } catch (error) {
+      if (error.code === 'EEXIST') throw new Error(`Reconciliation stopped; ${operation.path} appeared during the plan.`);
+      throw error;
+    }
+  }
+  console.log('Reconciled missing Lighthouse-managed paths. Run lighthouse verify to check the complete projection.');
+}
+
+async function writeTextAtomically(path, content) {
+  const temporary = `${path}.tmp-${process.pid}`;
+  await writeFile(temporary, content, { flag: 'wx' });
+  await rename(temporary, path);
+}
+
+async function applyUpgrade(manifest, plan) {
+  if (plan.problems.length) throw new Error(`Upgrade stopped; ${plan.problems.join(' ')}`);
+  const blocked = plan.changes.filter((change) => ['conflicting', 'breaking'].includes(change.classification));
+  if (blocked.length) throw new Error(`Upgrade stopped; resolve ownership conflicts for: ${blocked.map((change) => change.path).join(', ')}.`);
+  const files = managedFiles(manifest);
+  const previous = await readUpgradeState();
+  const snapshots = new Map();
+  const updates = plan.changes.filter((change) => ['add', 'update', 'record'].includes(change.action));
+  for (const change of updates) {
+    const target = resolve(root, change.path);
+    snapshots.set(change.path, await exists(target) ? await readFile(target, 'utf8') : null);
+  }
+  const stateSnapshot = await readFile(upgradeStatePath, 'utf8');
+  try {
+    for (const change of updates) {
+      const target = resolve(root, change.path);
+      await mkdir(dirname(target), { recursive: true });
+      await writeTextAtomically(target, files[change.path]);
+    }
+    const next = upgradeState(manifest, files, { ...previous, lastAppliedMigration: `upgrade-${cliPackage.version}` });
+    for (const path of Object.keys(next.files)) {
+      const selected = plan.changes.find((change) => change.path === path);
+      if (!selected || selected.action === 'preserve' || selected.action === 'review') {
+        if (previous.files?.[path]) next.files[path] = previous.files[path];
+        else delete next.files[path];
+      }
+    }
+    next.lastAppliedMigration = `upgrade-${cliPackage.version}`;
+    await writeTextAtomically(upgradeStatePath, `${JSON.stringify(next, null, 2)}\n`);
   } catch (error) {
-    if (error.code === 'ENOENT') { console.error(`${projection} is missing; run lighthouse init after reviewing the manifest.`); process.exit(1); }
-    throw error;
+    for (const [path, content] of snapshots) {
+      const target = resolve(root, path);
+      if (content === null) await rm(target, { force: true });
+      else await writeFile(target, content);
+    }
+    await writeFile(upgradeStatePath, stateSnapshot);
+    throw new Error(`Upgrade rolled back: ${error.message}`);
+  }
+  const preserved = plan.changes.filter((change) => change.classification === 'customized').map((change) => change.path);
+  console.log(`Applied Lighthouse upgrade ${cliPackage.version}. Run lighthouse verify to check the result.`);
+  if (preserved.length) console.log(`Preserved customized paths for review: ${preserved.join(', ')}`);
+}
+
+async function upgrade(args) {
+  const manifest = await readManifest();
+  if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');
+  const problems = validate(manifest);
+  if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
+  const plan = await planUpgrade(manifest, scopesFromArgs(args));
+  const format = formatFromArgs(args);
+  const apply = args.includes('--apply');
+  const dryRun = args.includes('--dry-run') || !apply;
+  if (args.includes('--apply') && args.includes('--dry-run')) throw new Error('--apply and --dry-run cannot be used together.');
+  if (format === 'json' && apply) throw new Error('--format json is available for dry-run upgrade plans; use text when applying.');
+  if (format === 'json') console.log(JSON.stringify(plan, null, 2));
+  else printUpgradePlan(plan);
+  if (dryRun) {
+    if (format !== 'json') console.log('Dry run: nothing was changed. Re-run with --apply after reviewing the plan.');
+    if (plan.problems.length) process.exitCode = 1;
+    return;
+  }
+  await applyUpgrade(manifest, plan);
+}
+
+const authorityCommands = [
+  {
+    label: 'ProductShape',
+    packageName: '@prodshape/cli',
+    command: 'prodshape',
+    initArgs: ['init', '--full', '--sdd', 'none', '--gitignore'],
+    repair: 'prodshape init --full --sdd none --gitignore',
+  },
+  {
+    label: 'ArcShape',
+    packageName: '@arcshape/cli',
+    command: 'arcshape',
+    initArgs: ['init', '--no-agents'],
+    applyArgs: ['init', '--no-agents', '--yes'],
+    repair: 'arcshape init --no-agents --yes',
+  },
+];
+
+function providerExecutable(authority) {
+  const packageJson = packageRequire.resolve(`${authority.packageName}/package.json`);
+  const metadata = JSON.parse(readFileSync(packageJson, 'utf8'));
+  const binary = typeof metadata.bin === 'string' ? metadata.bin : metadata.bin?.[authority.command];
+  if (!binary) throw new Error(`${authority.packageName} does not declare a ${authority.command} executable`);
+  return resolve(dirname(packageJson), binary);
+}
+
+function providerHasConflict(output) {
+  return output.split('\n').some((line) => /^\s*conflict\b/i.test(line))
+    || /Conflicts\s*\(\s*[1-9]\d*\s*\)/i.test(output);
+}
+
+function runAuthorityCommand(authority, dryRun) {
+  const initArgs = dryRun ? authority.initArgs : (authority.applyArgs ?? authority.initArgs);
+  const args = [providerExecutable(authority), ...initArgs];
+  if (dryRun) args.push('--dry-run');
+  const result = spawnSync(process.execPath, args, {
+    cwd: root,
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+  console.log(`\n${authority.label} ${dryRun ? 'preflight' : 'apply'}:`);
+  if (result.stdout) process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  return {
+    ok: result.status === 0 && !providerHasConflict(output),
+    output,
+    status: result.status,
+  };
+}
+
+async function writeManifestAtomically(manifest) {
+  const temporary = `${manifestPath}.tmp-${process.pid}`;
+  await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  await rename(temporary, manifestPath);
+}
+
+async function ensureProjectionReady(manifest) {
+  const target = resolve(root, projection);
+  try {
+    const current = await readFile(target, 'utf8');
+    if (current !== render(manifest)) {
+      throw new Error(`${projection} has drifted; regenerate it from lighthouse.json before running lighthouse authorities --apply.`);
+    }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
+}
+
+async function writeProjection(manifest) {
+  const target = resolve(root, projection);
+  await writeFile(target, render(manifest), { flag: 'w' });
+}
+
+async function authorities(args) {
+  const manifest = await readManifest();
+  if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');
+  const problems = validate(manifest);
+  if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
+  const apply = args.includes('--apply');
+  const dryRun = args.includes('--dry-run') || !apply;
+  if (args.includes('--apply') && args.includes('--dry-run')) throw new Error('--apply and --dry-run cannot be used together.');
+  console.log('Lighthouse authority plan:');
+  console.log('  ProductShape: initialize the full ProductShape layout without an SDD integration');
+  console.log('  ArcShape: initialize arc42 documentation without installing agent capabilities');
+  console.log('  Provider-owned files remain under provider control; Lighthouse records only exact versions.');
+  const preflights = authorityCommands.map((authority) => ({ authority, result: runAuthorityCommand(authority, true) }));
+  const failed = preflights.filter(({ result }) => !result.ok);
+  if (failed.length) {
+    throw new Error(failed.map(({ authority }) => `${authority.label} preflight failed; repair with: ${authority.repair}`).join('\n'));
+  }
+  if (dryRun) {
+    console.log('Dry run: nothing was changed. Re-run with --apply to apply both provider plans.');
+    return;
+  }
+  await ensureProjectionReady(manifest);
+  for (const authority of authorityCommands) {
+    const result = runAuthorityCommand(authority, false);
+    if (!result.ok) throw new Error(`${authority.label} apply failed; repair with: ${authority.repair}`);
+  }
+  const updated = {
+    ...manifest,
+    integrations: { ...manifest.integrations, ...authorityVersions },
+  };
+  await writeManifestAtomically(updated);
+  await writeProjection(updated);
+  console.log(`Recorded ProductShape ${authorityVersions.productShape} and ArcShape ${authorityVersions.arcShape} in lighthouse.json.`);
+}
+
+function gitBranch() {
+  try {
+    return execFileSync('git', ['branch', '--show-current'], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  }
+  catch { return ''; }
+}
+
+function validateGitConventions(repository) {
+  const problems = [];
+  const branch = gitBranch();
+  if (branch && !['main', 'master'].includes(branch) && !new RegExp(repository.conventions.branchPattern, 'u').test(branch)) {
+    problems.push(`branch ${branch} does not match ${repository.conventions.branchPattern}`);
+  }
+  const message = process.env.LIGHTHOUSE_COMMIT_MESSAGE;
+  if (message && repository.conventions.commits === 'conventional'
+      && !/^(?:feat|fix|docs|refactor|test|chore|build|ci|perf|revert)(?:\([^)]+\))?!?: .+/u.test(message.trim())) {
+    problems.push('commit message does not follow Conventional Commits');
+  }
+  return problems;
+}
+
+async function verify(manifest, format = 'text') {
+  const manifestProblems = validate(manifest);
+  const validManifest = manifestProblems.length === 0;
+  const repository = normalizeRepository(manifest?.repository);
+  const managed = validManifest ? managedFiles(manifest) : {};
+  const report = await evaluateGuardrails({
+    catalog: readGuardrailCatalog(),
+    manifest,
+    manifestProblems,
+    repository,
+    managedFiles: managed,
+    resolve: (path) => resolve(root, path),
+    exists,
+    isDirectory,
+    readFile,
+    validateGitConventions,
+    branch: gitBranch(),
+  });
+  if (format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+    if (report.problems.length) process.exitCode = 1;
+    return;
+  }
+  if (report.problems.length) throw new Error(report.problems.join('\n'));
+  console.log('Lighthouse manifest, repository boundaries and managed projection are valid.');
+}
+
+function formatFromArgs(args) {
+  const index = args.indexOf('--format');
+  if (index !== -1) return args[index + 1];
+  return args.find((arg) => arg.startsWith('--format='))?.slice('--format='.length) ?? 'text';
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+const commandArgs = args.slice(1);
+let invalidArgument = false;
+for (let index = 0; index < commandArgs.length; index += 1) {
+  const arg = commandArgs[index];
+  if (arg === '--dry-run') continue;
+  if (arg === '--apply') { if (!['authorities', 'reconcile', 'upgrade'].includes(command)) invalidArgument = true; continue; }
+  if (arg === '--name') { if (!commandArgs[index + 1]) invalidArgument = true; else index += 1; continue; }
+  if (arg.startsWith('--name=') && arg.length > '--name='.length) continue;
+  if (arg === '--format') {
+    if (!['verify', 'upgrade'].includes(command) || !['text', 'json'].includes(commandArgs[index + 1])) invalidArgument = true;
+    else index += 1;
+    continue;
+  }
+  if (arg.startsWith('--format=') && ['text', 'json'].includes(arg.slice('--format='.length))) {
+    if (!['verify', 'upgrade'].includes(command)) invalidArgument = true;
+    continue;
+  }
+  if (arg === '--scope') {
+    if (command !== 'upgrade' || !commandArgs[index + 1]) invalidArgument = true;
+    else index += 1;
+    continue;
+  }
+  if (arg.startsWith('--scope=') && arg.length > '--scope='.length) {
+    if (command !== 'upgrade') invalidArgument = true;
+    continue;
+  }
+  invalidArgument = true;
+}
+if (!['init', 'authorities', 'reconcile', 'upgrade', 'verify'].includes(command) || invalidArgument) {
+  console.error(usage);
+  process.exit(2);
+}
+try {
+  if (command === 'init') await initialize(args.slice(1));
+  else if (command === 'authorities') await authorities(args.slice(1));
+  else if (command === 'reconcile') await reconcile(args.slice(1));
+  else if (command === 'upgrade') await upgrade(args.slice(1));
+  else {
+    const manifest = await readManifest();
+    if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');
+    await verify(manifest, formatFromArgs(commandArgs));
   }
-  console.log('Lighthouse manifest and managed projection are valid.');
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
 }