@juangcarmona/lighthouse-sdlc 0.6.0 → 0.7.0

package/README.md

@@ -4,6 +4,8 @@ This package provides the provider-neutral delivery contract for Lighthouse adop
 
 It owns the six lifecycle skills, their command entrypoints, route, stage and gate descriptors, deterministic triage and decomposition projections, rebuildable state checks and the provider-neutral control-plane contract.
 
+It publishes `command-aliases.json` as the versioned, machine-readable mapping from selected `/lh:*` aliases to canonical `/lighthouse:*` command assets. Run `lighthouse-sdlc aliases --format json` to inspect it; the configured agent host decides how to expose the aliases.
+
 It also provides the `browser-e2e` evidence contract for Playwright journeys. The contract belongs to the SDLC because it records delivery evidence; the tests, journeys and browser configuration remain owned by the adopter.
 
 It does not run agents, store transcripts, dispatch work between repositories or replace ProductShape, ArcShape, OpenSpec or an agent host.

package/command-aliases.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "./schemas/command-aliases.schema.json",
+  "schemaVersion": 1,
+  "contractVersion": 1,
+  "package": { "name": "@juangcarmona/lighthouse-sdlc" },
+  "canonicalNamespace": "/lighthouse",
+  "aliasNamespace": "/lh",
+  "aliases": [
+    { "alias": "/lh:control", "canonical": "/lighthouse:control-plane", "asset": "commands/control-plane.md" },
+    { "alias": "/lh:gh-decompose", "canonical": "/lighthouse:github-decompose", "asset": "commands/github-decompose.md" },
+    { "alias": "/lh:gh-triage", "canonical": "/lighthouse:github-triage", "asset": "commands/github-triage.md" },
+    { "alias": "/lh:result", "canonical": "/lighthouse:stage-result", "asset": "commands/stage-result.md" },
+    { "alias": "/lh:e2e", "canonical": "/lighthouse:browser-e2e", "asset": "commands/browser-e2e.md" },
+    { "alias": "/lh:caps", "canonical": "/lighthouse:capabilities", "asset": "commands/capabilities.md" },
+    { "alias": "/lh:labels", "canonical": "/lighthouse:reconcile-labels", "asset": "commands/reconcile-labels.md" },
+    { "alias": "/lh:gh-labels", "canonical": "/lighthouse:github-labels", "asset": "commands/github-labels.md" },
+    { "alias": "/lh:mem", "canonical": "/lighthouse:memory", "asset": "commands/memory.md" },
+    { "alias": "/lh:impl", "canonical": "/lighthouse:implement", "asset": "commands/implement.md" }
+  ]
+}

package/commands/aliases.md

@@ -0,0 +1,5 @@
+# `/lighthouse:aliases`
+
+Use `lighthouse-sdlc aliases --format json` to inspect the SDLC package's versioned agent-command aliases. The output maps each `/lh:*` alias to one canonical `/lighthouse:*` command and its packaged command asset.
+
+The alias listing is read-only. The configured agent host decides how to expose the aliases and must reference the canonical command asset instead of copying or maintaining a second command implementation.

package/contract.json

@@ -10,7 +10,7 @@
     { "name": "integrate", "skill": "skills/integrate/SKILL.md", "command": "commands/integrate.md", "gate": "done" },
     { "name": "review", "skill": "skills/review/SKILL.md", "command": "commands/review.md", "gate": null }
   ],
-  "utilities": ["status", "route", "state", "stage-result", "control-plane", "memory", "launch", "decompose", "stacked", "browser-e2e", "github-triage", "github-decompose", "reconcile-labels", "github-labels"],
+  "utilities": ["status", "aliases", "route", "state", "stage-result", "control-plane", "memory", "launch", "decompose", "stacked", "browser-e2e", "github-triage", "github-decompose", "reconcile-labels", "github-labels"],
   "routes": ["supervised", "plan-only", "unattended", "hotfix", "stacked"],
   "metaCommands": ["ff", "hotfix", "decompose", "stacked"],
   "gates": ["triaged", "ready", "planned", "done"],
@@ -26,6 +26,8 @@
     "capabilitiesSchema": "schemas/capabilities.schema.json",
     "browserE2eSchema": "schemas/browser-e2e.schema.json",
     "capabilityCatalog": "capabilities.json",
-    "capabilityCatalogSchema": "schemas/capability-catalog.schema.json"
+    "capabilityCatalogSchema": "schemas/capability-catalog.schema.json",
+    "commandAliases": "command-aliases.json",
+    "commandAliasesSchema": "schemas/command-aliases.schema.json"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -21,6 +21,7 @@
   },
   "files": [
     "commands",
+    "command-aliases.json",
     "contract.json",
     "capabilities.json",
     "gates.json",
@@ -46,6 +47,7 @@
     "./routes": "./src/routes.mjs",
     "./reconcile": "./src/reconcile.mjs",
     "./capabilities": "./src/capabilities.mjs",
+    "./aliases": "./src/aliases.mjs",
     "./stacked": "./src/stacked.mjs",
     "./workflow": "./src/workflow.mjs",
     "./browser-e2e": "./src/browser-e2e.mjs",
@@ -59,6 +61,8 @@
     "./schemas/capabilities.schema.json": "./schemas/capabilities.schema.json",
     "./schemas/capability-catalog.schema.json": "./schemas/capability-catalog.schema.json",
     "./schemas/browser-e2e.schema.json": "./schemas/browser-e2e.schema.json",
-    "./capabilities.json": "./capabilities.json"
+    "./capabilities.json": "./capabilities.json",
+    "./command-aliases.json": "./command-aliases.json",
+    "./schemas/command-aliases.schema.json": "./schemas/command-aliases.schema.json"
   }
 }

