@juangcarmona/lighthouse 0.1.0 → 0.2.1

package/README.md

@@ -4,17 +4,25 @@ This package is the core Lighthouse harness. It provides the `lighthouse` comman
 
 ## Initialize a repository
 
-Install the exact Lighthouse package artifacts selected for the release, create the project manifest and run `lighthouse init`. Inspect the generated `LIGHTHOUSE.md`, 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. 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.
 
-The harness package owns the baseline command and verification contract. The SDLC package owns lifecycle skills, commands and metacommands. The UI package owns visual tokens, native recipes and `DESIGN.md`. Stack profiles own their source templates, guidance and checks.
+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.
+
+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.
 
 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.
 
+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.
+
+The generated manifest enables the public-site route for greenfield repositories. Its build validates ProductShape and ArcShape before creating either snapshot; if the authorities are not ready, the build stops with the repair command instead of publishing a partial site.
+
+Initialization reports missing ProductShape and ArcShape authority inputs as adoption gaps. It does not copy or replace their provider-owned files. The SDLC package remains provider-neutral; an agent host decides where its skills and commands are projected.
+
 ## New repository
 
-1. Select the harness, SDLC, UI and stack profile artifacts required by the application.
-2. Create the manifest with exact package and integration versions.
-3. Run `lighthouse init`, review the generated projection and run `lighthouse verify`.
+1. Install the harness and the profile artifacts required by the application.
+2. Run `lighthouse init --name <product>` and review the proposed repository boundaries.
+3. Review the generated manifest and `LIGHTHOUSE.md`, then run `lighthouse verify`.
 4. Add the selected profile checks to the repository verification command and CI workflow.
 5. Record project-owned exceptions with an owner and review date.
 
@@ -22,12 +30,30 @@ ProductShape, ArcShape and OpenSpec keep their own files and commands. Add them
 
 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; preserve product-owned guidance and generated outputs.
+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.
 
 ## Current command scope
 
-The current command supports `init` and `verify`. It checks the manifest, exact version pins and generated content. Lifecycle stages, tracker operations, agent runs and CodeGraph checks require their own configured integrations.
+The command supports `init`, `authorities`, `reconcile` 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 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
+
+The CLI package owns a versioned catalog under `assets/guardrails/`; it describes the guardrails already present in the Lighthouse baseline and their applicability, level, kind, verification method and repair hint.
+
+`level` and `kind` are independent: `level` is `required`, `recommended` or `optional`, while `kind` is `hard` or `soft`; neither dimension selects the verification method.
+
+`lighthouse verify` keeps its existing human-readable success and failure output; `lighthouse verify --format json` exposes the same run for agents and CI without changing the default route.
+
+The catalog uses `passed` when evidence satisfies a check, `failed` when a deterministic check finds a problem, `drift` when managed content differs, `unavailable` when a declared checker cannot run or produce evidence, `unconfigured` when an applicable check or integration is not enabled, `pending-review` when semantic or human judgement is still required, and `not-applicable` when the selected baseline or profiles do not include the guardrail.
+
+Only `passed` and `not-applicable` satisfy a required guardrail; `pending-review` is not evidence of compliance and is distinct from both `unconfigured` and `unavailable`.
+
+To add a future guardrail, the catalog owner adds a JSON entry under the packaged `assets/guardrails/` surface, validates it against `assets/schemas/guardrails.schema.json`, declares its profile applicability and repair hint, and uses an existing checker or an explicit semantic or human verification method; in this delivery the surface belongs to the CLI package, and the CLI core does not change.
+
+A new deterministic checker mechanism or a new engineering practice is outside this catalog and requires a separate Product Change.

package/assets/guardrails/catalog.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../schemas/guardrails.schema.json",
+  "schemaVersion": 1,
+  "guardrails": [
+    {
+      "id": "foundation.manifest",
+      "owner": "lighthouse",
+      "appliesTo": { "baseline": true, "profiles": [] },
+      "level": "required",
+      "kind": "hard",
+      "verification": "deterministic",
+      "check": "manifest",
+      "failureHint": "Repair lighthouse.json and run lighthouse verify again."
+    },
+    {
+      "id": "repository.layout",
+      "owner": "lighthouse",
+      "appliesTo": { "baseline": true, "profiles": [] },
+      "level": "required",
+      "kind": "hard",
+      "verification": "deterministic",
+      "check": "layout",
+      "failureHint": "Create the declared src/, docs/, infra/ and scripts/ repository boundaries."
+    },
+    {
+      "id": "repository.managed-projection",
+      "owner": "lighthouse",
+      "appliesTo": { "baseline": true, "profiles": [] },
+      "level": "required",
+      "kind": "hard",
+      "verification": "deterministic",
+      "check": "managed-projection",
+      "failureHint": "Run lighthouse reconcile after reviewing the managed path plan."
+    },
+    {
+      "id": "repository.branch-convention",
+      "owner": "lighthouse",
+      "appliesTo": { "baseline": true, "profiles": [] },
+      "level": "required",
+      "kind": "hard",
+      "verification": "deterministic",
+      "check": "branch",
+      "failureHint": "Use the branch pattern declared in lighthouse.json."
+    }
+  ]
+}

