@juangcarmona/lighthouse-sdlc 0.0.0-stage → 0.3.0

package/README.md

@@ -1,3 +1,15 @@
-# 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, the triage schema and verifier, the 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.
+
+Run `lighthouse-sdlc triage --input <file>` to validate one structured triage result and receive its proposed workflow and classification labels. The command is read-only by default; `--apply --labels-file <file>` writes only after the report is ready and the labels file still matches the input.
+
+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/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,9 @@
+# `/lighthouse:triage`
+
+Run the `lighthouse-sdlc-triage` skill for one work item and stop at the `triaged` gate.
+
+The structured result records `size`, `urgency`, `impact`, `risk`, `blast-radius`, dependencies, route, owner, confidence and evidence, then proposes workflow and classification labels from the project's configuration.
+
+Use `lighthouse-sdlc triage --input <file>` for deterministic validation. The command is read-only unless an explicit `--apply --labels-file <file>` request is supplied.
+
+Represent evidence with `status: provided`, `status: unavailable` or `status: pending-review`; omit the item when evidence is absent. The report keeps those cases in `missingEvidence`, `unavailableChecks` and `pendingReview` respectively.

package/contract.json

@@ -0,0 +1,23 @@
+{
+  "$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",
+    "triageSchema": "schemas/triage.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,43 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.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",
+    "./triage": "./src/triage.mjs",
+    "./contract.json": "./contract.json",
+    "./schemas/control-plane.schema.json": "./schemas/control-plane.schema.json",
+    "./schemas/triage.schema.json": "./schemas/triage.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,42 @@
+{
+  "$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", "triageSchema"],
+      "properties": {
+        "routes": { "type": "string" },
+        "gates": { "type": "string" },
+        "controlPlaneSchema": { "type": "string" },
+        "triageSchema": { "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/schemas/triage.schema.json

@@ -0,0 +1,62 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-sdlc-triage.schema.json",
+  "title": "Lighthouse triage input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "workItem", "currentLabels", "assessment", "configuration"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "workItem": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "title"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "minLength": 1 }
+      }
+    },
+    "currentLabels": { "type": "array", "items": { "type": "string" } },
+    "assessment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["size", "urgency", "impact", "risk", "blastRadius", "dependencies", "route", "nextState", "owner", "confidence", "evidence"],
+      "properties": {
+        "size": { "enum": ["S", "M", "L", "XL"] },
+        "urgency": { "enum": ["normal", "asap", "now"] },
+        "impact": { "enum": ["low", "medium", "high"] },
+        "risk": { "enum": ["low", "medium", "high"] },
+        "blastRadius": { "enum": ["low", "medium", "high", "unknown"] },
+        "dependencies": { "type": "array" },
+        "route": { "enum": ["supervised", "plan-only", "unattended", "hotfix", "stacked"] },
+        "nextState": { "type": "string", "minLength": 1 },
+        "owner": { "type": "string", "minLength": 1 },
+        "confidence": { "type": "object" },
+        "evidence": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["field"],
+            "properties": {
+              "field": { "enum": ["size", "urgency", "impact", "risk", "blast-radius"] },
+              "status": { "enum": ["provided", "unavailable", "pending-review"] },
+              "source": { "type": "string", "minLength": 1 },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "configuration": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["labels", "transitions"],
+      "properties": {
+        "labels": { "type": "array" },
+        "transitions": { "type": "array" }
+      }
+    }
+  }
+}

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,21 @@
+---
+name: lighthouse-sdlc-triage
+description: Use when a work item enters the Lighthouse lifecycle and needs size, urgency, impact, dependencies, risk, 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 size, urgency, impact, dependencies, risk, blast radius, route and owner with confidence and evidence for each assessment.
+4. Mark each evidence field as provided, unavailable or pending-review; leave absent fields without an evidence item.
+5. Propose only the project's declared workflow and classification labels and report the transition.
+6. Return the structured triage record and stop at the `triaged` gate.
+
+## Completion
+
+The record names the route, owner, labels, assessments, confidence, evidence and next decision, and no later stage has started.

package/src/sdlc.mjs

