@juangcarmona/lighthouse-sdlc 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,11 @@
-# Temporary Holding Version
+# Lighthouse SDLC
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+This package provides the provider-neutral delivery contract for Lighthouse adopters.
+
+It owns the six lifecycle skills, their command entrypoints, route and gate descriptors, control-plane schema and deterministic package check.
+
+It does not run agents, store transcripts, dispatch work between repositories or replace ProductShape, ArcShape, OpenSpec or an agent host.
+
+Install it with the Lighthouse CLI or run `lighthouse-sdlc verify` from the package installation to check the distributed contract.
+
+The package is a source of lifecycle instructions and contracts; an adopter's host adapter decides where provider-specific projections are installed.

package/commands/implement.md

@@ -0,0 +1,3 @@
+# `/lighthouse:implement`
+
+Run the `lighthouse-sdlc-implement` skill for one approved plan and stop at the `done` gate.

package/commands/integrate.md

@@ -0,0 +1,3 @@
+# `/lighthouse:integrate`
+
+Run the `lighthouse-sdlc-integrate` skill for one completed slice and prepare the configured merge action.

package/commands/propose.md

@@ -0,0 +1,3 @@
+# `/lighthouse:propose`
+
+Run the `lighthouse-sdlc-propose` skill for one Ready work item and stop at the `planned` gate.

package/commands/refine.md

@@ -0,0 +1,3 @@
+# `/lighthouse:refine`
+
+Run the `lighthouse-sdlc-refine` skill for one triaged work item and stop at the `ready` gate.

package/commands/review.md

@@ -0,0 +1,3 @@
+# `/lighthouse:review`
+
+Run the `lighthouse-sdlc-review` skill for one integrated change and finish with a review record.

package/commands/status.md

@@ -0,0 +1,5 @@
+# `/lighthouse:status`
+
+Read `.lighthouse/sdlc.json` and report the selected SDLC package, routes, gates, state provider, memory scopes, role mappings and adapter gaps.
+
+Read-only completion means the report matches the declared control plane and names the next supported action for every gap.

package/commands/triage.md

@@ -0,0 +1,3 @@
+# `/lighthouse:triage`
+
+Run the `lighthouse-sdlc-triage` skill for one work item and stop at the `triaged` gate.

package/contract.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "./schemas/sdlc-contract.schema.json",
+  "name": "@juangcarmona/lighthouse-sdlc",
+  "version": "0.1.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" },
+    { "name": "propose", "skill": "skills/propose/SKILL.md", "command": "commands/propose.md", "gate": "planned" },
+    { "name": "implement", "skill": "skills/implement/SKILL.md", "command": "commands/implement.md", "gate": "done" },
+    { "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"],
+  "routes": ["supervised", "plan-only", "unattended", "hotfix", "stacked"],
+  "metaCommands": ["ff", "hotfix", "decompose", "stacked"],
+  "gates": ["triaged", "ready", "planned", "done"],
+  "assets": {
+    "routes": "routes.json",
+    "gates": "gates.json",
+    "controlPlaneSchema": "schemas/control-plane.schema.json"
+  }
+}

package/gates.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "./schemas/gates.schema.json",
+  "version": 1,
+  "gates": [
+    { "id": "triaged", "stage": "triage", "question": "Is the work item understood enough to choose a route?", "decisionOwner": "adopter" },
+    { "id": "ready", "stage": "refine", "question": "Is the problem defined well enough to design a solution?", "decisionOwner": "adopter" },
+    { "id": "planned", "stage": "propose", "question": "Is the solution and its evidence plan ready to implement?", "decisionOwner": "adopter" },
+    { "id": "done", "stage": "implement", "question": "Does the change satisfy its deterministic and named judgement checks?", "decisionOwner": "adopter" }
+  ]
+}

package/meta-commands/decompose.md

@@ -0,0 +1,3 @@
+# `/lighthouse:decompose`
+
+Split a large work item into dependency-ordered slices with independent acceptance evidence and a parent record.

package/meta-commands/ff.md

@@ -0,0 +1,5 @@
+# `/lighthouse:ff`
+
+Compose the stages declared by a selected route only when its independent review, correction limit and durable evidence are available.
+
+Stop at every human-only or forge-protected decision and report the next stage instead of invoking it implicitly.

package/meta-commands/hotfix.md

