@juangcarmona/lighthouse 0.1.0 → 0.3.0

package/README.md

@@ -4,17 +4,27 @@ 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.
+
+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.
 
 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 +32,32 @@ 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`, `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.
+
+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 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,29 @@
     "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"]},
+      {"const": ["LIGHTHOUSE.md", "scripts/lighthouse-guard.mjs", ".husky/commit-msg", ".husky/pre-push", ".github/workflows/lighthouse.yml", ".lighthouse/sdlc.json", ".lighthouse/upgrade.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/assets/schemas/lighthouse-upgrade.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-upgrade.schema.json",
+  "title": "Lighthouse upgrade ownership state",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "package", "baseline", "capabilities", "projections", "lastAppliedMigration", "files"],
+  "properties": {
+    "$schema": {"type": "string"},
+    "schemaVersion": {"const": 1},
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {"name": {"const": "@juangcarmona/lighthouse"}, "version": {"type": "string", "pattern": "^(?:\\d+\\.\\d+\\.\\d+|[a-f0-9]{40})$"}}
+    },
+    "baseline": {"type": "string", "minLength": 1},
+    "capabilities": {"$ref": "#/$defs/versions"},
+    "projections": {"$ref": "#/$defs/versions"},
+    "lastAppliedMigration": {"type": "string", "minLength": 1},
+    "files": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["hash", "scope"],
+        "properties": {
+          "hash": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+          "scope": {"enum": ["harness", "sdlc"]}
+        }
+      }
+    }
+  },
+  "$defs": {"versions": {"type": "object", "additionalProperties": {"type": ["string", "null"]}}}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Lighthouse adoption and verification CLI",
   "repository": {
@@ -19,7 +19,18 @@
   "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.3.0"
+  },
+  "files": [
+    "src/lighthouse.mjs",
+    "src/guardrails.mjs",
+    "assets",
+    "README.md",
+    "upgrades"
+  ],
   "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),
+  };
+}