@juangcarmona/lighthouse-sdlc 0.5.0 → 0.6.0

package/README.md

@@ -4,6 +4,8 @@ This package provides the provider-neutral delivery contract for Lighthouse adop
 
 It owns the six lifecycle skills, their command entrypoints, route, stage and gate descriptors, deterministic triage and decomposition projections, rebuildable state checks and the provider-neutral control-plane contract.
 
+It also provides the `browser-e2e` evidence contract for Playwright journeys. The contract belongs to the SDLC because it records delivery evidence; the tests, journeys and browser configuration remain owned by the adopter.
+
 It does not run agents, store transcripts, dispatch work between repositories or replace ProductShape, ArcShape, OpenSpec or an agent host.
 
 Install it with the Lighthouse CLI or run `lighthouse-sdlc verify` from the package installation to check the distributed contract.
@@ -12,6 +14,8 @@ Run `lighthouse-sdlc triage --input <file>` to validate one structured triage re
 
 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 browser-e2e --input <evidence.json>` to validate a Playwright journey result. It is read-only and does not start a browser or write provider state.
+
 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.

package/commands/browser-e2e.md

@@ -0,0 +1,10 @@
+# Browser E2E
+
+Use this command during `integrate` and `review` when the selected application exposes a browser journey.
+
+1. Read the ProductShape journey and its bounded context before choosing the test.
+2. Run the adopter's Playwright command and keep the report, screenshots, traces or videos under the repository's evidence path.
+3. Create a browser evidence JSON document with `runner: playwright`, the journey identity, evidence statuses, relative artifact paths and the next action.
+4. Run `lighthouse-sdlc browser-e2e --input <evidence.json>` and stop when the report is invalid or the journey is not passed.
+
+The command validates evidence; it does not start Playwright, invent product journeys or make browser tests mandatory for applications without a browser surface.

package/contract.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -48,6 +48,7 @@
     "./capabilities": "./src/capabilities.mjs",
     "./stacked": "./src/stacked.mjs",
     "./workflow": "./src/workflow.mjs",
+    "./browser-e2e": "./src/browser-e2e.mjs",
     "./contract.json": "./contract.json",
     "./schemas/control-plane.schema.json": "./schemas/control-plane.schema.json",
     "./schemas/triage.schema.json": "./schemas/triage.schema.json",
@@ -57,6 +58,7 @@
     "./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",
+    "./schemas/browser-e2e.schema.json": "./schemas/browser-e2e.schema.json",
     "./capabilities.json": "./capabilities.json"
   }
 }

package/schemas/browser-e2e.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/browser-e2e.schema.json",
+  "title": "Lighthouse browser end-to-end evidence",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "runner", "journey", "command", "status", "evidence", "artifacts", "nextAction"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "runner": { "const": "playwright" },
+    "journey": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "boundedContext"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "boundedContext": { "type": "string", "minLength": 1 },
+        "title": { "type": "string", "minLength": 1 }
+      }
+    },
+    "command": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["passed", "failed", "unavailable", "pending-review"] },
+    "evidence": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "source"],
+        "properties": {
+          "id": { "type": "string", "minLength": 1 },
+          "status": { "enum": ["passed", "failed", "unavailable", "pending-review"] },
+          "source": { "type": "string", "minLength": 1 },
+          "reason": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "artifacts": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "path"],
+        "properties": {
+          "type": { "enum": ["screenshot", "trace", "video", "report"] },
+          "path": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "nextAction": { "type": "string", "minLength": 1 }
+  }
+}

package/skills/browser-e2e/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: lighthouse-browser-e2e
+description: Validate Playwright browser evidence for a selected product journey during integration or review.
+---
+
+# Browser E2E
+
+Use this skill only when the selected application has a browser surface and the product definition names a journey to verify.
+
+Read the journey, bounded context and acceptance evidence before writing or changing a test. Keep the test in the adopter repository and use the project's existing Playwright configuration when one exists.
+
+Run the narrowest useful journey first. Collect the report and any screenshot, trace or video needed to inspect a failure. Store relative paths in the browser evidence document and validate it with `lighthouse-sdlc browser-e2e --input <evidence.json>`.
+
+Finish with one of `passed`, `failed`, `unavailable` or `pending-review`, plus a concrete `nextAction`. A missing artifact, unavailable browser or unresolved human judgement stays visible in the result.

package/src/browser-e2e.mjs

@@ -0,0 +1,48 @@
+const statuses = new Set(['passed', 'failed', 'unavailable', 'pending-review']);
+const artifactTypes = new Set(['screenshot', 'trace', 'video', 'report']);
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function validateBrowserEvidence(value) {
+  const errors = [];
+  if (!record(value)) return [issue('browser-e2e.invalid', 'browser evidence must be an object')];
+  if (value.schemaVersion !== 1) errors.push(issue('browser-e2e.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  if (value.runner !== 'playwright') errors.push(issue('browser-e2e.runner', 'runner must be playwright', 'runner'));
+  if (!record(value.journey) || typeof value.journey.id !== 'string' || !value.journey.id.trim() || typeof value.journey.boundedContext !== 'string' || !value.journey.boundedContext.trim()) {
+    errors.push(issue('browser-e2e.journey', 'journey needs an id and boundedContext', 'journey'));
+  }
+  if (typeof value.command !== 'string' || !value.command.trim()) errors.push(issue('browser-e2e.command', 'command must be a non-empty string', 'command'));
+  if (!statuses.has(value.status)) errors.push(issue('browser-e2e.status', `status must be one of ${[...statuses].join(', ')}`, 'status'));
+  if (!Array.isArray(value.evidence) || value.evidence.length === 0) errors.push(issue('browser-e2e.evidence', 'evidence must contain at least one item', 'evidence'));
+  else {
+    const ids = new Set();
+    for (const [index, item] of value.evidence.entries()) {
+      if (!record(item) || typeof item.id !== 'string' || !item.id.trim() || !statuses.has(item.status) || typeof item.source !== 'string' || !item.source.trim()) {
+        errors.push(issue('browser-e2e.evidence-item', `evidence[${index}] needs an id, supported status and source`, `evidence[${index}]`));
+        continue;
+      }
+      if (ids.has(item.id)) errors.push(issue('browser-e2e.evidence-duplicate', `evidence id ${item.id} is duplicated`, `evidence[${index}]`));
+      ids.add(item.id);
+      if (['failed', 'unavailable', 'pending-review'].includes(item.status) && (typeof item.reason !== 'string' || !item.reason.trim())) errors.push(issue('browser-e2e.evidence-reason', `evidence[${index}] needs a reason for status ${item.status}`, `evidence[${index}]`));
+    }
+  }
+  if (!Array.isArray(value.artifacts)) errors.push(issue('browser-e2e.artifacts', 'artifacts must be an array', 'artifacts'));
+  else for (const [index, artifact] of value.artifacts.entries()) {
+    if (!record(artifact) || !artifactTypes.has(artifact.type) || typeof artifact.path !== 'string' || !artifact.path.trim() || artifact.path.startsWith('/')) errors.push(issue('browser-e2e.artifact', `artifacts[${index}] needs a relative path and supported type`, `artifacts[${index}]`));
+  }
+  if (value.status === 'passed' && (!value.artifacts?.length || value.evidence?.some((item) => item.status !== 'passed'))) errors.push(issue('browser-e2e.passed-evidence', 'passed browser evidence needs artifacts and only passed evidence items', 'status'));
+  if (value.status !== 'passed' && value.evidence?.every((item) => item.status === 'passed')) errors.push(issue('browser-e2e.status-evidence', `status ${value.status} needs a matching evidence item`, 'status'));
+  if (typeof value.nextAction !== 'string' || !value.nextAction.trim()) errors.push(issue('browser-e2e.next-action', 'nextAction must be a non-empty string', 'nextAction'));
+  return errors;
+}
+
+export function browserEvidenceReport(value) {
+  const errors = validateBrowserEvidence(value);
+  return { schemaVersion: 1, status: errors.length ? 'invalid' : value.status, valid: errors.length === 0, errors, journey: value.journey ?? null, runner: value.runner ?? null, artifacts: value.artifacts ?? [] };
+}

package/src/sdlc.mjs

@@ -13,6 +13,7 @@ import { applyTriageLabels, buildTriageReport } from './triage.mjs';
 import { validateMemoryRecord } from './memory.mjs';
 import { replayWorkflow } from './workflow.mjs';
 import { validateStageResult } from './contracts.mjs';
+import { browserEvidenceReport } from './browser-e2e.mjs';
 import { readCapabilityCatalog, validateCapabilityCatalog } from './capabilities.mjs';
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -39,10 +40,10 @@ async function verifyContract() {
   for (const stage of stages) {
     for (const asset of [stage.skill, stage.command]) if (!(await exists(resolve(packageRoot, asset)))) problems.push(`missing stage asset ${asset}`);
   }
-  for (const asset of [contract.assets?.routes, contract.assets?.gates, contract.assets?.stages, contract.assets?.controlPlaneSchema, contract.assets?.triageSchema, contract.assets?.stageResultSchema, contract.assets?.stateSchema, contract.assets?.decompositionSchema, contract.assets?.capabilitiesSchema, contract.assets?.capabilityCatalog, contract.assets?.capabilityCatalogSchema]) {
+  for (const asset of [contract.assets?.routes, contract.assets?.gates, contract.assets?.stages, contract.assets?.controlPlaneSchema, contract.assets?.triageSchema, contract.assets?.stageResultSchema, contract.assets?.stateSchema, contract.assets?.decompositionSchema, contract.assets?.capabilitiesSchema, contract.assets?.capabilityCatalog, contract.assets?.capabilityCatalogSchema, contract.assets?.browserE2eSchema]) {
     if (!asset || !(await exists(resolve(packageRoot, asset)))) problems.push(`missing contract asset ${asset ?? '(empty)'}`);
   }
-  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'schemas/routes.schema.json', 'schemas/gates.schema.json', 'schemas/stages.schema.json', 'schemas/control-plane.schema.json', 'schemas/triage.schema.json', 'schemas/stage-result.schema.json', 'schemas/workflow-state.schema.json', 'schemas/decomposition.schema.json', 'schemas/capabilities.schema.json', 'schemas/capability-catalog.schema.json', 'src/capabilities.mjs', 'src/contracts.mjs', 'src/control-plane.mjs', 'src/decompose.mjs', 'src/github.mjs', 'src/memory.mjs', 'src/reconcile.mjs', 'src/routes.mjs', 'src/stacked.mjs', 'src/triage.mjs', 'src/workflow.mjs']) {
+  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'schemas/routes.schema.json', 'schemas/gates.schema.json', 'schemas/stages.schema.json', 'schemas/control-plane.schema.json', 'schemas/triage.schema.json', 'schemas/stage-result.schema.json', 'schemas/workflow-state.schema.json', 'schemas/decomposition.schema.json', 'schemas/capabilities.schema.json', 'schemas/capability-catalog.schema.json', 'schemas/browser-e2e.schema.json', 'src/browser-e2e.mjs', 'src/capabilities.mjs', 'src/contracts.mjs', 'src/control-plane.mjs', 'src/decompose.mjs', 'src/github.mjs', 'src/memory.mjs', 'src/reconcile.mjs', 'src/routes.mjs', 'src/stacked.mjs', 'src/triage.mjs', 'src/workflow.mjs']) {
     if (!(await exists(resolve(packageRoot, asset)))) problems.push(`missing package asset ${asset}`);
   }
   try {
@@ -160,6 +161,15 @@ async function runStageResult(args) {
   if (errors.length) process.exit(1);
 }
 
+async function runBrowserE2e(args) {
+  const inputPath = option(args, '--input');
+  const format = option(args, '--format') ?? 'json';
+  if (!inputPath) { console.error('Usage: lighthouse-sdlc browser-e2e --input <evidence.json> [--format <json|text>]'); process.exit(2); }
+  const report = browserEvidenceReport(await readJson(resolve(process.cwd(), inputPath)));
+  output(report, format);
+  if (!report.valid || report.status !== 'passed') process.exit(1);
+}
+
 async function runMemory(args) {
   const inputPath = option(args, '--input');
   const policyPath = option(args, '--policy');
@@ -318,8 +328,8 @@ async function runGithubLabels(args) {
 }
 
 const command = process.argv[2] ?? 'verify';
-if (!['contract', 'verify', 'triage', 'state', 'stage-result', 'control-plane', 'memory', 'launch', 'decompose', 'stacked', 'route', 'github-triage', 'github-decompose', 'reconcile-labels', 'github-labels'].includes(command)) {
-  console.error('Usage: lighthouse-sdlc <contract|verify|triage|state|stage-result|control-plane|memory|launch|decompose|stacked|route|github-triage|github-decompose|reconcile-labels|github-labels>');
+if (!['contract', 'verify', 'triage', 'state', 'stage-result', 'browser-e2e', 'control-plane', 'memory', 'launch', 'decompose', 'stacked', 'route', 'github-triage', 'github-decompose', 'reconcile-labels', 'github-labels'].includes(command)) {
+  console.error('Usage: lighthouse-sdlc <contract|verify|triage|state|stage-result|browser-e2e|control-plane|memory|launch|decompose|stacked|route|github-triage|github-decompose|reconcile-labels|github-labels>');
   process.exit(2);
 }
 if (command === 'contract') {
@@ -332,6 +342,8 @@ if (command === 'contract') {
   await runControlPlane(process.argv.slice(3));
 } else if (command === 'stage-result') {
   await runStageResult(process.argv.slice(3));
+} else if (command === 'browser-e2e') {
+  await runBrowserE2e(process.argv.slice(3));
 } else if (command === 'memory') {
   await runMemory(process.argv.slice(3));
 } else if (command === 'launch') {
@@ -359,4 +371,4 @@ if (command === 'contract') {
   console.log('Lighthouse SDLC package contract is valid.');
 }
 
-export { contractPath, runTriage, verifyContract, runState, runStageResult, runControlPlane, runMemory, runLaunch, runDecompose, runRoute, runStacked, runGithubTriage, runGithubDecompose, runReconcileLabels, runGithubLabels };
+export { contractPath, runTriage, verifyContract, runState, runStageResult, runBrowserE2e, runControlPlane, runMemory, runLaunch, runDecompose, runRoute, runStacked, runGithubTriage, runGithubDecompose, runReconcileLabels, runGithubLabels };