@juangcarmona/lighthouse 0.7.0 → 0.9.0

package/README.md

@@ -6,6 +6,8 @@ This package is the core Lighthouse harness. It provides the `lighthouse` comman
 
 Install the exact Lighthouse package artifact selected for the release and run `lighthouse init --name <product>` in a new repository. Add `--profile visual-theme` when the project wants the Lighthouse UI contract. Lighthouse creates the manifest, the `src/`, `docs/`, `infra/` and `scripts/` boundaries, the repository guardrails and the generated `LIGHTHOUSE.md`. Inspect the plan and projection, then run `lighthouse verify` before adding project-specific policy or exceptions.
 
+When the request is expressed in product terms, use the projected `.agents/skills/lighthouse-init/SKILL.md` to prepare a JSON plan that follows `assets/schemas/init-plan.schema.json`. A reference project is optional; the agent asks only the questions needed to resolve the application shape, stacks and profiles. `lighthouse init --plan-file <path>` previews the local operations by default, `--format json` emits the machine-readable plan and `--apply` is required to write it. The CLI does not inspect or copy a reference and performs no remote writes.
+
 For a Lighthouse-owned .NET backend, run `lighthouse create-dotnet <empty-target> --name <PascalCaseProduct>`. The creator seeds the modular backend, Aspire AppHost, CQRS/analyzer sources, tests, profile guidance and deterministic verifier into a new or empty directory. It refuses populated targets and never contacts a remote repository. Run `dotnet restore <Product>.slnx`, then `npm run verify` in the generated product.
 
 The manifest can declare `application.shape` and `application.stacks` when the project has enough information to select compatible profiles. `lighthouse profiles --format json` reports selected profiles, applicability, owned surfaces and verification layers without changing the repository.
@@ -16,7 +18,7 @@ Use `lighthouse upgrade` to preview a versioned foundation update. The command i
 
 The harness package owns the baseline command and verification contract. The SDLC package owns lifecycle skills, commands, metacommands, routes and gates, and `lighthouse init` records its selected version in `.lighthouse/sdlc.json`. The UI package owns visual tokens, native recipes, `DESIGN.md` and its agent skill. Selecting `visual-theme` projects the guide and skill into the adopter and enables its deterministic guardrail. Stack profiles own their source templates, guidance and checks; the .NET creator is the packaged entry point for the selected backend profile.
 
-ProductShape, ArcShape and OpenSpec keep their own files and commands. Add them through their supported integration routes when the project needs them, and keep their versions and managed paths visible in the project configuration.
+ProductShape, ArcShape and OpenSpec keep their own files and commands. Add them through their supported integration routes when the project needs them, and keep their versions and managed paths visible in the project configuration. In an existing repository, run `lighthouse authorities --adopt-existing` to validate the current ProductShape and ArcShape surfaces without running either initializer; review the dry-run plan and add `--apply` only to record both exact versions in Lighthouse-owned configuration.
 
 Use `lighthouse authorities` to prepare the two baseline authorities through their own CLIs. The command previews both plans by default; `--apply` runs ProductShape's full model initialization and ArcShape's architecture initialization without installing agent capabilities. Provider-owned files remain owned by the provider, and Lighthouse records the exact adopted versions in `lighthouse.json` only after both applications succeed.
 
@@ -37,12 +39,13 @@ Initialization reports missing ProductShape and ArcShape authority inputs as ado
 1. Inventory the current source layout, tools, managed files and CI before editing.
 2. Map existing files to the selected Lighthouse contracts and identify collisions.
 3. Adopt the manifest and verifier first; the initializer reports conflicts and preserves product-owned guidance and generated outputs.
-4. Add profiles one at a time and measure their checks before making a workflow status required.
-5. Record each exception in the project-owned documentation and remove it when the product is ready.
+4. If ProductShape or ArcShape already exists, run `lighthouse authorities --adopt-existing` and repair any provider validation result before applying it.
+5. Add profiles one at a time and measure their checks before making a workflow status required.
+6. Record each exception in the project-owned documentation and remove it when the product is ready.
 
 ## Current command scope
 
