@juangcarmona/lighthouse-sdlc 0.3.0 → 0.4.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,14 @@ 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`.
+
 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/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.2.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,19 @@
     { "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"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -26,6 +26,7 @@
     "meta-commands",
     "README.md",
     "routes.json",
+    "stages.json",
     "schemas",
     "skills",
     "src"
@@ -36,8 +37,22 @@
   "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",
+    "./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"
   }
 }

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/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.

package/src/contracts.mjs

@@ -0,0 +1,39 @@
+export const STAGES = Object.freeze(['triage', 'refine', 'propose', 'implement', 'integrate', 'review']);
+export const GATES = Object.freeze(['triaged', 'ready', 'planned', 'done']);
+export const EVIDENCE_STATUSES = Object.freeze(['passed', 'failed', 'unavailable', 'unconfigured', 'pending-review', 'not-applicable']);
+export const STAGE_STATUSES = Object.freeze(['ready', 'blocked', 'failed', 'passed']);
+
+const stageSet = new Set(STAGES);
+const gateSet = new Set(GATES);
+const evidenceStatusSet = new Set(EVIDENCE_STATUSES);
+const stageStatusSet = new Set(STAGE_STATUSES);
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function validateStageResult(value) {
+  const errors = [];
+  if (!isRecord(value)) return [issue('stage-result.invalid', 'stage result must be an object')];
+  if (value.schemaVersion !== 1) errors.push(issue('stage-result.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  for (const field of ['runId', 'nextAction']) if (typeof value[field] !== 'string' || !value[field].trim()) errors.push(issue(`stage-result.${field}`, `${field} must be a non-empty string`, field));
+  if (!stageSet.has(value.stage)) errors.push(issue('stage-result.stage', `stage must be one of ${STAGES.join(', ')}`, 'stage'));
+  if (!stageStatusSet.has(value.status)) errors.push(issue('stage-result.status', `status must be one of ${STAGE_STATUSES.join(', ')}`, 'status'));
+  if (value.gate !== null && !gateSet.has(value.gate)) errors.push(issue('stage-result.gate', `gate must be one of ${GATES.join(', ')} or null`, 'gate'));
+  if (!Array.isArray(value.evidence)) errors.push(issue('stage-result.evidence', 'evidence must be an array', 'evidence'));
+  else for (const [index, evidence] of value.evidence.entries()) {
+    if (!isRecord(evidence) || typeof evidence.id !== 'string' || !evidence.id.trim() || !evidenceStatusSet.has(evidence.status)) errors.push(issue('stage-result.evidence-item', `evidence[${index}] needs an id and a supported status`, `evidence[${index}]`));
+  }
+  for (const field of ['missingEvidence', 'unavailableChecks', 'pendingReview']) if (!Array.isArray(value[field]) || value[field].some((item) => typeof item !== 'string' || !item.trim())) errors.push(issue(`stage-result.${field}`, `${field} must be an array of names`, field));
+  if (value.input !== undefined && !isRecord(value.input)) errors.push(issue('stage-result.input', 'input must be an object when present', 'input'));
+  if (value.output !== undefined && !isRecord(value.output)) errors.push(issue('stage-result.output', 'output must be an object when present', 'output'));
+  return errors;
+}
+
+export function isValidStageResult(value) {
+  return validateStageResult(value).length === 0;
+}

package/src/control-plane.mjs

@@ -0,0 +1,51 @@
+import { MEMORY_SCOPES } from './memory.mjs';
+import { WORKFLOW_STATES } from './workflow.mjs';
+
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+export function validateControlPlane(value) {
+  const errors = [];
+  if (!isRecord(value)) return [issue('control-plane.invalid', 'control plane must be an object')];
+  if (value.schemaVersion !== 1) errors.push(issue('control-plane.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!isRecord(value.package) || typeof value.package.name !== 'string' || typeof value.package.version !== 'string') errors.push(issue('control-plane.package', 'package needs name and version', 'package'));
+  for (const field of ['routes', 'gates']) if (!Array.isArray(value[field]) || value[field].some((item) => typeof item !== 'string' || !item.trim())) errors.push(issue(`control-plane.${field}`, `${field} must be an array of names`, field));
+  if (!isRecord(value.state) || typeof value.state.provider !== 'string' || !value.state.provider.trim()) errors.push(issue('control-plane.state', 'state.provider is required', 'state'));
+  if (value.state?.states !== undefined && (!Array.isArray(value.state.states) || value.state.states.some((state) => !WORKFLOW_STATES.includes(state)))) errors.push(issue('control-plane.state-states', 'state.states must contain known workflow states', 'state.states'));
+  if (!isRecord(value.memory) || typeof value.memory.provider !== 'string' || !value.memory.provider.trim()) errors.push(issue('control-plane.memory', 'memory.provider is required', 'memory'));
+  if (!Array.isArray(value.memory?.scopes) || value.memory.scopes.length === 0 || value.memory.scopes.some((scope) => !MEMORY_SCOPES.includes(scope))) errors.push(issue('control-plane.memory-scopes', `memory.scopes must contain values from ${MEMORY_SCOPES.join(', ')}`, 'memory.scopes'));
+  if (value.memory?.scopes?.includes('shared') && value.memory.shared !== true) errors.push(issue('control-plane.shared-memory', 'shared memory requires memory.shared=true', 'memory.shared'));
+  if (!isRecord(value.roles)) errors.push(issue('control-plane.roles', 'roles must be an object', 'roles'));
+  else for (const [name, role] of Object.entries(value.roles)) {
+    if (typeof role === 'string' && role.trim()) continue;
+    if (!isRecord(role)) errors.push(issue('control-plane.role', `role ${name} must be an object or provider reference`, `roles.${name}`));
+    else {
+      for (const field of ['inputSchema', 'outputSchema']) if (typeof role[field] !== 'string' || !role[field].trim()) errors.push(issue('control-plane.role-schema', `role ${name} needs ${field}`, `roles.${name}.${field}`));
+      if (!Array.isArray(role.tools)) errors.push(issue('control-plane.role-tools', `role ${name} needs a tools array`, `roles.${name}.tools`));
+      if (!Array.isArray(role.writeScope)) errors.push(issue('control-plane.role-write-scope', `role ${name} needs a writeScope array`, `roles.${name}.writeScope`));
+    }
+  }
+  if (!isRecord(value.adapters)) errors.push(issue('control-plane.adapters', 'adapters must be an object', 'adapters'));
+  return errors;
+}
+
+export function validateLaunchRequest(request, controlPlane) {
+  const errors = [];
+  if (!isRecord(request)) return [issue('launch.invalid', 'launch request must be an object')];
+  for (const field of ['runId', 'role', 'outputSchema']) if (typeof request[field] !== 'string' || !request[field].trim()) errors.push(issue(`launch.${field}`, `${field} must be a non-empty string`, field));
+  const role = controlPlane?.roles?.[request.role];
+  if (!role) errors.push(issue('launch.role', `role ${request.role} is not declared`, 'role'));
+  if (role && request.outputSchema !== role.outputSchema) errors.push(issue('launch.output-schema', `outputSchema does not match role ${request.role}`, 'outputSchema'));
+  if (!Array.isArray(request.tools)) errors.push(issue('launch.tools', 'tools must be an array', 'tools'));
+  else if (role) for (const tool of request.tools) if (!role.tools.includes(tool)) errors.push(issue('launch.tool', `tool ${tool} is not allowed for role ${request.role}`, 'tools'));
+  if (!Array.isArray(request.writeScope)) errors.push(issue('launch.write-scope', 'writeScope must be an array', 'writeScope'));
+  else if (role) for (const path of request.writeScope) if (!role.writeScope.includes(path)) errors.push(issue('launch.write-path', `write path ${path} is not allowed for role ${request.role}`, 'writeScope'));
+  if (!isRecord(request.limits)) errors.push(issue('launch.limits', 'limits must be an object', 'limits'));
+  if (!Array.isArray(request.stopConditions)) errors.push(issue('launch.stop-conditions', 'stopConditions must be an array', 'stopConditions'));
+  return errors;
+}

package/src/decompose.mjs

@@ -0,0 +1,53 @@
+function isRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function orderSlices(slices) {
+  const byId = new Map(slices.map((slice) => [slice.id, slice]));
+  const visiting = new Set();
+  const visited = new Set();
+  const ordered = [];
+  const errors = [];
+  function visit(id) {
+    if (visited.has(id)) return;
+    if (visiting.has(id)) { errors.push(issue('decompose.cycle', `dependency cycle includes ${id}`, 'slices')); return; }
+    visiting.add(id);
+    for (const dependency of byId.get(id)?.dependencies ?? []) if (byId.has(dependency)) visit(dependency);
+    visiting.delete(id);
+    visited.add(id);
+    ordered.push(id);
+  }
+  for (const slice of slices) visit(slice.id);
+  return { ordered, errors };
+}
+
+export function buildDecompositionPlan(input) {
+  const errors = [];
+  if (!isRecord(input)) return { schemaVersion: 1, status: 'invalid', valid: false, canApply: false, errors: [issue('decompose.invalid', 'decomposition input must be an object')] };
+  if (input.schemaVersion !== 1) errors.push(issue('decompose.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (!isRecord(input.parent) || typeof input.parent.id !== 'string' || !input.parent.id.trim() || typeof input.parent.title !== 'string' || !input.parent.title.trim()) errors.push(issue('decompose.parent', 'parent needs id and title', 'parent'));
+  if (!Array.isArray(input.slices) || input.slices.length === 0) errors.push(issue('decompose.slices', 'slices must be a non-empty array', 'slices'));
+  const ids = new Set();
+  const slices = Array.isArray(input.slices) ? input.slices.map((slice, index) => {
+    if (!isRecord(slice) || typeof slice.id !== 'string' || !slice.id.trim() || typeof slice.title !== 'string' || !slice.title.trim()) { errors.push(issue('decompose.slice', `slice ${index} needs id and title`, `slices[${index}]`)); return null; }
+    if (ids.has(slice.id)) errors.push(issue('decompose.duplicate', `slice ${slice.id} appears more than once`, `slices[${index}].id`));
+    ids.add(slice.id);
+    if (!Array.isArray(slice.dependencies)) errors.push(issue('decompose.dependencies', `slice ${slice.id} needs a dependencies array`, `slices[${index}].dependencies`));
+    if (!Array.isArray(slice.acceptance) || slice.acceptance.length === 0 || slice.acceptance.some((item) => typeof item !== 'string' || !item.trim())) errors.push(issue('decompose.acceptance', `slice ${slice.id} needs independent acceptance evidence`, `slices[${index}].acceptance`));
+    return { id: slice.id, title: slice.title, acceptance: [...(slice.acceptance ?? [])], dependencies: [...(slice.dependencies ?? [])].sort(), scope: [...(slice.scope ?? [])].sort(), labels: [...(slice.labels ?? [])].sort() };
+  }).filter(Boolean) : [];
+  for (const slice of slices) for (const dependency of slice.dependencies) if (!ids.has(dependency)) errors.push(issue('decompose.unknown-dependency', `slice ${slice.id} depends on unknown slice ${dependency}`, 'slices'));
+  const order = orderSlices(slices);
+  errors.push(...order.errors);
+  const status = errors.length ? 'invalid' : 'ready';
+  return { schemaVersion: 1, status, valid: errors.length === 0, canApply: status === 'ready', parent: input.parent ?? null, slices, order: order.ordered, operations: status === 'ready' ? order.ordered.map((id) => ({ type: 'create-child', parentId: input.parent?.id, sliceId: id })) : [], errors };
+}
+
+export function applyDecompositionPlan(plan) {
+  if (!plan?.canApply) throw new Error('Decomposition plan is not ready to apply. Resolve its errors first.');
+  return { ...plan, applied: true };
+}