@adlc/gate-manifest 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chris Williams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,149 @@
+# gate-manifest
+
+**ADLC C11 — cross-cutting provenance.** A hash-chained evidence ledger that records what each ADLC gate verified, proving to auditors (and CI) that agentic code was checked before it shipped. Set `ADLC_MANIFEST_KEY` to add HMAC-SHA256 signatures so the chain attests *authorship*, not just internal consistency (see [Signing & provenance](#signing--provenance)).
+
+## ADLC phase
+
+Serves **C11** (cross-cutting provenance / agentic SLSA). Consumed by **P6 human-gate** reviewers who need `attest` output as a PR comment, and by **CI** which runs `verify` as a blocking gate.
+
+## Usage
+
+```
+gate-manifest record <gate-name> [--ticket id] [--data '{json}'] [--files a,b,c] [--dir path] [--json]
+gate-manifest verify [--json] [--dir path]
+gate-manifest show   [--ticket id] [--json] [--dir path]
+gate-manifest attest [--ticket id] [--dir path]
+```
+
+### record
+
+Append one entry to `.adlc/manifest.jsonl`.
+
+```sh
+gate-manifest record spec-lint --ticket T-42 --data '{"model":"haiku","pass":true}' --files src/foo.mjs,src/bar.mjs
+```
+
+The entry stored:
+
+```json
+{
+  "seq": 3,
+  "gate": "spec-lint",
+  "ticket": "T-42",
+  "ts": "2024-01-01T00:00:00.000Z",
+  "data": { "model": "haiku", "pass": true },
+  "files": { "src/foo.mjs": "<sha256>", "src/bar.mjs": "<sha256>" },
+  "prev": "<sha256 of the previous raw JSONL line, or null>",
+  "sig": "<HMAC-SHA256 over the canonical entry bytes — present only when ADLC_MANIFEST_KEY is set>"
+}
+```
+
+When `ADLC_MANIFEST_KEY` is set, `record` appends a `sig` (the human output prints `(signed)` / `(unsigned)`). See **Signing & provenance** below.
+
+| Flag | Description |
+|------|-------------|
+| `--ticket id` | Associate this entry with a ticket id (optional) |
+| `--data '{json}'` | Arbitrary JSON payload (must be valid JSON; malformed → exit 1) |
+| `--files a,b,c` | Comma-separated paths; each is SHA-256 hashed (missing files hash to null) |
+| `--dir path` | Override ledger directory (default `.adlc`) |
+| `--json` | Print the recorded entry as JSON |
+
+### verify
+
+Walk the raw ledger lines and validate the hash chain. Every entry's `prev` must equal `sha256` of the exact raw bytes of the previous line; sequence numbers must be strictly monotonically increasing.
+
+```sh
+gate-manifest verify          # human-readable
+gate-manifest verify --json   # machine-readable
+```
+
+**Exit 0** when valid (or empty manifest). **Exit 2** when the chain is broken — reports the seq and line number of the first break.
+
+When `ADLC_MANIFEST_KEY` is set, `verify` additionally checks every entry's HMAC signature. A missing sig (`unsigned entry`) or a wrong sig (`signature invalid`) breaks the chain. The JSON result includes `signed: true` only when a key was present and every entry verified cryptographically; otherwise `signed: false`.
+
+| Flag | Description |
+|------|-------------|
+| `--json` | Emit `{ valid, message, count, signed, break }` |
+| `--dir path` | Override ledger directory |
+
+### show
+
+Print entries from the ledger, optionally filtered by ticket.
+
+```sh
+gate-manifest show
+gate-manifest show --ticket T-42
+gate-manifest show --ticket T-42 --json
+```
+
+| Flag | Description |
+|------|-------------|
+| `--ticket id` | Filter to entries with this ticket id |
+| `--json` | Emit `{ entries, skipped }` |
+| `--dir path` | Override ledger directory |
+
+### attest
+
+Generate a Markdown summary suitable for a PR comment.
+
+```sh
+gate-manifest attest --ticket T-42
+```
+
+Output example:
+
+```markdown
+## Gate evidence for T-42
+
+| seq | gate | ts | files | data |
+|-----|------|-----|-------|------|
+| 1 | spec-lint | 2024-01-01T… | 0 | — |
+| 2 | hollow-test | 2024-01-01T… | 3 | model=haiku |
+
+Chain status: **valid** (2 entries)
+```
+
+| Flag | Description |
+|------|-------------|
+| `--ticket id` | Filter entries and use ticket id in heading |
+| `--dir path` | Override ledger directory |
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Gate passes (record, show, attest always; verify when chain is valid) |
+| 1 | Operational error (bad input, unreadable file, malformed `--data` JSON) |
+| 2 | Gate fails (verify detects chain break) |
+
+## Chain integrity
+
+`record` reads the ledger file via `readFileSync` (raw bytes) — never via `readEntries` which re-serialises and would lose byte-exact fidelity. The `prev` field is `sha256(previous raw JSONL line)` (null for the first entry). Tampering any middle line breaks all subsequent `prev` hashes, detected by `verify`.
+
+## Signing & provenance
+
+The hash chain alone proves **internal consistency**, not **authorship**. `sha256` is a public, keyless function: anyone who can write `manifest.jsonl` can recompute every `prev` and forge a clean chain from scratch. On its own the chain is therefore *not* cryptographic provenance — do not represent a hash-chain-only pass as in-toto/SLSA attestation.
+
+To get real provenance, set a secret signing key:
+
+```sh
+export ADLC_MANIFEST_KEY="$(openssl rand -hex 32)"   # store in your CI secret manager, never in the repo
+gate-manifest record spec-lint --ticket T-42
+gate-manifest verify --json    # → { ..., "signed": true }
+```
+
+- **record** computes `sig = HMAC-SHA256(key, canonicalEntryBytes)`. The signed bytes are the deterministic JSON of `{ seq, gate, ts, ticket?, data?, files, prev }` in that fixed key order (optional `ticket`/`data` included only when present), **excluding** `sig` itself. `sig` is appended last.
+- **verify** (run with the key) requires every entry to carry a valid sig — comparison is constant-time (`crypto.timingSafeEqual`). A missing sig → `unsigned entry`; a wrong sig → `signature invalid`. Either breaks the chain (exit 2). This defeats the forge-from-scratch attack: without the key, an attacker cannot produce valid signatures.
+- **verify** without a key still checks the hash chain but reports `signed: false`, so callers cannot claim cryptographic provenance.
+
+Zero-dependency: HMAC comes from Node's built-in `node:crypto`. Key management (rotation, distribution) is out of scope for this tool — supply the key via the environment.
+
+## Sibling tools
+
+- `rails-guard` (C5) — appends its own proof here after verifying diff is rails-clean.
+- `hollow-test` (C4) — appends coverage and mutation results.
+- `review-calibration` (C8) — appends prosecution verdicts and calibration score.
+
+## Core gaps
+
+None for ledger/CLI primitives — `sha256`, `hashFiles`, `appendEntry`, `readEntries`, `ledgerPath`, `ADLC_DIR`, `parseArgs`, `pass`, `gateFail`, `opError`, `printJson` from `@adlc/core` cover them. Core exposes `sha256` but no keyed-MAC primitive, so HMAC signing uses Node's built-in `node:crypto` (`createHmac`, `timingSafeEqual`) directly in `lib/sign.mjs` — still zero runtime dependencies.

package/bin/gate-manifest.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+// gate-manifest — ADLC C11 hash-chained agentic provenance ledger.
+// Verbs: record | verify | show | attest
+
+import { parseArgs, pass, gateFail, opError, printJson } from '@adlc/core';
+import { record, parseData } from '../lib/record.mjs';
+import { verify } from '../lib/verify.mjs';
+import { loadFiltered, renderEntries } from '../lib/show.mjs';
+import { buildAttest } from '../lib/attest.mjs';
+import { ADLC_DIR } from '@adlc/core';
+
+const { values: flags, positionals } = parseArgs({
+  options: {
+    ticket: { type: 'string' },
+    data:   { type: 'string' },
+    files:  { type: 'string' },
+    json:   { type: 'boolean', default: false },
+    dir:    { type: 'string', default: ADLC_DIR },
+  },
+});
+
+const verb = positionals[0];
+
+if (!verb) {
+  opError(
+    'usage: gate-manifest <verb> [options]\n' +
+    'verbs: record <gate-name> [--ticket id] [--data \'{json}\'] [--files a,b,c]\n' +
+    '       verify [--json]\n' +
+    '       show   [--ticket id] [--json]\n' +
+    '       attest [--ticket id]'
+  );
+}
+
+// ── record ──────────────────────────────────────────────────────────────────
+if (verb === 'record') {
+  const gate = positionals[1];
+  if (!gate) {
+    opError('usage: gate-manifest record <gate-name> [--ticket id] [--data \'{json}\'] [--files a,b,c]');
+  }
+
+  // Validate --data early so we get opError (exit 1) on bad JSON
+  try {
+    parseData(flags.data);
+  } catch (err) {
+    opError(err.message);
+  }
+
+  let entry;
+  try {
+    entry = record({
+      gate,
+      ticket: flags.ticket,
+      rawData: flags.data,
+      rawFiles: flags.files,
+      dir: flags.dir,
+    });
+  } catch (err) {
+    opError(err.message);
+  }
+
+  if (flags.json) {
+    printJson(entry);
+  } else {
+    const signed = typeof entry.sig === 'string' ? ' (signed)' : ' (unsigned)';
+    console.log(`recorded: seq=${entry.seq} gate=${entry.gate} ts=${entry.ts}${signed}`);
+  }
+
+  pass();
+}
+
+// ── verify ───────────────────────────────────────────────────────────────────
+if (verb === 'verify') {
+  const result = verify(flags.dir);
+
+  if (flags.json) {
+    printJson(result);
+  } else {
+    console.log(result.message);
+  }
+
+  if (result.valid) {
+    pass();
+  } else {
+    gateFail(`gate-manifest verify: ${result.message}`);
+  }
+}
+
+// ── show ─────────────────────────────────────────────────────────────────────
+if (verb === 'show') {
+  const { entries, skipped } = loadFiltered({ ticket: flags.ticket, dir: flags.dir });
+
+  if (flags.json) {
+    printJson({ entries, skipped });
+  } else {
+    const lines = renderEntries(entries);
+    for (const l of lines) console.log(l);
+    if (skipped.length > 0) {
+      console.warn(`warning: ${skipped.length} malformed line(s) skipped`);
+    }
+  }
+
+  pass();
+}
+
+// ── attest ───────────────────────────────────────────────────────────────────
+if (verb === 'attest') {
+  const md = buildAttest({ ticket: flags.ticket, dir: flags.dir });
+  console.log(md);
+  pass();
+}
+
+// Unknown verb
+opError(`unknown verb: ${verb}. Expected: record | verify | show | attest`);

package/lib/attest.mjs

@@ -0,0 +1,63 @@
+// attest.mjs — generate markdown gate evidence for a ticket (PR comment ready).
+
+import { verify } from './verify.mjs';
+import { loadFiltered } from './show.mjs';
+import { ADLC_DIR } from '@adlc/core';
+
+/**
+ * Summarise the `data` field of an entry for the attest table.
+ * Returns a short string.
+ */
+function dataSummary(data) {
+  if (!data || typeof data !== 'object') return '—';
+  const keys = Object.keys(data);
+  if (keys.length === 0) return '—';
+  // Show first two key=value pairs, truncated
+  return keys
+    .slice(0, 2)
+    .map(k => {
+      const v = String(data[k]);
+      return `${k}=${v.length > 20 ? v.slice(0, 17) + '...' : v}`;
+    })
+    .join(', ');
+}
+
+/**
+ * Build the attest markdown for a (possibly filtered) set of entries.
+ *
+ * @param {object} opts
+ * @param {string|undefined} opts.ticket  ticket id to filter on (also used in heading)
+ * @param {string} [opts.dir]  ledger directory (default ADLC_DIR)
+ * @returns {string}  markdown text
+ */
+export function buildAttest({ ticket, dir = ADLC_DIR } = {}) {
+  const { entries } = loadFiltered({ ticket, dir });
+  const chainResult = verify(dir);
+
+  const heading = ticket
+    ? `## Gate evidence for ${ticket}`
+    : '## Gate evidence';
+
+  const lines = [heading, ''];
+
+  if (entries.length === 0) {
+    lines.push('_No entries found._', '');
+  } else {
+    lines.push('| seq | gate | ts | files | data |');
+    lines.push('|-----|------|-----|-------|------|');
+    for (const e of entries) {
+      const fileCount = e.files ? Object.keys(e.files).length : 0;
+      const ds = dataSummary(e.data);
+      lines.push(`| ${e.seq} | ${e.gate} | ${e.ts} | ${fileCount} | ${ds} |`);
+    }
+    lines.push('');
+  }
+
+  const chainStatus = chainResult.valid
+    ? `Chain status: **valid** (${chainResult.count} entries)`
+    : `Chain status: **BROKEN** — ${chainResult.message}`;
+
+  lines.push(chainStatus);
+
+  return lines.join('\n');
+}

package/lib/record.mjs

@@ -0,0 +1,119 @@
+// record.mjs — build and append a manifest entry.
+// IMPORTANT: chain integrity depends on sha256(raw previous line bytes),
+// so we read the ledger file directly via readFileSync — never via readEntries
+// which parses and re-serialises, losing byte-exact fidelity.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { sha256, hashFiles, appendEntry, ledgerPath, ADLC_DIR } from '@adlc/core';
+import { getKey, signEntry } from './sign.mjs';
+
+/**
+ * Parse JSON data from a --data flag string.
+ * Returns parsed object or throws with a clear message.
+ */
+export function parseData(raw) {
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`--data is not valid JSON: ${err.message}`);
+  }
+}
+
+/**
+ * Parse a comma-separated file list from --files flag string.
+ * Returns array of trimmed non-empty paths.
+ */
+export function parseFileList(raw) {
+  if (!raw) return [];
+  return raw.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Read the last raw line (non-empty) from a ledger file.
+ * Returns null if the file does not exist or has no non-empty lines.
+ */
+export function readLastRawLine(filePath) {
+  if (!existsSync(filePath)) return null;
+  const content = readFileSync(filePath, 'utf8');
+  // Split on newline but keep exact bytes by splitting the buffer
+  const lines = content.split('\n');
+  // Walk backwards to find the last non-empty line
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (lines[i].trim()) return lines[i];
+  }
+  return null;
+}
+
+/**
+ * Build a new manifest entry object (pure, side-effect-free).
+ *
+ * @param {object} opts
+ * @param {string} opts.gate        gate name
+ * @param {string|undefined} opts.ticket  ticket id (optional)
+ * @param {object|undefined} opts.data   parsed JSON data (optional)
+ * @param {string[]} opts.filePaths  list of files to hash
+ * @param {string|null} opts.prevRawLine  raw bytes of the previous JSONL line (or null)
+ * @param {number} opts.prevSeq     sequence number of previous entry (0 if none)
+ * @param {string} opts.ts          ISO timestamp
+ * @param {string|null} [opts.key]  HMAC signing key; when present, entry gets a `sig`
+ * @returns manifest entry object
+ */
+export function buildEntry({ gate, ticket, data, filePaths, prevRawLine, prevSeq, ts, key = null }) {
+  const entry = {
+    seq: prevSeq + 1,
+    gate,
+    ts,
+  };
+
+  if (ticket !== undefined) entry.ticket = ticket;
+  if (data !== undefined) entry.data = data;
+
+  entry.files = filePaths.length > 0 ? hashFiles(filePaths) : {};
+  entry.prev = prevRawLine !== null ? sha256(prevRawLine) : null;
+
+  // Sign last: `sig` is computed over the canonical bytes of all other fields
+  // (see sign.mjs) and appended as the final field so it is excluded from the
+  // signed payload. Without a key the entry is unsigned and verify will flag it.
+  if (key) entry.sig = signEntry(key, entry);
+
+  return entry;
+}
+
+/**
+ * Record a new entry in the manifest ledger.
+ *
+ * @param {object} opts
+ * @param {string} opts.gate
+ * @param {string|undefined} opts.ticket
+ * @param {string|undefined} opts.rawData   raw --data string (parsed here)
+ * @param {string|undefined} opts.rawFiles  raw --files string (parsed here)
+ * @param {string} [opts.dir]  ledger directory (default ADLC_DIR)
+ * @returns the recorded entry object
+ * @throws Error for malformed --data JSON
+ */
+export function record({ gate, ticket, rawData, rawFiles, dir = ADLC_DIR }) {
+  const data = parseData(rawData);
+  const filePaths = parseFileList(rawFiles);
+
+  const lp = ledgerPath('manifest', dir);
+  const prevRawLine = readLastRawLine(lp);
+
+  // Determine previous seq by parsing the last raw line if present
+  let prevSeq = 0;
+  if (prevRawLine !== null) {
+    try {
+      const parsed = JSON.parse(prevRawLine);
+      prevSeq = typeof parsed.seq === 'number' ? parsed.seq : 0;
+    } catch {
+      // Malformed last line; still record but seq continues from 0
+    }
+  }
+
+  const ts = new Date().toISOString();
+  const key = getKey();
+  const entry = buildEntry({ gate, ticket, data, filePaths, prevRawLine, prevSeq, ts, key });
+
+  appendEntry('manifest', entry, dir);
+  return entry;
+}

