@juangcarmona/lighthouse-sdlc 0.6.0 → 0.8.0

package/README.md

@@ -4,10 +4,22 @@ 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 publishes `command-aliases.json` as the versioned, machine-readable mapping from selected `/lh:*` aliases to canonical `/lighthouse:*` command assets. Run `lighthouse-sdlc aliases --format json` to inspect it; the configured agent host decides how to expose the aliases.
+
 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 provides a neutral evidence contract for delivery, product and architecture references. `lighthouse-sdlc evidence` validates records or builds a deterministic coverage index; it does not replace ProductShape, ArcShape or a future quality evaluator.
+
 It does not run agents, store transcripts, dispatch work between repositories or replace ProductShape, ArcShape, OpenSpec or an agent host.
 
+## gh-aw workflow projection
+
+The package includes the six Lighthouse SDLC worker sources, their compiled `.lock.yml` workflows and the router projection. The Lighthouse CLI projects them into `.github/workflows` during initialization, reconciliation or an explicit `lighthouse upgrade --scope sdlc --apply`; package installation alone does not write repository files.
+
+The host must provide the runner capability `[self-hosted, linux, lighthouse-sdlc]`, the GitHub and gh-aw credentials required by the compiled workflow, the selected route and stage input, and durable evidence handling for the uploaded stage result. Each worker executes one declared stage and writes `/tmp/gh-aw/agent/stage-result.json`; the host remains responsible for runtime, queues, budgets and model selection. The generic runner capability is a contract, not a SoFa or Bastion identity.
+
+The router validates the existing Lighthouse route and `requires` declarations. A normal dispatch runs one stage. Only an explicit `ff` composition chains the selected route, and it stops when a worker fails. The `integrate` worker prepares the configured merge action without merging unless repository policy authorizes it; `review` closes the flow with `gate: null`.
+
 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.
