@juangcarmona/lighthouse-sdlc 0.3.0 → 0.5.0

package/README.md

@@ -2,7 +2,7 @@
 
 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 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 does not run agents, store transcripts, dispatch work between repositories or replace ProductShape, ArcShape, OpenSpec or an agent host.
 
@@ -10,6 +10,22 @@ Install it with the Lighthouse CLI or run `lighthouse-sdlc verify` from the pack
 
 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.
 
+Use `lighthouse-sdlc route --route <name>` to inspect a route before running it, `stage-result --input <file>` to validate a stage result, `state --input <events.json>` to replay workflow events, `control-plane --input <file>` to validate host declarations, `decompose --input <file>` to produce a dependency-checked slice plan and `stacked --input <file>` to produce an ordered pull-request plan.
+
+Use `lighthouse-sdlc github-triage --repo <owner/repo> --issue <number> --assessment <file>` for the first GitHub projection. It reads issue metadata by default; `--apply` is the explicit label mutation boundary and rereads the issue before writing.
+
+Use `lighthouse-sdlc github-decompose --repo <owner/repo> --issue <number> --input <file>` to turn a validated slice plan into child-issue operations. The default is a preview; `--apply` creates the child issues in dependency order with the parent link and acceptance evidence in each body.
+
+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/commands/control-plane.md

@@ -0,0 +1,3 @@
+# `/lighthouse:control-plane`
+
+Validate the repository-owned control-plane declaration for package ownership, routes, state, memory scopes, roles, tools and adapters.

package/commands/decompose.md

@@ -0,0 +1,3 @@
+# `/lighthouse:decompose`
+
+Produce a read-only dependency-ordered slice plan. Apply it only after parent identity, independent acceptance evidence, dependencies and cycle checks pass.

package/commands/github-decompose.md

@@ -0,0 +1,3 @@
+# `/lighthouse:github-decompose`
+
+Project an accepted dependency-ordered slice plan into GitHub child issues. Preview first and use `--apply` only after the parent and slices have been reviewed.

package/commands/github-labels.md

@@ -0,0 +1,3 @@
+# Reconcile GitHub labels
+
+Run `lighthouse-sdlc github-labels --repo <owner/repo> --input .lighthouse/capabilities.json` to preview the repository label plan. Add `--apply` only after reviewing it; the command creates missing labels, preserves existing labels and writes reconciliation evidence.

package/commands/github-triage.md

@@ -0,0 +1,3 @@
+# `/lighthouse:github-triage`
+
+Read one GitHub issue into the provider-neutral triage contract. Keep the operation read-only unless the adopter explicitly requests a validated label projection.

package/commands/launch.md

@@ -0,0 +1,3 @@
+# `/lighthouse:launch`
+
+Validate a bounded parent or child agent launch request against the declared role, tools, write scope, output schema, limits and stop conditions without executing an agent.

package/commands/memory.md

@@ -0,0 +1,3 @@
+# `/lighthouse:memory`
+
+Validate one typed memory record against its declared scope without storing it or making it a product, architecture or approval authority.

package/commands/reconcile-labels.md

@@ -0,0 +1,3 @@
+# Reconcile labels
+
+Run `lighthouse-sdlc reconcile-labels --input .lighthouse/capabilities.json --existing labels.json` to preview the label capability plan. Add `--apply` only after reviewing it; the command adds missing labels to the local fixture, preserves existing values and writes reconciliation evidence.

package/commands/route.md

@@ -0,0 +1,3 @@
+# `/lighthouse:route`
+
+Inspect a named delivery route, its ordered stages, prerequisites, human gates and next decision before allowing a mutation.

package/commands/stacked.md

@@ -0,0 +1,3 @@
+# `/lighthouse:stacked`
+
+Produce a dependency-ordered pull-request plan with isolated branches and explicit base changes. Apply only after the slice plan is accepted.

package/commands/stage-result.md

@@ -0,0 +1,3 @@
+# `/lighthouse:stage-result`
+
+Validate the structured result of a lifecycle stage before a route consumes its evidence or advances its gate.

package/commands/state.md

@@ -0,0 +1,3 @@
+# `/lighthouse:state`
+
+Replay append-only workflow events and report the current state for each run. Reject illegal transitions and duplicate event identifiers.

package/contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "./schemas/sdlc-contract.schema.json",
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.1.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" },
@@ -10,14 +10,21 @@
     { "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"],