package/lib/show.mjs

@@ -0,0 +1,57 @@
+// show.mjs — render manifest entries (with optional ticket filter).
+
+import { readEntries, ADLC_DIR } from '@adlc/core';
+
+/**
+ * Load entries from the manifest ledger, optionally filtered by ticket id.
+ *
+ * @param {object} opts
+ * @param {string|undefined} opts.ticket  filter to entries with this ticket id
+ * @param {string} [opts.dir]  ledger directory (default ADLC_DIR)
+ * @returns {{ entries: object[], skipped: object[] }}
+ */
+export function loadFiltered({ ticket, dir = ADLC_DIR } = {}) {
+  const { entries, skipped } = readEntries('manifest', dir);
+  const filtered = ticket
+    ? entries.filter(e => e.ticket === ticket)
+    : entries;
+  return { entries: filtered, skipped };
+}
+
+/**
+ * Render a single entry as a human-readable string array.
+ * @param {object} entry
+ * @returns {string[]}
+ */
+export function renderEntry(entry) {
+  const lines = [];
+  lines.push(`seq=${entry.seq}  gate=${entry.gate}  ts=${entry.ts}`);
+  if (entry.ticket) lines.push(`  ticket: ${entry.ticket}`);
+  if (entry.data && Object.keys(entry.data).length > 0) {
+    lines.push(`  data: ${JSON.stringify(entry.data)}`);
+  }
+  const fileCount = entry.files ? Object.keys(entry.files).length : 0;
+  if (fileCount > 0) {
+    lines.push(`  files (${fileCount}):`);
+    for (const [path, hash] of Object.entries(entry.files)) {
+      lines.push(`    ${path}: ${hash ?? 'null'}`);
+    }
+  }
+  lines.push(`  prev: ${entry.prev ?? 'null'}`);
+  return lines;
+}
+
+/**
+ * Render all entries as human-readable text lines.
+ * @param {object[]} entries
+ * @returns {string[]}
+ */
+export function renderEntries(entries) {
+  if (entries.length === 0) return ['(no entries)'];
+  const out = [];
+  for (const e of entries) {
+    out.push(...renderEntry(e));
+    out.push('');
+  }
+  return out;
+}