-The command supports `init`, `create-dotnet`, `authorities`, `reconcile`, `upgrade`, `capabilities` and `verify`. It checks the manifest, repository boundaries, Conventional Commits metadata, branch naming, the selected SDLC package projection and generated content. Lifecycle stages, tracker operations, agent runs and CodeGraph checks require their own configured integrations.
+The command supports `init`, `aliases`, `create-dotnet`, `authorities`, `reconcile`, `upgrade`, `capabilities` and `verify`. It checks the manifest, repository boundaries, Conventional Commits metadata, branch naming, the selected SDLC package projection and generated content. `lighthouse aliases --format json` exposes the installed `/lh:*` aliases and their canonical `/lighthouse:*` commands. `lighthouse authorities --adopt-existing` validates existing ProductShape and ArcShape authorities without writing provider-owned files. Lifecycle stages, tracker operations, agent runs and CodeGraph checks require their own configured integrations.
 
 Initialization installs `.husky/commit-msg`, `.husky/pre-push`, `scripts/lighthouse-guard.mjs` and `.github/workflows/lighthouse.yml` when those paths are free. Existing files remain project-owned and are reported as conflicts. Reconciliation can add missing managed paths after adoption, but it does not overwrite a path that has drifted or belongs to another tool.
 

package/assets/command-aliases.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "./schemas/command-aliases.schema.json",
+  "schemaVersion": 1,
+  "contractVersion": 1,
+  "package": { "name": "@juangcarmona/lighthouse" },
+  "canonicalNamespace": "/lighthouse",
+  "aliasNamespace": "/lh",
+  "aliases": [
+    { "alias": "/lh:init", "canonical": "/lighthouse:init", "asset": "skills/init/SKILL.md" }
+  ]
+}

package/assets/schemas/command-aliases.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-command-aliases.schema.json",
+  "title": "Lighthouse command aliases",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "contractVersion", "package", "canonicalNamespace", "aliasNamespace", "aliases"],
+  "properties": {
+    "$schema": {"type": "string"},
+    "schemaVersion": {"const": 1},
+    "contractVersion": {"const": 1},
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {"name": {"const": "@juangcarmona/lighthouse"}}
+    },
+    "canonicalNamespace": {"const": "/lighthouse"},
+    "aliasNamespace": {"const": "/lh"},
+    "aliases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["alias", "canonical", "asset"],
+        "properties": {
+          "alias": {"type": "string", "pattern": "^/lh:[a-z][a-z0-9-]*$"},
+          "canonical": {"type": "string", "pattern": "^/lighthouse:[a-z][a-z0-9-]*$"},
+          "asset": {"type": "string", "pattern": "^skills/[a-z0-9-]+/SKILL\\.md$"}
+        }
+      }
+    }
+  }
+}

package/assets/schemas/init-plan.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/init-plan.schema.json",
+  "title": "Lighthouse semantic initialization plan",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "product", "intent", "application", "profiles", "openQuestions"],
+  "properties": {
+    "$schema": {"type": "string"},
+    "schemaVersion": {"const": 1},
+    "product": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$"},
+    "intent": {"type": "string", "minLength": 1},
+    "application": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["shape", "stacks"],
+      "properties": {
+        "shape": {"enum": ["unknown", "frontend", "backend", "full-stack", "service", "library", "tooling", "cli", "worker", "mobile"]},
+        "stacks": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}
+      }
+    },
+    "profiles": {"type": "array", "items": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$"}, "uniqueItems": true},
+    "reference": {
+      "oneOf": [
+        {"type": "null"},
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["kind"],
+          "properties": {
+            "kind": {"enum": ["none", "local", "repository"]},
+            "location": {"type": "string", "minLength": 1},
+            "purpose": {"type": "string", "minLength": 1}
+          }
+        }
+      ]
+    },
+    "openQuestions": {"type": "array", "items": {"type": "string", "minLength": 1}, "uniqueItems": true}
+  }
+}

