@juangcarmona/lighthouse-sdlc 0.7.0 → 0.8.0

package/README.md

@@ -8,8 +8,18 @@ It publishes `command-aliases.json` as the versioned, machine-readable mapping f
 
 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.
@@ -18,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/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", "aliases", "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,6 +25,8 @@
     "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",
     "commandAliases": "command-aliases.json",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -31,6 +31,7 @@
     "stages.json",
     "schemas",
     "skills",
+    "workflows",
     "src"
   ],
   "bin": {
@@ -51,6 +52,7 @@
     "./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",
@@ -61,8 +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",
+    "./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"
+    "./schemas/command-aliases.schema.json": "./schemas/command-aliases.schema.json",
+    "./workflows/*": "./workflows/*"
   }
 }

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/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) };
+}

package/src/sdlc.mjs

@@ -14,6 +14,7 @@ import { validateMemoryRecord } from './memory.mjs';
 import { replayWorkflow } from './workflow.mjs';
 import { validateStageResult } from './contracts.mjs';
 import { browserEvidenceReport } from './browser-e2e.mjs';
+import { buildEvidenceIndex, evidenceReport, validateEvidenceIndex, validateEvidenceRecord } from './evidence.mjs';
 import { readCapabilityCatalog, validateCapabilityCatalog } from './capabilities.mjs';
 import { readCommandAliases, validateCommandAliases, verifyCommandAliases } from './aliases.mjs';
 
@@ -41,10 +42,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, contract.assets?.browserE2eSchema, contract.assets?.commandAliases, contract.assets?.commandAliasesSchema]) {
+  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, contract.assets?.evidenceRecordSchema, contract.assets?.evidenceIndexSchema, contract.assets?.commandAliases, contract.assets?.commandAliasesSchema]) {
     if (!asset || !(await exists(resolve(packageRoot, asset)))) problems.push(`missing contract asset ${asset ?? '(empty)'}`);
   }
-  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'command-aliases.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', 'schemas/command-aliases.schema.json', 'src/aliases.mjs', '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']) {
+  for (const asset of ['routes.json', 'gates.json', 'stages.json', 'command-aliases.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', 'schemas/evidence-record.schema.json', 'schemas/evidence-index.schema.json', 'schemas/command-aliases.schema.json', 'src/aliases.mjs', 'src/browser-e2e.mjs', 'src/evidence.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 {
@@ -190,6 +191,44 @@ async function runBrowserE2e(args) {
   if (!report.valid || report.status !== 'passed') process.exit(1);
 }
 
+async function runEvidence(args) {
+  const inputPath = option(args, '--input');
+  const outputPath = option(args, '--output');
+  const format = option(args, '--format') ?? 'json';
+  const build = args.includes('--build');
+  if (!inputPath || !['json', 'text'].includes(format) || (build && !outputPath)) {
+    console.error('Usage: lighthouse-sdlc evidence --input <record|index|records.json> [--build --output <index.json>] [--format <json|text>]');
+    process.exit(2);
+  }
+  const input = await readJson(resolve(process.cwd(), inputPath));
+  let report;
+  if (build) {
+    const result = buildEvidenceIndex(input.records, input);
+    report = { schemaVersion: 1, status: result.errors.length ? 'invalid' : 'valid', valid: result.errors.length === 0, index: result.index, errors: result.errors };
+    if (result.index) {
+      const output = resolve(process.cwd(), outputPath);
+      await mkdir(dirname(output), { recursive: true });
+      for (const reference of result.index.records) {
+        const record = input.records.find((item) => item.id === reference.id);
+        const recordPath = resolve(dirname(output), reference.path);
+        await mkdir(dirname(recordPath), { recursive: true });
+        await writeFile(recordPath, `${JSON.stringify(record, null, 2)}\n`);
+      }
+      await writeFile(output, `${JSON.stringify(result.index, null, 2)}\n`);
+    }
+  } else {
+    const errors = input?.kind ? validateEvidenceRecord(input) : validateEvidenceIndex(input);
+    report = { ...evidenceReport(input), errors };
+  }
+  if (format === 'json') output(report, format);
+  else {
+    console.log(`Evidence: ${report.status}`);
+    for (const error of report.errors) console.error(`  ${error.code}: ${error.message}`);
+    if (report.index) console.log(`  Coverage entries: ${report.index.coverage.length}`);
+  }
+  if (!report.valid) process.exit(1);
+}
+
 async function runMemory(args) {
   const inputPath = option(args, '--input');
   const policyPath = option(args, '--policy');
@@ -348,8 +387,8 @@ async function runGithubLabels(args) {
 }
 
 const command = process.argv[2] ?? 'verify';
-if (!['contract', 'verify', 'aliases', '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|aliases|triage|state|stage-result|browser-e2e|control-plane|memory|launch|decompose|stacked|route|github-triage|github-decompose|reconcile-labels|github-labels>');
+if (!['contract', 'verify', 'aliases', 'triage', 'state', 'stage-result', 'browser-e2e', 'evidence', 'control-plane', 'memory', 'launch', 'decompose', 'stacked', 'route', 'github-triage', 'github-decompose', 'reconcile-labels', 'github-labels'].includes(command)) {
+  console.error('Usage: lighthouse-sdlc <contract|verify|aliases|triage|state|stage-result|browser-e2e|evidence|control-plane|memory|launch|decompose|stacked|route|github-triage|github-decompose|reconcile-labels|github-labels>');
   process.exit(2);
 }
 if (command === 'contract') {
@@ -366,6 +405,8 @@ if (command === 'contract') {
   await runStageResult(process.argv.slice(3));
 } else if (command === 'browser-e2e') {
   await runBrowserE2e(process.argv.slice(3));
+} else if (command === 'evidence') {
+  await runEvidence(process.argv.slice(3));
 } else if (command === 'memory') {
   await runMemory(process.argv.slice(3));
 } else if (command === 'launch') {
@@ -393,4 +434,4 @@ if (command === 'contract') {
   console.log('Lighthouse SDLC package contract is valid.');
 }
 
-export { contractPath, runTriage, verifyContract, runAliases, runState, runStageResult, runBrowserE2e, runControlPlane, runMemory, runLaunch, runDecompose, runRoute, runStacked, runGithubTriage, runGithubDecompose, runReconcileLabels, runGithubLabels };
+export { contractPath, runTriage, verifyContract, runAliases, runState, runStageResult, runBrowserE2e, runEvidence, runControlPlane, runMemory, runLaunch, runDecompose, runRoute, runStacked, runGithubTriage, runGithubDecompose, runReconcileLabels, runGithubLabels };