@juangcarmona/lighthouse 0.3.1 → 0.5.0

package/README.md

@@ -4,13 +4,13 @@ This package is the core Lighthouse harness. It provides the `lighthouse` comman
 
 ## Initialize a repository
 
-Install the exact Lighthouse package artifact selected for the release and run `lighthouse init --name <product>` in a new repository. 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.
+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.
 
 Use `lighthouse reconcile` to preview missing Lighthouse-managed paths in an existing adoption. It does not write by default; add `--apply` only after reviewing the plan. Existing files whose content differs from the generated projection are conflicts and are never overwritten by reconciliation.
 
 Use `lighthouse upgrade` to preview a versioned foundation update. The command is dry-run by default, accepts `--scope harness`, `--scope sdlc` or `--scope all`, preserves customized projections and stops when ownership evidence is missing. Add `--apply` only after reviewing the plan, then run `lighthouse verify`.
 
-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 and `DESIGN.md`. Stack profiles own their source templates, guidance and checks.
+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.
 
 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.
 
@@ -38,12 +38,14 @@ Initialization reports missing ProductShape and ArcShape authority inputs as ado
 
 ## Current command scope
 
-The command supports `init`, `authorities`, `reconcile`, `upgrade` 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`, `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.
 
 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.
 
 The upgrade route records the ownership hashes in `.lighthouse/upgrade.json`. A missing or stale state file is an adoption gap; reconcile it first instead of allowing a full re-adoption. Upgrade plans report the source and target package and baseline, selected scopes, classifications, preserved paths, verification and recovery action.
 
+The installed SDLC package also publishes a versioned capability catalog. `selected-by-default` capabilities appear as pending until the adopter selects or declines them; `opt-in` capabilities remain available without blocking `upgrade` or `verify`. `lighthouse capabilities select` and `lighthouse capabilities decline` record an explicit local choice, and `lighthouse verify --format json` exposes the adoption status and next command. For the GitHub labels slice, generate a local plan with `lighthouse capabilities plan --id labels --provider github --repo <owner/repo> --plan-file .lighthouse/reconciliation/labels.plan.json`, then apply it only with the plan hash returned by that command.
+
 The package does not contain the repository gallery, provider-owned integrations or reference source. Those remain with the source repository or the profile that owns them.
 
 ## Guardrail catalog

package/assets/guardrails/catalog.json

@@ -41,6 +41,16 @@
       "verification": "deterministic",
       "check": "branch",
       "failureHint": "Use the branch pattern declared in lighthouse.json."
+    },
+    {
+      "id": "visual.design-contract",
+      "owner": "@juangcarmona/lighthouse-ui",
+      "appliesTo": { "baseline": false, "profiles": ["visual-theme"] },
+      "level": "required",
+      "kind": "hard",
+      "verification": "deterministic",
+      "check": "ui-design",
+      "failureHint": "Run lighthouse reconcile after reviewing the visual-theme profile plan, then run lighthouse verify again."
     }
   ]
 }

package/assets/schemas/lighthouse-manifest.schema.json

@@ -12,12 +12,13 @@
     "product": {"type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$"},
     "profiles": {"type": "array", "items": {"enum": ["node-tooling", "dotnet-backend", "visual-theme"]}, "uniqueItems": true},
     "integrations": {"type": "object", "additionalProperties": false, "required": ["productShape", "arcShape"], "properties": {"productShape": {"$ref": "#/$defs/pin"}, "arcShape": {"$ref": "#/$defs/pin"}}},