package/assets/skills/init/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: lighthouse-init
+description: Turn a natural-language project request into a reviewable Lighthouse initialization plan.
+---
+
+# Lighthouse semantic initialization
+
+Use this skill when an adopter describes a project in product terms and wants Lighthouse to prepare its foundation.
+
+## Inputs
+
+1. Read the installed profile catalog and the repository's current Lighthouse manifest when one exists.
+2. Treat a reference project as optional. If the adopter names one, record its location and purpose; do not assume it exists or copy it.
+3. Ask only the questions needed to resolve the application shape, stacks, profiles and material profile combinations. Keep unresolved questions in the plan instead of guessing.
+
+## Plan
+
+Write a JSON plan that validates against `assets/schemas/init-plan.schema.json` with `schemaVersion: 1`, `product`, `intent`, `application`, `profiles`, optional `reference` metadata and `openQuestions`.
+
+Select profiles from the installed catalog. Do not invent a profile, make a stack mandatory, or turn a reference into a requirement. An absent reference is represented by an omitted `reference` field or `{"kind":"none"}`.
+
+## Apply
+
+Review the generated plan with the adopter, then run `lighthouse init --plan-file <path>` for a dry run. Use `--format json` for agent consumption. Apply only after the adopter explicitly authorizes `lighthouse init --plan-file <path> --apply`.
+
+The CLI owns deterministic validation, profile compatibility, conflict detection and local writes. It does not inspect or copy the reference and it performs no remote writes. A plan with `openQuestions` is not ready to apply.
+
+Use `lighthouse aliases --format json` to discover the installed `/lh:*` aliases and their canonical `/lighthouse:*` commands. The generated `.lighthouse/commands.json` is the host-readable projection; aliases reference the package-owned command or skill asset and never create a second implementation.
+
+After applying, run `lighthouse verify` and report the created, preserved and conflicting paths. Keep product and architecture work in ProductShape and ArcShape's own routes.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -20,13 +20,15 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@arcshape/cli": "0.1.3",
+    "@arcshape/cli": "0.1.6",
     "@juangcarmona/lighthouse-ui": "0.2.0",
