@juangcarmona/lighthouse-sdlc 0.7.0 → 0.9.0

package/README.md

@@ -8,8 +8,28 @@ 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.
 
+## External host contract
+
+`src/host-contract.mjs` validates a supervised `triage` or `refine` request against a trusted host policy and validates the resulting stage/effect envelope. It is exported as `@juangcarmona/lighthouse-sdlc/host-contract`. See [the wire contract](host-contract.md) for fields and host obligations. Execution, credentials, admission, cancellation and publication remain host responsibilities.
+
+Print the opt-in GitHub adapter with `node node_modules/@juangcarmona/lighthouse-sdlc/src/host-contract.mjs workflow`. It expects a provisioned `lighthouse-host-bridge` on a repository runner labelled `lighthouse-host`. Installing the package does not enable that adapter. The existing gh-aw projection remains a separate execution path.
+
+## 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.
+
+Workers resolve instructions and validators from the installed SDLC package and reject a version mismatch with `.lighthouse/sdlc.json` before execution. Consumers need a committed npm lockfile.
+
+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. The current worker host cannot verify human gate decisions, so it rejects `ff` for every bundled route. Use individual stage dispatches under host supervision until an approval adapter exists. The `integrate` worker prepares the configured merge action without merging unless repository policy authorizes it; `review` closes the flow with `gate: null`.
+
+Workers require `stage-result --require-complete --stage <stage> --run-id <id>` before reporting success. This checks the dispatched identity, the gate in `stages.json`, `status: passed`, empty blocker arrays and resolved evidence statuses. Plain `stage-result --input <file>` still validates the structure of reports, including blocked reports. Completion validation does not verify evidence provenance or grant approval to cross a human gate; the host owns those checks.
+
 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 +38,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/commands/stage-result.md

@@ -1,3 +1,3 @@
 # `/lighthouse:stage-result`
 
-Validate the structured result of a lifecycle stage before a route consumes its evidence or advances its gate.
+Use `lighthouse-sdlc stage-result --input <file>` to validate a report's structure, including unresolved reports. Before reporting worker success, add `--require-complete --stage <stage> --run-id <id>` to require the dispatched identity, the declared gate, a passed status and no unresolved evidence or blockers. Host approval remains necessary to cross human gates.

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/host-contract.md

@@ -0,0 +1,38 @@
+# Supervised external host contract
+
+Schema version 1 supports one triage or refinement stage. The executable validator in `src/host-contract.mjs` is authoritative; unknown request and effect fields fail validation. Hosts install an exact package version outside the execution workspace.
+
+## Request
+
+| Field | Meaning |
+| --- | --- |
+| `schemaVersion` | `1`. |
+| `runId` | SHA-256 event identity, stable across delivery retries. |
+| `repository`, `issue` | Registered repository and positive issue number. |
+| `stage`, `route` | `triage` or `refine`, with route `supervised`. |
+| `sourceRevision` | Immutable source commit. |
+| `workflowRevision`, `workflowRunId` | Trusted workflow commit and positive GitHub Actions run identifier. |
+| `packageVersion`, `policyDigest` | Exact installed SDLC version and SHA-256 of the host policy file bytes. |
+| `deadline` | Future timestamp within the host's `maxSeconds` limit (at most one hour). |
+| `writeScope` | Empty array for these read-only stages. |
+| `predecessor`, `approvalCommentId` | Both null for triage. Refine requires `{runId, resultDigest}` and a positive owner decision comment identifier. |
+
+A host policy declares `repository`, `owner`, `stages`, `workflowRevision`, `packageVersion` and `maxSeconds`. Policy is provisioned by the operator and is never supplied by the engine. The host must authenticate the caller and verify workflow identity, current source, policy and owner decision with their authoritative providers. Passing local JSON validation alone does not establish provenance.
+
+## Result and effect
+
+The engine writes `{schemaVersion: 1, result, effect}`. `result` follows the existing stage-result contract and must match the admitted run, stage and gate. A `passed` result must also pass completion validation. `ready`, `blocked` and `failed` remain distinct reports; none approves a human gate.
+
+The only effect is `{type: "issue-comment", body: "..."}` with 1–16000 characters. The engine cannot select a repository, issue, credential or merge action. The publisher reserves `<!-- lighthouse-run:` markers and derives the destination from admission. It may publish clarification or blocked-stage reports but must never treat those as completed stages.
+
+Before applying an effect, the host rechecks authority and work-item freshness, persists publication intent and fences the publisher. It retains an immutable receipt or an explicit uncertain outcome. A retry must reconcile that outcome before emitting another effect. A completed stage waits for a verifiable owner decision; the envelope itself grants no approval.
+
+## Commands
+
+```sh
+node node_modules/@juangcarmona/lighthouse-sdlc/src/host-contract.mjs request request.json policy.json
+node node_modules/@juangcarmona/lighthouse-sdlc/src/host-contract.mjs context request.json issue.json predecessor.json
+node node_modules/@juangcarmona/lighthouse-sdlc/src/host-contract.mjs result request.json envelope.json
+```
+
+Omit `predecessor.json` for triage. Context contains trusted stage instructions plus untrusted issue/source references; the host keeps source read-only and supplies only an output directory. The result command does not execute or publish anything.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juangcarmona/lighthouse-sdlc",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Provider-neutral SDLC skills, commands and route contracts for Lighthouse adopters",
   "repository": {
@@ -27,10 +27,12 @@
     "gates.json",
     "meta-commands",
     "README.md",
+    "host-contract.md",
     "routes.json",
     "stages.json",
     "schemas",
     "skills",
+    "workflows",
     "src"
   ],
   "bin": {
@@ -51,6 +53,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 +64,12 @@
     "./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/*",
+    "./host-contract": "./src/host-contract.mjs"
   }
 }

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