package/assets/schemas/guardrails.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/guardrails.schema.json",
+  "title": "Lighthouse guardrail catalog",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "schemaVersion", "guardrails"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "guardrails": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/guardrail" }
+    }
+  },
+  "$defs": {
+    "guardrail": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "owner", "appliesTo", "level", "kind", "verification", "check", "failureHint"],
+      "properties": {
+        "id": { "type": "string", "pattern": "^[a-z0-9]+(?:[.-][a-z0-9]+)*$" },
+        "owner": { "type": "string", "minLength": 1 },
+        "appliesTo": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["baseline", "profiles"],
+          "properties": {
+            "baseline": { "type": "boolean" },
+            "profiles": { "type": "array", "items": { "type": "string" }, "uniqueItems": true }
+          }
+        },
+        "level": { "enum": ["required", "recommended", "optional"] },
+        "kind": { "enum": ["hard", "soft"] },
+        "verification": { "enum": ["deterministic", "semantic", "human"] },
+        "check": { "type": "string", "minLength": 1 },
+        "failureHint": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

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

@@ -11,8 +11,28 @@
     "baseline": {"const": "0.1.0"},
     "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", "agenticSdlc"], "properties": {"productShape": {"$ref": "#/$defs/pin"}, "arcShape": {"$ref": "#/$defs/pin"}, "agenticSdlc": {"$ref": "#/$defs/pin"}}},