@@ -0,0 +1,3 @@
+# `/lighthouse:hotfix`
+
+Use the `hotfix` route for a confirmed defect with a rollback plan, keeping triage, Done evidence, integration and review visible.

package/meta-commands/stacked.md

@@ -0,0 +1,3 @@
+# `/lighthouse:stacked`
+
+Prepare dependency-ordered changes as isolated pull requests and keep each slice within its declared scope.

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "type": "module",
+  "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juangcarmona/lighthouse.git",
+    "directory": "src/packages/sdlc"
+  },
+  "homepage": "https://juangcarmona.github.io/lighthouse/",
+  "bugs": {
+    "url": "https://github.com/juangcarmona/lighthouse/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "files": [
+    "commands",
+    "contract.json",
+    "gates.json",
+    "meta-commands",
+    "README.md",
+    "routes.json",
+    "schemas",
+    "skills",
+    "src"
+  ],
+  "bin": {
+    "lighthouse-sdlc": "./src/sdlc.mjs"
+  },
+  "exports": {
+    ".": "./src/sdlc.mjs",
+    "./contract.json": "./contract.json",
+    "./schemas/control-plane.schema.json": "./schemas/control-plane.schema.json"
+  }
+}

package/routes.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "./schemas/routes.schema.json",
+  "version": 1,
+  "routes": [
+    { "id": "supervised", "stages": ["triage", "refine", "propose", "implement", "integrate", "review"], "humanGates": ["triaged", "ready", "planned", "done"] },
+    { "id": "plan-only", "stages": ["triage", "refine", "propose"], "humanGates": ["triaged", "ready", "planned"] },
+    { "id": "unattended", "stages": ["triage", "refine", "propose", "implement", "integrate", "review"], "humanGates": ["triaged", "ready", "planned", "done"], "requires": ["bounded-agent-run", "independent-review"] },
+    { "id": "hotfix", "stages": ["triage", "implement", "integrate", "review"], "humanGates": ["triaged", "done"], "requires": ["confirmed-defect", "rollback-plan"] },
+    { "id": "stacked", "stages": ["triage", "refine", "propose", "implement", "integrate", "review"], "humanGates": ["triaged", "ready", "planned", "done"], "requires": ["dependency-order", "isolated-change-scope"] }
+  ]
+}

package/schemas/control-plane.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-sdlc-control-plane.schema.json",
+  "title": "Lighthouse SDLC control plane",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "package", "routes", "gates", "state", "memory", "roles", "adapters"],
+  "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+$" }
+      }
+    },
+    "routes": { "type": "array", "items": { "type": "string" } },
+    "gates": { "type": "array", "items": { "type": "string" } },
+    "state": { "type": "object", "additionalProperties": false, "required": ["provider"], "properties": { "provider": { "type": "string" } } },
+    "memory": { "type": "object", "additionalProperties": false, "required": ["provider", "scopes"], "properties": { "provider": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } },
+    "roles": { "type": "object", "additionalProperties": { "type": "string" } },
+    "adapters": { "type": "object", "additionalProperties": { "type": "string" } }
+  }
+}

package/schemas/gates.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/sdlc-gates.schema.json",
+  "title": "Lighthouse SDLC gates",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "version", "gates"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "gates": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/gate" } }
+  },
+  "$defs": {
+    "gate": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "stage", "question", "decisionOwner"],
+      "properties": {
+        "id": { "type": "string" },
+        "stage": { "type": "string" },
+        "question": { "type": "string" },
+        "decisionOwner": { "type": "string" }
+      }
+    }
+  }
+}

package/schemas/routes.schema.json

@@ -0,0 +1,26 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/sdlc-routes.schema.json",
+  "title": "Lighthouse SDLC routes",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "version", "routes"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "routes": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/route" } }
+  },
+  "$defs": {
+    "route": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "stages", "humanGates"],
+      "properties": {
+        "id": { "type": "string" },
+        "stages": { "type": "array", "minItems": 1, "items": { "type": "string" } },
+        "humanGates": { "type": "array", "items": { "type": "string" } },
+        "requires": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}