@@ -16,6 +28,8 @@ Use `lighthouse-sdlc route --route <name>` to inspect a route before running it,
 
 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 evidence --input <record-or-index.json>` to validate evidence, or add `--build --output <index.json>` to build an index and its compact record files from full records. The command is read-only unless the output path is explicitly provided.
+
 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/command-aliases.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "./schemas/command-aliases.schema.json",
+  "schemaVersion": 1,
+  "contractVersion": 1,
+  "package": { "name": "@juangcarmona/lighthouse-sdlc" },
+  "canonicalNamespace": "/lighthouse",
+  "aliasNamespace": "/lh",
+  "aliases": [
+    { "alias": "/lh:control", "canonical": "/lighthouse:control-plane", "asset": "commands/control-plane.md" },
+    { "alias": "/lh:gh-decompose", "canonical": "/lighthouse:github-decompose", "asset": "commands/github-decompose.md" },
+    { "alias": "/lh:gh-triage", "canonical": "/lighthouse:github-triage", "asset": "commands/github-triage.md" },
+    { "alias": "/lh:result", "canonical": "/lighthouse:stage-result", "asset": "commands/stage-result.md" },
+    { "alias": "/lh:e2e", "canonical": "/lighthouse:browser-e2e", "asset": "commands/browser-e2e.md" },
+    { "alias": "/lh:caps", "canonical": "/lighthouse:capabilities", "asset": "commands/capabilities.md" },
+    { "alias": "/lh:labels", "canonical": "/lighthouse:reconcile-labels", "asset": "commands/reconcile-labels.md" },
+    { "alias": "/lh:gh-labels", "canonical": "/lighthouse:github-labels", "asset": "commands/github-labels.md" },
+    { "alias": "/lh:mem", "canonical": "/lighthouse:memory", "asset": "commands/memory.md" },
+    { "alias": "/lh:impl", "canonical": "/lighthouse:implement", "asset": "commands/implement.md" }
+  ]
+}

package/commands/aliases.md

@@ -0,0 +1,5 @@
+# `/lighthouse:aliases`
+
+Use `lighthouse-sdlc aliases --format json` to inspect the SDLC package's versioned agent-command aliases. The output maps each `/lh:*` alias to one canonical `/lighthouse:*` command and its packaged command asset.
+
+The alias listing is read-only. The configured agent host decides how to expose the aliases and must reference the canonical command asset instead of copying or maintaining a second command implementation.

package/commands/evidence.md

@@ -0,0 +1,9 @@
+# evidence
+
+Validate one evidence record or an evidence index without writing repository or provider state.
+
+Use `lighthouse-sdlc evidence --input <record-or-index.json> --format json` to validate an existing artifact.
+
+Use `lighthouse-sdlc evidence --input <records.json> --build --output .lighthouse/evidence/index.json` to build a deterministic index from full records and write the compact record files beside it. The input object must contain `records` and may contain `indexId`, `runId`, `repository`, `revision` and `subjects`.
+
+The index reports evidence coverage for ProductShape, ArcShape, Lighthouse or other explicitly referenced subjects. It does not decide product scope, architecture ownership or quality policy.

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", "browser-e2e", "github-triage", "github-decompose", "reconcile-labels", "github-labels"],
+  "utilities": ["status", "aliases", "route", "state", "stage-result", "control-plane", "memory", "launch", "decompose", "stacked", "browser-e2e", "evidence", "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"],
@@ -25,7 +25,11 @@
     "decompositionSchema": "schemas/decomposition.schema.json",
     "capabilitiesSchema": "schemas/capabilities.schema.json",
     "browserE2eSchema": "schemas/browser-e2e.schema.json",
+    "evidenceRecordSchema": "schemas/evidence-record.schema.json",
+    "evidenceIndexSchema": "schemas/evidence-index.schema.json",
     "capabilityCatalog": "capabilities.json",
-    "capabilityCatalogSchema": "schemas/capability-catalog.schema.json"
+    "capabilityCatalogSchema": "schemas/capability-catalog.schema.json",
+    "commandAliases": "command-aliases.json",
+    "commandAliasesSchema": "schemas/command-aliases.schema.json"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -21,6 +21,7 @@
   },
   "files": [
     "commands",
+    "command-aliases.json",
     "contract.json",
     "capabilities.json",
     "gates.json",
@@ -30,6 +31,7 @@
     "stages.json",
     "schemas",
     "skills",
+    "workflows",
     "src"
   ],
   "bin": {
@@ -46,9 +48,11 @@
     "./routes": "./src/routes.mjs",
     "./reconcile": "./src/reconcile.mjs",
     "./capabilities": "./src/capabilities.mjs",
+    "./aliases": "./src/aliases.mjs",
     "./stacked": "./src/stacked.mjs",
     "./workflow": "./src/workflow.mjs",
     "./browser-e2e": "./src/browser-e2e.mjs",
+    "./evidence": "./src/evidence.mjs",
     "./contract.json": "./contract.json",
     "./schemas/control-plane.schema.json": "./schemas/control-plane.schema.json",
     "./schemas/triage.schema.json": "./schemas/triage.schema.json",
@@ -59,6 +63,11 @@
     "./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"
+    "./schemas/evidence-record.schema.json": "./schemas/evidence-record.schema.json",
+    "./schemas/evidence-index.schema.json": "./schemas/evidence-index.schema.json",
+    "./capabilities.json": "./capabilities.json",
+    "./command-aliases.json": "./command-aliases.json",
+    "./schemas/command-aliases.schema.json": "./schemas/command-aliases.schema.json",
+    "./workflows/*": "./workflows/*"
   }
 }

package/schemas/command-aliases.schema.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-sdlc-command-aliases.schema.json",
+  "title": "Lighthouse SDLC command aliases",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "contractVersion", "package", "canonicalNamespace", "aliasNamespace", "aliases"],
+  "properties": {
+    "$schema": {"type": "string"},
+    "schemaVersion": {"const": 1},
+    "contractVersion": {"const": 1},
+    "package": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {"name": {"const": "@juangcarmona/lighthouse-sdlc"}}
+    },
+    "canonicalNamespace": {"const": "/lighthouse"},
+    "aliasNamespace": {"const": "/lh"},
+    "aliases": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["alias", "canonical", "asset"],
+        "properties": {
+          "alias": {"type": "string", "pattern": "^/lh:[a-z][a-z0-9-]*$"},
+          "canonical": {"type": "string", "pattern": "^/lighthouse:[a-z][a-z0-9-]*$"},
+          "asset": {"type": "string", "pattern": "^(commands|meta-commands)/[a-z0-9-]+\\.md$"}
+        }
+      }
+    }
+  }
+}

package/schemas/evidence-index.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-evidence-index.schema.json",
+  "title": "Lighthouse evidence index",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "indexId", "runId", "records", "coverage"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "indexId": { "type": "string", "minLength": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "repository": { "type": "string", "minLength": 1 },
+    "revision": { "type": "string", "minLength": 1 },
+    "records": { "type": "array", "items": { "$ref": "#/$defs/recordRef" } },
+    "coverage": { "type": "array", "items": { "$ref": "#/$defs/coverage" } }
+  },
+  "$defs": {
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 }
+      }
+    },
+    "authorityRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authority", "id"],
+      "properties": {
+        "authority": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+" },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "recordRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["id", "path", "sha256", "kind", "status"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+" },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" },
+        "kind": { "type": "string", "minLength": 1 },
+        "status": { "enum": ["passed", "failed", "unavailable", "unconfigured", "pending-review", "not-applicable"] },
+        "subject": { "$ref": "#/$defs/subject" },
+        "authorityRefs": { "type": "array", "items": { "$ref": "#/$defs/authorityRef" } }
+      }
+    },
+    "coverage": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["subject", "status", "evidenceIds"],
+      "properties": {
+        "subject": { "$ref": "#/$defs/subject" },
+        "status": { "enum": ["unverified", "observed", "verified", "incomplete", "conflict", "not-applicable"] },
+        "evidenceIds": { "type": "array", "items": { "type": "string", "minLength": 1 } },
+        "nextAction": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}

package/schemas/evidence-record.schema.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/juangcarmona/lighthouse/schemas/lighthouse-evidence-record.schema.json",
+  "title": "Lighthouse evidence record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "id", "runId", "kind", "scope", "status", "producer", "payload"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "runId": { "type": "string", "minLength": 1 },
+    "kind": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+    "scope": { "enum": ["product", "architecture", "delivery", "release", "run"] },
+    "status": { "enum": ["passed", "failed", "unavailable", "unconfigured", "pending-review", "not-applicable"] },
+    "producer": { "type": "string", "minLength": 1 },
+    "subject": { "$ref": "#/$defs/subject" },
+    "authorityRefs": { "type": "array", "items": { "$ref": "#/$defs/authorityRef" } },
+    "source": { "$ref": "#/$defs/source" },
+    "observedAt": { "type": "string", "format": "date-time" },
+    "artifacts": { "type": "array", "items": { "$ref": "#/$defs/artifact" } },
+    "payload": { "type": "object" },
+    "nextAction": { "type": "string", "minLength": 1 }
+  },
+  "$defs": {
+    "subject": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "id"],
+      "properties": {
+        "type": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 }
+      }
+    },
+    "authorityRef": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["authority", "id"],
+      "properties": {
+        "authority": { "type": "string", "minLength": 1 },
+        "id": { "type": "string", "minLength": 1 },
+        "revision": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+" },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    },
+    "source": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "format": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+" },
+        "command": { "type": "string", "minLength": 1 }
+      }
+    },
+    "artifact": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["type", "path"],
+      "properties": {
+        "id": { "type": "string", "minLength": 1 },
+        "type": { "type": "string", "minLength": 1 },
+        "path": { "type": "string", "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$)).+" },
+        "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }
+      }
+    }
+  }
+}

package/schemas/sdlc-contract.schema.json

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

package/src/aliases.mjs

@@ -0,0 +1,57 @@
+import { access, readFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const contractPath = resolve(packageRoot, 'command-aliases.json');
+const packageName = '@juangcarmona/lighthouse-sdlc';
+const aliasPattern = /^\/lh:[a-z][a-z0-9-]*$/u;
+const canonicalPattern = /^\/lighthouse:[a-z][a-z0-9-]*$/u;
+const assetPattern = /^(?:commands|meta-commands)\/[a-z0-9-]+\.md$/u;
+
+async function exists(path) {
+  try { await access(path, constants.F_OK); return true; } catch { return false; }
+}
+
+export async function readCommandAliases(path = contractPath) {
+  return JSON.parse(await readFile(path, 'utf8'));
+}
+
+export function validateCommandAliases(contract) {
+  const errors = [];
+  if (!contract || typeof contract !== 'object' || Array.isArray(contract)) return [{ code: 'aliases.invalid', message: 'command alias contract must be an object' }];
+  if (contract.schemaVersion !== 1) errors.push({ code: 'aliases.schema-version', message: 'command alias schemaVersion must be 1' });
+  if (contract.contractVersion !== 1) errors.push({ code: 'aliases.contract-version', message: 'command alias contractVersion must be 1' });
+  if (contract.package?.name !== packageName) errors.push({ code: 'aliases.package', message: `command alias contract package must be ${packageName}` });
+  if (contract.canonicalNamespace !== '/lighthouse') errors.push({ code: 'aliases.canonical-namespace', message: 'canonical namespace must be /lighthouse' });
+  if (contract.aliasNamespace !== '/lh') errors.push({ code: 'aliases.alias-namespace', message: 'alias namespace must be /lh' });
+  if (!Array.isArray(contract.aliases) || contract.aliases.length === 0) return [...errors, { code: 'aliases.list', message: 'command alias contract must declare at least one alias' }];
+  const aliases = new Set();
+  const canonicals = new Set();
+  for (const [index, item] of contract.aliases.entries()) {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) {
+      errors.push({ code: 'aliases.entry', message: `alias ${index} must be an object` });
+      continue;
+    }
+    if (typeof item.alias !== 'string' || !aliasPattern.test(item.alias)) errors.push({ code: 'aliases.alias', message: `alias ${index} must use the /lh:<verb> form` });
+    if (typeof item.canonical !== 'string' || !canonicalPattern.test(item.canonical)) errors.push({ code: 'aliases.canonical', message: `alias ${index} must target a /lighthouse:<verb> command` });
+    if (typeof item.asset !== 'string' || !assetPattern.test(item.asset)) errors.push({ code: 'aliases.asset', message: `alias ${index} must reference a packaged command asset` });
+    if (aliases.has(item.alias)) errors.push({ code: 'aliases.duplicate', message: `alias ${item.alias} is declared more than once` });
+    if (canonicals.has(item.canonical)) errors.push({ code: 'aliases.duplicate-target', message: `canonical command ${item.canonical} has more than one alias` });
+    aliases.add(item.alias);
+    canonicals.add(item.canonical);
+  }
+  return errors;
+}
+
+export async function verifyCommandAliases(contract) {
+  const value = contract ?? await readCommandAliases();
+  const errors = validateCommandAliases(value);
+  for (const item of value.aliases ?? []) {
+    if (typeof item.asset === 'string' && !(await exists(resolve(packageRoot, item.asset)))) errors.push({ code: 'aliases.missing-asset', message: `alias ${item.alias} references missing asset ${item.asset}` });
+  }
+  return errors;
+}
+
+export { contractPath };

package/src/evidence.mjs

@@ -0,0 +1,204 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { EVIDENCE_STATUSES, validateStageResult } from './contracts.mjs';
+import { validateBrowserEvidence } from './browser-e2e.mjs';
+
+export const EVIDENCE_SCOPES = Object.freeze(['product', 'architecture', 'delivery', 'release', 'run']);
+export const COVERAGE_STATUSES = Object.freeze(['unverified', 'observed', 'verified', 'incomplete', 'conflict', 'not-applicable']);
+
+const evidenceStatusSet = new Set(EVIDENCE_STATUSES);
+const scopeSet = new Set(EVIDENCE_SCOPES);
+const coverageStatusSet = new Set(COVERAGE_STATUSES);
+
+function issue(code, message, field) {
+  return field ? { code, message, field } : { code, message };
+}
+
+function record(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function text(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function relativePath(value) {
+  return text(value) && !value.startsWith('/') && !value.split('/').includes('..');
+}
+
+function validSubject(value) {
+  return record(value) && text(value.type) && text(value.id);
+}
+
+function subjectKey(value) {
+  return `${value.type}:${value.id}`;
+}
+
+function validateAuthorityRefs(value, errors, field = 'authorityRefs') {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(issue('evidence.authority-refs', 'authorityRefs must be an array', field));
+    return;
+  }
+  for (const [index, item] of value.entries()) {
+    if (!record(item) || !text(item.authority) || !text(item.id)) errors.push(issue('evidence.authority-ref', `authorityRefs[${index}] needs authority and id`, `${field}[${index}]`));
+    if (item.path !== undefined && !relativePath(item.path)) errors.push(issue('evidence.authority-path', `authorityRefs[${index}].path must be relative`, `${field}[${index}].path`));
+  }
+}
+
+function validateArtifacts(value, errors, field = 'artifacts') {
+  if (value === undefined) return;
+  if (!Array.isArray(value)) {
+    errors.push(issue('evidence.artifacts', 'artifacts must be an array', field));
+    return;
+  }
+  const ids = new Set();
+  for (const [index, item] of value.entries()) {
+    if (!record(item) || !text(item.type) || !relativePath(item.path)) {
+      errors.push(issue('evidence.artifact', `artifacts[${index}] needs a type and relative path`, `${field}[${index}]`));
+      continue;
+    }
+    if (item.id !== undefined) {
+      if (!text(item.id) || ids.has(item.id)) errors.push(issue('evidence.artifact-id', `artifacts[${index}].id must be unique`, `${field}[${index}].id`));
+      ids.add(item.id);
+    }
+    if (item.sha256 !== undefined && !/^[a-f0-9]{64}$/u.test(item.sha256)) errors.push(issue('evidence.artifact-hash', `artifacts[${index}].sha256 must be a lowercase SHA-256`, `${field}[${index}].sha256`));
+  }
+}
+
+export function validateEvidenceRecord(value) {
+  const errors = [];
+  if (!record(value)) return [issue('evidence.invalid', 'evidence record must be an object')];
+  if (value.schemaVersion !== 1) errors.push(issue('evidence.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  for (const field of ['id', 'runId', 'kind', 'producer']) if (!text(value[field]) && field !== 'producer') errors.push(issue(`evidence.${field}`, `${field} must be a non-empty string`, field));
+  if (!text(value.producer)) errors.push(issue('evidence.producer', 'producer must be a non-empty string', 'producer'));
+  if (!scopeSet.has(value.scope)) errors.push(issue('evidence.scope', `scope must be one of ${EVIDENCE_SCOPES.join(', ')}`, 'scope'));
+  if (!evidenceStatusSet.has(value.status)) errors.push(issue('evidence.status', `status must be one of ${EVIDENCE_STATUSES.join(', ')}`, 'status'));
+  if (!record(value.payload)) errors.push(issue('evidence.payload', 'payload must be an object', 'payload'));
+  if (value.subject !== undefined && !validSubject(value.subject)) errors.push(issue('evidence.subject', 'subject needs a type and id', 'subject'));
+  validateAuthorityRefs(value.authorityRefs, errors);
+  validateArtifacts(value.artifacts, errors);
+  if (value.source !== undefined && (!record(value.source) || (value.source.path !== undefined && !relativePath(value.source.path)))) errors.push(issue('evidence.source', 'source must be an object with a relative path', 'source'));
+  if (value.observedAt !== undefined && (typeof value.observedAt !== 'string' || Number.isNaN(Date.parse(value.observedAt)))) errors.push(issue('evidence.observed-at', 'observedAt must be an ISO date-time', 'observedAt'));
+  if (['failed', 'unavailable', 'unconfigured', 'pending-review'].includes(value.status) && !text(value.nextAction)) errors.push(issue('evidence.next-action', `status ${value.status} needs nextAction`, 'nextAction'));
+  if (value.nextAction !== undefined && !text(value.nextAction)) errors.push(issue('evidence.next-action', 'nextAction must be a non-empty string when present', 'nextAction'));
+  return errors;
+}
+
+function clean(value) {
+  return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== undefined));
+}
+
+function recordFrom(value, { id, kind, scope = 'delivery', producer, subject, authorityRefs, source, artifacts, nextAction } = {}) {
+  const status = kind === 'stage-result'
+    ? ({ passed: 'passed', failed: 'failed', blocked: 'pending-review', ready: 'pending-review' }[value.status] ?? 'unconfigured')
+    : value.status;
+  return clean({
+    schemaVersion: 1,
+    id: id ?? `${kind}:${value.runId ?? value.journey?.id ?? 'unknown'}`,
+    runId: value.runId ?? `${kind}:${value.journey?.id ?? 'unknown'}`,
+    kind,
+    scope,
+    status,
+    producer,
+    subject,
+    authorityRefs,
+    source,
+    observedAt: value.observedAt,
+    artifacts: artifacts ?? value.artifacts ?? [],
+    payload: value,
+    nextAction: nextAction ?? value.nextAction,
+  });
+}
+
+export function adaptStageResult(value, options = {}) {
+  const errors = validateStageResult(value);
+  return { record: errors.length ? null : recordFrom(value, { ...options, kind: 'stage-result', producer: options.producer ?? 'lighthouse-sdlc' }), errors };
+}
+
+export function adaptBrowserEvidence(value, options = {}) {
+  const errors = validateBrowserEvidence(value);
+  return { record: errors.length ? null : recordFrom(value, { ...options, kind: 'browser-e2e', producer: options.producer ?? 'lighthouse-sdlc' }), errors };
+}
+
+function hash(value) {
+  return createHash('sha256').update(JSON.stringify(value)).digest('hex');
+}
+
+function coverageStatus(records) {
+  if (!records.length) return 'unverified';
+  const statuses = new Set(records.map((item) => item.status));
+  if (statuses.size === 1 && statuses.has('passed')) return 'verified';
+  if (statuses.has('failed') && statuses.size > 1) return 'conflict';
+  if (statuses.has('failed') || statuses.has('unavailable') || statuses.has('unconfigured') || statuses.has('pending-review')) return 'incomplete';
+  if (statuses.size === 1 && statuses.has('not-applicable')) return 'not-applicable';
+  return 'observed';
+}
+
+export function buildEvidenceIndex(records, { indexId = 'evidence-index', runId, repository, revision, subjects = [], recordPaths = {} } = {}) {
+  const errors = [];
+  if (!Array.isArray(records) || records.length === 0) errors.push(issue('evidence.index-records', 'records must contain at least one evidence record', 'records'));
+  const validRecords = Array.isArray(records) ? records : [];
+  for (const [index, item] of validRecords.entries()) for (const error of validateEvidenceRecord(item)) errors.push({ ...error, field: error.field ? `records[${index}].${error.field}` : `records[${index}]` });
+  const ids = new Set();
+  for (const [index, item] of validRecords.entries()) {
+    if (ids.has(item.id)) errors.push(issue('evidence.duplicate-id', `records[${index}] duplicates evidence id ${item.id}`, `records[${index}].id`));
+    ids.add(item.id);
+  }
+  const effectiveRunId = runId ?? validRecords[0]?.runId;
+  if (!text(effectiveRunId)) errors.push(issue('evidence.index-run-id', 'runId must be provided or present on every record', 'runId'));
+  const expected = [...subjects, ...validRecords.filter((item) => item.subject).map((item) => item.subject)];
+  const subjectMap = new Map();
+  for (const item of expected) if (validSubject(item)) subjectMap.set(subjectKey(item), item);
+  const refs = validRecords.map((item) => clean({ id: item.id, path: recordPaths[item.id] ?? `records/${item.id}.json`, sha256: hash(item), kind: item.kind, status: item.status, subject: item.subject, authorityRefs: item.authorityRefs }));
+  const coverage = [...subjectMap.entries()].map(([key, subject]) => {
+    const related = validRecords.filter((item) => item.subject && subjectKey(item.subject) === key);
+    const status = coverageStatus(related);
+    return clean({ subject, status, evidenceIds: related.map((item) => item.id), nextAction: status === 'verified' || status === 'not-applicable' ? undefined : `Collect or resolve evidence for ${key}.` });
+  });
+  if (errors.length) return { index: null, errors };
+  return {
+    index: clean({ schemaVersion: 1, indexId, runId: effectiveRunId, repository, revision, records: refs, coverage }),
+    errors: [],
+  };
+}
+
+export function validateEvidenceIndex(value) {
+  const errors = [];
+  if (!record(value)) return [issue('evidence-index.invalid', 'evidence index must be an object')];
+  if (value.schemaVersion !== 1) errors.push(issue('evidence-index.schema-version', 'schemaVersion must be 1', 'schemaVersion'));
+  for (const field of ['indexId', 'runId']) if (!text(value[field])) errors.push(issue(`evidence-index.${field}`, `${field} must be a non-empty string`, field));
+  if (!Array.isArray(value.records)) errors.push(issue('evidence-index.records', 'records must be an array', 'records'));
+  else {
+    const ids = new Set();
+    for (const [index, item] of value.records.entries()) {
+      if (!record(item) || !text(item.id) || !relativePath(item.path) || !/^[a-f0-9]{64}$/u.test(item.sha256) || !text(item.kind) || !evidenceStatusSet.has(item.status)) errors.push(issue('evidence-index.record-ref', `records[${index}] needs id, relative path, SHA-256, kind and status`, `records[${index}]`));
+      if (item?.id && ids.has(item.id)) errors.push(issue('evidence-index.duplicate-id', `records[${index}] duplicates evidence id ${item.id}`, `records[${index}].id`));
+      if (item?.id) ids.add(item.id);
+      if (item?.subject !== undefined && !validSubject(item.subject)) errors.push(issue('evidence-index.subject', `records[${index}].subject needs a type and id`, `records[${index}].subject`));
+      validateAuthorityRefs(item?.authorityRefs, errors, `records[${index}].authorityRefs`);
+    }
+  }
+  if (!Array.isArray(value.coverage)) errors.push(issue('evidence-index.coverage', 'coverage must be an array', 'coverage'));
+  else {
+    const subjects = new Set();
+    for (const [index, item] of value.coverage.entries()) {
+      if (!record(item) || !validSubject(item.subject) || !coverageStatusSet.has(item.status) || !Array.isArray(item.evidenceIds)) errors.push(issue('evidence-index.coverage-entry', `coverage[${index}] needs subject, status and evidenceIds`, `coverage[${index}]`));
+      const key = item?.subject && validSubject(item.subject) ? subjectKey(item.subject) : null;
+      if (key && subjects.has(key)) errors.push(issue('evidence-index.coverage-duplicate', `coverage[${index}] duplicates subject ${key}`, `coverage[${index}].subject`));
+      if (key) subjects.add(key);
+    }
+  }
+  return errors;
+}
+
+export function evidenceReport(value) {
+  const errors = value?.kind ? validateEvidenceRecord(value) : validateEvidenceIndex(value);
+  return { schemaVersion: 1, status: errors.length ? 'invalid' : 'valid', valid: errors.length === 0, errors };
+}
+
+export async function readEvidenceIndex(path, cwd = process.cwd()) {
+  const value = JSON.parse(await readFile(resolve(cwd, path), 'utf8'));
+  return { value, errors: validateEvidenceIndex(value) };
+}