@@ -1,3 +1,6 @@
+import stageContract from '../stages.json' with { type: 'json' };
+import resultSchema from '../schemas/stage-result.schema.json' with { type: 'json' };
+
 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']);
@@ -19,6 +22,7 @@ function isRecord(value) {
 export function validateStageResult(value) {
   const errors = [];
   if (!isRecord(value)) return [issue('stage-result.invalid', 'stage result must be an object')];
+  for (const key of Object.keys(value)) if (!(Object.hasOwn(resultSchema.properties, key))) errors.push(issue('stage-result.unknown-field', `${key} is unsupported`, key));
   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'));
@@ -26,6 +30,10 @@ export function validateStageResult(value) {
   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)) {
+      for (const key of Object.keys(evidence)) if (!(Object.hasOwn(resultSchema.properties.evidence.items.properties, key))) errors.push(issue('stage-result.evidence-field', `evidence[${index}].${key} is unsupported`, `evidence[${index}]`));
+      for (const key of ['source', 'reason']) if (evidence[key] !== undefined && typeof evidence[key] !== 'string') errors.push(issue('stage-result.evidence-field', `evidence[${index}].${key} must be a string`, `evidence[${index}]`));
+    }
     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));
@@ -37,3 +45,22 @@ export function validateStageResult(value) {
 export function isValidStageResult(value) {
   return validateStageResult(value).length === 0;
 }
+
+export function validateStageCompletion(value, { stage, runId } = {}) {
+  const errors = validateStageResult(value);
+  const expected = stageContract.stages.find((item) => item.id === stage);
+  if (!expected) errors.push(issue('stage-completion.expected-stage', 'a declared expected stage is required'));
+  if (typeof runId !== 'string' || !runId.trim()) errors.push(issue('stage-completion.expected-run', 'a non-empty expected runId is required'));
+  if (!isRecord(value)) return errors;
+  if (value.stage !== stage) errors.push(issue('stage-completion.stage', 'result stage does not match the dispatched stage', 'stage'));
+  if (expected && value.gate !== expected.gate) errors.push(issue('stage-completion.gate', 'result gate does not match stages.json', 'gate'));
+  if (value.runId !== runId) errors.push(issue('stage-completion.run', 'result runId does not match the dispatched run', 'runId'));
+  if (value.status !== 'passed') errors.push(issue('stage-completion.status', 'only a passed result can complete a worker', 'status'));
+  for (const field of ['missingEvidence', 'unavailableChecks', 'pendingReview']) {
+    if (Array.isArray(value[field]) && value[field].length) errors.push(issue(`stage-completion.${field}`, `${field} must be empty to complete a worker`, field));
+  }
+  if (Array.isArray(value.evidence)) for (const [index, evidence] of value.evidence.entries()) {
+    if (!['passed', 'not-applicable'].includes(evidence?.status)) errors.push(issue('stage-completion.evidence', 'unresolved evidence prevents worker completion', `evidence[${index}]`));
+  }
+  return errors;
+}

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