-    "@prodshape/cli": "0.22.0",
-    "@juangcarmona/lighthouse-sdlc": "0.6.0"
+    "@prodshape/cli": "0.23.0",
+    "@juangcarmona/lighthouse-sdlc": "0.8.0"
   },
   "files": [
     "src/lighthouse.mjs",
+    "src/aliases.mjs",
+    "src/init-plan.mjs",
     "src/guardrails.mjs",
     "assets",
     "README.md",

package/src/aliases.mjs

@@ -0,0 +1,56 @@
+import { access } from 'node:fs/promises';
+import { constants, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contractPath = resolve(packageRoot, 'assets/command-aliases.json');
+const packageName = '@juangcarmona/lighthouse';
+const aliasPattern = /^\/lh:[a-z][a-z0-9-]*$/u;
+const canonicalPattern = /^\/lighthouse:[a-z][a-z0-9-]*$/u;
+const assetPattern = /^skills\/[a-z0-9-]+\/SKILL\.md$/u;
+
+async function exists(path) {
+  try { await access(path, constants.F_OK); return true; } catch { return false; }
+}
+
+export function readCommandAliases(path = contractPath) {
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function validateCommandAliases(contract) {
+  const errors = [];
+  if (!contract || typeof contract !== 'object' || Array.isArray(contract)) return [{ code: 'aliases.invalid', message: 'command alias contract must be an object' }];
+  if (contract.schemaVersion !== 1) errors.push({ code: 'aliases.schema-version', message: 'command alias schemaVersion must be 1' });
+  if (contract.contractVersion !== 1) errors.push({ code: 'aliases.contract-version', message: 'command alias contractVersion must be 1' });
+  if (contract.package?.name !== packageName) errors.push({ code: 'aliases.package', message: `command alias contract package must be ${packageName}` });
+  if (contract.canonicalNamespace !== '/lighthouse') errors.push({ code: 'aliases.canonical-namespace', message: 'canonical namespace must be /lighthouse' });
+  if (contract.aliasNamespace !== '/lh') errors.push({ code: 'aliases.alias-namespace', message: 'alias namespace must be /lh' });
+  if (!Array.isArray(contract.aliases) || contract.aliases.length === 0) return [...errors, { code: 'aliases.list', message: 'command alias contract must declare at least one alias' }];
+  const aliases = new Set();
+  const canonicals = new Set();
+  for (const [index, item] of contract.aliases.entries()) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      errors.push({ code: 'aliases.entry', message: `alias ${index} must be an object` });
+      continue;
+    }
+    if (typeof item.alias !== 'string' || !aliasPattern.test(item.alias)) errors.push({ code: 'aliases.alias', message: `alias ${index} must use the /lh:<verb> form` });
+    if (typeof item.canonical !== 'string' || !canonicalPattern.test(item.canonical)) errors.push({ code: 'aliases.canonical', message: `alias ${index} must target a /lighthouse:<verb> command` });
+    if (typeof item.asset !== 'string' || !assetPattern.test(item.asset)) errors.push({ code: 'aliases.asset', message: `alias ${index} must reference a packaged skill asset` });
+    if (aliases.has(item.alias)) errors.push({ code: 'aliases.duplicate', message: `alias ${item.alias} is declared more than once` });
+    if (canonicals.has(item.canonical)) errors.push({ code: 'aliases.duplicate-target', message: `canonical command ${item.canonical} has more than one alias` });
+    aliases.add(item.alias);
+    canonicals.add(item.canonical);
+  }
+  return errors;
+}
+
+export async function verifyCommandAliases(contract = readCommandAliases()) {
+  const errors = validateCommandAliases(contract);
+  for (const item of contract.aliases ?? []) {
+    if (typeof item.asset === 'string' && !(await exists(resolve(packageRoot, 'assets', item.asset)))) errors.push({ code: 'aliases.missing-asset', message: `alias ${item.alias} references missing asset ${item.asset}` });
+  }
+  return errors;
+}
+
+export { contractPath };

package/src/create-dotnet.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { lstat, mkdir, mkdtemp, readFile, readdir, rename, rm, rmdir, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { createRequire } from 'node:module';
@@ -9,6 +10,23 @@ const templateRoot = resolve(packageRoot, 'assets/dotnet-template');
 const cliPackage = JSON.parse(await readFile(resolve(packageRoot, 'package.json'), 'utf8'));
 const require = createRequire(import.meta.url);
 const sdlcContract = JSON.parse(await readFile(require.resolve('@juangcarmona/lighthouse-sdlc/contract.json'), 'utf8'));
+const sdlcPackageRoot = dirname(require.resolve('@juangcarmona/lighthouse-sdlc/contract.json'));
+const sdlcWorkflowPaths = [
+  '.github/workflows/lighthouse-sdlc-router.yml',
+  '.github/workflows/lighthouse-sdlc-triage.md',
+  '.github/workflows/lighthouse-sdlc-triage.lock.yml',
+  '.github/workflows/lighthouse-sdlc-refine.md',
+  '.github/workflows/lighthouse-sdlc-refine.lock.yml',
+  '.github/workflows/lighthouse-sdlc-propose.md',
+  '.github/workflows/lighthouse-sdlc-propose.lock.yml',
+  '.github/workflows/lighthouse-sdlc-implement.md',
+  '.github/workflows/lighthouse-sdlc-implement.lock.yml',
+  '.github/workflows/lighthouse-sdlc-integrate.md',
+  '.github/workflows/lighthouse-sdlc-integrate.lock.yml',
+  '.github/workflows/lighthouse-sdlc-review.md',
+  '.github/workflows/lighthouse-sdlc-review.lock.yml',
+  '.github/workflows/shared/lighthouse-sdlc-stage.md',
+];
 const args = process.argv.slice(2);
 const target = args[0] ? resolve(args[0]) : null;
 const name = args.includes('--name') ? args[args.indexOf('--name') + 1] : null;
@@ -74,19 +92,23 @@ try {
   await writeFile(solutionFile, `<Solution>\n${projects.map((project) => `  ${project}`).join('\n')}\n</Solution>\n`);
 
   await copy(resolve(packageRoot, 'src/lighthouse.mjs'), resolve(stage, 'scripts/lighthouse.mjs'));
+  await copy(resolve(packageRoot, 'src/aliases.mjs'), resolve(stage, 'scripts/aliases.mjs'));
+  await copy(resolve(packageRoot, 'src/init-plan.mjs'), resolve(stage, 'scripts/init-plan.mjs'));
   await copy(resolve(packageRoot, 'src/guardrails.mjs'), resolve(stage, 'scripts/guardrails.mjs'));
   await copy(resolve(packageRoot, 'src/profiles.mjs'), resolve(stage, 'scripts/profiles.mjs'));
   await copy(resolve(packageRoot, 'src/verify-dotnet.mjs'), resolve(stage, 'scripts/verify-dotnet.mjs'));
   await copy(resolve(packageRoot, 'assets/guardrails'), resolve(stage, 'assets/guardrails'));
   await copy(resolve(packageRoot, 'assets/profiles'), resolve(stage, 'assets/profiles'));
   await copy(resolve(packageRoot, 'assets/schemas'), resolve(stage, 'schemas'));
+  await copy(resolve(packageRoot, 'assets/command-aliases.json'), resolve(stage, 'assets/command-aliases.json'));
+  await copy(resolve(packageRoot, 'assets/skills/init'), resolve(stage, 'assets/skills/init'));
 
   await writeFile(resolve(stage, 'lighthouse.json'), `${JSON.stringify({
     $schema: './schemas/lighthouse-manifest.schema.json', schemaVersion: 1, baseline: '0.1.0',
     product: name, application: { shape: 'backend', stacks: ['dotnet'] }, profiles: ['dotnet-backend'],
     integrations: { productShape: null, arcShape: null },
     packages: { sdlc: { name: '@juangcarmona/lighthouse-sdlc', version: sdlcContract.version } },
-    managed: ['LIGHTHOUSE.md', 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.lighthouse/sdlc.json', '.lighthouse/upgrade.json', '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'],
+    managed: ['LIGHTHOUSE.md', 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.lighthouse/sdlc.json', ...sdlcWorkflowPaths, '.agents/skills/lighthouse-init/SKILL.md', '.lighthouse/upgrade.json', '.lighthouse/commands.json', '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'],
     repository: {
       layout: ['src', 'docs', 'infra', 'scripts'], publicSite: { enabled: true },
       conventions: { commits: 'conventional', branchPattern: '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$' },
@@ -103,6 +125,14 @@ try {
 
   const initialized = (await import('node:child_process')).spawnSync(process.execPath, [resolve(stage, 'scripts/lighthouse.mjs'), 'init'], { cwd: stage, encoding: 'utf8' });
   if (initialized.status !== 0) throw new Error(initialized.stderr || 'Projection generation failed.');
+  await copy(resolve(sdlcPackageRoot, 'workflows'), resolve(stage, '.github/workflows'));
+  const upgradePath = resolve(stage, '.lighthouse/upgrade.json');
+  const upgrade = JSON.parse(await readFile(upgradePath, 'utf8'));
+  for (const path of sdlcWorkflowPaths) {
+    const content = await readFile(resolve(stage, path), 'utf8');
+    upgrade.files[path] = { hash: createHash('sha256').update(content).digest('hex'), scope: 'sdlc' };
+  }
+  await writeFile(upgradePath, `${JSON.stringify(upgrade, null, 2)}\n`);
   if (existing) await rmdir(target);
   await rename(stage, target);
   process.stdout.write(`Created ${name} in ${target}. Run dotnet restore ${name}.slnx, then npm run verify.\n`);

package/src/init-plan.mjs

@@ -0,0 +1,62 @@
+const productNamePattern = /^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/u;
+const shapes = new Set(['unknown', 'frontend', 'backend', 'full-stack', 'service', 'library', 'tooling', 'cli', 'worker', 'mobile']);
+const referenceKinds = new Set(['none', 'local', 'repository']);
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function uniqueStrings(value, name, { required = false } = {}) {
+  if (!Array.isArray(value) || (required && value.length === 0) || value.some((item) => typeof item !== 'string' || item.length === 0)) {
+    return [`${name} must contain non-empty strings`];
+  }
+  return new Set(value).size === value.length ? [] : [`${name} must be unique`];
+}
+
+function referenceProblems(reference) {
+  if (reference === undefined || reference === null) return [];
+  if (!isObject(reference)) return ['reference must be null or an object'];
+  const problems = [];
+  if (!referenceKinds.has(reference.kind)) problems.push('reference.kind must be none, local or repository');
+  if (reference.kind !== 'none' && (typeof reference.location !== 'string' || reference.location.length === 0)) {
+    problems.push('reference.location is required for local and repository references');
+  }
+  if (reference.kind === 'none' && 'location' in reference) problems.push('reference.location is not allowed when reference.kind is none');
+  if ('purpose' in reference && (typeof reference.purpose !== 'string' || reference.purpose.length === 0)) problems.push('reference.purpose must be a non-empty string');
+  return problems;
+}
+
+export function validateInitPlan(plan, supportedProfiles) {
+  if (!isObject(plan)) return ['plan must be an object'];
+  const problems = [];
+  const allowed = new Set(['$schema', 'schemaVersion', 'product', 'intent', 'application', 'profiles', 'reference', 'openQuestions']);
+  for (const key of Object.keys(plan)) if (!allowed.has(key)) problems.push(`unknown field ${key}`);
+  if (plan.schemaVersion !== 1) problems.push('schemaVersion must be 1');
+  if (typeof plan.product !== 'string' || !productNamePattern.test(plan.product)) problems.push('product must be a readable name of 1–64 characters');
+  if (typeof plan.intent !== 'string' || plan.intent.trim().length === 0) problems.push('intent must be a non-empty string');
+  if (!isObject(plan.application)) problems.push('application must be an object');
+  else {
+    if (!shapes.has(plan.application.shape)) problems.push(`application.shape must be one of ${[...shapes].join(', ')}`);
+    problems.push(...uniqueStrings(plan.application.stacks, 'application.stacks'));
+  }
+  problems.push(...uniqueStrings(plan.profiles, 'profiles'));
+  for (const profile of plan.profiles ?? []) {
+    if (!supportedProfiles.includes(profile)) problems.push(`unknown profile ${profile}; use ${supportedProfiles.join(', ')}`);
+  }
+  problems.push(...referenceProblems(plan.reference));
+  problems.push(...uniqueStrings(plan.openQuestions, 'openQuestions'));
+  return problems;
+}
+
+export function hasUnresolvedQuestions(plan) {
+  return Array.isArray(plan.openQuestions) && plan.openQuestions.length > 0;
+}
+
+export function manifestFromInitPlan(plan, createManifest) {
+  const manifest = createManifest(plan.product, plan.profiles);
+  manifest.application = {
+    shape: plan.application.shape,
+    stacks: [...plan.application.stacks],
+  };
+  return manifest;
+}

package/src/lighthouse.mjs

@@ -7,9 +7,13 @@ 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;
+let sdlcEvidence;
 try {
   [sdlcCapabilities, sdlcReconcile, sdlcGithub] = await Promise.all([
     import('@juangcarmona/lighthouse-sdlc/capabilities'),
@@ -17,6 +21,8 @@ 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. */ }
+try { sdlcEvidence = await import('@juangcarmona/lighthouse-sdlc/evidence'); } catch { /* Older standalone installations may not publish evidence. */ }
 
 const root = process.cwd();
 const packageRequire = createRequire(import.meta.url);
@@ -34,6 +40,22 @@ 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 uiPackage = { name: '@juangcarmona/lighthouse-ui', version: installedPackageVersion('@juangcarmona/lighthouse-ui', 'DESIGN.md') ?? '0.1.0' };
+const sdlcWorkflowPaths = Object.freeze([
+  '.github/workflows/lighthouse-sdlc-router.yml',
+  '.github/workflows/lighthouse-sdlc-triage.md',
+  '.github/workflows/lighthouse-sdlc-triage.lock.yml',
+  '.github/workflows/lighthouse-sdlc-refine.md',
+  '.github/workflows/lighthouse-sdlc-refine.lock.yml',
+  '.github/workflows/lighthouse-sdlc-propose.md',
+  '.github/workflows/lighthouse-sdlc-propose.lock.yml',
+  '.github/workflows/lighthouse-sdlc-implement.md',
+  '.github/workflows/lighthouse-sdlc-implement.lock.yml',
+  '.github/workflows/lighthouse-sdlc-integrate.md',
+  '.github/workflows/lighthouse-sdlc-integrate.lock.yml',
+  '.github/workflows/lighthouse-sdlc-review.md',
+  '.github/workflows/lighthouse-sdlc-review.lock.yml',
+  '.github/workflows/shared/lighthouse-sdlc-stage.md',
+]);
 const managedPaths = [
   projection,
   'scripts/lighthouse-guard.mjs',
@@ -41,7 +63,10 @@ const managedPaths = [
   '.husky/pre-push',
   '.github/workflows/lighthouse.yml',
   '.lighthouse/sdlc.json',
+  ...sdlcWorkflowPaths,
+  '.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'],
@@ -52,13 +77,15 @@ const profileManagedPaths = Object.freeze({
   '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 previousManagedPaths = [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml', '.lighthouse/sdlc.json', '.agents/skills/lighthouse-init/SKILL.md'];
 const legacyManagedPaths = [projection];
+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.23.0', arcShape: '0.1.6' };
 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],
@@ -73,8 +100,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', ...sdlcWorkflowPaths],
   };
 }
 
@@ -83,6 +110,18 @@ function packageAsset(packageName, entry) {
   return readFileSync(path, 'utf8');
 }
 
+function sdlcWorkflowFiles() {
+  const files = {};
+  for (const target of sdlcWorkflowPaths) {
+    try {
+      files[target] = packageAsset('@juangcarmona/lighthouse-sdlc', `workflows/${target.slice('.github/workflows/'.length)}`);
+    } catch {
+      return {};
+    }
+  }
+  return files;
+}
+
 function profileAssets(manifest) {
   const assets = {};
   if ((manifest?.profiles ?? []).includes('visual-theme')) {
@@ -270,7 +309,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) {
@@ -354,6 +393,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),
@@ -361,10 +453,13 @@ 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));
+  Object.assign(files, sdlcWorkflowFiles());
   const controlPlane = sdlcControlPlane(manifest);
   if (controlPlane) files['.lighthouse/sdlc.json'] = controlPlane;
+  files['.lighthouse/commands.json'] = commandAliasProjectionText(commandAliasesProjection());
   return files;
 }
 
@@ -586,7 +681,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) {
@@ -637,6 +738,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 = [];
@@ -694,6 +892,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);
@@ -854,6 +1054,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'));
@@ -887,6 +1106,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' });
@@ -907,7 +1252,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) {
@@ -945,6 +1290,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'], {
@@ -994,6 +1370,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;
@@ -1018,6 +1428,9 @@ async function verify(manifest, format = 'text') {
     });
     report.summary.unconfigured = (report.summary.unconfigured ?? 0) + (pending.length ? 1 : 0);
   }
+  const evidenceResult = await verifyEvidenceIndex();
+  report.results.push(evidenceResult);
+  report.summary[evidenceResult.status] = (report.summary[evidenceResult.status] ?? 0) + 1;
   if (format === 'json') {
     console.log(JSON.stringify(report, null, 2));
     if (report.problems.length) process.exitCode = 1;
@@ -1027,6 +1440,72 @@ async function verify(manifest, format = 'text') {
   console.log('Lighthouse manifest, repository boundaries and managed projection are valid.');
 }
 
+async function verifyEvidenceIndex() {
+  const evidencePath = '.lighthouse/evidence/index.json';
+  const result = {
+    id: 'foundation.evidence',
+    owner: '@juangcarmona/lighthouse-sdlc',
+    level: 'recommended',
+    kind: 'hard',
+    verification: 'deterministic',
+    status: 'unconfigured',
+    evidence: [],
+    problems: [],
+    nextAction: `lighthouse-sdlc evidence --build --input <records.json> --output ${evidencePath}`,
+  };
+  if (!(await exists(resolve(root, evidencePath)))) return result;
+  if (!sdlcEvidence) {
+    result.status = 'unavailable';
+    result.problems.push('The installed SDLC package does not expose the evidence contract.');
+    result.nextAction = 'Install a Lighthouse SDLC package that exports the evidence contract.';
+    return result;
+  }
+  let index;
+  try { index = JSON.parse(await readFile(resolve(root, evidencePath), 'utf8')); }
+  catch (error) {
+    result.status = 'failed';
+    result.problems.push(`Cannot read ${evidencePath}: ${error.message}`);
+    result.nextAction = `Repair ${evidencePath} and run lighthouse verify again.`;
+    return result;
+  }
+  const errors = sdlcEvidence.validateEvidenceIndex(index);
+  for (const error of errors) result.problems.push(`${error.field ?? 'index'}: ${error.message}`);
+  const records = [];
+  for (const reference of Array.isArray(index.records) ? index.records : []) {
+    if (!reference || typeof reference !== 'object' || typeof reference.path !== 'string') continue;
+    const path = resolve(root, '.lighthouse/evidence', reference.path);
+    if (!(await exists(path))) {
+      result.problems.push(`Missing evidence record ${reference.path}.`);
+      continue;
+    }
+    try {
+      const content = await readFile(path, 'utf8');
+      const record = JSON.parse(content);
+      for (const error of sdlcEvidence.validateEvidenceRecord(record)) result.problems.push(`${reference.path}: ${error.message}`);
+      const observedHash = createHash('sha256').update(JSON.stringify(record)).digest('hex');
+      if (observedHash !== reference.sha256) result.problems.push(`${reference.path}: SHA-256 does not match the index.`);
+      result.evidence.push({ id: reference.id, path: reference.path, status: record.status, sha256: observedHash });
+      records.push(record);
+    } catch (error) {
+      result.problems.push(`${reference.path}: ${error.message}`);
+    }
+  }
+  if (!errors.length && records.length === (index.records ?? []).length) {
+    const rebuilt = sdlcEvidence.buildEvidenceIndex(records, {
+      indexId: index.indexId,
+      runId: index.runId,
+      repository: index.repository,
+      revision: index.revision,
+      subjects: (index.coverage ?? []).map((item) => item.subject),
+      recordPaths: Object.fromEntries((index.records ?? []).map((item) => [item.id, item.path])),
+    });
+    if (rebuilt.errors.length || JSON.stringify(rebuilt.index?.coverage) !== JSON.stringify(index.coverage)) result.problems.push('Evidence coverage does not match the referenced records; rebuild the index.');
+  }
+  result.status = result.problems.length ? 'failed' : 'passed';
+  result.nextAction = result.problems.length ? `Repair ${evidencePath} or its records, then run lighthouse verify again.` : null;
+  return result;
+}
+
 async function profiles(manifest, format = 'text') {
   const composition = composeProfiles(readProfileCatalog(), manifest);
   if (format === 'json') {
@@ -1212,7 +1691,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') {
@@ -1225,12 +1705,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') {
@@ -1243,19 +1723,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));