package/lib/sign.mjs

@@ -0,0 +1,83 @@
+// sign.mjs — keyed signing for manifest entries (HMAC-SHA256, zero-dep).
+//
+// WHY: the hash chain (`prev` = sha256(previous raw line)) is keyless. Anyone
+// who can write the ledger file can recompute every `prev` and forge a clean
+// chain from scratch — sha256 is a public function with no secret. To make the
+// chain a real *provenance* signal (in-toto/SLSA-style), each entry is signed
+// with HMAC-SHA256 under a secret key (env ADLC_MANIFEST_KEY). An attacker
+// without the key cannot produce a valid `sig`, so a forged chain fails verify.
+//
+// CANONICAL BYTES SIGNED — must be byte-identical on record and verify:
+//   We sign the deterministic JSON of an object containing ONLY the
+//   chain-relevant fields, in this fixed key order:
+//       { seq, gate, ts, ticket, data, files, prev }
+//   built via canonicalEntryBytes() below. Optional fields (ticket, data) are
+//   included only when present on the entry — matching how buildEntry omits
+//   them — so the signed bytes mirror the entry's own shape. The `sig` field
+//   itself is never part of the signed bytes.
+
+import { createHmac, timingSafeEqual } from 'node:crypto';
+
+/** Env var holding the secret signing key. */
+export const KEY_ENV = 'ADLC_MANIFEST_KEY';
+
+/**
+ * Read the signing key from the environment.
+ * Returns the key string, or null when unset/empty.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string|null}
+ */
+export function getKey(env = process.env) {
+  const k = env[KEY_ENV];
+  return typeof k === 'string' && k.length > 0 ? k : null;
+}
+
+/**
+ * Build the canonical byte string that gets signed for an entry.
+ *
+ * Deterministic: fixed key order, optional fields included only when the entry
+ * carries them. The `sig` field is always excluded.
+ *
+ * @param {object} entry  a manifest entry (with or without `sig`)
+ * @returns {string} canonical JSON string
+ */
+export function canonicalEntryBytes(entry) {
+  const canonical = {
+    seq: entry.seq,
+    gate: entry.gate,
+    ts: entry.ts,
+  };
+  if (entry.ticket !== undefined) canonical.ticket = entry.ticket;
+  if (entry.data !== undefined) canonical.data = entry.data;
+  canonical.files = entry.files;
+  canonical.prev = entry.prev;
+  return JSON.stringify(canonical);
+}
+
+/**
+ * Compute the HMAC-SHA256 signature (hex) of an entry under a key.
+ * @param {string} key
+ * @param {object} entry
+ * @returns {string} hex digest
+ */
+export function signEntry(key, entry) {
+  return createHmac('sha256', key).update(canonicalEntryBytes(entry)).digest('hex');
+}
+
+/**
+ * Constant-time check that `entry.sig` is the correct HMAC for `key`.
+ * Returns false when sig is missing, malformed, or wrong.
+ * @param {string} key
+ * @param {object} entry
+ * @returns {boolean}
+ */
+export function verifyEntrySig(key, entry) {
+  if (typeof entry.sig !== 'string' || entry.sig.length === 0) return false;
+  const expected = signEntry(key, entry);
+  // Both are hex strings of equal length (sha256 → 64 hex chars) when sig is
+  // well-formed; guard against length mismatch which timingSafeEqual rejects.
+  const a = Buffer.from(entry.sig, 'utf8');
+  const b = Buffer.from(expected, 'utf8');
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}