@@ -0,0 +1,126 @@
+#!/usr/bin/env node
+import { access, readFile, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyTriageLabels, buildTriageReport } from './triage.mjs';
+
+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, contract.assets?.triageSchema]) {
+    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', 'schemas/triage.schema.json', 'src/triage.mjs']) {
+    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;
+}
+
+function option(args, name) {
+  const index = args.indexOf(name);
+  if (index !== -1) return args[index + 1];
+  const prefix = `${name}=`;
+  return args.find((arg) => arg.startsWith(prefix))?.slice(prefix.length);
+}
+
+function triageText(report) {
+  const lines = [
+    `Triage: ${report.status}`,
+    `Work item: ${report.workItem?.id ?? '(unknown)'} — ${report.workItem?.title ?? '(untitled)'}`,
+    `Size: ${report.assessment.size}`,
+    `Urgency: ${report.assessment.urgency}`,
+    `Impact: ${report.assessment.impact}`,
+    `Risk: ${report.assessment.risk}`,
+    `Blast radius: ${report.assessment.blastRadius}`,
+    `Route: ${report.assessment.route ?? '(unknown)'}`,
+    `Transition: ${report.transition.from ?? '(unknown)'} -> ${report.transition.to ?? '(unknown)'}`,
+    `Labels: ${report.labels.proposed.join(', ') || '(none)'}`,
+  ];
+  if (report.missingEvidence.length) lines.push(`Missing evidence: ${report.missingEvidence.join(', ')}`);
+  if (report.unavailableChecks.length) lines.push(`Unavailable checks: ${report.unavailableChecks.join(', ')}`);
+  if (report.pendingReview.length) lines.push(`Pending review: ${report.pendingReview.join(', ')}`);
+  for (const error of report.errors) lines.push(`Error: ${error.message}`);
+  lines.push(report.applied ? 'Applied: yes' : 'Applied: no (read-only)');
+  return `${lines.join('\n')}\n`;
+}
+
+async function runTriage(args) {
+  const inputPath = option(args, '--input');
+  const configPath = option(args, '--config');
+  const labelsPath = option(args, '--labels-file');
+  const format = option(args, '--format') ?? 'text';
+  const apply = args.includes('--apply');
+  if (!inputPath || !['text', 'json'].includes(format) || (apply && !labelsPath)) {
+    console.error('Usage: lighthouse-sdlc triage --input <file> [--config <file>] [--format <text|json>] [--apply --labels-file <file>]');
+    process.exit(2);
+  }
+  const input = await readJson(resolve(process.cwd(), inputPath));
+  if (configPath) input.configuration = await readJson(resolve(process.cwd(), configPath));
+  const report = buildTriageReport(input);
+  report.applied = false;
+  if (apply && report.canApply) {
+    const labelsFile = resolve(process.cwd(), labelsPath);
+    const current = await readJson(labelsFile);
+    const expected = JSON.stringify(report.labels.current);
+    if (!Array.isArray(current) || JSON.stringify([...new Set(current)].sort()) !== expected) throw new Error('labels file does not match currentLabels; refusing to apply the triage projection');
+    await writeFile(labelsFile, `${JSON.stringify(applyTriageLabels(report), null, 2)}\n`);
+    report.applied = true;
+  }
+  if (format === 'json') console.log(JSON.stringify(report, null, 2));
+  else process.stdout.write(triageText(report));
+  if (report.status !== 'ready') process.exit(1);
+}
+
+const command = process.argv[2] ?? 'verify';
+if (!['contract', 'verify', 'triage'].includes(command)) {
+  console.error('Usage: lighthouse-sdlc <contract|verify|triage>');
+  process.exit(2);
+}
+if (command === 'contract') {
+  console.log(await readFile(contractPath, 'utf8'));
+} else if (command === 'triage') {
+  await runTriage(process.argv.slice(3));
+} 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, runTriage, verifyContract };

package/src/triage.mjs

