rcf-lite 0.25.0 → 0.26.0

package/rcf/user-stories/us-15301.json

@@ -0,0 +1,31 @@
+{
+  "createdAt": "2026-09-08T12:17:35.296Z",
+  "updatedAt": "2026-09-08T12:19:48.200Z",
+  "asA": "rcf-lite maintainer applying edge-cloudflare-tunnel v1.0.0",
+  "iWant": "real-account-connector-healthy to actually provision the throwaway hetzner server through the T-1 fixture surface and run cloudflared tunnel info <name> asserting healthy connector count (when both CI_HAS_CLOUDFLARE_ACCOUNT and CI_HAS_HETZNER_ACCOUNT are set), real-account-tunnel-hostname-routes to drive undici for the public-hostname sub-case (activated on CI_HAS_CLOUDFLARE_ACCOUNT) and a two-identity JWT probe for the access-gated sub-case (activated only when CI_HAS_CLOUDFLARE_ACCESS is also set), and manifest-schema-validate to fail with a fixture-setup pointer when the credentials placeholder is missing rather than warn",
+  "soThat": "the real-account tunnel run proves connectors are up and routes actually serve on Cloudflare, the warn-on-env-set branches never again mask a broken driver, and a missing fixture pointer surfaces as a clear failure not a warning",
+  "description": "Part of H-2. connector-healthy consumes the hetzner fixture as-is; its defects are H-1 scope at HQ; if the fixture path fails locally the driver fails with a pointer naming the fixture step, never warn. hostname-routes: the public-hostname sub-case fetches the scratch subdomain via undici; the access-gated sub-case obtains an Access Service Token identity, exchanges it for a JWT and asserts an authenticated fetch succeeds AND an unauthenticated fetch is denied; the AUD sub-case stays pass-with-skip when CI_HAS_CLOUDFLARE_ACCESS is unset (HQ note: Access is not enabled on the HQ account today, so at gate time the AUD sub-case stays pass-with-skip until HQ enables Access, expected not a driver defect). Env-absent branch keeps pass-with-skip on both probes; a pass must never again be reachable from account-flag presence alone.",
+  "usId": "US-15301",
+  "prdId": "PRD-001",
+  "reqId": "REQ-153",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "H-2 tunnel real drivers: connector-healthy exercises cloudflared tunnel info against the throwaway hetzner server; hostname-routes drives undici and (when Access is enabled) a two-identity JWT probe; manifest-schema-validate placeholder becomes fail-with-pointer",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15301-1",
+      "description": "When both CI_HAS_CLOUDFLARE_ACCOUNT and CI_HAS_HETZNER_ACCOUNT are set with the required credentials, real-account-connector-healthy provisions the throwaway hetzner server via the T-1 hetzner fixture surface, brings a named cloudflared tunnel connector up on it, runs cloudflared tunnel info <name> through a cloudflared control shim, asserts the reported healthy connector count is at least one, captures a tunnelConnectorUp event on the injected event sink, and tears the connector and server down on exit. If the hetzner fixture path fails locally the driver fails with a pointer naming the failed fixture step (hetzner fixture defects are H-1 scope at HQ, never a warn on this driver). Env-absent branch keeps section 3.5 pass-with-skip.",
+      "testable": true
+    },
+    {
+      "id": "AC-15301-2",
+      "description": "When CI_HAS_CLOUDFLARE_ACCOUNT is set with the required tunnel credentials, real-account-tunnel-hostname-routes drives an undici fetch against the configured scratch subdomain for the public-hostname sub-case, asserts an HTTP 200 with expected body signature. When CI_HAS_CLOUDFLARE_ACCESS is ALSO set with Access service-token identities, the same probe drives a two-identity JWT sub-case: identity A obtains a JWT via the Service Token exchange and an authenticated fetch to the access-gated hostname succeeds; identity B without a JWT is denied (HTTP 302 to Access or HTTP 401). accountBoundSkipped is never set on the account-set branch; a pass is unreachable from CI_HAS_CLOUDFLARE_ACCOUNT presence alone on this probe. The access-gated sub-case remains pass-with-skip when CI_HAS_CLOUDFLARE_ACCESS is unset (HQ note: not enabled on HQ account today, expected). Env-absent branch keeps pass-with-skip.",
+      "testable": true
+    },
+    {
+      "id": "AC-15301-3",
+      "description": "manifest-schema-validate.mjs returns aggregateVerdict fail (not warn) with a detail string naming the missing credentials placeholder file and the fixture-setup step that would create it when the credentials placeholder is absent. The warn-on-missing-credentials-placeholder branch is removed.",
+      "testable": true
+    }
+  ]
+}

