@juangcarmona/lighthouse-sdlc 0.4.0 → 0.5.0

package/README.md

@@ -18,6 +18,14 @@ Use `lighthouse-sdlc github-decompose --repo <owner/repo> --issue <number> --inp
 
 Declare selected adoption capabilities in a JSON file that follows `schemas/capabilities.schema.json`. `reconcile-labels` previews and optionally applies the first local label projection; `github-labels` reads the repository labels through `gh`, creates only missing labels after an explicit `--apply`, preserves existing values and records `.lighthouse/reconciliation/labels.json`.
 
+`capabilities.json` is the versioned adoption catalog. It currently declares the GitHub labels capability, its label roles and classifications, suggested colors and descriptions, declared transition policy and allowed operations.
+
+The catalog is descriptive until a consumer creates an explicit plan. `lighthouse upgrade` can discover it, but only `lighthouse capabilities apply --plan-file ... --authorize ...` may write provider state.
+
+Every catalog entry must name a registered adapter. Package verification fails when an entry has no adapter, and a new adapter is complete only when its plan, apply, verification, evidence and packaged-consumer fixture are covered by CI.
+
+`selected-by-default` capabilities appear as pending until the adopter selects or declines them. `opt-in` capabilities appear as available and do not make `upgrade` or `verify` fail until the adopter selects them.
+
 Evidence is explicit: an absent field appears in `missingEvidence`, a check that cannot run appears in `unavailableChecks`, and a judgement awaiting review appears in `pendingReview`. Only `provided` evidence can make a report ready to apply.
 
 The package is a source of lifecycle instructions and contracts; an adopter's host adapter decides where provider-specific projections are installed.

package/capabilities.json

@@ -0,0 +1,50 @@
+{
+  "$schema": "./schemas/capability-catalog.schema.json",
+  "schemaVersion": 1,
+  "package": { "name": "@juangcarmona/lighthouse-sdlc", "version": "0.5.0" },
+  "capabilities": [
+    {
+      "id": "labels",
+      "provider": "github",
+      "adapter": "github-labels",
+      "version": "1",
+      "title": "Lighthouse tracker labels",
+      "selection": "selected-by-default",
+      "configuration": {
+        "roles": ["state", "command", "classification"],
+        "labels": [
+          { "name": "triage", "role": "state", "color": "8B949E", "description": "Work item is being assessed." },
+          { "name": "refine", "role": "state", "color": "4DA3FF", "description": "Work item is being refined." },
+          { "name": "implement", "role": "state", "color": "1F6FEB", "description": "Work item is being implemented." },
+          { "name": "wip", "role": "state", "color": "D29922", "description": "Work item is actively in progress." },
+          { "name": "review", "role": "state", "color": "A371F7", "description": "Work item is awaiting review." },
+          { "name": "size-s", "role": "classification", "dimension": "size", "value": "S", "color": "BFE3FF", "description": "Small work item." },
+          { "name": "size-m", "role": "classification", "dimension": "size", "value": "M", "color": "80C2FF", "description": "Medium work item." },
+          { "name": "size-l", "role": "classification", "dimension": "size", "value": "L", "color": "4DA3FF", "description": "Large work item." },
+          { "name": "size-xl", "role": "classification", "dimension": "size", "value": "XL", "color": "1F6FEB", "description": "Extra-large work item." },
+          { "name": "urgency-normal", "role": "classification", "dimension": "urgency", "value": "normal", "color": "8B949E", "description": "Normal urgency." },
+          { "name": "urgency-asap", "role": "classification", "dimension": "urgency", "value": "asap", "color": "D29922", "description": "High urgency." },
+          { "name": "urgency-now", "role": "classification", "dimension": "urgency", "value": "now", "color": "CF222E", "description": "Immediate urgency." },
+          { "name": "impact-low", "role": "classification", "dimension": "impact", "value": "low", "color": "E9D5FF", "description": "Low impact." },
+          { "name": "impact-medium", "role": "classification", "dimension": "impact", "value": "medium", "color": "A371F7", "description": "Medium impact." },
+          { "name": "impact-high", "role": "classification", "dimension": "impact", "value": "high", "color": "6E40C9", "description": "High impact." },
+          { "name": "risk-low", "role": "classification", "dimension": "risk", "value": "low", "color": "FFEBE9", "description": "Low delivery risk." },
+          { "name": "risk-medium", "role": "classification", "dimension": "risk", "value": "medium", "color": "F0883E", "description": "Medium delivery risk." },
+          { "name": "risk-high", "role": "classification", "dimension": "risk", "value": "high", "color": "CF222E", "description": "High delivery risk." },
+          { "name": "blast-radius-low", "role": "classification", "dimension": "blast-radius", "value": "low", "color": "C7F0E8", "description": "Small affected surface." },
+          { "name": "blast-radius-medium", "role": "classification", "dimension": "blast-radius", "value": "medium", "color": "4FB3A4", "description": "Medium affected surface." },
+          { "name": "blast-radius-high", "role": "classification", "dimension": "blast-radius", "value": "high", "color": "0F766E", "description": "Large affected surface." }
+        ],
+        "transitions": [{ "from": "triage", "to": "refine" }],
+        "transitionPolicy": {
+          "mode": "declared-only",
+          "description": "Only transitions declared by the adopter are legal; the catalog supplies the initial triage-to-refine example."
+        }
+      },
+      "operations": {
+        "allowed": ["create", "preserve"],
+        "blocked": ["modify", "rename", "remove", "ambiguous"]
+      }
+    }
+  ]
+}

package/commands/capabilities.md

@@ -0,0 +1,13 @@
+# Capability adoption
+
+The SDLC package publishes `capabilities.json` as the versioned catalog of adoptable provider capabilities.
+
+The Lighthouse CLI reads this catalog during `upgrade`; package installation and upgrade never write to an external provider.
+
+Use `lighthouse capabilities select --id labels --provider github` to make the default selection explicit, or `lighthouse capabilities decline --id labels --provider github` to record an intentional opt-out without contacting GitHub.
+
+Use `lighthouse capabilities plan --id labels --provider github --repo <owner/repo> --plan-file .lighthouse/reconciliation/labels.plan.json` to read the current labels and produce a deterministic plan; pass `--input <capabilities.json>` when the adopter declares a mapping instead of using the catalog projection.
+
+Use `lighthouse capabilities apply --plan-file .lighthouse/reconciliation/labels.plan.json --authorize <plan-hash>` only after reviewing the plan; the command rereads GitHub, creates missing labels, preserves existing values and records evidence.
+
+The plan blocks modifications, renames, removals and ambiguous matches; rerunning the same plan is safe and a failed run can resume after a fresh read.

package/contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./schemas/sdlc-contract.schema.json",
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.2.0",
+  "version": "0.5.0",
   "stages": [
     { "name": "triage", "skill": "skills/triage/SKILL.md", "command": "commands/triage.md", "gate": "triaged" },
     { "name": "refine", "skill": "skills/refine/SKILL.md", "command": "commands/refine.md", "gate": "ready" },
@@ -23,6 +23,8 @@
     "stageResultSchema": "schemas/stage-result.schema.json",
     "stateSchema": "schemas/workflow-state.schema.json",
     "decompositionSchema": "schemas/decomposition.schema.json",
-    "capabilitiesSchema": "schemas/capabilities.schema.json"
+    "capabilitiesSchema": "schemas/capabilities.schema.json",
+    "capabilityCatalog": "capabilities.json",
+    "capabilityCatalogSchema": "schemas/capability-catalog.schema.json"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -22,6 +22,7 @@
   "files": [
     "commands",
     "contract.json",
+    "capabilities.json",
     "gates.json",
     "meta-commands",
     "README.md",
@@ -44,6 +45,7 @@
     "./memory": "./src/memory.mjs",
     "./routes": "./src/routes.mjs",
     "./reconcile": "./src/reconcile.mjs",
+    "./capabilities": "./src/capabilities.mjs",
     "./stacked": "./src/stacked.mjs",
     "./workflow": "./src/workflow.mjs",
     "./contract.json": "./contract.json",
@@ -53,6 +55,8 @@
     "./schemas/stage-result.schema.json": "./schemas/stage-result.schema.json",
     "./schemas/workflow-state.schema.json": "./schemas/workflow-state.schema.json",
     "./schemas/decomposition.schema.json": "./schemas/decomposition.schema.json",
-    "./schemas/capabilities.schema.json": "./schemas/capabilities.schema.json"
+    "./schemas/capabilities.schema.json": "./schemas/capabilities.schema.json",
+    "./schemas/capability-catalog.schema.json": "./schemas/capability-catalog.schema.json",
+    "./capabilities.json": "./capabilities.json"
   }
 }

package/schemas/capability-catalog.schema.json

@@ -0,0 +1,88 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/capability-catalog.schema.json",
+  "title": "Lighthouse adoptable capability catalog",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "package", "capabilities"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "version"],
+      "properties": {
+        "name": { "const": "@juangcarmona/lighthouse-sdlc" },
+        "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" }
+      }
+    },
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "provider", "adapter", "version", "title", "selection", "configuration", "operations"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "provider": { "type": "string", "minLength": 1 },
+          "adapter": { "type": "string", "minLength": 1 },
+          "version": { "type": "string", "minLength": 1 },
+          "title": { "type": "string", "minLength": 1 },
+          "selection": { "enum": ["selected-by-default", "opt-in"] },
+          "configuration": {
+            "type": "object",
+            "additionalProperties": true,
+            "properties": {
+              "roles": { "type": "array", "items": { "enum": ["state", "command", "classification"] } },
+              "labels": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["name", "role", "description"],
+                  "properties": {
+                    "name": { "type": "string", "minLength": 1 },
+                    "role": { "enum": ["state", "command", "classification"] },
+                    "dimension": { "type": "string" },
+                    "value": { "type": "string" },
+                    "color": { "type": "string", "pattern": "^[0-9A-Fa-f]{6}$" },
+                    "description": { "type": "string", "minLength": 1 }
+                  }
+                }
+              },
+              "transitions": {
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "additionalProperties": false,
+                  "required": ["from", "to"],
+                  "properties": { "from": { "type": "string" }, "to": { "type": "string" } }
+                }
+              },
+              "transitionPolicy": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["mode", "description"],
+                "properties": {
+                  "mode": { "enum": ["declared-only"] },
+                  "description": { "type": "string", "minLength": 1 }
+                }
+              }
+            }
+          },
+          "operations": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["allowed", "blocked"],
+            "properties": {
+              "allowed": { "type": "array", "items": { "enum": ["create", "preserve", "modify", "rename", "remove", "ambiguous", "unsupported"] } },
+              "blocked": { "type": "array", "items": { "enum": ["create", "preserve", "modify", "rename", "remove", "ambiguous", "unsupported"] } }
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/src/capabilities.mjs

@@ -0,0 +1,84 @@
+import { readFile } from 'node:fs/promises';
+import { resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+const capabilityAdapters = Object.freeze({
+  'labels/github': 'github-labels',
+});
+
+export function capabilityAdapter(capability) {
+  return capabilityAdapters[`${capability?.id ?? ''}/${capability?.provider ?? ''}`] ?? null;
+}
+
+export function initialAdoptionStatus(capability) {
+  return capability?.selection === 'opt-in' ? 'available' : 'pending-adoption';
+}
+
+export async function readCapabilityCatalog(path = resolve(packageRoot, 'capabilities.json')) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+export function validateCapabilityCatalog(catalog) {
+  const errors = [];
+  if (!isRecord(catalog)) return [issue('catalog.invalid', 'capability catalog must be an object')];
+  if (catalog.schemaVersion !== 1) errors.push(issue('catalog.schema-version', 'catalog schemaVersion must be 1', 'schemaVersion'));
+  if (catalog.package?.name !== '@juangcarmona/lighthouse-sdlc') errors.push(issue('catalog.package', 'catalog package name is incorrect', 'package.name'));
+  if (typeof catalog.package?.version !== 'string' || !/^\d+\.\d+\.\d+$/.test(catalog.package.version)) errors.push(issue('catalog.package-version', 'catalog package version must be semver-like', 'package.version'));
+  if (!Array.isArray(catalog.capabilities) || catalog.capabilities.length === 0) return [...errors, issue('catalog.capabilities', 'catalog capabilities must be a non-empty array', 'capabilities')];
+  const ids = new Set();
+  for (const capability of catalog.capabilities) {
+    if (!isRecord(capability) || typeof capability.id !== 'string' || !capability.id.trim()) {
+      errors.push(issue('catalog.capability', 'every catalog capability needs an id', 'capabilities'));
+      continue;
+    }
+    if (ids.has(capability.id)) errors.push(issue('catalog.duplicate', `catalog capability ${capability.id} appears more than once`, 'capabilities'));
+    ids.add(capability.id);
+    if (typeof capability.provider !== 'string' || !capability.provider) errors.push(issue('catalog.provider', `catalog capability ${capability.id} needs a provider`, 'capabilities'));
+    if (typeof capability.version !== 'string' || !capability.version) errors.push(issue('catalog.version', `catalog capability ${capability.id} needs a version`, 'capabilities'));
+    if (typeof capability.adapter !== 'string' || !capability.adapter) errors.push(issue('catalog.adapter', `catalog capability ${capability.id} needs an adapter`, 'capabilities'));
+    else if (capability.adapter !== capabilityAdapter(capability)) errors.push(issue('catalog.adapter-unsupported', `catalog capability ${capability.id} does not have a registered ${capability.adapter} adapter`, 'capabilities'));
+    if (!isRecord(capability.configuration)) errors.push(issue('catalog.configuration', `catalog capability ${capability.id} needs a configuration object`, 'capabilities'));
+    if (capability.adapter === 'github-labels' && (!Array.isArray(capability.configuration?.labels) || !Array.isArray(capability.configuration?.transitions))) {
+      errors.push(issue('catalog.configuration', `catalog capability ${capability.id} needs labels and transitions for the github-labels adapter`, 'capabilities'));
+    }
+    if (!isRecord(capability.operations) || !Array.isArray(capability.operations.allowed) || !Array.isArray(capability.operations.blocked)) errors.push(issue('catalog.operations', `catalog capability ${capability.id} needs operation policy`, 'capabilities'));
+    else {
+      const allowed = new Set(capability.operations.allowed);
+      const blocked = new Set(capability.operations.blocked);
+      const operationKinds = new Set(['create', 'preserve', 'modify', 'rename', 'remove', 'ambiguous', 'unsupported']);
+      for (const kind of [...allowed, ...blocked]) if (!operationKinds.has(kind)) errors.push(issue('catalog.operation-kind', `catalog capability ${capability.id} uses unknown operation ${kind}`, 'capabilities'));
+      for (const kind of allowed) if (blocked.has(kind)) errors.push(issue('catalog.operation-overlap', `catalog capability ${capability.id} marks ${kind} as both allowed and blocked`, 'capabilities'));
+    }
+  }
+  return errors;
+}
+
+export function catalogCapability(catalog, id) {
+  return catalog?.capabilities?.find((capability) => capability.id === id) ?? null;
+}
+
+export function declarationFromCatalog(catalog, id = 'labels') {
+  const capability = catalogCapability(catalog, id);
+  if (!capability) throw new Error(`Capability ${id} is not declared by the installed SDLC package.`);
+  return {
+    schemaVersion: 1,
+    capabilities: [{
+      id: capability.id,
+      provider: capability.provider,
+      version: capability.version,
+      adapter: capability.adapter,
+      catalogVersion: catalog.package.version,
+      configuration: capability.configuration,
+    }],
+  };
+}

package/src/reconcile.mjs

@@ -111,17 +111,17 @@ export function buildLabelReconciliationPlan(declaration, existingLabels, previo
     if (!current) {
       const equivalents = existingByComparableName.get(comparableName(label.name)) ?? [];
       if (equivalents.length) {
-        changes.push({ name: label.name, status: 'conflict', desired: label, candidates: equivalents });
+        changes.push({ name: label.name, status: 'conflict', operation: 'ambiguous', desired: label, candidates: equivalents });
         continue;
       }
-      changes.push({ name: label.name, status: 'missing', desired: label });
-      operations.push({ type: 'create-label', name: label.name, color: label.color ?? '8B949E', description: label.description ?? '' });
+      changes.push({ name: label.name, status: 'missing', operation: 'create', desired: label });
+      operations.push({ type: 'create-label', kind: 'create', name: label.name, color: label.color ?? '8B949E', description: label.description ?? '' });
       continue;
     }
     const customized = (label.color !== null && current.color !== label.color) || (label.description !== null && current.description !== label.description);
-    changes.push({ name: label.name, status: customized ? 'customized' : 'unchanged', existing: current, desired: label });
+    changes.push({ name: label.name, status: customized ? 'customized' : 'unchanged', operation: 'preserve', blockedOperations: customized ? ['modify'] : [], existing: current, desired: label });
   }
-  for (const label of existing.labels) if (!desiredNames.has(label.name)) changes.push({ name: label.name, status: 'preserved', existing: label });
+  for (const label of existing.labels) if (!desiredNames.has(label.name)) changes.push({ name: label.name, status: 'preserved', operation: 'preserve', existing: label });
   changes.sort((left, right) => left.name.localeCompare(right.name));
   const target = [...existing.labels, ...operations.map((operation) => ({ name: operation.name, color: operation.color, description: operation.description }))].sort((left, right) => left.name.localeCompare(right.name));
   const observedHash = digest(existing.labels);
@@ -140,7 +140,10 @@ export function buildLabelReconciliationPlan(declaration, existingLabels, previo
     desiredHash: digest(desired),
     observedHash,
     targetHash,
+    target,
     drift,
+    operationPolicy: capability?.operations ?? { allowed: ['create', 'preserve'], blocked: ['modify', 'rename', 'remove', 'ambiguous'] },
+    blockedOperations: changes.flatMap((change) => change.blockedOperations ?? []),
     changes,
     operations,
     errors,
@@ -150,7 +153,8 @@ export function buildLabelReconciliationPlan(declaration, existingLabels, previo
       desiredHash: digest(desired),
       observedHash: targetHash,
       targetHash,
-      operations: operations.map(({ type, name, color: labelColor, description }) => ({ type, name, color: labelColor, description })),
+      operations: operations.map(({ type, kind, name, color: labelColor, description }) => ({ type, kind, name, color: labelColor, description })),
+      blockedOperations: changes.flatMap((change) => change.blockedOperations ?? []),
       verified: false,
     },
   };

package/src/sdlc.mjs

@@ -13,6 +13,7 @@ import { applyTriageLabels, buildTriageReport } from './triage.mjs';
 import { validateMemoryRecord } from './memory.mjs';
 import { replayWorkflow } from './workflow.mjs';
 import { validateStageResult } from './contracts.mjs';
+import { readCapabilityCatalog, validateCapabilityCatalog } from './capabilities.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const contractPath = resolve(packageRoot, 'contract.json');
@@ -38,10 +39,10 @@ async function verifyContract() {
   for (const stage of stages) {
     for (const asset of [stage.skill, stage.command]) if (!(await exists(resolve(packageRoot, asset)))) problems.push(`missing stage asset ${asset}`);
   }
-  for (const asset of [contract.assets?.routes, contract.assets?.gates, contract.assets?.stages, contract.assets?.controlPlaneSchema, contract.assets?.triageSchema, contract.assets?.stageResultSchema, contract.assets?.stateSchema, contract.assets?.decompositionSchema, contract.assets?.capabilitiesSchema]) {
+  for (const asset of [contract.assets?.routes, contract.assets?.gates, contract.assets?.stages, contract.assets?.controlPlaneSchema, contract.assets?.triageSchema, contract.assets?.stageResultSchema, contract.assets?.stateSchema, contract.assets?.decompositionSchema, contract.assets?.capabilitiesSchema, contract.assets?.capabilityCatalog, contract.assets?.capabilityCatalogSchema]) {
     if (!asset || !(await exists(resolve(packageRoot, asset)))) problems.push(`missing contract asset ${asset ?? '(empty)'}`);
   }
-  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'schemas/routes.schema.json', 'schemas/gates.schema.json', 'schemas/stages.schema.json', 'schemas/control-plane.schema.json', 'schemas/triage.schema.json', 'schemas/stage-result.schema.json', 'schemas/workflow-state.schema.json', 'schemas/decomposition.schema.json', 'schemas/capabilities.schema.json', 'src/contracts.mjs', 'src/control-plane.mjs', 'src/decompose.mjs', 'src/github.mjs', 'src/memory.mjs', 'src/reconcile.mjs', 'src/routes.mjs', 'src/stacked.mjs', 'src/triage.mjs', 'src/workflow.mjs']) {
+  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'schemas/routes.schema.json', 'schemas/gates.schema.json', 'schemas/stages.schema.json', 'schemas/control-plane.schema.json', 'schemas/triage.schema.json', 'schemas/stage-result.schema.json', 'schemas/workflow-state.schema.json', 'schemas/decomposition.schema.json', 'schemas/capabilities.schema.json', 'schemas/capability-catalog.schema.json', 'src/capabilities.mjs', 'src/contracts.mjs', 'src/control-plane.mjs', 'src/decompose.mjs', 'src/github.mjs', 'src/memory.mjs', 'src/reconcile.mjs', 'src/routes.mjs', 'src/stacked.mjs', 'src/triage.mjs', 'src/workflow.mjs']) {
     if (!(await exists(resolve(packageRoot, asset)))) problems.push(`missing package asset ${asset}`);
   }
   try {
@@ -59,6 +60,10 @@ async function verifyContract() {
     const stageIds = stages.stages?.map((stage) => stage.id) ?? [];
     if (stageIds.join(',') !== expectedStages.join(',')) problems.push('stages.json does not match contract stages');
   } catch (error) { problems.push(`Cannot read stages.json: ${error.message}`); }
+  try {
+    const catalog = await readCapabilityCatalog();
+    problems.push(...validateCapabilityCatalog(catalog).map((error) => `${error.code}: ${error.message}`));
+  } catch (error) { problems.push(`Cannot read capabilities.json: ${error.message}`); }
   for (const command of ['status', ...expectedStages, ...(contract.utilities ?? []).filter((command) => command !== 'status')]) if (!(await exists(resolve(packageRoot, `commands/${command}.md`)))) problems.push(`missing command asset ${command}`);
   for (const metaCommand of contract.metaCommands ?? []) if (!(await exists(resolve(packageRoot, `meta-commands/${metaCommand}.md`)))) problems.push(`missing meta-command asset ${metaCommand}`);
   return problems;