package/schemas/sdlc-contract.schema.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/sdlc-contract.schema.json",
+  "title": "Lighthouse SDLC package contract",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "name", "version", "stages", "utilities", "routes", "metaCommands", "gates", "assets"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "name": { "const": "@juangcarmona/lighthouse-sdlc" },
+    "version": { "type": "string", "pattern": "^\\d+\\.\\d+\\.\\d+$" },
+    "stages": { "type": "array", "minItems": 6, "items": { "$ref": "#/$defs/stage" } },
+    "utilities": { "type": "array", "items": { "type": "string" } },
+    "routes": { "type": "array", "items": { "type": "string" } },
+    "metaCommands": { "type": "array", "items": { "type": "string" } },
+    "gates": { "type": "array", "items": { "type": "string" } },
+    "assets": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["routes", "gates", "controlPlaneSchema"],
+      "properties": {
+        "routes": { "type": "string" },
+        "gates": { "type": "string" },
+        "controlPlaneSchema": { "type": "string" }
+      }
+    }
+  },
+  "$defs": {
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "skill", "command", "gate"],
+      "properties": {
+        "name": { "type": "string" },
+        "skill": { "type": "string" },
+        "command": { "type": "string" },
+        "gate": { "type": ["string", "null"] }
+      }
+    }
+  }
+}

package/skills/implement/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: lighthouse-sdlc-implement
+description: Use when a planned work item is approved for bounded implementation and needs red-green checks, evidence and Definition of Done verification.
+---
+
+# Implement
+
+Implement one planned slice at a time.
+
+## Steps
+
+1. Read the approved plan, slice boundary, allowed paths and Definition of Done.
+2. Start with the smallest failing deterministic check when the stack supports red-green development.
+3. Make the smallest change that turns the check green, then run the required unit, integration and applicable higher-level checks.
+4. Record changed paths, commands, results, evidence and any finding that needs a human decision.
+5. Stop at the `done` gate when the Definition of Done is satisfied.
+
+## Completion
+
+The slice has reviewable code and evidence for every required check, with no silent scope expansion or automatic transition to integration.

package/skills/integrate/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: lighthouse-sdlc-integrate
+description: Use when an implemented slice is ready for dependency checks, pull request coordination, tracker synchronization and merge preparation.
+---
+
+# Integrate
+
+Prepare a completed slice for the project's forge and branch policy.
+
+## Steps
+
+1. Recheck the Done evidence and the declared dependency order.
+2. Verify the branch, commit, pull request and required CI checks against project policy.
+3. Synchronize the work item and pull request state using the project's configured labels.
+4. Prepare the merge or stacked change action and leave protected or human decisions explicit.
+5. Return the integration record without merging unless the selected route and repository policy authorize it.
+
+## Completion
+
+The change is ready for its configured merge action, every required check is linked and unresolved decisions have an owner.

package/skills/propose/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: lighthouse-sdlc-propose
+description: Use when a ready work item needs a solution proposal, OpenSpec change artifacts, test impact and a human-readable change overview.
+---
+
+# Propose
+
+Describe the smallest implementable solution for a Ready item.
+
+## Steps
+
+1. Read the Ready evidence and inspect the current product and architecture authorities.
+2. Create or update the OpenSpec change artifacts through the installed OpenSpec workflow.
+3. Describe the solution, interfaces, data effects, test impact, slices, risks and Definition of Done.
+4. Write `change-overview` prose with the Humanizer skill while preserving facts, links, commands, frontmatter and code.
+5. Stop at the `planned` gate and state the human decision required before implementation.
+
+## Completion
+
+The change artifacts explain the future state, the slices are dependency ordered, the evidence plan is explicit and the Planned decision remains visible.

package/skills/refine/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: lighthouse-sdlc-refine
+description: Use when a triaged work item needs a precise problem, scope, acceptance criteria, dependencies and Definition of Ready.
+---
+
+# Refine
+
+Turn a triaged item into a problem that can be designed.
+
+## Steps
+
+1. Read the triage record, product context and relevant architecture evidence.
+2. State the problem, affected users, constraints, acceptance criteria and explicit out-of-scope work.
+3. Resolve or record dependencies, risks, assumptions and missing evidence.
+4. Check the Definition of Ready and return the evidence that supports each check.
+5. Stop at the `ready` gate and name the next decision.
+
+## Completion
+
+The work item has a bounded problem statement, testable acceptance criteria, resolved owners for open dependencies and a Ready decision.