@@ -0,0 +1,284 @@
+const DIMENSIONS = Object.freeze({
+  size: ['S', 'M', 'L', 'XL'],
+  urgency: ['normal', 'asap', 'now'],
+  impact: ['low', 'medium', 'high'],
+  risk: ['low', 'medium', 'high'],
+  'blast-radius': ['low', 'medium', 'high'],
+});
+
+const CONFIDENCE = new Set(['low', 'medium', 'high']);
+const ROLES = new Set(['state', 'command', 'classification']);
+const ROUTES = new Set(['supervised', 'plan-only', 'unattended', 'hotfix', 'stacked']);
+const DEPENDENCY_STATES = new Set(['resolved', 'open', 'unknown']);
+const EVIDENCE_STATES = new Set(['provided', 'unavailable', 'pending-review']);
+const HEX = /^[0-9a-f]{6}$/iu;
+const EVIDENCE_FIELDS = ['size', 'urgency', 'impact', 'risk', 'blast-radius'];
+
+export const suggestedLabelColors = Object.freeze({
+  'size-s': 'BFE3FF',
+  'size-m': '80C2FF',
+  'size-l': '4DA3FF',
+  'size-xl': '1F6FEB',
+  'urgency-normal': '8B949E',
+  'urgency-asap': 'D29922',
+  'urgency-now': 'CF222E',
+  'impact-low': 'E9D5FF',
+  'impact-medium': 'A371F7',
+  'impact-high': '6E40C9',
+  'risk-low': 'FFEBE9',
+  'risk-medium': 'F0883E',
+  'risk-high': 'CF222E',
+  'blast-radius-low': 'C7F0E8',
+  'blast-radius-medium': '4FB3A4',
+  'blast-radius-high': '0F766E',
+});
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizedValue(dimension, value) {
+  if (dimension === 'size') return String(value ?? '').toUpperCase();
+  return String(value ?? '').toLowerCase();
+}
+
+function labelFor(dimension, value) {
+  return `${dimension}-${normalizedValue(dimension, value).toLowerCase()}`;
+}
+
+function issue(code, message, field) {
+  return field ? { code, field, message } : { code, message };
+}
+
+function addIssue(issues, code, message, field) {
+  issues.push(issue(code, message, field));
+}
+
+function validateConfiguration(configuration) {
+  const errors = [];
+  const labels = Array.isArray(configuration?.labels) ? configuration.labels : null;
+  const byName = new Map();
+  const classifications = new Map();
+  const stateLabels = new Set();
+  const commandLabels = new Set();
+
+  if (!labels) addIssue(errors, 'configuration.labels', 'configuration.labels must be an array', 'configuration.labels');
+  for (const descriptor of labels ?? []) {
+    if (!isRecord(descriptor) || typeof descriptor.name !== 'string' || !descriptor.name.trim()) {
+      addIssue(errors, 'label.invalid', 'every label descriptor needs a non-empty name', 'configuration.labels');
+      continue;
+    }
+    const name = descriptor.name.trim();
+    if (byName.has(name)) addIssue(errors, 'label.duplicate', `label ${name} is declared more than once`, 'configuration.labels');
+    byName.set(name, descriptor);
+    if (!ROLES.has(descriptor.role)) {
+      addIssue(errors, 'label.role', `label ${name} must use role state, command or classification`, 'configuration.labels');
+      continue;
+    }
+    if (descriptor.role === 'state') stateLabels.add(name);
+    if (descriptor.role === 'command') commandLabels.add(name);
+    if (descriptor.role !== 'classification') continue;
+    const dimension = String(descriptor.dimension ?? '').toLowerCase();
+    const value = normalizedValue(dimension, descriptor.value);
+    if (!Object.hasOwn(DIMENSIONS, dimension) || !DIMENSIONS[dimension].includes(value)) {
+      addIssue(errors, 'label.classification', `label ${name} has an invalid classification dimension or value`, 'configuration.labels');
+      continue;
+    }
+    if (labelFor(dimension, value) !== name) {
+      addIssue(errors, 'label.syntax', `classification label ${name} must use the ${labelFor(dimension, value)} syntax`, 'configuration.labels');
+    }
+    const key = `${dimension}:${value}`;
+    if (classifications.has(key)) addIssue(errors, 'label.classification-duplicate', `classification ${key} is declared more than once`, 'configuration.labels');
+    classifications.set(key, name);
+    if (descriptor.color !== undefined && (typeof descriptor.color !== 'string' || !HEX.test(descriptor.color))) {
+      addIssue(errors, 'label.color', `classification label ${name} color must be six hexadecimal characters`, 'configuration.labels');
+    }
+  }
+
+  const transitions = Array.isArray(configuration?.transitions) ? configuration.transitions : [];
+  const transitionSet = new Set();
+  for (const transition of transitions) {
+    if (!isRecord(transition) || typeof transition.from !== 'string' || typeof transition.to !== 'string') {
+      addIssue(errors, 'transition.invalid', 'every transition needs from and to labels', 'configuration.transitions');
+      continue;
+    }
+    const key = `${transition.from}->${transition.to}`;
+    if (transitionSet.has(key)) addIssue(errors, 'transition.duplicate', `transition ${key} is declared more than once`, 'configuration.transitions');
+    transitionSet.add(key);
+  }
+
+  return { errors, byName, classifications, stateLabels, commandLabels, transitionSet };
+}
+
+function validateWorkItem(workItem, errors) {
+  if (!isRecord(workItem)) {
+    addIssue(errors, 'work-item.invalid', 'workItem must be an object', 'workItem');
+    return;
+  }
+  for (const field of ['id', 'title']) {
+    if (typeof workItem[field] !== 'string' || !workItem[field].trim()) addIssue(errors, `work-item.${field}`, `workItem.${field} must be a non-empty string`, `workItem.${field}`);
+  }
+  if (workItem.type !== undefined && (typeof workItem.type !== 'string' || !workItem.type.trim())) addIssue(errors, 'work-item.type', 'workItem.type must be a non-empty string when provided', 'workItem.type');
+}
+
+function validateAssessment(assessment, errors) {
+  if (!isRecord(assessment)) {
+    addIssue(errors, 'assessment.invalid', 'assessment must be an object', 'assessment');
+    return;
+  }
+  for (const dimension of Object.keys(DIMENSIONS)) {
+    const value = normalizedValue(dimension, assessment[dimension === 'blast-radius' ? 'blastRadius' : dimension]);
+    if (!DIMENSIONS[dimension].includes(value) && !(dimension === 'blast-radius' && value === 'unknown')) {
+      addIssue(errors, `assessment.${dimension}`, `${dimension} has an unsupported value`, `assessment.${dimension}`);
+    }
+  }
+  if (!ROUTES.has(assessment.route)) addIssue(errors, 'assessment.route', `route must be one of ${[...ROUTES].join(', ')}`, 'assessment.route');
+  if (typeof assessment.nextState !== 'string' || !assessment.nextState.trim()) addIssue(errors, 'assessment.next-state', 'nextState must be a non-empty string', 'assessment.nextState');
+  if (typeof assessment.owner !== 'string' || !assessment.owner.trim()) addIssue(errors, 'assessment.owner', 'owner must be a non-empty string', 'assessment.owner');
+  if (!isRecord(assessment.confidence)) {
+    addIssue(errors, 'assessment.confidence', 'confidence must be an object with one value per triage dimension', 'assessment.confidence');
+  } else {
+    for (const dimension of EVIDENCE_FIELDS) if (!CONFIDENCE.has(assessment.confidence[dimension])) addIssue(errors, `assessment.confidence.${dimension}`, `${dimension} confidence must be low, medium or high`, `assessment.confidence.${dimension}`);
+  }
+  if (!Array.isArray(assessment.dependencies)) {
+    addIssue(errors, 'assessment.dependencies', 'dependencies must be an array', 'assessment.dependencies');
+  } else {
+    for (const dependency of assessment.dependencies) {
+      if (!isRecord(dependency) || typeof dependency.id !== 'string' || !DEPENDENCY_STATES.has(dependency.status)) addIssue(errors, 'assessment.dependency', 'each dependency needs an id and a resolved, open or unknown status', 'assessment.dependencies');
+    }
+  }
+  if (!Array.isArray(assessment.evidence)) {
+    addIssue(errors, 'assessment.evidence', 'evidence must be an array', 'assessment.evidence');
+  } else {
+    const fields = new Set();
+    for (const evidence of assessment.evidence) {
+      const status = evidence?.status ?? 'provided';
+      const valid = isRecord(evidence) && EVIDENCE_FIELDS.includes(evidence.field) && EVIDENCE_STATES.has(status);
+      if (!valid) {
+        addIssue(errors, 'assessment.evidence-item', 'each evidence item needs a known field and a provided, unavailable or pending-review status', 'assessment.evidence');
+        continue;
+      }
+      if (fields.has(evidence.field)) addIssue(errors, 'assessment.evidence-duplicate', `${evidence.field} has more than one evidence status`, 'assessment.evidence');
+      fields.add(evidence.field);
+      if (status === 'provided' && (typeof evidence.source !== 'string' || !evidence.source.trim())) addIssue(errors, 'assessment.evidence-source', 'provided evidence needs a non-empty source', 'assessment.evidence');
+      if (status !== 'provided' && (typeof evidence.reason !== 'string' || !evidence.reason.trim())) addIssue(errors, 'assessment.evidence-reason', `${status} evidence needs a non-empty reason`, 'assessment.evidence');
+    }
+  }
+}
+
+function currentState(labels, configuration) {
+  const states = labels.filter((label) => configuration.stateLabels.has(label));
+  return { states, value: states.length === 1 ? states[0] : null };
+}
+
+function classificationState(labels, configuration) {
+  const byDimension = new Map();
+  for (const label of labels) {
+    const descriptor = configuration.byName.get(label);
+    if (!descriptor || descriptor.role !== 'classification') continue;
+    const list = byDimension.get(descriptor.dimension) ?? [];
+    list.push(label);
+    byDimension.set(descriptor.dimension, list);
+  }
+  return byDimension;
+}
+
+function proposedLabels(currentLabels, assessment, configuration) {
+  const result = new Set(currentLabels.filter((label) => {
+    const descriptor = configuration.byName.get(label);
+    return !descriptor || (descriptor.role !== 'state' && descriptor.role !== 'classification' && descriptor.role !== 'command');
+  }));
+  for (const label of configuration.stateLabels) if (currentLabels.includes(label)) result.add(label);
+  for (const label of configuration.commandLabels) if (currentLabels.includes(label)) result.delete(label);
+  const state = currentState(currentLabels, configuration).value;
+  if (state) result.delete(state);
+  if (assessment.nextState) result.add(assessment.nextState);
+  for (const dimension of Object.keys(DIMENSIONS)) {
+    const key = dimension === 'blast-radius' ? 'blastRadius' : dimension;
+    const value = normalizedValue(dimension, assessment[key]);
+    for (const label of configuration.classifications.values()) {
+      const descriptor = configuration.byName.get(label);
+      if (descriptor?.dimension === dimension) result.delete(label);
+    }
+    if (value !== 'UNKNOWN') {
+      const label = configuration.classifications.get(`${dimension}:${value}`);
+      if (label) result.add(label);
+    }
+  }
+  return [...result].sort((a, b) => a.localeCompare(b));
+}
+
+export function buildTriageReport(input) {
+  const errors = [];
+  if (!isRecord(input)) return { schemaVersion: 1, status: 'invalid', valid: false, canApply: false, errors: [issue('input.invalid', 'triage input must be an object')], warnings: [], missingEvidence: [], unavailableChecks: [], pendingReview: [], labels: { current: [], proposed: [] } };
+  if (input.schemaVersion !== 1) addIssue(errors, 'input.schema-version', 'schemaVersion must be 1', 'schemaVersion');
+  const configuration = validateConfiguration(input.configuration);
+  errors.push(...configuration.errors);
+  const currentLabels = Array.isArray(input.currentLabels) ? [...new Set(input.currentLabels.filter((label) => typeof label === 'string'))].sort() : [];
+  if (!Array.isArray(input.currentLabels)) addIssue(errors, 'labels.invalid', 'currentLabels must be an array', 'currentLabels');
+  validateWorkItem(input.workItem, errors);
+  validateAssessment(input.assessment, errors);
+
+  const state = currentState(currentLabels, configuration);
+  if (state.states.length > 1) addIssue(errors, 'state.ambiguous', `work item has multiple workflow state labels: ${state.states.join(', ')}`, 'currentLabels');
+  if (state.states.length === 0) addIssue(errors, 'state.missing', 'work item needs one configured workflow state label', 'currentLabels');
+  const assessment = isRecord(input.assessment) ? input.assessment : {};
+  if (state.value && typeof assessment.nextState === 'string' && configuration.stateLabels.has(assessment.nextState)) {
+    if (state.value !== assessment.nextState && !configuration.transitionSet.has(`${state.value}->${assessment.nextState}`)) addIssue(errors, 'transition.illegal', `transition ${state.value}->${assessment.nextState} is not configured`, 'assessment.nextState');
+  } else if (typeof assessment.nextState === 'string' && assessment.nextState && !configuration.stateLabels.has(assessment.nextState)) {
+    addIssue(errors, 'transition.unconfigured', `next state ${assessment.nextState} is not configured`, 'assessment.nextState');
+  }
+  const currentClassifications = classificationState(currentLabels, configuration);
+  for (const [dimension, values] of currentClassifications) if (values.length > 1) addIssue(errors, 'classification.ambiguous', `work item has multiple ${dimension} classification labels: ${values.join(', ')}`, 'currentLabels');
+  for (const dimension of Object.keys(DIMENSIONS)) {
+    const value = normalizedValue(dimension, assessment[dimension === 'blast-radius' ? 'blastRadius' : dimension]);
+    if (value !== 'UNKNOWN' && configuration.classifications.has(`${dimension}:${value}`) === false) addIssue(errors, 'classification.unconfigured', `${labelFor(dimension, value)} is not configured`, `assessment.${dimension}`);
+  }
+
+  const evidence = Array.isArray(assessment.evidence) ? assessment.evidence : [];
+  const evidenceFields = new Set(evidence.filter(isRecord).map((item) => item.field));
+  const missingEvidence = EVIDENCE_FIELDS.filter((field) => !evidenceFields.has(field));
+  const unavailableChecks = evidence.filter((item) => isRecord(item) && item.status === 'unavailable').map((item) => item.field);
+  const pendingReview = evidence.filter((item) => isRecord(item) && item.status === 'pending-review').map((item) => item.field);
+  const warnings = [
+    ...missingEvidence.map((field) => issue('evidence.missing', `${field} has no evidence record`, field)),
+    ...unavailableChecks.map((field) => issue('evidence.unavailable', `${field} could not be checked`, field)),
+    ...pendingReview.map((field) => issue('evidence.pending-review', `${field} is waiting for judgement`, field)),
+  ];
+  const proposed = proposedLabels(currentLabels, assessment, configuration);
+  const status = errors.length ? 'invalid' : warnings.length ? 'blocked' : 'ready';
+  return {
+    schemaVersion: 1,
+    status,
+    valid: errors.length === 0,
+    canApply: status === 'ready',
+    workItem: input.workItem ?? null,
+    assessment: {
+      size: normalizedValue('size', assessment.size),
+      urgency: normalizedValue('urgency', assessment.urgency),
+      impact: normalizedValue('impact', assessment.impact),
+      risk: normalizedValue('risk', assessment.risk),
+      blastRadius: normalizedValue('blast-radius', assessment.blastRadius),
+      dependencies: assessment.dependencies ?? [],
+      route: assessment.route ?? null,
+      owner: assessment.owner ?? null,
+      confidence: assessment.confidence ?? {},
+      evidence,
+    },
+    transition: { from: state.value, to: assessment.nextState ?? null },
+    labels: { current: currentLabels, proposed },
+    missingEvidence,
+    unavailableChecks,
+    pendingReview,
+    suggestedColors: suggestedLabelColors,
+    errors,
+    warnings,
+  };
+}
+
+export function applyTriageLabels(report) {
+  if (!report?.canApply) throw new Error('Triage report is not ready to apply. Resolve its errors or outstanding evidence state first.');
+  return [...report.labels.proposed];
+}
+
+export { DIMENSIONS, ROUTES, validateConfiguration };