+  "utilities": ["status", "route", "state", "stage-result", "control-plane", "memory", "launch", "decompose", "stacked", "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"],
   "assets": {
     "routes": "routes.json",
     "gates": "gates.json",
+    "stages": "stages.json",
     "controlPlaneSchema": "schemas/control-plane.schema.json",
-    "triageSchema": "schemas/triage.schema.json"
+    "triageSchema": "schemas/triage.schema.json",
+    "stageResultSchema": "schemas/stage-result.schema.json",
+    "stateSchema": "schemas/workflow-state.schema.json",
+    "decompositionSchema": "schemas/decomposition.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.3.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -22,10 +22,12 @@
   "files": [
     "commands",
     "contract.json",
+    "capabilities.json",
     "gates.json",
     "meta-commands",
     "README.md",
     "routes.json",
+    "stages.json",
     "schemas",
     "skills",
     "src"
@@ -36,8 +38,25 @@
   "exports": {
     ".": "./src/sdlc.mjs",
     "./triage": "./src/triage.mjs",
+    "./contracts": "./src/contracts.mjs",
+    "./control-plane": "./src/control-plane.mjs",
+    "./decompose": "./src/decompose.mjs",
+    "./github": "./src/github.mjs",
+    "./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",
     "./schemas/control-plane.schema.json": "./schemas/control-plane.schema.json",
-    "./schemas/triage.schema.json": "./schemas/triage.schema.json"
+    "./schemas/triage.schema.json": "./schemas/triage.schema.json",
+    "./schemas/stages.schema.json": "./schemas/stages.schema.json",
+    "./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/capability-catalog.schema.json": "./schemas/capability-catalog.schema.json",
+    "./capabilities.json": "./capabilities.json"
   }
 }

package/schemas/capabilities.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-capabilities.schema.json",
+  "title": "Lighthouse capability declaration",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "capabilities"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "schemaVersion": { "const": 1 },
+    "capabilities": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "provider", "version"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "provider": { "type": "string", "minLength": 1 },
+          "version": { "type": "string", "minLength": 1 },
+          "configuration": { "type": "object" }
+        }
+      }
+    }
+  }
+}

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/schemas/control-plane.schema.json

@@ -19,9 +19,24 @@
     },
     "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" } },
+    "state": { "type": "object", "additionalProperties": false, "required": ["provider"], "properties": { "provider": { "type": "string" }, "states": { "type": "array", "items": { "enum": ["ready", "running", "waiting-human", "blocked", "succeeded", "failed", "cancelled"] } } } },
+    "memory": { "type": "object", "additionalProperties": false, "required": ["provider", "scopes"], "properties": { "provider": { "type": "string" }, "scopes": { "type": "array", "items": { "enum": ["run", "project", "shared"] } }, "shared": { "type": "boolean" } } },
+    "roles": { "type": "object", "additionalProperties": { "anyOf": [{ "type": "string" }, { "$ref": "#/$defs/role" }] } },
     "adapters": { "type": "object", "additionalProperties": { "type": "string" } }
+  },
+  "$defs": {
+    "role": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["inputSchema", "outputSchema", "tools", "writeScope"],
+      "properties": {
+        "inputSchema": { "type": "string" },
+        "outputSchema": { "type": "string" },
+        "tools": { "type": "array", "items": { "type": "string" } },
+        "writeScope": { "type": "array", "items": { "type": "string" } },
+        "limits": { "type": "object" },
+        "stopConditions": { "type": "array", "items": { "type": "string" } }
+      }
+    }
   }
 }

package/schemas/decomposition.schema.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-decomposition.schema.json",
+  "title": "Lighthouse decomposition input",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "parent", "slices"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "parent": { "type": "object", "required": ["id", "title"], "properties": { "id": { "type": "string" }, "title": { "type": "string" } }, "additionalProperties": true },
+    "slices": { "type": "array", "minItems": 1, "items": { "type": "object", "required": ["id", "title", "acceptance", "dependencies"], "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "acceptance": { "type": "array", "items": { "type": "string" } }, "dependencies": { "type": "array", "items": { "type": "string" } }, "scope": { "type": "array", "items": { "type": "string" } }, "labels": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": true } }
+  }
+}

package/schemas/sdlc-contract.schema.json

@@ -17,12 +17,17 @@
     "assets": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["routes", "gates", "controlPlaneSchema", "triageSchema"],
+      "required": ["routes", "gates", "stages", "controlPlaneSchema", "triageSchema", "stageResultSchema", "stateSchema", "decompositionSchema", "capabilitiesSchema"],
       "properties": {
         "routes": { "type": "string" },
         "gates": { "type": "string" },
+        "stages": { "type": "string" },
         "controlPlaneSchema": { "type": "string" },
-        "triageSchema": { "type": "string" }
+        "triageSchema": { "type": "string" },
+        "stageResultSchema": { "type": "string" },
+        "stateSchema": { "type": "string" },
+        "decompositionSchema": { "type": "string" },
+        "capabilitiesSchema": { "type": "string" }
       }
     }
   },