package/rcf/user-stories/us-15401.json

@@ -0,0 +1,31 @@
+{
+  "createdAt": "2026-09-08T12:17:35.792Z",
+  "updatedAt": "2026-09-08T12:19:48.599Z",
+  "asA": "rcf-lite maintainer applying the four Cloudflare-platform blueprints",
+  "iWant": "no SIMULATE_ read anywhere in a shipped probe body on the four blueprints, no fail envelope committed under .rcf/reports on the four blueprints, and every committed envelope reflecting a shipped-code pass run against the re-anchored probes",
+  "soThat": "the mutation-purity rule holds at the probe boundary, envelopes are trusted evidence rather than stale fail records, and honest labelling of local test doubles restores probe-comment credibility",
+  "description": "Part of H-2. All SIMULATE_ branches in shipped probe bodies (kv cache-aside-hit-then-miss, kv event-secrecy, DO sole-reader-scan, DO storage-round-trip, DO websocket-hub-broadcast) move to fixture-side shim modules under packages/rcf-lite/test/fixtures/cf-platform/ or .../cf-edge/. New shim files carry the h2-cf-platform-probe-integrity slug prefix (short form h2-cf acceptable). Every driver's negative path is proven by firing the fixture-side mutation switch and observing the FAIL tail; only shipped-code pass envelopes are committed. The committed fail envelope at .rcf/reports/blueprints/platform-cloudflare-kv/event-secrecy.json is deleted and a shipped-code pass envelope committed in its place; the other four kv envelopes are regenerated so committed envelopes reflect re-anchored shipped-code runs. Probe comments labelling doubles as fake state / fake WebSocket pair / fake clock are reworded to name the local double honestly, or adjudicated acceptable with reason in the PR body.",
+  "usId": "US-15401",
+  "prdId": "PRD-001",
+  "reqId": "REQ-154",
+  "version": "0.1.0",
+  "status": "draft",
+  "title": "H-2 cross-cutting probe hygiene: SIMULATE_ branches out of probe bodies into fixture shims; no fail envelope committed; probe comments name test doubles honestly",
+  "acceptanceCriteria": [
+    {
+      "id": "AC-15401-1",
+      "description": "A grep for the token SIMULATE_ across every shipped probe module (contributions/probes/*.mjs) on the four Cloudflare-platform blueprints (platform-cloudflare-kv, platform-cloudflare-durable-objects, messaging-queue-cloudflare, edge-cloudflare-tunnel) returns zero hits. Every mutation switch previously read from a probe body is now read from a fixture-side shim module under packages/rcf-lite/test/fixtures/cf-platform/ or .../cf-edge/ whose file name carries the h2-cf-platform-probe-integrity slug prefix (short form h2-cf acceptable). For each moved switch, a corresponding FAIL tail is observed and recorded in the PR provenance transcript when the shims switch is on.",
+      "testable": true
+    },
+    {
+      "id": "AC-15401-2",
+      "description": "No committed report under .rcf/reports/blueprints/{platform-cloudflare-kv, platform-cloudflare-durable-objects, messaging-queue-cloudflare, edge-cloudflare-tunnel}/ carries aggregateVerdict fail or warn. Every committed envelope on the four blueprints reflects a shipped-code pass run against the re-anchored probes; the previously committed fail envelope at .rcf/reports/blueprints/platform-cloudflare-kv/event-secrecy.json is replaced with a shipped-code pass envelope.",
+      "testable": true
+    },
+    {
+      "id": "AC-15401-3",
+      "description": "Every probe-comment or probe-utils-comment surfaced by stage-1 marker rows (kv fake clock; DO fake state; DO probe-utils lines 73 and 75; DO websocket-hub-broadcast fake WebSocket pair; kv not-yet elicit-gating wording) is either reworded to name the local test double honestly on its terms (a fixture in-memory driver realises the Workers KV binding shape; a synthetic WebSocket pair; an elicited fake wall-clock advanced deterministically by the fixture; a follow-up work-item note in place of not-yet) or adjudicated acceptable in the PR body with a stated reason. No shipped probe comment on the four blueprints carries a bare fake / not-yet marker without either honest naming or an adjudication row.",
+      "testable": true
+    }
+  ]
+}

package/releases/releases.yaml

@@ -40,8 +40,18 @@
 # `npm install rcf-lite`.
 
 feedVersion: 1
-latest: "0.25.0"
+latest: "0.26.0"
 releases:
+  - version: "0.26.0"
+    date: "2026-09-09"
+    breaking: false
+    headlines:
+      - "rcf-lite 0.26.0 is a hardening and authoring release. The Cloudflare-platform blueprints on the shelf pick up real-account probe drivers with positive evidence and one shared account-token env matrix."
+      - "The blueprint authoring standard gains three new sections (7c REQ-layer sufficiency, 7d positive-evidence verification, 7e single-definition ownership), ten checklist rows and RULE 16 in the managed agent block."
+      - "The rcf define blueprint verb group gains a lint-consistency subverb, a per-slug disposition ledger with an apply-time prompt and a read-only dispositions view, and the identity seed grows a register field. The schema floor moves to rcf-schemas 0.6.2."
+    minAgentAction: null
+    notesUrl: "https://stravica.ai/docs/rcf/changelog/"
+
   - version: "0.25.0"
     date: "2026-09-08"
     breaking: false

package/src/blueprint/apply.js

@@ -21,6 +21,7 @@ import { updateManifest } from './manifest-writer.js';
 import { stampId } from './namespace.js';
 import { nextResolutionId } from './resolutions.js';
 import { buildRefusalMessage, discoverAppliedCapabilities, runCustomAuthCapabilityElicits, runElicitationPhase, writeSidecar } from './capabilities.js';