package/schemas/command-aliases.schema.json

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

package/src/aliases.mjs

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

package/src/sdlc.mjs

@@ -15,6 +15,7 @@ import { replayWorkflow } from './workflow.mjs';
 import { validateStageResult } from './contracts.mjs';
 import { browserEvidenceReport } from './browser-e2e.mjs';
 import { readCapabilityCatalog, validateCapabilityCatalog } from './capabilities.mjs';
+import { readCommandAliases, validateCommandAliases, verifyCommandAliases } from './aliases.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const contractPath = resolve(packageRoot, 'contract.json');
@@ -40,10 +41,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, contract.assets?.capabilityCatalog, contract.assets?.capabilityCatalogSchema, contract.assets?.browserE2eSchema]) {
+  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, contract.assets?.browserE2eSchema, contract.assets?.commandAliases, contract.assets?.commandAliasesSchema]) {
     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', 'schemas/capability-catalog.schema.json', 'schemas/browser-e2e.schema.json', 'src/browser-e2e.mjs', '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']) {
+  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'command-aliases.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', 'schemas/browser-e2e.schema.json', 'schemas/command-aliases.schema.json', 'src/aliases.mjs', 'src/browser-e2e.mjs', '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 {
@@ -65,11 +66,30 @@ async function verifyContract() {
     const catalog = await readCapabilityCatalog();
     problems.push(...validateCapabilityCatalog(catalog).map((error) => `${error.code}: ${error.message}`));
   } catch (error) { problems.push(`Cannot read capabilities.json: ${error.message}`); }
+  try {
+    const aliases = await readCommandAliases();
+    problems.push(...(await verifyCommandAliases(aliases)).map((error) => `${error.code}: ${error.message}`));
+  } catch (error) { problems.push(`Cannot read command-aliases.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;
 }
 
+async function runAliases(args) {
+  const format = option(args, '--format') ?? 'json';
+  if (!['json', 'text'].includes(format)) { console.error('Usage: lighthouse-sdlc aliases [--format <json|text>]'); process.exit(2); }
+  const contract = await readCommandAliases();
+  const errors = await verifyCommandAliases(contract);
+  const result = { schemaVersion: 1, status: errors.length ? 'invalid' : 'valid', valid: errors.length === 0, package: contract.package, contractVersion: contract.contractVersion, canonicalNamespace: contract.canonicalNamespace, aliasNamespace: contract.aliasNamespace, aliases: contract.aliases, errors };
+  if (format === 'json') console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log(`SDLC command aliases: ${result.status}`);
+    for (const alias of result.aliases) console.log(`  ${alias.alias} -> ${alias.canonical}`);
+    for (const error of result.errors) console.error(`  ${error.code}: ${error.message}`);
+  }
+  if (errors.length) process.exit(1);
+}
+
 function option(args, name) {
   const index = args.indexOf(name);
   if (index !== -1) return args[index + 1];
@@ -328,14 +348,16 @@ async function runGithubLabels(args) {
 }
 
 const command = process.argv[2] ?? 'verify';
-if (!['contract', 'verify', 'triage', 'state', 'stage-result', 'browser-e2e', 'control-plane', 'memory', 'launch', 'decompose', 'stacked', 'route', 'github-triage', 'github-decompose', 'reconcile-labels', 'github-labels'].includes(command)) {
-  console.error('Usage: lighthouse-sdlc <contract|verify|triage|state|stage-result|browser-e2e|control-plane|memory|launch|decompose|stacked|route|github-triage|github-decompose|reconcile-labels|github-labels>');
+if (!['contract', 'verify', 'aliases', 'triage', 'state', 'stage-result', 'browser-e2e', 'control-plane', 'memory', 'launch', 'decompose', 'stacked', 'route', 'github-triage', 'github-decompose', 'reconcile-labels', 'github-labels'].includes(command)) {
+  console.error('Usage: lighthouse-sdlc <contract|verify|aliases|triage|state|stage-result|browser-e2e|control-plane|memory|launch|decompose|stacked|route|github-triage|github-decompose|reconcile-labels|github-labels>');
   process.exit(2);
 }
 if (command === 'contract') {
   console.log(await readFile(contractPath, 'utf8'));
 } else if (command === 'triage') {
   await runTriage(process.argv.slice(3));
+} else if (command === 'aliases') {
+  await runAliases(process.argv.slice(3));
 } else if (command === 'state') {
   await runState(process.argv.slice(3));
 } else if (command === 'control-plane') {
@@ -371,4 +393,4 @@ if (command === 'contract') {
   console.log('Lighthouse SDLC package contract is valid.');
 }
 
-export { contractPath, runTriage, verifyContract, runState, runStageResult, runBrowserE2e, runControlPlane, runMemory, runLaunch, runDecompose, runRoute, runStacked, runGithubTriage, runGithubDecompose, runReconcileLabels, runGithubLabels };
+export { contractPath, runTriage, verifyContract, runAliases, runState, runStageResult, runBrowserE2e, runControlPlane, runMemory, runLaunch, runDecompose, runRoute, runStacked, runGithubTriage, runGithubDecompose, runReconcileLabels, runGithubLabels };