@juangcarmona/lighthouse 0.6.0 → 0.8.0

package/src/lighthouse.mjs

@@ -7,9 +7,12 @@ import { basename, dirname, resolve } from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { evaluateGuardrails, readGuardrailCatalog } from './guardrails.mjs';
 import { composeProfiles, normalizeApplication, profileCompositionResult, readProfileCatalog } from './profiles.mjs';
+import { hasUnresolvedQuestions, manifestFromInitPlan, validateInitPlan } from './init-plan.mjs';
+import { readCommandAliases, verifyCommandAliases } from './aliases.mjs';
 let sdlcCapabilities;
 let sdlcReconcile;
 let sdlcGithub;
+let sdlcAliases;
 try {
   [sdlcCapabilities, sdlcReconcile, sdlcGithub] = await Promise.all([
     import('@juangcarmona/lighthouse-sdlc/capabilities'),
@@ -17,6 +20,7 @@ try {
     import('@juangcarmona/lighthouse-sdlc/github'),
   ]);
 } catch { /* Standalone generated starters can run without the optional SDLC package. */ }
+try { sdlcAliases = await import('@juangcarmona/lighthouse-sdlc/aliases'); } catch { /* Older standalone installations may not publish aliases. */ }
 
 const root = process.cwd();
 const packageRequire = createRequire(import.meta.url);
@@ -41,19 +45,28 @@ const managedPaths = [
   '.husky/pre-push',
   '.github/workflows/lighthouse.yml',
   '.lighthouse/sdlc.json',
+  '.agents/skills/lighthouse-init/SKILL.md',
   upgradeStateRelative,
+  '.lighthouse/commands.json',
 ];
 const profileManagedPaths = Object.freeze({
   'visual-theme': ['docs/design/DESIGN.md', '.agents/skills/lighthouse-ui/SKILL.md'],
   'dotnet-backend': ['docs/profiles/dotnet/README.md', 'docs/profiles/dotnet/adoption.md', 'docs/profiles/dotnet/architecture.md', 'docs/profiles/dotnet/guardrails.md', 'docs/profiles/dotnet/practices.md', 'docs/profiles/dotnet/testing-and-development.md', 'docs/profiles/dotnet/use-cases.md', '.agents/skills/lighthouse-dotnet/SKILL.md'],
+  'react-web-platform': ['docs/profiles/react-web-platform/README.md', 'docs/profiles/react-web-platform/adoption.md', 'docs/profiles/react-web-platform/structure.md', 'docs/profiles/react-web-platform/guardrails.md', 'docs/profiles/react-web-platform/testing.md', '.agents/skills/lighthouse-react-web/SKILL.md'],
+  'web-bff': ['docs/profiles/web-bff/README.md', 'docs/profiles/web-bff/adoption.md', 'docs/profiles/web-bff/security.md', 'docs/profiles/web-bff/testing.md', '.agents/skills/lighthouse-web-bff/SKILL.md'],
+  'pwa-capability': ['docs/profiles/pwa-capability/README.md', 'docs/profiles/pwa-capability/adoption.md', 'docs/profiles/pwa-capability/guardrails.md', 'docs/profiles/pwa-capability/offline.md', 'docs/profiles/pwa-capability/testing.md', '.agents/skills/lighthouse-pwa/SKILL.md'],
+  'mobile-expo': ['docs/profiles/mobile-expo/README.md', 'docs/profiles/mobile-expo/adoption.md', 'docs/profiles/mobile-expo/guardrails.md', 'docs/profiles/mobile-expo/testing.md', '.agents/skills/lighthouse-mobile-expo/SKILL.md'],
+  'mobile-maui': ['docs/profiles/mobile-maui/README.md', 'docs/profiles/mobile-maui/adoption.md', 'docs/profiles/mobile-maui/guardrails.md', 'docs/profiles/mobile-maui/testing.md', '.agents/skills/lighthouse-mobile-maui/SKILL.md'],
 });
 const previousManagedPaths = managedPaths.slice(0, -1);
 const legacyManagedPaths = [projection];
-const supportedProfiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
+const preSemanticManagedPaths = [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.lighthouse/sdlc.json', upgradeStateRelative];
+const preSemanticWithoutUpgradePaths = preSemanticManagedPaths.slice(0, -1);
+const supportedProfiles = readProfileCatalog().profiles.map(({ id }) => id);
 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 authorityVersions = { productShape: '0.22.0', arcShape: '0.1.4' };
 const upgradeSchema = './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-upgrade.schema.json';
-const usage = 'Usage: lighthouse <init|create-dotnet|profiles|authorities|reconcile|upgrade|capabilities|verify> [--name <product>] [--profile <profile>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
+const usage = 'Usage: lighthouse <init|aliases|create-dotnet|profiles|authorities|reconcile|upgrade|capabilities|verify> [--name <product>] [--plan-file <path>] [--profile <profile>] [--scope <harness|sdlc|all>] [--format <text|json>] [--adopt-existing] [--dry-run] [--apply]';
 
 const defaultRepository = () => ({
   layout: [...layout],
@@ -68,8 +81,8 @@ function managedPathsFor(manifest) {
 
 function upgradeScopesFor(manifest) {
   return {
-    harness: [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', ...((manifest?.profiles ?? []).flatMap((profile) => profileManagedPaths[profile] ?? []))],
-    sdlc: ['.lighthouse/sdlc.json'],
+    harness: [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.agents/skills/lighthouse-init/SKILL.md', ...((manifest?.profiles ?? []).flatMap((profile) => profileManagedPaths[profile] ?? []))],
+    sdlc: ['.lighthouse/sdlc.json', '.lighthouse/commands.json'],
   };
 }
 
@@ -96,6 +109,46 @@ function profileAssets(manifest) {
       catch (error) { throw new Error(`Cannot read the installed Lighthouse .NET profile: ${error.message}`); }
     }
   }
+  if ((manifest?.profiles ?? []).includes('react-web-platform')) {
+    const files = ['README.md', 'adoption.md', 'structure.md', 'guardrails.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-react-web/SKILL.md' : `docs/profiles/react-web-platform/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/react-web-platform/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse React web profile: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('web-bff')) {
+    const files = ['README.md', 'adoption.md', 'security.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-web-bff/SKILL.md' : `docs/profiles/web-bff/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/web-bff/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse web BFF profile: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('pwa-capability')) {
+    const files = ['README.md', 'adoption.md', 'guardrails.md', 'offline.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-pwa/SKILL.md' : `docs/profiles/pwa-capability/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/pwa-capability/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse PWA capability: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('mobile-expo')) {
+    const files = ['README.md', 'adoption.md', 'guardrails.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-mobile-expo/SKILL.md' : `docs/profiles/mobile-expo/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/mobile-expo/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse Expo mobile profile: ${error.message}`); }
+    }
+  }
+  if ((manifest?.profiles ?? []).includes('mobile-maui')) {
+    const files = ['README.md', 'adoption.md', 'guardrails.md', 'testing.md', 'SKILL.md'];
+    for (const file of files) {
+      const target = file === 'SKILL.md' ? '.agents/skills/lighthouse-mobile-maui/SKILL.md' : `docs/profiles/mobile-maui/${file}`;
+      try { assets[target] = readFileSync(new URL(`../assets/profiles/mobile-maui/${file}`, import.meta.url), 'utf8'); }
+      catch (error) { throw new Error(`Cannot read the installed Lighthouse .NET MAUI mobile profile: ${error.message}`); }
+    }
+  }
   return assets;
 }
 
@@ -225,7 +278,7 @@ function render(manifest) {
   const sdlcLine = selectedSdlc ? `- SDLC package: \`${selectedSdlc.name}@${selectedSdlc.version}\`\n` : '';
   const selectedUi = manifest.packages?.ui;
   const uiLine = selectedUi ? `- UI package: \`${selectedUi.name}@${selectedUi.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}${uiLine}- 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`;
+  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}${uiLine}- 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, command aliases and host adapters without storing agent runtime data. Use \`lighthouse aliases --format json\` or \`.lighthouse/commands.json\` to discover canonical and short agent commands.\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) {
@@ -309,6 +362,59 @@ jobs:
 `;
 }
 
+function readSdlcCommandAliases() {
+  try {
+    const path = packageRequire.resolve('@juangcarmona/lighthouse-sdlc/command-aliases.json');
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch { return null; }
+}
+
+function commandAliasesProjection() {
+  const contracts = [{ contract: readCommandAliases(), packageVersion: cliPackage.version }];
+  const sdlc = readSdlcCommandAliases();
+  if (sdlc) contracts.push({ contract: sdlc, packageVersion: sdlcPackage.version });
+  const aliases = contracts.flatMap(({ contract, packageVersion }) => (contract.aliases ?? []).map((alias) => ({
+    ...alias,
+    owner: contract.package.name,
+    packageVersion,
+  })));
+  return {
+    schemaVersion: 1,
+    contractVersion: 1,
+    canonicalNamespace: '/lighthouse',
+    aliasNamespace: '/lh',
+    packages: contracts.map(({ contract, packageVersion }) => ({
+      name: contract.package.name,
+      version: packageVersion,
+      contractVersion: contract.contractVersion,
+      aliases: contract.aliases,
+    })),
+    aliases,
+  };
+}
+
+function commandAliasProjectionText(projection) {
+  return `${JSON.stringify(projection, null, 2)}\n`;
+}
+
+async function commandAliases(format = 'text') {
+  const harness = readCommandAliases();
+  const errors = await verifyCommandAliases(harness);
+  const sdlc = readSdlcCommandAliases();
+  if (!sdlc) errors.push({ code: 'aliases.sdlc-unavailable', message: 'The installed SDLC package does not publish command aliases; upgrade it before using the SDLC alias namespace.' });
+  else if (sdlcAliases) errors.push(...(await sdlcAliases.verifyCommandAliases(sdlc)));
+  else errors.push({ code: 'aliases.sdlc-validator-unavailable', message: 'The installed SDLC package does not publish its alias validator.' });
+  const projection = commandAliasesProjection();
+  const report = { ...projection, status: errors.length ? 'invalid' : 'valid', valid: errors.length === 0, errors };
+  if (format === 'json') console.log(JSON.stringify(report, null, 2));
+  else {
+    console.log(`Lighthouse command aliases: ${report.status}`);
+    for (const alias of report.aliases) console.log(`  ${alias.alias} -> ${alias.canonical}`);
+    for (const error of report.errors) console.error(`  ${error.code}: ${error.message}`);
+  }
+  if (errors.length) process.exitCode = 1;
+}
+
 function managedFiles(manifest) {
   const files = {
     [projection]: render(manifest),
@@ -316,10 +422,12 @@ function managedFiles(manifest) {
     '.husky/commit-msg': commitHook(),
     '.husky/pre-push': prePushHook(),
     '.github/workflows/lighthouse.yml': workflow(),
+    '.agents/skills/lighthouse-init/SKILL.md': readFileSync(new URL('../assets/skills/init/SKILL.md', import.meta.url), 'utf8'),
   };
   Object.assign(files, profileAssets(manifest));
   const controlPlane = sdlcControlPlane(manifest);
   if (controlPlane) files['.lighthouse/sdlc.json'] = controlPlane;
+  files['.lighthouse/commands.json'] = commandAliasProjectionText(commandAliasesProjection());
   return files;
 }
 
@@ -541,7 +649,13 @@ function validate(manifest) {
   const previousCompleteManaged = Array.isArray(manifest.managed)
     && manifest.managed.length === previousManagedPaths.length
     && manifest.managed.every((entry, index) => entry === previousManagedPaths[index]);
-  if (!legacyManaged && !profilelessManaged && !previousCompleteManaged && !completeManaged) {
+  const preSemanticManaged = Array.isArray(manifest.managed)
+    && manifest.managed.length === preSemanticManagedPaths.length
+    && manifest.managed.every((entry, index) => entry === preSemanticManagedPaths[index]);
+  const preSemanticWithoutUpgrade = Array.isArray(manifest.managed)
+    && manifest.managed.length === preSemanticWithoutUpgradePaths.length
+    && manifest.managed.every((entry, index) => entry === preSemanticWithoutUpgradePaths[index]);
+  if (!legacyManaged && !profilelessManaged && !previousCompleteManaged && !completeManaged && !preSemanticManaged && !preSemanticWithoutUpgrade) {
     problems.push(`managed must be ${legacyManagedPaths.join(', ')}, the previous Lighthouse guardrail set or the selected profile set`);
   }
   if ('repository' in manifest) {
@@ -592,6 +706,103 @@ function productNameFromArgs(args) {
   return value;
 }
 
+function valueFromArgs(args, name) {
+  const index = args.indexOf(name);
+  if (index !== -1) return args[index + 1];
+  return args.find((arg) => arg.startsWith(`${name}=`))?.slice(name.length + 1);
+}
+
+async function readInitPlan(planFile) {
+  let plan;
+  try { plan = JSON.parse(await readFile(resolve(root, planFile), 'utf8')); }
+  catch (error) { throw new Error(`Cannot read initialization plan ${planFile}: ${error.message}`); }
+  const problems = validateInitPlan(plan, supportedProfiles);
+  if (problems.length) throw new Error(`Invalid initialization plan:\n${problems.map((problem) => `  ${problem}`).join('\n')}`);
+  return plan;
+}
+
+function printInitializationPlan(plan, result, format) {
+  const report = {
+    schemaVersion: 1,
+    intent: plan.intent,
+    product: plan.product,
+    application: plan.application,
+    profiles: plan.profiles,
+    reference: plan.reference ?? null,
+    openQuestions: plan.openQuestions,
+    status: result.plan.conflicts.length || plan.openQuestions.length ? 'blocked' : 'ready',
+    manifest: {
+      product: result.manifest.product,
+      application: result.manifest.application,
+      profiles: result.manifest.profiles,
+    },
+    operations: result.plan.operations.map(({ path, action }) => ({ path, action })),
+    conflicts: result.plan.conflicts,
+    apply: 'lighthouse init --plan-file <path> --apply',
+  };
+  if (format === 'json') {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  console.log('Lighthouse semantic initialization plan:');
+  console.log(`  product ${plan.product}`);
+  console.log(`  intent ${plan.intent}`);
+  console.log(`  application ${plan.application.shape} (${plan.application.stacks.join(', ') || 'no stack'})`);
+  console.log(`  profiles ${plan.profiles.join(', ') || 'none'}`);
+  console.log(`  reference ${plan.reference?.kind ?? 'none'}`);
+  if (plan.openQuestions.length) for (const question of plan.openQuestions) console.error(`  question ${question}`);
+  for (const operation of result.plan.operations) console.log(`  ${operation.action} ${operation.path}`);
+  for (const conflict of result.plan.conflicts) console.error(`  conflict ${conflict}`);
+  console.log('  default is dry-run; apply only after review with --apply');
+}
+
+async function initializeFromPlan(args, planFile) {
+  const plan = await readInitPlan(planFile);
+  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 semantic initialization dry runs; omit it when applying.');
+  const existing = await readManifest();
+  let manifest;
+  if (existing) {
+    const problems = validate(existing);
+    if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
+    if (existing.product !== plan.product) throw new Error(`Initialization plan targets ${plan.product}, but lighthouse.json belongs to ${existing.product}.`);
+    if (JSON.stringify(existing.profiles ?? []) !== JSON.stringify(plan.profiles)) throw new Error('Initialization plan profiles differ from lighthouse.json; resolve the selection before applying.');
+    if (JSON.stringify(normalizeApplication(existing.application)) !== JSON.stringify(plan.application)) throw new Error('Initialization plan application differs from lighthouse.json; resolve the selection before applying.');
+    manifest = existing;
+  } else {
+    manifest = manifestFromInitPlan(plan, defaultManifest);
+  }
+  const problems = validate(manifest);
+  if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
+  const composition = composeProfiles(readProfileCatalog(), manifest);
+  if (composition.status === 'failed') throw new Error(`Initialization plan has incompatible profiles:\n${composition.selected.flatMap((profile) => profile.problems).map((problem) => `  ${problem}`).join('\n')}`);
+  const initialization = { manifest, plan: await planInitialization(manifest, !existing) };
+  printInitializationPlan(plan, initialization, format);
+  if (initialization.plan.conflicts.length) {
+    if (dryRun) process.exitCode = 1;
+    else throw new Error('Initialization stopped; resolve the reported conflicts and run the plan again.');
+    return;
+  }
+  if (hasUnresolvedQuestions(plan)) {
+    if (dryRun) process.exitCode = 1;
+    else throw new Error('Initialization stopped; answer the open questions before using --apply.');
+    return;
+  }
+  if (dryRun) return;
+  if (!existing) await writeFile(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
+  for (const operation of initialization.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);
+  console.log(`Initialized ${manifest.product} from the semantic plan. Run lighthouse verify.`);
+}
+
 async function planInitialization(manifest, manifestMissing) {
   const operations = [];
   const conflicts = [];
@@ -649,6 +860,8 @@ function printReconciliationPlan(plan) {
 }
 
 async function initialize(args) {
+  const planFile = valueFromArgs(args, '--plan-file');
+  if (planFile) return initializeFromPlan(args, planFile);
   let manifest = await readManifest();
   const manifestMissing = !manifest;
   const selectedProfiles = profileArguments(args);
@@ -809,6 +1022,25 @@ const authorityCommands = [
   },
 ];
 
+const authorityAdoptionCommands = [
+  {
+    id: 'productShape',
+    label: 'ProductShape',
+    packageName: '@prodshape/cli',
+    command: 'prodshape',
+    path: 'docs/product/model',
+    validateArgs: ['validate', '--format', 'json'],
+  },
+  {
+    id: 'arcShape',
+    label: 'ArcShape',
+    packageName: '@arcshape/cli',
+    command: 'arcshape',
+    path: 'docs/architecture',
+    validateArgs: ['validate', '--docs', 'docs/architecture', '--links', '--citations', '--format', 'json'],
+  },
+];
+
 function providerExecutable(authority) {
   const packageJson = packageRequire.resolve(`${authority.packageName}/package.json`);
   const metadata = JSON.parse(readFileSync(packageJson, 'utf8'));
@@ -842,6 +1074,132 @@ function runAuthorityCommand(authority, dryRun) {
   };
 }
 
+function parseProviderReport(output) {
+  const text = output.trim();
+  try { return JSON.parse(text); } catch { /* The provider may prefix JSON with a diagnostic line. */ }
+  const start = text.indexOf('{');
+  const end = text.lastIndexOf('}');
+  if (start === -1 || end <= start) return null;
+  try { return JSON.parse(text.slice(start, end + 1)); } catch { return null; }
+}
+
+function authorityStatus(present, validation, recordedVersion, providerVersion) {
+  if (!present) return 'absent';
+  if (validation.status === 'unavailable') return 'unavailable';
+  if (!validation.valid) return 'invalid';
+  if (recordedVersion && recordedVersion !== providerVersion) return 'drifted';
+  return recordedVersion ? 'adopted' : 'ready';
+}
+
+async function runAuthorityValidation(authority, manifest) {
+  const providerVersion = installedPackageVersion(authority.packageName, 'package.json');
+  const present = await isDirectory(resolve(root, authority.path));
+  const command = `${authority.command} ${authority.validateArgs.join(' ')}`;
+  if (!present) {
+    return {
+      id: authority.id,
+      label: authority.label,
+      provider: authority.packageName,
+      version: providerVersion,
+      path: authority.path,
+      command,
+      recordedVersion: manifest.integrations[authority.id],
+      status: 'absent',
+      valid: false,
+      diagnostics: [`${authority.path} is missing`],
+      nextAction: `Create the ${authority.label} authority through its supported initializer, then rerun lighthouse authorities --adopt-existing.`,
+    };
+  }
+  if (!providerVersion) {
+    return {
+      id: authority.id,
+      label: authority.label,
+      provider: authority.packageName,
+      version: null,
+      path: authority.path,
+      command,
+      recordedVersion: manifest.integrations[authority.id],
+      status: 'unavailable',
+      valid: false,
+      diagnostics: [`${authority.packageName} is not installed`],
+      nextAction: `Install ${authority.packageName}, then rerun lighthouse authorities --adopt-existing.`,
+    };
+  }
+  let result;
+  try {
+    result = spawnSync(process.execPath, [providerExecutable(authority), ...authority.validateArgs], {
+      cwd: root,
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+  } catch (error) {
+    return {
+      id: authority.id,
+      label: authority.label,
+      provider: authority.packageName,
+      version: providerVersion,
+      path: authority.path,
+      command,
+      recordedVersion: manifest.integrations[authority.id],
+      status: 'unavailable',
+      valid: false,
+      diagnostics: [error.message],
+      nextAction: `Run ${command} directly, repair the provider and rerun lighthouse authorities --adopt-existing.`,
+    };
+  }
+  const output = `${result.stdout ?? ''}${result.stderr ?? ''}`;
+  const report = parseProviderReport(output);
+  const valid = result.status === 0 && report?.valid !== false;
+  const status = authorityStatus(present, { status: result.status === null ? 'unavailable' : 'completed', valid }, manifest.integrations[authority.id], providerVersion);
+  return {
+    id: authority.id,
+    label: authority.label,
+    provider: authority.packageName,
+    version: providerVersion,
+    path: authority.path,
+    command,
+    recordedVersion: manifest.integrations[authority.id],
+    status,
+    valid,
+    diagnostics: report?.diagnostics ?? (valid ? [] : [output.trim().split('\n').filter(Boolean).slice(-3).join(' ') || `${authority.label} validation failed`]),
+    nextAction: status === 'invalid' ? `Run ${command} directly, repair the reported authority and rerun lighthouse authorities --adopt-existing.` : null,
+  };
+}
+
+async function authorityAdoptionPlan(manifest) {
+  const authorities = await Promise.all(authorityAdoptionCommands.map((authority) => runAuthorityValidation(authority, manifest)));
+  const blocking = authorities.filter((authority) => ['absent', 'invalid', 'unavailable'].includes(authority.status));
+  const changed = authorities.some((authority) => ['ready', 'drifted'].includes(authority.status));
+  const status = blocking.length ? 'blocked' : changed ? 'ready' : 'adopted';
+  return {
+    schemaVersion: 1,
+    command: 'lighthouse authorities --adopt-existing',
+    status,
+    remoteWrites: 'none',
+    providerWrites: 'none',
+    authorities,
+    operations: changed ? [
+      { action: 'record', path: 'lighthouse.json', values: Object.fromEntries(authorities.map((authority) => [authority.id, authority.version])) },
+      { action: 'regenerate', path: 'LIGHTHOUSE.md' },
+    ] : [],
+    apply: 'lighthouse authorities --adopt-existing --apply',
+  };
+}
+
+function printAuthorityAdoptionPlan(plan) {
+  console.log(`Lighthouse existing-authority adoption plan: ${plan.status}`);
+  console.log('  ProductShape and ArcShape provider files remain untouched.');
+  console.log('  Remote writes: none.');
+  for (const authority of plan.authorities) {
+    const version = authority.version ?? 'unavailable';
+    console.log(`  ${authority.label}: ${authority.status} (${version}) ${authority.path}`);
+    for (const diagnostic of authority.diagnostics) console.error(`    ${diagnostic}`);
+    if (authority.nextAction) console.error(`    next: ${authority.nextAction}`);
+  }
+  for (const operation of plan.operations) console.log(`  ${operation.action} ${operation.path}`);
+  console.log('  default is dry-run; apply only after review with --apply');
+}
+
 async function writeManifestAtomically(manifest) {
   const temporary = `${manifestPath}.tmp-${process.pid}`;
   await writeFile(temporary, `${JSON.stringify(manifest, null, 2)}\n`, { flag: 'wx' });
@@ -862,7 +1220,7 @@ async function ensureProjectionReady(manifest) {
 
 async function writeProjection(manifest) {
   const target = resolve(root, projection);
-  await writeFile(target, render(manifest), { flag: 'w' });
+  await writeTextAtomically(target, render(manifest));
 }
 
 async function authorities(args) {
@@ -900,6 +1258,37 @@ async function authorities(args) {
   console.log(`Recorded ProductShape ${authorityVersions.productShape} and ArcShape ${authorityVersions.arcShape} in lighthouse.json.`);
 }
 
+async function adoptExistingAuthorities(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;
+  const format = formatFromArgs(args);
+  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 existing-authority adoption dry runs; omit it when applying.');
+  const plan = await authorityAdoptionPlan(manifest);
+  if (format === 'json') console.log(JSON.stringify(plan, null, 2));
+  else printAuthorityAdoptionPlan(plan);
+  if (dryRun) {
+    if (plan.status === 'blocked') process.exitCode = 1;
+    return;
+  }
+  if (plan.status === 'blocked') throw new Error('Existing-authority adoption stopped; resolve the reported provider conditions and rerun the plan.');
+  await ensureProjectionReady(manifest);
+  const updated = {
+    ...manifest,
+    integrations: Object.fromEntries(plan.authorities.map((authority) => [authority.id, authority.version])),
+  };
+  if (JSON.stringify(updated) !== JSON.stringify(manifest)) await writeManifestAtomically(updated);
+  if (!await exists(resolve(root, projection))) await writeProjection(updated);
+  else if (await readFile(resolve(root, projection), 'utf8') !== render(updated)) await writeProjection(updated);
+  const verified = await authorityAdoptionPlan(updated);
+  if (verified.status !== 'adopted') throw new Error('Existing-authority adoption was written but did not verify; rerun lighthouse authorities --adopt-existing and inspect the provider report.');
+  console.log('Recorded and verified the existing ProductShape and ArcShape authorities. Provider-owned files were not changed.');
+}
+
 function gitBranch() {
   try {
     return execFileSync('git', ['branch', '--show-current'], {
@@ -949,6 +1338,40 @@ async function verify(manifest, format = 'text') {
   const profileResult = profileCompositionResult(profileComposition);
   report.results.push(profileResult);
   report.summary[profileResult.status] = (report.summary[profileResult.status] ?? 0) + 1;
+  if (validManifest) {
+    const recordedAuthorities = [manifest.integrations.productShape, manifest.integrations.arcShape];
+    const anyRecorded = recordedAuthorities.some((version) => version !== null);
+    const authorityPlan = anyRecorded ? await authorityAdoptionPlan(manifest) : null;
+    const authorityStatuses = authorityPlan?.authorities.map((authority) => authority.status) ?? [];
+    const authorityStatus = !anyRecorded ? 'unconfigured'
+      : authorityStatuses.includes('unavailable') ? 'unavailable'
+        : authorityStatuses.some((status) => ['absent', 'invalid'].includes(status)) ? 'failed'
+          : authorityStatuses.includes('drifted') ? 'drift'
+            : 'passed';
+    const authorityProblems = !anyRecorded
+      ? ['ProductShape and ArcShape are not recorded; run lighthouse authorities --adopt-existing after reviewing its dry-run plan.']
+      : authorityPlan.authorities.filter((authority) => authority.status !== 'adopted').flatMap((authority) => [
+        `${authority.label} is ${authority.status}${authority.diagnostics.length ? `: ${authority.diagnostics.join('; ')}` : ''}`,
+        ...(authority.nextAction ? [authority.nextAction] : []),
+      ]);
+    const authorityResult = {
+      id: 'foundation.authorities',
+      owner: 'lighthouse',
+      level: anyRecorded ? 'required' : 'recommended',
+      kind: 'hard',
+      verification: 'deterministic',
+      status: authorityStatus,
+      evidence: authorityPlan?.authorities.map((authority) => ({ id: authority.id, path: authority.path, version: authority.version, recordedVersion: authority.recordedVersion, command: authority.command })) ?? [],
+      problems: authorityProblems,
+      nextAction: authorityProblems.length ? 'lighthouse authorities --adopt-existing' : null,
+    };
+    report.results.push(authorityResult);
+    report.summary[authorityStatus] = (report.summary[authorityStatus] ?? 0) + 1;
+    if (authorityResult.level === 'required' && !['passed', 'not-applicable'].includes(authorityStatus)) {
+      report.blocking.push(authorityResult.id);
+      report.problems.push(...authorityProblems);
+    }
+  }
   const adoption = Object.values(capabilityAdoption(await readUpgradeState()));
   for (const item of adoption) {
     if (item.status !== 'adopted' || !item.recordPath || await exists(resolve(root, item.recordPath))) continue;
@@ -1167,7 +1590,8 @@ for (let index = 0; index < commandArgs.length; index += 1) {
   const arg = commandArgs[index];
   if (command === 'capabilities' && index === 0 && ['select', 'decline', 'plan', 'apply'].includes(arg)) continue;
   if (arg === '--dry-run') continue;
-  if (arg === '--apply') { if (!['authorities', 'reconcile', 'upgrade'].includes(command)) invalidArgument = true; continue; }
+  if (arg === '--apply') { if (!['init', 'authorities', 'reconcile', 'upgrade'].includes(command)) invalidArgument = true; continue; }
+  if (arg === '--adopt-existing') { if (command !== 'authorities') 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 === '--profile') {
@@ -1180,12 +1604,12 @@ for (let index = 0; index < commandArgs.length; index += 1) {
     continue;
   }
   if (arg === '--format') {
-    if (!['profiles', 'verify', 'upgrade', 'capabilities'].includes(command) || !['text', 'json'].includes(commandArgs[index + 1])) invalidArgument = true;
+    if (!['init', 'aliases', 'profiles', 'authorities', 'verify', 'upgrade', 'capabilities'].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 (!['profiles', 'verify', 'upgrade', 'capabilities'].includes(command)) invalidArgument = true;
+    if (!['init', 'aliases', 'profiles', 'authorities', 'verify', 'upgrade', 'capabilities'].includes(command)) invalidArgument = true;
     continue;
   }
   if (arg === '--scope') {
@@ -1198,19 +1622,24 @@ for (let index = 0; index < commandArgs.length; index += 1) {
     continue;
   }
   if (['--id', '--provider', '--repo', '--input', '--plan-file', '--authorize'].includes(arg)) {
-    if (!commandArgs[index + 1]) invalidArgument = true;
+    if (!commandArgs[index + 1] || (arg === '--plan-file' && !['init', 'capabilities'].includes(command))) invalidArgument = true;
     else index += 1;
     continue;
   }
-  if (['--id=', '--provider=', '--repo=', '--input=', '--plan-file=', '--authorize='].some((prefix) => arg.startsWith(prefix) && arg.length > prefix.length)) continue;
+  if (['--id=', '--provider=', '--repo=', '--input=', '--plan-file=', '--authorize='].some((prefix) => arg.startsWith(prefix) && arg.length > prefix.length)) {
+    if (arg.startsWith('--plan-file=') && !['init', 'capabilities'].includes(command)) invalidArgument = true;
+    continue;
+  }
   invalidArgument = true;
 }
-if (!['init', 'profiles', 'authorities', 'reconcile', 'upgrade', 'capabilities', 'verify'].includes(command) || invalidArgument) {
+if (!['init', 'aliases', 'profiles', 'authorities', 'reconcile', 'upgrade', 'capabilities', 'verify'].includes(command) || invalidArgument) {
   console.error(usage);
   process.exit(2);
 }
 try {
   if (command === 'init') await initialize(args.slice(1));
+  else if (command === 'aliases') await commandAliases(formatFromArgs(commandArgs));
+  else if (command === 'authorities' && commandArgs.includes('--adopt-existing')) await adoptExistingAuthorities(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));