+import { APPLY_DISPOSITION_PROMPT, initialiseLedger } from './disposition-ledger.js';
 
 /**
  * @typedef {object} ApplyResult
@@ -410,11 +411,36 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
     });
   }
 
+  // Disposition ledger. On a fresh apply, initialise
+  // rcf/blueprints/<slug>.disposition.json with one record per
+  // contributed AC so the applying agent has a machine-readable walk
+  // list. Reads AC ids and their `disposition` field (rcf-schemas
+  // 0.6.2) from the SOURCE user-story JSON so the record reflects the
+  // authored shape, not the stamped one; `fixed` ACs land as accepted
+  // with the sentinel reason, `template` and unmarked ACs land as
+  // pending-disposition. Re-apply leaves an existing ledger untouched.
+  let ledgerPath = null;
+  let dispositionPrompt = null;
+  let acCount = 0;
+  if (!dryRun) {
+    const acDescriptors = await collectAcDescriptorsFromSource(source, blueprint, namespace);
+    acCount = acDescriptors.length;
+    if (acCount > 0) {
+      const ledgerRes = await initialiseLedger({ projectRoot, slug: appliedSlug, acDescriptors, now });
+      ledgerPath = ledgerRes.path;
+      if (!ledgerRes.alreadyExisted) {
+        dispositionPrompt = APPLY_DISPOSITION_PROMPT(appliedSlug, blueprint.version, acCount);
+      }
+    }
+  }
+
   return {
     applied: true,
     slug: appliedSlug,
     version: blueprint.version,
     contributions: writtenContributions,
+    ...(ledgerPath ? { ledgerPath, dispositionAcCount: acCount } : {}),
+    ...(dispositionPrompt ? { dispositionPrompt } : {}),
     ...(wroteSidecar ? { sidecarPath, appliedCapabilities, appliedElicitations } : {}),
     // Companion-suggestion mechanism (spec 2.6). Bubble the source
     // blueprint's `suggestedCompanions[]` up on the result so the CLI
@@ -428,6 +454,44 @@ export async function applyBlueprint({ projectRoot, tree, source, displaySource,
   };
 }
 
+/**
+ * Walk the blueprint's user-story contributions on-disk and collect
+ * every AC as a { id, storyId, sourceDisposition? } descriptor for the
+ * disposition ledger. AC ids and story ids are stamped with the
+ * applied namespace so they match what the applying agent sees in the
+ * tree (rather than the raw blueprint-slug ids on the source files).
+ *
+ * `disposition` on the AC (rcf-schemas 0.6.2 $defs.acDisposition) is
+ * `fixed` | `template` and is optional; an unmarked AC lands as
+ * pending-disposition with no `sourceDisposition` field so the operator
+ * can decide.
+ */
+async function collectAcDescriptorsFromSource(sourcePath, blueprint, namespace) {
+  const descriptors = [];
+  for (const c of blueprint.contributions ?? []) {
+    if (c.kind !== 'us' || typeof c.path !== 'string') continue;
+    const abs = join(sourcePath, 'contributions', c.path);
+    let doc;
+    try { doc = JSON.parse(await readFile(abs, 'utf8')); } catch { continue; }
+    const rawStoryId = typeof doc.usId === 'string' ? doc.usId : c.id;
+    // Re-stamp under the applied namespace so a library-qualified apply
+    // (namespace differs from the blueprint's own slug) records the
+    // story id the applying agent will actually see on the tree.
+    const storyStamped = stampId(rawStoryId, namespace);
+    const storyId = 'error' in storyStamped ? rawStoryId : storyStamped.id;
+    const acs = Array.isArray(doc.acceptanceCriteria) ? doc.acceptanceCriteria : [];
+    for (const ac of acs) {
+      if (!ac || typeof ac.id !== 'string') continue;
+      const descriptor = { id: ac.id, storyId };
+      if (ac.disposition === 'fixed' || ac.disposition === 'template') {
+        descriptor.sourceDisposition = ac.disposition;
+      }
+      descriptors.push(descriptor);
+    }
+  }
+  return descriptors;
+}
+
 function stampContributions(contributions, namespace) {
   const out = [];
   for (const c of contributions ?? []) {

package/src/blueprint/consistency-lint.js

@@ -0,0 +1,432 @@
+// Blueprint chain-consistency lint (spec section 5 of the integration
+// and contradiction protocol, 2026-09-09).
+//
+// Two passes over ONE blueprint's own JSON and markdown. Pure functions;
+// the CLI seam loads the blueprint from disk and hands the model in.
+//
+// PASS 1: single-definition ownership, MECHANICAL ONLY.
+//   The check is intentionally conservative. Pass 1 fires when the
+//   same identifier-shaped literal appears on more than one artefact
+//   and one of the appearances is case-INCONSISTENT with the owning
+//   TAC on a case-sensitive axis (HTTP header, env-var, camelCase
+//   JSON field name in a strict-parse context). A byte-identical
+//   restatement is only flagged when the owning TAC declares the
+//   token on its `interfaces[]` (the strict interface surface) and
+//   the restating AC carries no `ownerRef` back to that TAC. Every
+//   other kind of appearance is treated as a reference, not a
+//   restatement (the mechanical detector cannot reliably tell a
+//   duplicate literal from a legitimate mention without domain
+//   knowledge, and the spec explicitly names four human-read shapes
+//   the lint does not catch, per section 5.7).
+//
+// PASS 2: REQ delivery, MECHANICAL.
+//   A REQ whose description carries a promise phrase (must / requires
+//   / guarantees / ceiling / never / invariant / on boot / at boot /
+//   event / boundary) must carry a `deliveredBy` link into a TAC or
+//   ADR. When the link points at a TAC in the same blueprint, the
+//   TAC's responsibilities and interfaces must reference the field
+//   (or the REQ's subject, when no `field` sub-path is given).
+//
+// Every finding carries a stable `id` the operator can quote in the
+// blueprint README under "Known chain-consistency-lint suppressions"
+// (pass 1 only; pass 2 findings are not suppressible per spec 5.8).
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @typedef {object} ConsistencyFinding
+ * @property {string} id
+ * @property {'pass1'|'pass2'} pass
+ * @property {'contractDrift'|'undeclaredRestatement'|'reqNoDelivery'|'reqDeliveryNotCarried'} kind
+ * @property {string} subject
+ * @property {string[]} refs
+ * @property {string} message
+ * @property {boolean} [suppressed]
+ * @property {string}  [suppressionReason]
+ */
+
+const HTTP_HEADER_RE = /^[A-Z][A-Za-z0-9]*(-[A-Z][A-Za-z0-9]*)+$/;
+const HTTP_HEADER_LOWER_RE = /^[a-z][a-z0-9]*(-[a-z][a-z0-9]*)+$/;
+const ENV_VAR_RE = /^[A-Z][A-Z0-9]*(_[A-Z0-9]+)+$/;
+const CAMEL_JSON_FIELD_RE = /^[a-z][a-zA-Z0-9]*$/;
+
+/**
+ * Extract identifier-shaped tokens from a body of text: dashed
+ * identifiers (Cf-Turnstile-Response, run_worker_first),
+ * ALL_CAPS_ENV_VARS, and camelCase / PascalCase runs. Duplicates are
+ * preserved so callers can index by occurrence.
+ *
+ * @param {string} text
+ */
+function extractTokens(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const out = [];
+  const re = /[A-Za-z][A-Za-z0-9]*(?:[-_][A-Za-z0-9]+)+|[A-Z][a-z]+(?:[A-Z][a-z]*)+|[a-z]+(?:[A-Z][a-z]*){1,}/g;
+  for (const m of text.matchAll(re)) out.push(m[0]);
+  return out;
+}
+
+/**
+ * Classify a token for case-sensitivity purposes.
+ *
+ * @param {string} token
+ * @returns {'header'|'headerLower'|'envVar'|'jsonField'|'identifier'}
+ */
+function tokenClass(token) {
+  if (ENV_VAR_RE.test(token)) return 'envVar';
+  if (HTTP_HEADER_RE.test(token)) return 'header';
+  if (HTTP_HEADER_LOWER_RE.test(token)) return 'headerLower';
+  if (CAMEL_JSON_FIELD_RE.test(token)) return 'jsonField';
+  return 'identifier';
+}
+
+// TAC / ADR / REQ / US / PRD / TAD / BS / FBS id prefixes: these read
+// as identifier-shaped but they are meta references, not contract
+// literals. Skip them in both directions of the drift check.
+const ID_TOKEN_RE = /^(?:TAC|ADR|REQ|US|PRD|TAD|BS|FBS|TS|CN|AC)[-_A-Z0-9-]*$/;
+
+// Small stop-list of ordinary English hyphenated / camel-cased words
+// that appear as identifier-shape but are prose, not contracts.
+const PROSE_TOKENS = new Set([
+  'stable-coded', 'per-environment', 'wall-clock', 'operator-authored',
+  'project-authored', 'vendor-resolved', 'required-absent',
+  'deployable-to-slice', 'rotation-days', 'admin-UI',
+  'read-through', 'write-through', 'follow-up',
+]);
+
+function isNoise(token) {
+  if (token.length < 4) return true;
+  if (ID_TOKEN_RE.test(token)) return true;
+  if (PROSE_TOKENS.has(token)) return true;
+  return false;
+}
+
+/**
+ * Owned-token dictionary. Keyed by lower-case token; the value is the
+ * canonical spelling on the owning TAC's interface surface, plus the
+ * TAC id and field where it lives.
+ *
+ * Only `interfaces[].name` and `interfaces[].summary` (backtick-quoted
+ * spans only) plus `internalStructure` (backtick-quoted spans only)
+ * count as owning surfaces. `responsibilities[]` and `purpose` are
+ * prose narrative where a mention is a reference, not a declaration.
+ */
+function collectOwnedTokens(tacs) {
+  /** @type {Map<string, { canonical: string, tacId: string, field: string, klass: string }>} */
+  const owned = new Map();
+  // record() takes an `onlySensitive` flag. For strict interface
+  // surfaces (`interfaces[].name`, `internalStructure` backtick spans,
+  // `responsibilities[]` backtick spans) we record every non-prose
+  // token including camelCase field names. For less-strict prose
+  // surfaces (interface summaries, purpose, responsibilities prose)
+  // we only record tokens classified as `header` / `headerLower` /
+  // `envVar`, because a prose mention of a camelCase word is usually
+  // a reference and only case-sensitive axes reliably indicate a
+  // literal declaration.
+  const record = (token, tacId, field, onlySensitive) => {
+    if (isNoise(token)) return;
+    const klass = tokenClass(token);
+    if (klass === 'identifier') return;
+    if (onlySensitive && klass === 'jsonField') return;
+    const key = token.toLowerCase();
+    if (!owned.has(key)) owned.set(key, { canonical: token, tacId, field, klass });
+  };
+  for (const tac of tacs) {
+    const tacId = tac.tacId || tac.id || '(unknown-tac)';
+    // Strict interface surfaces first so their spellings win the
+    // Map's first-write-wins semantics over any weaker prose mention.
+    if (Array.isArray(tac.interfaces)) {
+      for (let i = 0; i < tac.interfaces.length; i += 1) {
+        const iface = tac.interfaces[i];
+        if (iface && typeof iface.name === 'string') {
+          for (const t of extractTokens(iface.name)) record(t, tacId, `interfaces[${i}].name`, false);
+        }
+        if (iface && typeof iface.summary === 'string') {
+          for (const m of iface.summary.matchAll(/`+([^`]+)`+/g)) {
+            for (const t of extractTokens(m[1])) record(t, tacId, `interfaces[${i}].summary`, false);
+          }
+          // Plain-text summary: case-sensitive axes only. This is what
+          // catches `Cf-Turnstile-Response` on TAC-3602's guard summary.
+          for (const t of extractTokens(iface.summary)) record(t, tacId, `interfaces[${i}].summary`, true);
+        }
+      }
+    }
+    if (typeof tac.internalStructure === 'string') {
+      for (const m of tac.internalStructure.matchAll(/`+([^`]+)`+/g)) {
+        for (const t of extractTokens(m[1])) record(t, tacId, 'internalStructure', false);
+      }
+      for (const t of extractTokens(tac.internalStructure)) record(t, tacId, 'internalStructure', true);
+    }
+    if (Array.isArray(tac.responsibilities)) {
+      for (let i = 0; i < tac.responsibilities.length; i += 1) {
+        const s = tac.responsibilities[i];
+        if (typeof s !== 'string') continue;
+        for (const m of s.matchAll(/`+([^`]+)`+/g)) {
+          for (const t of extractTokens(m[1])) record(t, tacId, `responsibilities[${i}]`, false);
+        }
+        for (const t of extractTokens(s)) record(t, tacId, `responsibilities[${i}]`, true);
+      }
+    }
+    if (typeof tac.purpose === 'string') {
+      // Purpose prose: header / envVar only (never fires on ordinary
+      // English or camelCase identifiers).
+      for (const t of extractTokens(tac.purpose)) record(t, tacId, 'purpose', true);
+    }
+  }
+  return owned;
+}
+
+/**
+ * Collect artefact surfaces (holderId, holderKind, field, text,
+ * optional ownerRef on ACs). Used by pass 1's cross-surface walk.
+ */
+function collectArtefactSurfaces(input) {
+  const surfaces = [];
+  for (const req of input.reqs) {
+    const rid = req.reqId || req.id || '(unknown-req)';
+    if (typeof req.description === 'string') surfaces.push({ holderId: rid, holderKind: 'req', field: 'description', text: req.description });
+  }
+  for (const us of input.userStories) {
+    const usid = us.usId || us.id || '(unknown-us)';
+    if (typeof us.iWant === 'string') surfaces.push({ holderId: usid, holderKind: 'us', field: 'iWant', text: us.iWant });
+    if (Array.isArray(us.acceptanceCriteria)) {
+      for (const ac of us.acceptanceCriteria) {
+        const acid = ac.id || `${usid}-AC?`;
+        const ownerRef = ac.ownerRef && typeof ac.ownerRef === 'object' ? ac.ownerRef : null;
+        for (const f of ['description', 'given', 'when', 'then']) {
+          if (typeof ac[f] === 'string') surfaces.push({ holderId: acid, holderKind: 'ac', field: f, text: ac[f], parentUsId: usid, ownerRef });
+        }
+      }
+    }
+  }
+  for (const adr of input.adrs) {
+    const aid = adr.adrId || adr.id || '(unknown-adr)';
+    for (const f of ['context', 'decision', 'consequences']) {
+      if (typeof adr[f] === 'string') surfaces.push({ holderId: aid, holderKind: 'adr', field: f, text: adr[f] });
+    }
+  }
+  if (typeof input.guideMarkdown === 'string' && input.guideMarkdown.length > 0) {
+    surfaces.push({ holderId: 'guide', holderKind: 'guide', field: 'body', text: input.guideMarkdown });
+  }
+  return surfaces;
+}
+
+/**
+ * @param {{ slug: string, sourcePath: string, tacs: object[], reqs: object[], userStories: object[], adrs: object[], guideMarkdown?: string }} input
+ * @returns {ConsistencyFinding[]}
+ */
+export function runPass1(input) {
+  const owned = collectOwnedTokens(input.tacs);
+  if (owned.size === 0) return [];
+  const surfaces = collectArtefactSurfaces(input);
+  /** @type {ConsistencyFinding[]} */
+  const findings = [];
+  const seen = new Set();
+
+  for (const surface of surfaces) {
+    for (const raw of extractTokens(surface.text)) {
+      if (isNoise(raw)) continue;
+      const key = raw.toLowerCase();
+      const owner = owned.get(key);
+      if (!owner) continue;
+      const isSensitive = owner.klass === 'header' || owner.klass === 'envVar' || owner.klass === 'headerLower';
+      // Contract drift: the same lower-cased token, spelled
+      // differently, on a case-sensitive axis (HTTP header or
+      // env-var). This is the primary mechanical catch and includes
+      // the `Cf-Turnstile-Response` / `cf-turnstile-response`
+      // specimen shape.
+      if (isSensitive && owner.canonical !== raw) {
+        // Sentence-start capitalisation is not contract drift.
+        // Skip when the two tokens differ ONLY in the case of the
+        // very first character (rest of the token is byte-identical).
+        if (owner.canonical.length === raw.length
+          && owner.canonical.slice(1) === raw.slice(1)
+          && owner.canonical[0].toLowerCase() === raw[0].toLowerCase()) continue;
+        const id = `pass1-drift-${owner.tacId}-${owner.canonical}`;
+        const dedupe = `${id}::${surface.holderId}::${raw}`;
+        if (!seen.has(dedupe)) {
+          seen.add(dedupe);
+          findings.push({
+            id, pass: 'pass1', kind: 'contractDrift',
+            subject: owner.canonical,
+            refs: [owner.tacId, surface.holderId],
+            message: `${surface.holderId}.${surface.field} spells '${owner.canonical}' as '${raw}'; owner ${owner.tacId}.${owner.field} declares '${owner.canonical}'.`,
+          });
+        }
+        continue;
+      }
+      // Undeclared restatement: only fires for AC surfaces (the
+      // schema field `ownerRef` lives on AC records), only when the
+      // owning surface is an `interfaces[].name` (the strict
+      // interface surface), and only when the AC does not name an
+      // `ownerRef.tacId` matching the owning TAC. Every other cross
+      // surface mention is read as a reference, not a restatement.
+      if (surface.holderKind !== 'ac') continue;
+      if (!owner.field.startsWith('interfaces[') || !owner.field.endsWith('].name')) continue;
+      const ownerRef = surface.ownerRef;
+      const declared = ownerRef && typeof ownerRef.tacId === 'string' && ownerRef.tacId === owner.tacId;
+      if (declared) continue;
+      const id = `pass1-restated-${owner.tacId}-${owner.canonical}`;
+      const dedupe = `${id}::${surface.holderId}`;
+      if (seen.has(dedupe)) continue;
+      seen.add(dedupe);
+      findings.push({
+        id, pass: 'pass1', kind: 'undeclaredRestatement',
+        subject: owner.canonical,
+        refs: [owner.tacId, surface.holderId],
+        message: `${surface.holderId}.${surface.field} restates '${owner.canonical}' owned by ${owner.tacId}.${owner.field}; declare ownerRef or turn the mention into a reference.`,
+      });
+    }
+  }
+  return findings;
+}
+
+// REQ description phrases that read as an externally observable
+// promise the lint asks a TAC or ADR to deliver.
+const PROMISE_TERMS = [
+  'must', 'requires', 'required', 'guarantee', 'guarantees', 'guaranteed',
+  'ceiling', 'never', 'invariant', 'on boot', 'at boot', 'boot event',
+  'always', 'ensures', 'refuse', 'refuses', 'forbid', 'forbidden',
+];
+
+export function runPass2(input) {
+  const findings = [];
+  const tacsById = new Map();
+  for (const t of input.tacs) tacsById.set(t.tacId || t.id, t);
+  for (const req of input.reqs) {
+    const rid = req.reqId || req.id || '(unknown-req)';
+    const desc = typeof req.description === 'string' ? req.description : '';
+    const promises = PROMISE_TERMS.some((term) => new RegExp(`(^|[^A-Za-z])${term}([^A-Za-z]|$)`, 'i').test(desc));
+    if (!promises) continue;
+    const delivery = req.deliveredBy && typeof req.deliveredBy === 'object' ? req.deliveredBy : null;
+    if (!delivery || (!delivery.tacId && !delivery.adrId)) {
+      findings.push({
+        id: `pass2-no-delivery-${rid}`, pass: 'pass2', kind: 'reqNoDelivery',
+        subject: rid, refs: [rid],
+        message: `${rid}.description promises an externally observable property but declares no deliveredBy link into a TAC or ADR.`,
+      });
+      continue;
+    }
+    if (delivery.tacId) {
+      const target = tacsById.get(delivery.tacId);
+      if (!target) {
+        findings.push({
+          id: `pass2-delivery-missing-tac-${rid}-${delivery.tacId}`, pass: 'pass2', kind: 'reqDeliveryNotCarried',
+          subject: rid, refs: [rid, delivery.tacId],
+          message: `${rid}.deliveredBy names TAC ${delivery.tacId} which is not present in the blueprint.`,
+        });
+        continue;
+      }
+      const carried = collectTacSurfaceText(target).toLowerCase();
+      const field = typeof delivery.field === 'string' ? delivery.field.toLowerCase() : '';
+      const fieldTail = field ? field.split('.').pop() : '';
+      if (fieldTail && !carried.includes(fieldTail)) {
+        findings.push({
+          id: `pass2-delivery-field-missing-${rid}-${delivery.tacId}`, pass: 'pass2', kind: 'reqDeliveryNotCarried',
+          subject: rid, refs: [rid, delivery.tacId, fieldTail],
+          message: `${rid}.deliveredBy points at ${delivery.tacId}.${delivery.field} but that field is not present on the TAC's responsibilities or interfaces.`,
+        });
+      }
+    }
+  }
+  return findings;
+}
+
+function collectTacSurfaceText(tac) {
+  const parts = [];
+  if (typeof tac.purpose === 'string') parts.push(tac.purpose);
+  if (typeof tac.internalStructure === 'string') parts.push(tac.internalStructure);
+  if (Array.isArray(tac.responsibilities)) parts.push(tac.responsibilities.filter((s) => typeof s === 'string').join(' '));
+  if (Array.isArray(tac.interfaces)) {
+    for (const iface of tac.interfaces) {
+      if (iface && typeof iface.name === 'string') parts.push(iface.name);
+      if (iface && typeof iface.summary === 'string') parts.push(iface.summary);
+    }
+  }
+  return parts.join(' ');
+}
+
+/**
+ * Load a blueprint from disk into the shape the passes consume.
+ *
+ * @param {string} sourcePath
+ * @returns {Promise<{ slug: string, sourcePath: string, tacs: object[], reqs: object[], userStories: object[], adrs: object[], guideMarkdown: string } | { error: string }>}
+ */
+export async function loadForLint(sourcePath) {
+  let meta;
+  try {
+    const raw = await readFile(join(sourcePath, 'blueprint.json'), 'utf8');
+    meta = JSON.parse(raw);
+  } catch (err) {
+    return { error: `cannot read blueprint.json under ${sourcePath}: ${err.message}` };
+  }
+  const slug = meta.slug || '(unknown-slug)';
+  const contributions = Array.isArray(meta.contributions) ? meta.contributions : [];
+  const tacs = []; const reqs = []; const userStories = []; const adrs = [];
+  for (const c of contributions) {
+    if (!c || typeof c.path !== 'string') continue;
+    const abs = join(sourcePath, 'contributions', c.path);
+    let doc;
+    try { doc = JSON.parse(await readFile(abs, 'utf8')); } catch { continue; }
+    switch (c.kind) {
+      case 'tac': tacs.push(doc); break;
+      case 'req': reqs.push(doc); break;
+      case 'us': userStories.push(doc); break;
+      case 'adr': adrs.push(doc); break;
+      default: break;
+    }
+  }
+  let guideMarkdown = '';
+  try {
+    const entries = await readdir(join(sourcePath, 'guide'));
+    for (const name of entries) {
+      if (!name.endsWith('.md')) continue;
+      guideMarkdown += `${await readFile(join(sourcePath, 'guide', name), 'utf8')}\n`;
+    }
+  } catch { /* no guide directory is fine */ }
+  return { slug, sourcePath, tacs, reqs, userStories, adrs, guideMarkdown };
+}
+
+/**
+ * Extract "Known chain-consistency-lint suppressions" entries from a
+ * blueprint's README.md. Returns a Map from finding id to reason.
+ */
+export async function loadSuppressions(sourcePath) {
+  const out = new Map();
+  let readme;
+  try { readme = await readFile(join(sourcePath, 'README.md'), 'utf8'); } catch { return out; }
+  const m = readme.match(/##\s+Known chain-consistency-lint suppressions([\s\S]*?)(\n##\s+|$)/);
+  if (!m) return out;
+  for (const line of m[1].split('\n')) {
+    const rm = line.match(/^\s*[-*]\s+([A-Za-z0-9][A-Za-z0-9._:-]*)\s*:\s*(.+?)\s*$/);
+    if (rm) out.set(rm[1], rm[2]);
+  }
+  return out;
+}
+
+/**
+ * Run both passes and shape the result envelope. Pass 1 findings that
+ * appear in `suppressions` are marked `suppressed: true`; pass 2
+ * findings are never suppressible.
+ */
+export function runLint(input, suppressions = new Map()) {
+  const pass1 = runPass1(input);
+  const pass2 = runPass2(input);
+  let suppressedCount = 0;
+  for (const f of pass1) {
+    if (suppressions.has(f.id)) {
+      f.suppressed = true;
+      f.suppressionReason = suppressions.get(f.id);
+      suppressedCount += 1;
+    }
+  }
+  const findings = [...pass1, ...pass2];
+  const unsuppressed = findings.filter((f) => !f.suppressed);
+  return {
+    blueprint: input.slug,
+    findings,
+    verdict: unsuppressed.length === 0 ? 'pass' : 'fail',
+    passCounts: { pass1: pass1.length, pass2: pass2.length, suppressed: suppressedCount },
+  };
+}