-    "managed": {"const": ["LIGHTHOUSE.md"]}
+    "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"}}}}},
+    "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"]}
+    ]},
+    "repository": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["layout", "publicSite", "conventions"],
+      "properties": {
+        "layout": {"const": ["src", "docs", "infra", "scripts"]},
+        "publicSite": {"type": "object", "additionalProperties": false, "required": ["enabled"], "properties": {"enabled": {"type": "boolean"}}},
+        "conventions": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["commits", "branchPattern"],
+          "properties": {"commits": {"const": "conventional"}, "branchPattern": {"type": "string", "minLength": 1}}
+        }
+      }
+    }
   },
   "$defs": {
     "pin": {"type": ["string", "null"], "pattern": "^(?:\\d+\\.\\d+\\.\\d+|[a-f0-9]{40})$"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -19,7 +19,17 @@
   "engines": {
     "node": ">=22"
   },
-  "files": ["src/lighthouse.mjs", "assets", "README.md"],
+  "dependencies": {
+    "@arcshape/cli": "0.1.3",
+    "@prodshape/cli": "0.22.0",
+    "@juangcarmona/lighthouse-sdlc": "0.2.0"
+  },
+  "files": [
+    "src/lighthouse.mjs",
+    "src/guardrails.mjs",
+    "assets",
+    "README.md"
+  ],
   "bin": {
     "lighthouse": "./src/lighthouse.mjs"
   }

package/src/guardrails.mjs

@@ -0,0 +1,140 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const catalogDirectory = fileURLToPath(new URL('../assets/guardrails/', import.meta.url));
+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']);
+
+function descriptorProblems(descriptor) {
+  const problems = [];
+  if (!descriptor || typeof descriptor !== 'object' || Array.isArray(descriptor)) return ['descriptor must be an object'];
+  for (const key of ['id', 'owner', 'appliesTo', 'level', 'kind', 'verification', 'check', 'failureHint']) {
+    if (!(key in descriptor)) problems.push(`missing ${key}`);
+  }
+  if (typeof descriptor.id !== 'string' || !/^[a-z0-9]+(?:[.-][a-z0-9]+)*$/u.test(descriptor.id)) problems.push('id must use lowercase dot or hyphen notation');
+  if (typeof descriptor.owner !== 'string' || !descriptor.owner) problems.push('owner must be a non-empty string');
+  if (!descriptor.appliesTo || typeof descriptor.appliesTo !== 'object' || Array.isArray(descriptor.appliesTo)
+      || typeof descriptor.appliesTo.baseline !== 'boolean' || !Array.isArray(descriptor.appliesTo.profiles)
+      || descriptor.appliesTo.profiles.some((profile) => typeof profile !== 'string')) {
+    problems.push('appliesTo must declare baseline and profile names');
+  }
+  if (!allowedLevels.has(descriptor.level)) problems.push('level must be required, recommended or optional');
+  if (!allowedKinds.has(descriptor.kind)) problems.push('kind must be hard or soft');
+  if (!allowedVerification.has(descriptor.verification)) problems.push('verification must be deterministic, semantic or human');
+  if (typeof descriptor.check !== 'string' || !descriptor.check) problems.push('check must be a non-empty string');
+  if (typeof descriptor.failureHint !== 'string' || !descriptor.failureHint) problems.push('failureHint must be a non-empty string');
+  return problems;
+}
+
+function catalogProblems(catalog) {
+  const problems = [];
+  if (!catalog || typeof catalog !== 'object' || Array.isArray(catalog)) return ['catalog must be an object'];
+  if (catalog.schemaVersion !== 1) problems.push('schemaVersion must be 1');
+  if (!Array.isArray(catalog.guardrails)) problems.push('guardrails must be an array');
+  const ids = new Set();
+  for (const descriptor of catalog.guardrails ?? []) {
+    problems.push(...descriptorProblems(descriptor).map((problem) => `${descriptor?.id ?? '<unknown>'}: ${problem}`));
+    if (descriptor?.id && ids.has(descriptor.id)) problems.push(`${descriptor.id}: duplicate id`);
+    if (descriptor?.id) ids.add(descriptor.id);
+  }
+  return problems;
+}
+
+export function readGuardrailCatalog() {
+  const files = readdirSync(catalogDirectory).filter((file) => file.endsWith('.json')).sort();
+  const catalogs = files.map((file) => JSON.parse(readFileSync(join(catalogDirectory, file), 'utf8')));
+  const catalog = {
+    schemaVersion: 1,
+    guardrails: catalogs.flatMap((item) => item.guardrails ?? []),
+  };
+  const problems = catalogProblems(catalog);
+  if (problems.length) throw new Error(`Invalid guardrail catalog:\n${problems.join('\n')}`);
+  return catalog;
+}
+
+export function initialReviewStatus(descriptor) {
+  return descriptor.verification === 'deterministic' ? 'unavailable' : 'pending-review';
+}
+
+function appliesTo(descriptor, manifest) {
+  const selectedProfiles = new Set(manifest.profiles ?? []);
+  return descriptor.appliesTo.baseline || descriptor.appliesTo.profiles.some((profile) => selectedProfiles.has(profile));
+}
+
+function result(descriptor, status, evidence = [], problems = []) {
+  return {
+    id: descriptor.id,
+    owner: descriptor.owner,
+    level: descriptor.level,
+    kind: descriptor.kind,
+    verification: descriptor.verification,
+    status,
+    evidence,
+    problems,
+    nextAction: status === 'passed' || status === 'not-applicable' ? null : descriptor.failureHint,
+  };
+}
+
+async function runDeterministicCheck(descriptor, context) {
+  if (descriptor.check === 'manifest') return result(descriptor, 'passed', [{ path: 'lighthouse.json' }]);
+  if (descriptor.check === 'layout') {
+    const missing = [];
+    for (const directory of context.repository.layout) {
+      if (!(await context.isDirectory(context.resolve(directory)))) missing.push(`missing repository boundary ${directory}/; run lighthouse init`);
+    }
+    return result(descriptor, missing.length ? 'failed' : 'passed', context.repository.layout.map((directory) => ({ path: `${directory}/` })), missing);
+  }
+  if (descriptor.check === 'managed-projection') {
+    const missing = [];
+    const drifted = [];
+    for (const [file, expected] of Object.entries(context.managedFiles)) {
+      const target = context.resolve(file);
+      if (!(await context.exists(target))) missing.push(`${file} is missing; run lighthouse init after reviewing the plan`);
+      else if (await context.readFile(target, 'utf8') !== expected) drifted.push(`${file} has drifted; regenerate it from lighthouse.json`);
+    }
+    const problems = [...missing, ...drifted];
+    return result(descriptor, drifted.length ? 'drift' : missing.length ? 'failed' : 'passed', Object.keys(context.managedFiles).map((path) => ({ path })), problems);
+  }
+  if (descriptor.check === 'branch') {
+    const problems = context.validateGitConventions(context.repository);
+    return result(descriptor, problems.length ? 'failed' : 'passed', [{ value: context.branch ?? '' }, { pattern: context.repository.conventions.branchPattern }], 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 }) {
+  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 results = [];
+  for (const descriptor of catalog.guardrails) {
+    if (!appliesTo(descriptor, manifest)) {
+      results.push(result(descriptor, 'not-applicable'));
+      continue;
+    }
+    if (descriptor.verification !== 'deterministic') {
+      results.push(result(descriptor, initialReviewStatus(descriptor)));
+      continue;
+    }
+    results.push(await runDeterministicCheck(descriptor, context));
+  }
+  return report(results);
+}
+
+function report(results) {
+  const blocking = results.filter((item) => item.level === 'required' && !['passed', 'not-applicable'].includes(item.status));
+  const summary = Object.fromEntries([...allowedStatuses].map((status) => [status, results.filter((item) => item.status === status).length]));
+  return {
+    schemaVersion: 1,
+    results,
+    summary,
+    blocking: blocking.map((item) => item.id),
+    problems: blocking.flatMap((item) => item.problems),
+  };
+}

package/src/lighthouse.mjs

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