package/lib/verify.mjs

@@ -0,0 +1,155 @@
+// verify.mjs — walk raw lines and validate the hash chain.
+// Each entry's `prev` must equal sha256(previous raw line).
+// Sequence numbers must be strictly monotonically increasing.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { sha256, ledgerPath, ADLC_DIR } from '@adlc/core';
+import { getKey, verifyEntrySig } from './sign.mjs';
+
+/**
+ * Result of a chain verification.
+ * @typedef {object} VerifyResult
+ * @property {boolean} valid
+ * @property {string} message    human-readable summary
+ * @property {number} count      number of entries checked
+ * @property {boolean} signed    true only when a key was present AND every
+ *                               entry verified cryptographically. When no key
+ *                               is set this is false: callers MUST NOT claim
+ *                               cryptographic provenance from a hash-chain-only
+ *                               pass.
+ * @property {object|null} break  null if valid; { seq, lineNo, reason } if broken
+ */
+
+/**
+ * Verify the manifest ledger's hash chain — and, when ADLC_MANIFEST_KEY is
+ * set, the HMAC signature of every entry that carries one.
+ *
+ * Reads raw lines directly (never via readEntries) so that sha256 is computed
+ * over the exact bytes that were written.
+ *
+ * Security model:
+ *  - No key in env  → hash chain checked only; result.signed = false. The chain
+ *    proves *internal consistency*, not authorship — a writer can forge it.
+ *  - Key in env     → every entry MUST carry a valid sig. A missing sig
+ *    ('unsigned entry') or wrong sig ('signature invalid') breaks the chain.
+ *    This defeats the forge-from-scratch attack: without the key an attacker
+ *    cannot produce valid signatures, so verify (run WITH the key) returns
+ *    valid:false.
+ *
+ * @param {string} [dir]  ledger directory (default ADLC_DIR)
+ * @returns {VerifyResult}
+ */
+export function verify(dir = ADLC_DIR) {
+  const lp = ledgerPath('manifest', dir);
+  const key = getKey();
+
+  if (!existsSync(lp)) {
+    return { valid: true, message: 'empty manifest', count: 0, signed: false, break: null };
+  }
+
+  const content = readFileSync(lp, 'utf8');
+  const rawLines = content.split('\n');
+
+  // Filter to non-empty lines, keeping original 1-based line numbers
+  const nonEmpty = rawLines
+    .map((line, i) => ({ line, lineNo: i + 1 }))
+    .filter(({ line }) => line.trim() !== '');
+
+  if (nonEmpty.length === 0) {
+    return { valid: true, message: 'empty manifest', count: 0, signed: false, break: null };
+  }
+
+  let prevRawLine = null;
+  let prevSeq = null;
+
+  for (const { line, lineNo } of nonEmpty) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      return {
+        valid: false,
+        message: `chain broken at line ${lineNo}: malformed JSON`,
+        count: lineNo - 1,
+        signed: false,
+        break: { seq: null, lineNo, reason: 'malformed JSON' },
+      };
+    }
+
+    // Check prev hash
+    if (prevRawLine === null) {
+      // First entry: prev must be null
+      if (entry.prev !== null) {
+        return {
+          valid: false,
+          message: `chain broken at seq ${entry.seq} (line ${lineNo}): first entry prev must be null`,
+          count: 0,
+          signed: false,
+          break: { seq: entry.seq, lineNo, reason: 'first entry prev must be null' },
+        };
+      }
+    } else {
+      const expected = sha256(prevRawLine);
+      if (entry.prev !== expected) {
+        return {
+          valid: false,
+          message: `chain broken at seq ${entry.seq} (line ${lineNo}): prev hash mismatch`,
+          count: lineNo - 1,
+          signed: false,
+          break: { seq: entry.seq, lineNo, reason: 'prev hash mismatch' },
+        };
+      }
+    }
+
+    // Check seq monotonicity
+    if (prevSeq !== null && entry.seq <= prevSeq) {
+      return {
+        valid: false,
+        message: `chain broken at seq ${entry.seq} (line ${lineNo}): seq must be strictly increasing`,
+        count: lineNo - 1,
+        signed: false,
+        break: { seq: entry.seq, lineNo, reason: 'seq not monotonically increasing' },
+      };
+    }
+
+    // Check HMAC signature when a key is configured. With a key, EVERY entry
+    // must carry a valid sig — otherwise the chain is not cryptographically
+    // attestable and a forged-from-scratch chain would slip through.
+    if (key !== null) {
+      if (entry.sig === undefined || entry.sig === null) {
+        return {
+          valid: false,
+          message: `chain broken at seq ${entry.seq} (line ${lineNo}): unsigned entry`,
+          count: lineNo - 1,
+          signed: false,
+          break: { seq: entry.seq, lineNo, reason: 'unsigned entry' },
+        };
+      }
+      if (!verifyEntrySig(key, entry)) {
+        return {
+          valid: false,
+          message: `chain broken at seq ${entry.seq} (line ${lineNo}): signature invalid`,
+          count: lineNo - 1,
+          signed: false,
+          break: { seq: entry.seq, lineNo, reason: 'signature invalid' },
+        };
+      }
+    }
+
+    prevRawLine = line;
+    prevSeq = entry.seq;
+  }
+
+  // signed:true only when a key verified every entry. With no key, the chain
+  // is internally consistent but NOT cryptographically attested.
+  const signed = key !== null;
+  return {
+    valid: true,
+    message: signed
+      ? `manifest ok, signed (${nonEmpty.length} entries)`
+      : `manifest ok (${nonEmpty.length} entries)`,
+    count: nonEmpty.length,
+    signed,
+    break: null,
+  };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@adlc/gate-manifest",
+  "version": "1.0.0",
+  "description": "Hash-chained evidence ledger recording what each ADLC gate verified — agentic provenance with optional HMAC signing (C11).",
+  "type": "module",
+  "license": "MIT",
+  "author": "Chris Williams (@voodootikigod)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/voodootikigod/adlc.git",
+    "directory": "packages/gate-manifest"
+  },
+  "homepage": "https://github.com/voodootikigod/adlc/tree/main/packages/gate-manifest#readme",
+  "bugs": "https://github.com/voodootikigod/adlc/issues",
+  "keywords": [
+    "adlc",
+    "agentic",
+    "ai",
+    "llm",
+    "cli",
+    "gate-manifest",
+    "gate"
+  ],
+  "bin": {
+    "gate-manifest": "./bin/gate-manifest.mjs"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@adlc/core": "1.0.0"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}