package/skills/review/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: lighthouse-sdlc-review
+description: Use after integration to record delivery evidence, findings, follow-up work and process learning for one completed change.
+---
+
+# Review
+
+Close the delivery record and make the next improvement visible.
+
+## Steps
+
+1. Read the change overview, implementation evidence, integration result and review findings.
+2. Classify findings as accepted, deferred, fixed or rejected with an owner and follow-up reference.
+3. Record the evidence, outcome, useful learning and any product or architecture follow-up.
+4. Confirm the work item and pull request have the project's final labels.
+5. End the route with a review record and return the next backlog decision without opening another delivery gate.
+
+## Completion
+
+The completed change has a durable review record, classified findings and a clear follow-up owner.

package/skills/triage/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: lighthouse-sdlc-triage
+description: Use when a work item enters the Lighthouse lifecycle and needs urgency, impact, dependencies, risk, complexity, blast radius and a delivery route.
+---
+
+# Triage
+
+Classify one work item before refinement.
+
+## Steps
+
+1. Read the work item, its linked Product Change and the repository control plane.
+2. Inspect the affected code and architecture evidence with the available repository tools.
+3. Record urgency, impact, dependencies, risk, complexity, blast radius, route and owner with a confidence note for each estimate.
+4. Apply only the project's declared tracker labels and report the label changes.
+5. Return the structured triage record and stop at the `triaged` gate.
+
+## Completion
+
+The record names the route, owner, labels, estimates, confidence and next decision, and no later stage has started.

package/src/sdlc.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+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, 'contract.json');
+
+async function readJson(path) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+async function exists(path) {
+  try { await access(path, constants.F_OK); return true; } catch { return false; }
+}
+
+async function verifyContract() {
+  const problems = [];
+  let contract;
+  try { contract = await readJson(contractPath); }
+  catch (error) { return [`Cannot read contract.json: ${error.message}`]; }
+  if (contract.name !== '@juangcarmona/lighthouse-sdlc') problems.push('contract name is incorrect');
+  if (!/^\d+\.\d+\.\d+$/.test(contract.version ?? '')) problems.push('contract version must be semver-like');
+  const stages = Array.isArray(contract.stages) ? contract.stages : [];
+  const expectedStages = ['triage', 'refine', 'propose', 'implement', 'integrate', 'review'];
+  if (stages.map((stage) => stage.name).join(',') !== expectedStages.join(',')) problems.push('stages must be triage, refine, propose, implement, integrate, review in order');
+  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?.controlPlaneSchema]) {
+    if (!asset || !(await exists(resolve(packageRoot, asset)))) problems.push(`missing contract asset ${asset ?? '(empty)'}`);
+  }
+  for (const asset of ['routes.json', 'gates.json', 'schemas/routes.schema.json', 'schemas/gates.schema.json', 'schemas/control-plane.schema.json']) {
+    if (!(await exists(resolve(packageRoot, asset)))) problems.push(`missing package asset ${asset}`);
+  }
+  try {
+    const routes = await readJson(resolve(packageRoot, 'routes.json'));
+    const routeIds = routes.routes?.map((route) => route.id) ?? [];
+    if (routeIds.join(',') !== contract.routes.join(',')) problems.push('routes.json does not match contract routes');
+  } catch (error) { problems.push(`Cannot read routes.json: ${error.message}`); }
+  try {
+    const gates = await readJson(resolve(packageRoot, 'gates.json'));
+    const gateIds = gates.gates?.map((gate) => gate.id) ?? [];
+    if (gateIds.join(',') !== contract.gates.join(',')) problems.push('gates.json does not match contract gates');
+  } catch (error) { problems.push(`Cannot read gates.json: ${error.message}`); }
+  for (const command of ['status', ...expectedStages]) 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;
+}
+
+const command = process.argv[2] ?? 'verify';
+if (!['contract', 'verify'].includes(command)) {
+  console.error('Usage: lighthouse-sdlc <contract|verify>');
+  process.exit(2);
+}
+if (command === 'contract') {
+  console.log(await readFile(contractPath, 'utf8'));
+} else {
+  const problems = await verifyContract();
+  if (problems.length) {
+    for (const problem of problems) console.error(problem);
+    process.exit(1);
+  }
+  console.log('Lighthouse SDLC package contract is valid.');
+}
+
+export { contractPath, verifyContract };