package/schemas/stage-result.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-stage-result.schema.json",
+  "title": "Lighthouse SDLC stage result",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "runId", "stage", "status", "gate", "evidence", "missingEvidence", "unavailableChecks", "pendingReview", "nextAction"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "stage": { "enum": ["triage", "refine", "propose", "implement", "integrate", "review"] },
+    "status": { "enum": ["ready", "blocked", "failed", "passed"] },
+    "gate": { "type": ["string", "null"] },
+    "input": { "type": "object" },
+    "output": { "type": "object" },
+    "evidence": { "type": "array", "items": { "type": "object", "required": ["id", "status"], "properties": { "id": { "type": "string" }, "status": { "enum": ["passed", "failed", "unavailable", "unconfigured", "pending-review", "not-applicable"] }, "source": { "type": "string" }, "reason": { "type": "string" } }, "additionalProperties": false } },
+    "missingEvidence": { "type": "array", "items": { "type": "string" } },
+    "unavailableChecks": { "type": "array", "items": { "type": "string" } },
+    "pendingReview": { "type": "array", "items": { "type": "string" } },
+    "nextAction": { "type": "string", "minLength": 1 }
+  }
+}

package/schemas/stages.schema.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/sdlc-stages.schema.json",
+  "title": "Lighthouse SDLC stages",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["$schema", "version", "stages"],
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "const": 1 },
+    "stages": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/stage" } }
+  },
+  "$defs": {
+    "stage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "gate", "input", "output", "mutation"],
+      "properties": {
+        "id": { "type": "string" },
+        "gate": { "type": ["string", "null"] },
+        "input": { "type": "string" },
+        "output": { "type": "string" },
+        "mutation": { "enum": ["none", "explicit", "workspace"] }
+      }
+    }
+  }
+}

package/schemas/workflow-state.schema.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-workflow-state.schema.json",
+  "title": "Lighthouse workflow state event",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "eventId", "runId", "route", "stage", "from", "to", "actor", "timestamp", "reason", "evidence"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "eventId": { "type": "string", "minLength": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "parentRunId": { "type": "string" },
+    "route": { "type": "string", "minLength": 1 },
+    "stage": { "type": "string", "minLength": 1 },
+    "from": { "type": ["string", "null"] },
+    "to": { "type": "string", "enum": ["ready", "running", "waiting-human", "blocked", "succeeded", "failed", "cancelled"] },
+    "actor": { "type": "string", "minLength": 1 },
+    "timestamp": { "type": "string", "minLength": 1 },
+    "reason": { "type": "string", "minLength": 1 },
+    "evidence": { "type": "array" }
+  }
+}

package/skills/implement/SKILL.md

@@ -13,8 +13,8 @@ Implement one planned slice at a time.
 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.
+5. Return a stage result with `stage: implement`, `gate: done`, implementation evidence as output and separate `missingEvidence`, `unavailableChecks` and `pendingReview` arrays; stop at `done` 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.
+The slice has reviewable code and a valid `done` stage result for every required check, with no silent scope expansion or automatic transition to integration.

package/skills/integrate/SKILL.md

@@ -13,8 +13,8 @@ Prepare a completed slice for the project's forge and branch policy.
 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.
+5. Return a stage result with `stage: integrate`, the integration record as output, evidence entries and separate `missingEvidence`, `unavailableChecks` and `pendingReview` arrays 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.
+The change is ready for its configured merge action, every required check is linked and unresolved decisions have an owner in the integration result.

package/skills/propose/SKILL.md

@@ -13,8 +13,8 @@ Describe the smallest implementable solution for a Ready item.
 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.
+5. Return a stage result with `stage: propose`, `gate: planned`, the change artifacts as output, evidence entries and separate `missingEvidence`, `unavailableChecks` and `pendingReview` arrays.
 
 ## Completion
 
-The change artifacts explain the future state, the slices are dependency ordered, the evidence plan is explicit and the Planned decision remains visible.
+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

@@ -13,8 +13,8 @@ Turn a triaged item into a problem that can be designed.
 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.
+5. Return a stage result with `stage: refine`, `gate: ready`, the bounded problem as output, evidence entries and separate `missingEvidence`, `unavailableChecks` and `pendingReview` arrays.
 
 ## Completion
 
-The work item has a bounded problem statement, testable acceptance criteria, resolved owners for open dependencies and a Ready decision.
+The work item has a bounded problem statement, testable acceptance criteria, resolved owners for open dependencies and a `ready` stage result that names the next decision.

package/skills/review/SKILL.md

@@ -13,8 +13,8 @@ Close the delivery record and make the next improvement visible.
 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.
+5. Return a stage result with `stage: review`, `gate: null`, the review record as output, evidence entries and separate `missingEvidence`, `unavailableChecks` and `pendingReview` arrays without opening another delivery gate.
 
 ## Completion
 
-The completed change has a durable review record, classified findings and a clear follow-up owner.
+The completed change has a durable review result, classified findings and a clear follow-up owner.

package/skills/triage/SKILL.md

@@ -14,8 +14,8 @@ Classify one work item before refinement.
 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.
+6. Return a stage result with `stage: triage`, `gate: triaged`, the triage record as output, evidence entries and separate `missingEvidence`, `unavailableChecks` and `pendingReview` arrays.
 
 ## Completion
 
-The record names the route, owner, labels, assessments, confidence, evidence and next decision, and no later stage has started.
+The record names the route, owner, labels, assessments, confidence and next decision, and the stage result stops at `triaged` without starting a later stage.