-    "packages": {"type": "object", "additionalProperties": false, "required": ["sdlc"], "properties": {"sdlc": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-sdlc"}, "version": {"$ref": "#/$defs/pin"}}}}},
+    "packages": {"type": "object", "additionalProperties": false, "required": ["sdlc"], "properties": {"sdlc": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-sdlc"}, "version": {"$ref": "#/$defs/pin"}}}, "ui": {"type": "object", "additionalProperties": false, "required": ["name", "version"], "properties": {"name": {"const": "@juangcarmona/lighthouse-ui"}, "version": {"$ref": "#/$defs/pin"}}}}},
     "managed": {"anyOf": [
       {"const": ["LIGHTHOUSE.md"]},
       {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml"]},
       {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json"]},
-      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json"]}
+      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json"]},
+      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.json", "docs/design/DESIGN.md", ".agents/skills/lighthouse-ui/SKILL.md"]}
     ]},
     "repository": {
       "type": "object",

package/assets/schemas/lighthouse-upgrade.schema.json

@@ -16,6 +16,24 @@
     },
     "baseline": {"type": "string", "minLength": 1},
     "capabilities": {"$ref": "#/$defs/versions"},
+    "adoption": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "provider", "version", "catalogVersion", "nextAction"],
+        "properties": {
+          "id": {"type": "string"},
+          "status": {"enum": ["available", "pending-adoption", "adopted", "declined", "drifted", "blocked", "failed", "unavailable"]},
+          "selection": {"enum": ["selected-by-default", "opt-in"]},
+          "provider": {"type": "string"},
+          "version": {"type": "string"},
+          "catalogVersion": {"type": "string"},
+          "nextAction": {"type": ["string", "null"]},
+          "recordPath": {"type": "string"}
+        }
+      }
+    },
     "projections": {"$ref": "#/$defs/versions"},
     "lastAppliedMigration": {"type": "string", "minLength": 1},
     "files": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -21,8 +21,9 @@
   },
   "dependencies": {
     "@arcshape/cli": "0.1.3",
+    "@juangcarmona/lighthouse-ui": "0.2.0",
     "@prodshape/cli": "0.22.0",
-    "@juangcarmona/lighthouse-sdlc": "0.4.0"
+    "@juangcarmona/lighthouse-sdlc": "0.5.0"
   },
   "files": [
     "src/lighthouse.mjs",

package/src/guardrails.mjs

@@ -7,6 +7,7 @@ const allowedLevels = new Set(['required', 'recommended', 'optional']);
 const allowedKinds = new Set(['hard', 'soft']);
 const allowedVerification = new Set(['deterministic', 'semantic', 'human']);
 const allowedStatuses = new Set(['passed', 'failed', 'drift', 'unavailable', 'unconfigured', 'pending-review', 'not-applicable']);
+const requiredVisualTokens = ['--lh-canvas', '--lh-surface', '--lh-text', '--lh-action', '--lh-border', '--lh-focus'];
 
 function descriptorProblems(descriptor) {
   const problems = [];
@@ -102,16 +103,30 @@ async function runDeterministicCheck(descriptor, context) {
     const problems = context.validateGitConventions(context.repository);
     return result(descriptor, problems.length ? 'failed' : 'passed', [{ value: context.branch ?? '' }, { pattern: context.repository.conventions.branchPattern }], problems);
   }
+  if (descriptor.check === 'ui-design') {
+    const expected = ['docs/design/DESIGN.md', '.agents/skills/lighthouse-ui/SKILL.md'];
+    const missing = [];
+    const drifted = [];
+    for (const path of expected) {
+      const target = context.resolve(path);
+      if (!context.managedFiles[path] || !(await context.exists(target))) missing.push(path);
+      else if (await context.readFile(target, 'utf8') !== context.managedFiles[path]) drifted.push(`${path} has drifted; regenerate it from the visual-theme profile.`);
+    }
+    const tokenProblems = requiredVisualTokens.filter((token) => !context.uiTokens?.includes(token)).map((token) => `${token} is missing from the installed Lighthouse UI token source.`);
+    const problems = [...missing.map((path) => `${path} is missing; run lighthouse reconcile after reviewing the visual-theme profile plan.`), ...drifted, ...tokenProblems];
+    const status = drifted.length ? 'drift' : problems.length ? 'failed' : 'passed';
+    return result(descriptor, status, [...expected.map((path) => ({ path })), ...requiredVisualTokens.map((token) => ({ token }))], problems);
+  }
   return result(descriptor, 'unavailable', [], [`No deterministic checker is registered for ${descriptor.id}.`]);
 }
 
-export async function evaluateGuardrails({ catalog, manifest, manifestProblems, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch }) {
+export async function evaluateGuardrails({ catalog, manifest, manifestProblems, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch, uiTokens }) {
   if (manifestProblems.length) {
     const descriptor = catalog.guardrails.find((item) => item.check === 'manifest') ?? catalog.guardrails[0];
     const failed = result(descriptor, 'failed', [{ path: 'lighthouse.json' }], manifestProblems.map((problem) => `Invalid lighthouse.json: ${problem}`));
     return report([failed]);
   }
-  const context = { manifest, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch };
+  const context = { manifest, repository, managedFiles, resolve, exists, isDirectory, readFile, validateGitConventions, branch, uiTokens };
   const results = [];
   for (const descriptor of catalog.guardrails) {
     if (!appliesTo(descriptor, manifest)) {

package/src/lighthouse.mjs

@@ -6,6 +6,16 @@ import { createRequire } from 'node:module';
 import { basename, dirname, resolve } from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { evaluateGuardrails, readGuardrailCatalog } from './guardrails.mjs';
+let sdlcCapabilities;
+let sdlcReconcile;
+let sdlcGithub;
+try {
+  [sdlcCapabilities, sdlcReconcile, sdlcGithub] = await Promise.all([
+    import('@juangcarmona/lighthouse-sdlc/capabilities'),
+    import('@juangcarmona/lighthouse-sdlc/reconcile'),
+    import('@juangcarmona/lighthouse-sdlc/github'),
+  ]);
+} catch { /* Standalone generated starters can run without the optional SDLC package. */ }
 
 const root = process.cwd();
 const packageRequire = createRequire(import.meta.url);
@@ -22,6 +32,7 @@ const upgradeStateRelative = '.lighthouse/upgrade.json';
 const upgradeStatePath = resolve(root, upgradeStateRelative);
 const layout = ['src', 'docs', 'infra', 'scripts'];
 const sdlcPackage = { name: '@juangcarmona/lighthouse-sdlc', version: installedPackageVersion('@juangcarmona/lighthouse-sdlc', 'contract.json') ?? '0.1.0' };
+const uiPackage = { name: '@juangcarmona/lighthouse-ui', version: installedPackageVersion('@juangcarmona/lighthouse-ui', 'DESIGN.md') ?? '0.1.0' };
 const managedPaths = [
   projection,
   'scripts/lighthouse-guard.mjs',
@@ -31,16 +42,16 @@ const managedPaths = [
   '.lighthouse/sdlc.json',
   upgradeStateRelative,
 ];
+const profileManagedPaths = Object.freeze({
+  'visual-theme': ['docs/design/DESIGN.md', '.agents/skills/lighthouse-ui/SKILL.md'],
+});
 const previousManagedPaths = managedPaths.slice(0, -1);
 const legacyManagedPaths = [projection];
+const supportedProfiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
 const branchPattern = '^(feat|fix|docs|refactor|test|chore|build|ci|perf|revert)/[1-9]\\d*-[a-z0-9]+(?:-[a-z0-9]+)*$';
 const authorityVersions = { productShape: '0.22.0', arcShape: '0.1.3' };
-const upgradeScopes = {
-  harness: [projection, 'scripts/lighthouse-guard.mjs', '.husky/commit-msg', '.husky/pre-push', '.github/workflows/lighthouse.yml'],
-  sdlc: ['.lighthouse/sdlc.json'],
-};
 const upgradeSchema = './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-upgrade.schema.json';
-const usage = 'Usage: lighthouse <init|authorities|reconcile|upgrade|verify> [--name <product>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
+const usage = 'Usage: lighthouse <init|authorities|reconcile|upgrade|capabilities|verify> [--name <product>] [--profile <profile>] [--scope <harness|sdlc|all>] [--format <text|json>] [--dry-run] [--apply]';
 
 const defaultRepository = () => ({
   layout: [...layout],
@@ -48,16 +59,59 @@ const defaultRepository = () => ({
   conventions: { commits: 'conventional', branchPattern },
 });
 
-function defaultManifest(product) {
+function managedPathsFor(manifest) {
+  const profiles = manifest?.profiles ?? [];
+  return [...managedPaths, ...profiles.flatMap((profile) => profileManagedPaths[profile] ?? [])];
+}
+
+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'],
+  };
+}
+
+function packageAsset(packageName, entry) {
+  const path = packageRequire.resolve(`${packageName}/${entry}`);
+  return readFileSync(path, 'utf8');
+}
+
+function profileAssets(manifest) {
+  if (!(manifest?.profiles ?? []).includes('visual-theme')) return {};
+  try {
+    return {
+      'docs/design/DESIGN.md': packageAsset('@juangcarmona/lighthouse-ui', 'DESIGN.md'),
+      '.agents/skills/lighthouse-ui/SKILL.md': packageAsset('@juangcarmona/lighthouse-ui', 'skills/ui-design/SKILL.md'),
+    };
+  } catch (error) {
+    throw new Error(`Cannot read the installed Lighthouse UI profile: ${error.message}`);
+  }
+}
+
+function profileArguments(args) {
+  const selected = [];
+  for (let index = 0; index < args.length; index += 1) {
+    if (args[index] !== '--profile' && !args[index].startsWith('--profile=')) continue;
+    const value = args[index] === '--profile' ? args[++index] : args[index].slice('--profile='.length);
+    if (!value || !supportedProfiles.includes(value)) throw new Error(`Unknown profile ${value ?? ''}; use ${supportedProfiles.join(', ')}.`);
+    if (!selected.includes(value)) selected.push(value);
+  }
+  return selected;
+}
+
+function defaultManifest(product, profiles = []) {
+  const draft = { profiles: [...profiles] };
+  const packages = { sdlc: { ...sdlcPackage } };
+  if (profiles.includes('visual-theme')) packages.ui = { ...uiPackage };
   return {
     $schema: './node_modules/@juangcarmona/lighthouse/assets/schemas/lighthouse-manifest.schema.json',
     schemaVersion: 1,
     baseline: '0.1.0',
     product,
-    profiles: [],
+    profiles: [...profiles],
     integrations: { productShape: null, arcShape: null },
-    packages: { sdlc: { ...sdlcPackage } },
-    managed: [...managedPaths],
+    packages,
+    managed: managedPathsFor(draft),
     repository: defaultRepository(),
   };
 }
@@ -96,6 +150,45 @@ function sdlcContract() {
   }
 }
 
+function sdlcCapabilityCatalog() {
+  if (!sdlcCapabilities) return null;
+  try {
+    const path = packageRequire.resolve('@juangcarmona/lighthouse-sdlc/capabilities.json');
+    const catalog = JSON.parse(readFileSync(path, 'utf8'));
+    const errors = sdlcCapabilities.validateCapabilityCatalog(catalog);
+    if (errors.length) throw new Error(errors.map((error) => error.message).join('; '));
+    return catalog;
+  } catch (error) {
+    throw new Error(`Cannot read the installed SDLC capability catalog: ${error.message}`);
+  }
+}
+
+function capabilityAdoption(previous = null) {
+  const catalog = sdlcCapabilityCatalog();
+  if (!catalog) return {};
+  return Object.fromEntries(catalog.capabilities.map((capability) => {
+    const current = previous?.adoption?.[capability.id];
+    const status = current?.catalogVersion === catalog.package.version
+      ? current.status
+      : sdlcCapabilities.initialAdoptionStatus?.(capability) ?? 'pending-adoption';
+    const nextAction = status === 'available'
+      ? `lighthouse capabilities select --id ${capability.id} --provider ${capability.provider}`
+      : ['adopted', 'declined'].includes(status)
+        ? null
+        : `lighthouse capabilities plan --id ${capability.id} --provider ${capability.provider} --repo <owner/repo> --plan-file .lighthouse/reconciliation/${capability.id}.plan.json`;
+    return [capability.id, {
+      id: capability.id,
+      status,
+      selection: capability.selection,
+      provider: capability.provider,
+      version: capability.version,
+      catalogVersion: catalog.package.version,
+      nextAction,
+      ...(current?.recordPath ? { recordPath: current.recordPath } : {}),
+    }];
+  }));
+}
+
 function sdlcControlPlane(manifest) {
   const selected = normalizeSdlcPackage(manifest);
   if (!selected) return null;
@@ -118,7 +211,9 @@ function render(manifest) {
   const publicSite = repository.publicSite.enabled ? 'enabled' : 'disabled';
   const selectedSdlc = normalizeSdlcPackage(manifest);
   const sdlcLine = selectedSdlc ? `- SDLC package: \`${selectedSdlc.name}@${selectedSdlc.version}\`\n` : '';
-  return `<!-- Generated by Lighthouse. Edit lighthouse.json and regenerate this file. -->\n\n# ${manifest.product} repository baseline\n\n- Baseline: \`${manifest.baseline}\`\n- Product: \`${manifest.product}\`\n- Profiles: ${manifest.profiles.length ? manifest.profiles.map((x) => `\`${x}\``).join(', ') : 'none'}\n${sdlcLine}- ProductShape: ${manifest.integrations.productShape ?? 'not adopted'}\n- ArcShape: ${manifest.integrations.arcShape ?? 'not adopted'}\n- Public site: \`${publicSite}\`\n- Repository roots: ${repository.layout.map((x) => `\`${x}/\``).join(', ')}\n- Commit convention: \`${repository.conventions.commits}\`\n\n## Delivery contract\n\nProductShape remains the source of product intent and Product Changes. ArcShape remains the source of architecture documentation and decisions. Lighthouse installs the repository baseline and verifies the selected integrations without replacing either authority.\n\nThe repository keeps source code in \`src/\`, documentation in \`docs/\`, infrastructure in \`infra/\` and repository automation in \`scripts/\`. A project may record a narrow, owned exception, but an initializer never overwrites an existing project file.\n\nThe selected SDLC package owns lifecycle skills, commands, meta-commands, routes and gates. The \`.lighthouse/\` control plane records the selected package and host adapters without storing agent runtime data.\n\nWhen the public site is enabled, its publication is allowed only after ProductShape and ArcShape validate successfully. A missing or invalid authority stops the build before deployment and reports the command that can repair the missing input.\n\nThis file is managed. Put repository-specific policy in its own documentation and keep this projection generated from \`lighthouse.json\`.\n`;
+  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`;
 }
 
 function guardrailScript(manifest) {
@@ -210,6 +305,7 @@ function managedFiles(manifest) {
     '.husky/pre-push': prePushHook(),
     '.github/workflows/lighthouse.yml': workflow(),
   };
+  Object.assign(files, profileAssets(manifest));
   const controlPlane = sdlcControlPlane(manifest);
   if (controlPlane) files['.lighthouse/sdlc.json'] = controlPlane;
   return files;
@@ -220,9 +316,10 @@ function contentHash(content) {
 }
 
 function upgradeState(manifest, files = managedFiles(manifest), previous = null) {
+  const scopes = upgradeScopesFor(manifest);
   const entries = Object.fromEntries(Object.entries(files).map(([path, content]) => [path, {
     hash: contentHash(content),
-    scope: Object.entries(upgradeScopes).find(([, paths]) => paths.includes(path))?.[0] ?? 'harness',
+    scope: Object.entries(scopes).find(([, paths]) => paths.includes(path))?.[0] ?? 'harness',
   }]));
   return {
     $schema: upgradeSchema,
@@ -230,6 +327,7 @@ function upgradeState(manifest, files = managedFiles(manifest), previous = null)
     package: { name: cliPackage.name, version: cliPackage.version },
     baseline: manifest.baseline,
     capabilities: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
+    adoption: capabilityAdoption(previous),
     projections: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
     lastAppliedMigration: previous?.lastAppliedMigration ?? 'foundation-init-1',
     files: entries,
@@ -259,7 +357,8 @@ function stateProblems(state) {
   return problems;
 }
 
-function scopesFromArgs(args) {
+function scopesFromArgs(args, manifest) {
+  const upgradeScopes = upgradeScopesFor(manifest);
   const selected = new Set();
   for (let index = 0; index < args.length; index += 1) {
     if (args[index] !== '--scope' && !args[index].startsWith('--scope=')) continue;
@@ -275,7 +374,8 @@ function scopesFromArgs(args) {
   return selected.size ? selected : new Set(Object.keys(upgradeScopes));
 }
 
-function selectedPaths(scopes) {
+function selectedPaths(scopes, manifest) {
+  const upgradeScopes = upgradeScopesFor(manifest);
   return new Set([...scopes].flatMap((scope) => upgradeScopes[scope]));
 }
 
@@ -293,7 +393,8 @@ async function planUpgrade(manifest, scopes) {
   const state = await readUpgradeState();
   const problems = stateProblems(state);
   const files = managedFiles(manifest);
-  const paths = selectedPaths(scopes);
+  const paths = selectedPaths(scopes, manifest);
+  const upgradeScopes = upgradeScopesFor(manifest);
   const changes = [];
   for (const path of Object.keys(files).filter((candidate) => paths.has(candidate))) {
     const target = resolve(root, path);
@@ -311,6 +412,7 @@ async function planUpgrade(manifest, scopes) {
       package: state?.package ?? null,
       baseline: state?.baseline ?? null,
       capabilities: state?.capabilities ?? null,
+      adoption: state?.adoption ?? null,
       projections: state?.projections ?? null,
       lastAppliedMigration: state?.lastAppliedMigration ?? null,
     },
@@ -318,6 +420,7 @@ async function planUpgrade(manifest, scopes) {
       package: { name: cliPackage.name, version: cliPackage.version },
       baseline: manifest.baseline,
       capabilities: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
+      adoption: capabilityAdoption(state),
       projections: { harness: '1', sdlc: files['.lighthouse/sdlc.json'] ? '1' : null },
     },
     scopes: [...scopes],
@@ -325,6 +428,11 @@ async function planUpgrade(manifest, scopes) {
     changes,
     verification: ['lighthouse verify'],
     recovery: 'Restore the pre-update commit or rerun lighthouse upgrade after resolving the reported ownership conflict.',
+    adoption: {
+      status: Object.values(capabilityAdoption(state)).some((item) => !['adopted', 'declined', 'available'].includes(item.status)) ? 'pending' : 'complete',
+      capabilities: capabilityAdoption(state),
+      externalWrites: 'none',
+    },
     problems,
   };
 }
@@ -336,6 +444,12 @@ function printUpgradePlan(plan) {
   console.log(`  scopes ${plan.scopes.join(', ')}`);
   for (const prerequisite of plan.prerequisites) console.log(`  prerequisite ${prerequisite.status}: ${prerequisite.message}`);
   for (const change of plan.changes) console.log(`  ${change.classification} ${change.action} ${change.path}${change.reason ? ` (${change.reason})` : ''}`);
+  if (plan.adoption) {
+    console.log(`  capability adoption ${plan.adoption.status} (external writes: ${plan.adoption.externalWrites})`);
+    for (const capability of Object.values(plan.adoption.capabilities)) {
+      console.log(`  capability ${capability.id ?? capability.provider} ${capability.status}${capability.nextAction ? `; next: ${capability.nextAction}` : ''}`);
+    }
+  }
   if (plan.problems.length) for (const problem of plan.problems) console.error(`  adoption gap ${problem}`);
   console.log(`  verify ${plan.verification[0]}`);
   console.log(`  recovery ${plan.recovery}`);
@@ -355,7 +469,7 @@ function validate(manifest) {
   if (typeof manifest.product !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,63}$/.test(manifest.product)) {
     problems.push('product must be a readable name of 1–64 characters');
   }
-  const profiles = ['node-tooling', 'dotnet-backend', 'visual-theme'];
+  const profiles = supportedProfiles;
   if (!Array.isArray(manifest.profiles) || manifest.profiles.some((p) => !profiles.includes(p))
       || new Set(manifest.profiles).size !== manifest.profiles.length) {
     problems.push('profiles must be unique supported profile names');
@@ -372,26 +486,42 @@ function validate(manifest) {
   if ('packages' in manifest) {
     const packages = manifest.packages;
     const selected = packages?.sdlc;
+    const selectedUi = packages?.ui;
+    const hasVisualProfile = manifest.profiles?.includes('visual-theme');
     if (!packages || typeof packages !== 'object' || Array.isArray(packages)
-        || Object.keys(packages).length !== 1
+        || !Object.keys(packages).every((key) => ['sdlc', 'ui'].includes(key))
+        || Object.keys(packages).length < 1 || Object.keys(packages).length > 2
         || !selected || typeof selected !== 'object' || Array.isArray(selected)
         || Object.keys(selected).length !== 2
         || selected.name !== sdlcPackage.name
         || typeof selected.version !== 'string' || !pin.test(selected.version)) {
       problems.push(`packages.sdlc must declare ${sdlcPackage.name} and an exact version or commit hash`);
     }
+    if (hasVisualProfile && (!selectedUi || typeof selectedUi !== 'object' || Array.isArray(selectedUi)
+        || Object.keys(selectedUi).length !== 2
+        || selectedUi.name !== uiPackage.name
+        || typeof selectedUi.version !== 'string' || !pin.test(selectedUi.version))) {
+      problems.push(`packages.ui must declare ${uiPackage.name} and an exact version or commit hash when visual-theme is selected`);
+    }
+    if (!hasVisualProfile && selectedUi) problems.push('packages.ui requires the visual-theme profile');
+  } else if (manifest.profiles?.includes('visual-theme')) {
+    problems.push(`packages must declare ${sdlcPackage.name} and ${uiPackage.name} when visual-theme is selected`);
   }
   const legacyManaged = Array.isArray(manifest.managed)
     && manifest.managed.length === legacyManagedPaths.length
     && manifest.managed.every((entry, index) => entry === legacyManagedPaths[index]);
+  const expectedManagedPaths = managedPathsFor(manifest);
   const completeManaged = Array.isArray(manifest.managed)
+    && manifest.managed.length === expectedManagedPaths.length
+    && manifest.managed.every((entry, index) => entry === expectedManagedPaths[index]);
+  const profilelessManaged = Array.isArray(manifest.managed)
     && manifest.managed.length === managedPaths.length
     && manifest.managed.every((entry, index) => entry === managedPaths[index]);
   const previousCompleteManaged = Array.isArray(manifest.managed)
     && manifest.managed.length === previousManagedPaths.length
     && manifest.managed.every((entry, index) => entry === previousManagedPaths[index]);
-  if (!legacyManaged && !previousCompleteManaged && !completeManaged) {
-    problems.push(`managed must be ${legacyManagedPaths.join(', ')}, the previous Lighthouse guardrail set or the current complete set`);
+  if (!legacyManaged && !profilelessManaged && !previousCompleteManaged && !completeManaged) {
+    problems.push(`managed must be ${legacyManagedPaths.join(', ')}, the previous Lighthouse guardrail set or the selected profile set`);
   }
   if ('repository' in manifest) {
     const repository = manifest.repository;
@@ -500,7 +630,12 @@ function printReconciliationPlan(plan) {
 async function initialize(args) {
   let manifest = await readManifest();
   const manifestMissing = !manifest;
-  if (!manifest) manifest = defaultManifest(productNameFromArgs(args));
+  const selectedProfiles = profileArguments(args);
+  if (!manifest) manifest = defaultManifest(productNameFromArgs(args), selectedProfiles);
+  else if (selectedProfiles.some((profile) => !(manifest.profiles ?? []).includes(profile))) {
+    const missing = selectedProfiles.filter((profile) => !(manifest.profiles ?? []).includes(profile));
+    throw new Error(`The existing lighthouse.json does not select ${missing.join(', ')}; edit its profiles and rerun lighthouse init.`);
+  }
   const problems = validate(manifest);
   if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
   const plan = await planInitialization(manifest, manifestMissing);
@@ -619,7 +754,7 @@ async function upgrade(args) {
   if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');
   const problems = validate(manifest);
   if (problems.length) throw new Error(problems.map((problem) => `Invalid lighthouse.json: ${problem}`).join('\n'));
-  const plan = await planUpgrade(manifest, scopesFromArgs(args));
+  const plan = await planUpgrade(manifest, scopesFromArgs(args, manifest));
   const format = formatFromArgs(args);
   const apply = args.includes('--apply');
   const dryRun = args.includes('--dry-run') || !apply;
@@ -786,7 +921,32 @@ async function verify(manifest, format = 'text') {
     readFile,
     validateGitConventions,
     branch: gitBranch(),
+    uiTokens: manifest?.profiles?.includes('visual-theme') ? packageAsset('@juangcarmona/lighthouse-ui', 'tokens.css') : null,
   });
+  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;
+    item.status = 'failed';
+    item.nextAction = `lighthouse capabilities plan --id ${item.id} --provider ${item.provider} --repo <owner/repo> --plan-file .lighthouse/reconciliation/${item.id}.plan.json`;
+  }
+  if (adoption.length) {
+    const pending = adoption.filter((item) => !['adopted', 'declined', 'available'].includes(item.status));
+    const available = adoption.some((item) => item.status === 'available');
+    const declined = adoption.some((item) => item.status === 'declined');
+    report.results.push({
+      id: 'foundation.capability-adoption',
+      owner: '@juangcarmona/lighthouse-sdlc',
+      level: 'recommended',
+      kind: 'hard',
+      verification: 'deterministic',
+      status: pending.length ? 'unconfigured' : available || declined ? 'not-applicable' : 'passed',
+      adoptionStatus: pending.length ? pending[0].status : available ? 'available' : declined ? 'declined' : 'adopted',
+      evidence: adoption.map((item) => ({ capability: item.id, catalogVersion: item.catalogVersion })),
+      problems: pending.map((item) => `${item.id} is ${item.status}; run ${item.nextAction}`),
+      nextAction: pending[0]?.nextAction ?? null,
+    });
+    report.summary.unconfigured = (report.summary.unconfigured ?? 0) + (pending.length ? 1 : 0);
+  }
   if (format === 'json') {
     console.log(JSON.stringify(report, null, 2));
     if (report.problems.length) process.exitCode = 1;
@@ -796,6 +956,158 @@ async function verify(manifest, format = 'text') {
   console.log('Lighthouse manifest, repository boundaries and managed projection are valid.');
 }
 
+function planHash(plan) {
+  const { authorization, ...payload } = plan;
+  return contentHash(JSON.stringify(payload));
+}
+
+function capabilityPlanText(plan) {
+  const lines = [
+    `Capability adoption: ${plan.status}`,
+    `Capability: ${plan.capability.id}@${plan.capability.version} (${plan.capability.provider})`,
+    `Repository: ${plan.repository.repo}`,
+    `Remote writes: none`,
+    `Authorization: ${plan.authorization.planHash}`,
+  ];
+  for (const change of plan.reconciliation.changes) lines.push(`  ${change.status} ${change.name}`);
+  if (plan.nextAction) lines.push(`Next: ${plan.nextAction}`);
+  return `${lines.join('\n')}\n`;
+}
+
+async function writeCapabilityPlan(path, plan) {
+  const target = resolve(root, path);
+  await mkdir(dirname(target), { recursive: true });
+  await writeTextAtomically(target, `${JSON.stringify(plan, null, 2)}\n`);
+}
+
+async function writeCapabilityEvidence(plan, status, extra = {}) {
+  const path = resolve(root, '.lighthouse/reconciliation', `${plan.capability.id}.json`);
+  await mkdir(dirname(path), { recursive: true });
+  const evidence = {
+    schemaVersion: 1,
+    capability: plan.capability,
+    catalogVersion: plan.catalogVersion,
+    provider: plan.repository,
+    desiredHash: plan.reconciliation.desiredHash,
+    observedHash: extra.observedHash ?? plan.reconciliation.observedHash,
+    targetHash: extra.targetHash ?? plan.reconciliation.targetHash,
+    operations: extra.operations ?? plan.reconciliation.operations,
+    operationPolicy: plan.reconciliation.operationPolicy ?? plan.operationPolicy ?? null,
+    blockedOperations: extra.blockedOperations ?? plan.reconciliation.blockedOperations ?? [],
+    conflicts: extra.conflicts ?? plan.reconciliation.changes.filter((change) => change.status === 'conflict'),
+    status,
+    verified: status === 'adopted',
+  };
+  await writeTextAtomically(path, `${JSON.stringify(evidence, null, 2)}\n`);
+  return path;
+}
+
+async function capabilities(args) {
+  const action = args[0];
+  const id = args.includes('--id') ? args[args.indexOf('--id') + 1] : args.find((arg) => arg.startsWith('--id='))?.slice(5) ?? 'labels';
+  const provider = args.includes('--provider') ? args[args.indexOf('--provider') + 1] : args.find((arg) => arg.startsWith('--provider='))?.slice(11) ?? 'github';
+  const repo = args.includes('--repo') ? args[args.indexOf('--repo') + 1] : args.find((arg) => arg.startsWith('--repo='))?.slice(7);
+  const inputPath = args.includes('--input') ? args[args.indexOf('--input') + 1] : args.find((arg) => arg.startsWith('--input='))?.slice(8);
+  const format = formatFromArgs(args);
+  const planFile = args.includes('--plan-file') ? args[args.indexOf('--plan-file') + 1] : args.find((arg) => arg.startsWith('--plan-file='))?.slice(12);
+  if (['select', 'decline'].includes(action)) {
+    const catalog = sdlcCapabilityCatalog();
+    if (!catalog) throw new Error('The installed SDLC package does not publish the capability adoption contract; upgrade it before selecting capabilities.');
+    const capability = catalog.capabilities.find((item) => item.id === id && item.provider === provider);
+    if (!capability) throw new Error(`Capability ${id} for provider ${provider} is not declared by the installed SDLC package.`);
+    const state = await readUpgradeState();
+    if (!state) throw new Error('Cannot select a capability before Lighthouse ownership evidence exists; run lighthouse init or reconcile --apply.');
+    state.adoption = state.adoption ?? {};
+    const status = action === 'decline' ? 'declined' : 'pending-adoption';
+    state.adoption[id] = {
+      id,
+      status,
+      selection: capability.selection,
+      provider: capability.provider,
+      version: capability.version,
+      catalogVersion: catalog.package.version,
+      nextAction: status === 'declined' ? null : `lighthouse capabilities plan --id ${id} --provider ${provider} --repo <owner/repo> --plan-file .lighthouse/reconciliation/${id}.plan.json`,
+    };
+    await writeTextAtomically(upgradeStatePath, `${JSON.stringify(state, null, 2)}\n`);
+    const result = { schemaVersion: 1, capability: id, provider, status, applied: true };
+    if (format === 'json') console.log(JSON.stringify(result, null, 2)); else console.log(`Capability ${id}: ${status}.`);
+    return;
+  }
+  if (action === 'plan') {
+    if (!repo || !planFile) throw new Error('Usage: lighthouse capabilities plan --id <capability> --provider github --repo <owner/repo> --plan-file <path> [--input <capabilities.json>] [--format <text|json>]');
+    const catalog = sdlcCapabilityCatalog();
+    if (!catalog || !sdlcCapabilities || !sdlcReconcile || !sdlcGithub) throw new Error('The installed SDLC package does not publish the capability adoption contract; upgrade it before planning adoption.');
+    const capability = catalog.capabilities.find((item) => item.id === id && item.provider === provider);
+    if (!capability) throw new Error(`Capability ${id} for provider ${provider} is not declared by the installed SDLC package.`);
+    const declaration = inputPath ? JSON.parse(await readFile(resolve(root, inputPath), 'utf8')) : sdlcCapabilities.declarationFromCatalog(catalog, id);
+    const labels = await sdlcGithub.readGithubLabels(repo);
+    const reconciliation = sdlcReconcile.buildLabelReconciliationPlan(declaration, labels, await (async () => {
+      const path = resolve(root, '.lighthouse/reconciliation', `${id}.json`);
+      try { return JSON.parse(await readFile(path, 'utf8')); } catch { return null; }
+    })());
+    const plan = {
+      schemaVersion: 1,
+      status: reconciliation.status,
+      capability: { id: capability.id, provider: capability.provider, selection: capability.selection, version: capability.version },
+      catalogVersion: catalog.package.version,
+      operationPolicy: capability.operations,
+      repository: { provider, repo },
+      declaration,
+      reconciliation,
+      authorization: { required: true, planHash: '' },
+      nextAction: reconciliation.canApply ? `lighthouse capabilities apply --plan-file ${planFile} --authorize <plan-hash>` : 'Resolve the reported conflicts before authorizing this plan.',
+    };
+    plan.authorization.planHash = planHash(plan);
+    await writeCapabilityPlan(planFile, plan);
+    if (format === 'json') console.log(JSON.stringify(plan, null, 2)); else process.stdout.write(capabilityPlanText(plan));
+    if (!reconciliation.valid || !reconciliation.canApply) process.exitCode = 1;
+    return;
+  }
+  if (action === 'apply') {
+    const authorization = args.includes('--authorize') ? args[args.indexOf('--authorize') + 1] : args.find((arg) => arg.startsWith('--authorize='))?.slice(12);
+    if (!planFile || !authorization) throw new Error('Usage: lighthouse capabilities apply --plan-file <path> --authorize <plan-hash> [--format <text|json>]');
+    const plan = JSON.parse(await readFile(resolve(root, planFile), 'utf8'));
+    if (authorization !== plan.authorization?.planHash || planHash(plan) !== authorization) throw new Error('Capability plan authorization does not match the plan file; generate a new plan.');
+    if (!plan.reconciliation?.canApply) throw new Error('Capability plan is blocked; resolve its conflicts and generate a new plan.');
+    if (!sdlcReconcile || !sdlcGithub) throw new Error('The installed SDLC package does not publish the capability adoption contract; upgrade it before applying adoption.');
+    const current = await sdlcGithub.readGithubLabels(plan.repository.repo);
+    let reconciliation = sdlcReconcile.buildLabelReconciliationPlan(plan.declaration, current, plan.reconciliation.record);
+    const originalOperations = new Set(plan.reconciliation.operations.map((operation) => operation.name));
+    const plannedTarget = new Map((plan.reconciliation.target ?? []).map((label) => [label.name, JSON.stringify(label)]));
+    const outsidePlanDrift = current.some((label) => !plannedTarget.has(label.name) || (plannedTarget.has(label.name) && !originalOperations.has(label.name) && JSON.stringify(label) !== plannedTarget.get(label.name)));
+    if (reconciliation.observedHash !== plan.reconciliation.observedHash && (outsidePlanDrift || reconciliation.operations.some((operation) => !originalOperations.has(operation.name)))) {
+      throw new Error('GitHub labels changed outside this plan; refusing to apply. Generate a new plan.');
+    }
+    const completed = [];
+    try {
+      for (const operation of reconciliation.operations) {
+        await sdlcGithub.createGithubLabel(plan.repository.repo, operation, { dryRun: false });
+        completed.push(operation);
+      }
+    } catch (error) {
+      await writeCapabilityEvidence(plan, 'failed', { operations: completed, observedHash: reconciliation.observedHash });
+      throw new Error(`Capability adoption stopped after ${completed.length} operation(s): ${error.message}`);
+    }
+    const finalLabels = await sdlcGithub.readGithubLabels(plan.repository.repo);
+    const final = sdlcReconcile.buildLabelReconciliationPlan(plan.declaration, finalLabels, plan.reconciliation.record);
+    if (!final.valid || final.operations.length || final.changes.some((change) => change.status === 'conflict')) {
+      await writeCapabilityEvidence(plan, 'blocked', { operations: completed, observedHash: final.observedHash, targetHash: final.targetHash, conflicts: final.changes.filter((change) => change.status === 'conflict') });
+      throw new Error('Capability adoption did not reach the declared state; inspect the evidence and generate a new plan.');
+    }
+    const evidencePath = await writeCapabilityEvidence(plan, 'adopted', { operations: completed, observedHash: final.observedHash, targetHash: final.targetHash });
+    const state = await readUpgradeState();
+    if (state) {
+      state.adoption = state.adoption ?? {};
+      state.adoption[id] = { id, status: 'adopted', selection: plan.capability.selection, provider: plan.capability.provider, version: plan.capability.version, catalogVersion: plan.catalogVersion, nextAction: null, recordPath: '.lighthouse/reconciliation/labels.json' };
+      await writeTextAtomically(upgradeStatePath, `${JSON.stringify(state, null, 2)}\n`);
+    }
+    const result = { ...plan, status: 'adopted', evidencePath, reconciliation: final, applied: true };
+    if (format === 'json') console.log(JSON.stringify(result, null, 2)); else process.stdout.write(capabilityPlanText(result));
+    return;
+  }
+  throw new Error('Usage: lighthouse capabilities <select|decline|plan|apply> ...');
+}
+
 function formatFromArgs(args) {
   const index = args.indexOf('--format');
   if (index !== -1) return args[index + 1];
@@ -808,17 +1120,27 @@ const commandArgs = args.slice(1);
 let invalidArgument = false;
 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 === '--name') { if (!commandArgs[index + 1]) invalidArgument = true; else index += 1; continue; }
   if (arg.startsWith('--name=') && arg.length > '--name='.length) continue;
+  if (arg === '--profile') {
+    if (command !== 'init' || !commandArgs[index + 1]) invalidArgument = true;
+    else index += 1;
+    continue;
+  }
+  if (arg.startsWith('--profile=') && arg.length > '--profile='.length) {
+    if (command !== 'init') invalidArgument = true;
+    continue;
+  }
   if (arg === '--format') {
-    if (!['verify', 'upgrade'].includes(command) || !['text', 'json'].includes(commandArgs[index + 1])) invalidArgument = true;
+    if (!['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 (!['verify', 'upgrade'].includes(command)) invalidArgument = true;
+    if (!['verify', 'upgrade', 'capabilities'].includes(command)) invalidArgument = true;
     continue;
   }
   if (arg === '--scope') {
@@ -830,9 +1152,15 @@ for (let index = 0; index < commandArgs.length; index += 1) {
     if (command !== 'upgrade') invalidArgument = true;
     continue;
   }
+  if (['--id', '--provider', '--repo', '--input', '--plan-file', '--authorize'].includes(arg)) {
+    if (!commandArgs[index + 1]) invalidArgument = true;
+    else index += 1;
+    continue;
+  }
+  if (['--id=', '--provider=', '--repo=', '--input=', '--plan-file=', '--authorize='].some((prefix) => arg.startsWith(prefix) && arg.length > prefix.length)) continue;
   invalidArgument = true;
 }
-if (!['init', 'authorities', 'reconcile', 'upgrade', 'verify'].includes(command) || invalidArgument) {
+if (!['init', 'authorities', 'reconcile', 'upgrade', 'capabilities', 'verify'].includes(command) || invalidArgument) {
   console.error(usage);
   process.exit(2);
 }
@@ -841,6 +1169,7 @@ try {
   else if (command === 'authorities') await authorities(args.slice(1));
   else if (command === 'reconcile') await reconcile(args.slice(1));
   else if (command === 'upgrade') await upgrade(args.slice(1));
+  else if (command === 'capabilities') await capabilities(args.slice(1));
   else {
     const manifest = await readManifest();
     if (!manifest) throw new Error('Cannot read lighthouse.json: file does not exist; run lighthouse init --name <product>.');

package/upgrades/0.4.0.md

@@ -0,0 +1,7 @@
+# Lighthouse 0.4.0
+
+This release discovers the installed SDLC capability catalog during `lighthouse upgrade` and records pending adoption in `.lighthouse/upgrade.json`.
+
+The upgrade remains local and dry-run by default. Review the plan, generate a provider plan with `lighthouse capabilities plan`, then authorize its application explicitly with the returned plan hash.
+
+No package installation, local upgrade or implicit hook writes to GitHub.